Skip to main content

Contributing to ToolHive

Thank you for your interest in contributing to ToolHive! This page provides an overview of the project's architecture and links to resources for contributing to each component.

Project overview​

ToolHive is composed of several independently developed components, each with its own codebase, contributing guide, and development workflow. The components work together to provide a complete platform for running and managing Model Context Protocol (MCP) servers.

All ToolHive components are open source and licensed under the Apache 2.0 license.

Project components​

ToolHive CLI, API, and Kubernetes Operator​

The core ToolHive repository contains the command-line interface, API server, and Kubernetes operator. These components share a common codebase and provide the runtime environment for deploying and managing MCP servers.

Repository: stacklok/toolhive

Key resources:

ToolHive desktop UI​

The ToolHive Desktop UI is a cross-platform application that provides a graphical interface for discovering, installing, and managing MCP servers. It's built with TypeScript and Electron, and runs on macOS, Windows, and Linux.

Repository: stacklok/toolhive-studio

Key resources:

ToolHive Cloud UI​

The ToolHive Cloud UI is a web application for visualizing MCP servers running in user infrastructure with easy URL copying for integration with AI agents. Built with Next.js and TypeScript, this is an experimental project that is actively being developed and tested.

Repository: stacklok/toolhive-cloud-ui

Key resources:

Registry server​

The Registry Server is an API server that implements the official MCP Registry API. It provides standardized access to MCP servers from multiple backends, including file-based and other API-compliant registries.

Repository: stacklok/toolhive-registry-server

Key resources:

Built-in registry​

The built-in registry contains the curated list of MCP servers available in ToolHive. If you want to add a new MCP server to the registry, this is the repository to contribute to.

Repository: stacklok/toolhive-registry

Key resources:

Dockyard​

Dockyard is a tool that packages MCP servers into containers. It handles the containerization process, making it easy to run MCP servers in isolated environments.

Repository: stacklok/dockyard

Key resources:

MCP Optimizer​

The MCP Optimizer acts as an intelligent intermediary between AI clients and MCP servers. It provides tool discovery, unified access to multiple MCP servers through a single endpoint, and intelligent routing. The optimizer reduces token usage by narrowing down the toolset to only relevant tools for each request.

Repository: StacklokLabs/mcp-optimizer

Key resources:

Documentation website​

The documentation website (this site) is built with Docusaurus and contains guides, tutorials, and reference documentation for all ToolHive components.

Repository: stacklok/docs-website

Key resources:

Ways to contribute​

We welcome contributions of all kinds, and no contribution is too small. Whether you're fixing a typo, improving documentation, or adding a major feature, your help is appreciated. First-time contributors are especially welcome!

Here are some ways you can contribute to ToolHive:

  • Code: Fix bugs, add features, or improve performance in any of the project components.
  • Documentation: Write guides, improve existing docs, add examples, or fix typos.
  • Testing: Test new features, report bugs, or contribute automated tests.
  • Bug triage: Help review and reproduce issues reported by others.
  • Examples and tutorials: Create sample projects or write tutorials showing how to use ToolHive.
  • MCP servers: Submit new MCP servers to the registry or improve existing ones.
  • Community support: Help answer questions in GitHub issues or on Discord.
  • Design and UX: Contribute to the UI design or suggest improvements to the user experience.

Getting started​

Ready to contribute? Here are some ways to get involved:

  1. Explore the codebase: Browse the repositories that interest you and read through the contributing guides to understand the development workflow.

  2. Find an issue: Look for issues labeled good first issue or help wanted in the issue trackers. These are great starting points for new contributors.

  3. Join the community: Connect with other contributors in the Stacklok Discord community. The #toolhive-developers channel is dedicated to technical discussions.

  4. Report bugs: If you find a bug, open an issue in the appropriate repository with a clear description and steps to reproduce.

  5. Suggest features: Have an idea for a new feature? Open an issue to discuss it with the maintainers before starting work.

Code of conduct​

All contributors are expected to follow the Stacklok Code of Conduct. We're committed to providing a welcoming and inclusive environment for everyone.

Additional resources​