First off, thank you for taking the time to contribute to ToolHive! 👍 🎉 ToolHive is released under the Apache 2.0 license. If you would like to contribute something or want to hack on the code, this document should help you get started. You can find some hints for starting development in ToolHive's developer guide.
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to code-of-conduct@stacklok.dev.
If you think you have found a security vulnerability in ToolHive please DO NOT disclose it publicly until we've had a chance to fix it. Please don't report security vulnerabilities using GitHub issues; instead, please follow this process
We use GitHub issues to track bugs and enhancements. If you have a general usage question, please ask in ToolHive's discussion forum.
If you are reporting a bug, please help to speed up problem diagnosis by providing as much information as possible. Ideally, that would include a small sample project that reproduces the problem.
PRs to resolve existing issues are greatly appreciated, and issues labeled as "good first issue" are a great place to start!
- -All commits must include a Signed-off-by trailer at the end of each commit message to indicate that the contributor agrees to the Developer Certificate of Origin. For additional details, check out the DCO instructions.
- Create an issue outlining the fix or feature.
- Fork the ToolHive repository to your own GitHub account and clone it locally.
- Hack on your changes.
- Correctly format your commit messages, see Commit message guidelines below.
- Open a PR with a title that follows the conventional commit format (e.g.,
feat: add new featureorfix: resolve issue). The PR title will be validated to ensure it follows the conventional commit specification. Ensure the description reflects the content of the PR. - Ensure that CI passes, if it fails, fix the failures.
- Every pull request requires a review from the core ToolHive team before merging.
- Once approved, all of your commits will be squashed into a single commit with your PR title.
To improve code review efficiency, PRs are automatically labeled based on their size (total lines changed = additions + deletions):
| Label | Lines Changed |
|---|---|
| size/XS | < 100 |
| size/S | 100-299 |
| size/M | 300-599 |
| size/L | 600-999 |
| size/XL | ≥ 1000 |
Best practices:
- Keep PRs small and focused when possible (size/XS or size/S are ideal)
- Break large features into smaller, reviewable chunks
- If you need to create a large PR (size/XL), consider splitting it into multiple PRs or add a comment explaining why it needs to be large
The ToolHive user documentation website is maintained in the docs-website repository. If you want to contribute to the documentation, please open a PR in that repo.
Please review the README and STYLE-GUIDE in the docs-website repository for more information on how to contribute to the documentation.
We follow the Conventional Commits specification for commit messages:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Types:
feat: A new featurefix: A bug fixdocs: Documentation only changesstyle: Changes that do not affect the meaning of the code (white-space, formatting, etc.)refactor: A code change that neither fixes a bug nor adds a featureperf: A code change that improves performancetest: Adding missing tests or correcting existing testschore: Changes to the build process or auxiliary tools and libraries
Examples:
feat: add new MCP server registry endpointfix(ui): resolve button alignment issue in dark modedocs: update installation instructionstest: add unit tests for secret validation