{"id":45579581,"url":"https://github.com/stacklok/toolhive-catalog","last_synced_at":"2026-04-24T23:06:59.760Z","repository":{"id":311134305,"uuid":"1035921321","full_name":"stacklok/toolhive-catalog","owner":"stacklok","description":"ToolHive's registry catalog of MCP servers","archived":false,"fork":false,"pushed_at":"2026-04-18T06:20:09.000Z","size":9706,"stargazers_count":18,"open_issues_count":8,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-18T08:37:38.512Z","etag":null,"topics":["catalog","mcp","model-context-protocol","registry"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacklok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-11T09:44:01.000Z","updated_at":"2026-04-17T19:19:36.000Z","dependencies_parsed_at":"2026-01-15T05:01:21.407Z","dependency_job_id":null,"html_url":"https://github.com/stacklok/toolhive-catalog","commit_stats":null,"previous_names":["stacklok/toolhive-registry","stacklok/toolhive-catalog"],"tags_count":216,"template":false,"template_full_name":null,"purl":"pkg:github/stacklok/toolhive-catalog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-catalog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-catalog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-catalog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-catalog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacklok","download_url":"https://codeload.github.com/stacklok/toolhive-catalog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-catalog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32126709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T07:37:52.372Z","status":"ssl_error","status_checked_at":"2026-04-22T07:37:51.635Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["catalog","mcp","model-context-protocol","registry"],"created_at":"2026-02-23T11:34:59.482Z","updated_at":"2026-04-22T08:01:47.585Z","avatar_url":"https://github.com/stacklok.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ToolHive Catalog\n\nThis repository contains the catalog of MCP (Model Context Protocol) servers and skills available for ToolHive. Each server entry provides AI assistants with specialized tools and capabilities, while skills provide reusable prompts and workflows that leverage those tools.\n\n## What is this?\n\nThink of this as a catalog of tools and skills that AI assistants can use. Each server entry represents a server that provides specific capabilities—like interacting with GitHub, querying databases, or fetching web content. Each skill entry is a reusable prompt or workflow that combines server tools to accomplish a specific task—like reviewing pull requests or debugging issues.\n\n## How to Add Your MCP Server\n\nAdding your MCP server to the registry is simple! You need to create a `server.json` file following the [upstream MCP ServerJSON schema](https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json), with ToolHive-specific extensions in the `_meta` field. We support two types of MCP servers:\n\n1. **Container-based servers** - Run as Docker containers (use `packages` field)\n2. **Remote servers** - Accessed via HTTP/HTTPS endpoints (use `remotes` field)\n\n### Step 1: Create a Folder\n\nCreate a new folder in `registries/toolhive/servers/` with your server's name (use lowercase and hyphens):\n\n```\nregistries/\n  └── toolhive/\n      └── servers/\n      │   └── my-awesome-server/\n      │       └── server.json\n      └── skills/\n          └── my-skill/\n              ├── skill.json\n              ├── icon.svg\n              └── skill/          # installable content (referenced by subfolder in skill.json)\n                  └── SKILL.md\n```\n\n### Step 2: Create Your server.json File\n\nChoose the appropriate format based on your server type:\n\n#### For Container-based Servers\n\nCreate a `server.json` file:\n\n```json\n{\n  \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n  \"name\": \"io.github.stacklok/my-server\",\n  \"description\": \"What your server does in one sentence\",\n  \"title\": \"my-server\",\n  \"repository\": {\n    \"url\": \"https://github.com/myorg/my-server\",\n    \"source\": \"github\"\n  },\n  \"version\": \"1.0.0\",\n  \"packages\": [\n    {\n      \"registryType\": \"oci\",\n      \"identifier\": \"ghcr.io/myorg/my-server:v1.0.0\",\n      \"transport\": {\n        \"type\": \"stdio\"\n      },\n      \"environmentVariables\": [\n        {\n          \"name\": \"API_KEY\",\n          \"description\": \"Your API key\",\n          \"isRequired\": true,\n          \"isSecret\": true\n        }\n      ]\n    }\n  ],\n  \"_meta\": {\n    \"io.modelcontextprotocol.registry/publisher-provided\": {\n      \"io.github.stacklok\": {\n        \"ghcr.io/myorg/my-server:v1.0.0\": {\n          \"tier\": \"Community\",\n          \"status\": \"Active\",\n          \"tags\": [\"api\", \"integration\"],\n          \"tools\": [\"tool_name_1\", \"tool_name_2\"]\n        }\n      }\n    }\n  }\n}\n```\n\n#### For Remote Servers\n\n```json\n{\n  \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n  \"name\": \"io.github.stacklok/my-remote-server\",\n  \"description\": \"What your server does in one sentence\",\n  \"title\": \"my-remote-server\",\n  \"repository\": {\n    \"url\": \"https://github.com/myorg/my-server\",\n    \"source\": \"github\"\n  },\n  \"version\": \"1.0.0\",\n  \"remotes\": [\n    {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://api.example.com/mcp\"\n    }\n  ],\n  \"_meta\": {\n    \"io.modelcontextprotocol.registry/publisher-provided\": {\n      \"io.github.stacklok\": {\n        \"https://api.example.com/mcp\": {\n          \"tier\": \"Community\",\n          \"status\": \"Active\",\n          \"tags\": [\"remote\", \"api\"],\n          \"tools\": [\"tool_name_1\", \"tool_name_2\"]\n        }\n      }\n    }\n  }\n}\n```\n\n### Key Concepts\n\n**The `_meta` extensions block** holds ToolHive-specific data (tier, status, tags, tools, permissions, etc.) nested under `io.modelcontextprotocol.registry/publisher-provided` \u003e `io.github.stacklok` \u003e `\u003cextension-key\u003e`.\n\nThe **extension key** must match:\n- For containers: the `packages[0].identifier` value (e.g., `ghcr.io/myorg/my-server:v1.0.0`)\n- For remotes: the `remotes[0].url` value (e.g., `https://api.example.com/mcp`)\n\n### Step 3: Add More Details (Optional but Recommended)\n\nYou can add more information in the `_meta` extensions block:\n\n```json\n{\n  \"ghcr.io/myorg/my-server:v1.0.0\": {\n    \"tier\": \"Community\",\n    \"status\": \"Active\",\n    \"tags\": [\"api\", \"integration\", \"productivity\"],\n    \"tools\": [\"tool_name_1\", \"tool_name_2\"],\n    \"permissions\": {\n      \"network\": {\n        \"outbound\": {\n          \"allow_host\": [\"api.example.com\"],\n          \"allow_port\": [443]\n        }\n      }\n    },\n    \"provenance\": {\n      \"cert_issuer\": \"https://token.actions.githubusercontent.com\",\n      \"repository_uri\": \"https://github.com/myorg/my-server\",\n      \"runner_environment\": \"github-hosted\",\n      \"signer_identity\": \"/.github/workflows/build.yml\",\n      \"sigstore_url\": \"tuf-repo-cdn.sigstore.dev\"\n    },\n    \"custom_metadata\": {\n      \"author\": \"My Organization\",\n      \"homepage\": \"https://docs.example.com\",\n      \"license\": \"MIT\"\n    }\n  }\n}\n```\n\n## How to Add a Skill\n\nSkills are reusable prompts and workflows that leverage MCP server tools. A skill is defined by a `SKILL.md` file (with YAML frontmatter) and a `skill.json` registry entry.\n\n### Step 1: Create the Directory Structure\n\nCreate a new folder in `registries/toolhive/skills/` with your skill's name. Skill content (SKILL.md and any bundled resources) lives in a `skill/` subfolder, separate from registry metadata (skill.json, icon.svg):\n\n```bash\nmkdir -p registries/toolhive/skills/my-skill/skill\n```\n\n### Step 2: Create the SKILL.md File\n\nCreate this inside the `skill/` subfolder. It uses YAML frontmatter for metadata and markdown for the prompt/instructions:\n\n```markdown\n---\nname: my-skill\ndescription: What this skill does in one sentence.\nversion: \"0.1.0\"\nallowed-tools:\n  - server/tool_name_1\n  - server/tool_name_2\nlicense: Apache-2.0\nmetadata:\n  author: Your Name\n---\n\n# My Skill\n\nInstructions and prompts for the AI assistant go here...\n```\n\n### Step 3: Create the skill.json File\n\nCreate this in the skill's root directory (next to `icon.svg`, not inside `skill/`). This registers the skill in the catalog. Note that the `subfolder` points to the `skill/` subdirectory so that only skill content is installed — not registry metadata like `skill.json` and `icon.svg`:\n\n```json\n{\n  \"namespace\": \"io.github.stacklok\",\n  \"name\": \"my-skill\",\n  \"title\": \"My Skill\",\n  \"description\": \"What this skill does in one sentence.\",\n  \"version\": \"0.1.0\",\n  \"status\": \"active\",\n  \"license\": \"Apache-2.0\",\n  \"allowedTools\": [\"server/tool_name_1\", \"server/tool_name_2\"],\n  \"repository\": {\n    \"url\": \"https://github.com/stacklok/toolhive-catalog\",\n    \"type\": \"git\"\n  },\n  \"icons\": [\n    {\n      \"src\": \"icon.svg\",\n      \"type\": \"image/svg+xml\"\n    }\n  ],\n  \"packages\": [\n    {\n      \"registryType\": \"git\",\n      \"url\": \"https://github.com/stacklok/toolhive-catalog\",\n      \"ref\": \"main\",\n      \"subfolder\": \"registries/toolhive/skills/my-skill/skill\"\n    }\n  ]\n}\n```\n\n### Step 4: Add an Icon\n\nAdd an `icon.svg` file to your skill directory.\n\n### Step 5: Validate\n\n```bash\ntask catalog:validate\ntask catalog:build\n```\n\nFor a complete example, see `registries/toolhive/skills/code-review/`.\n\n## Common Questions\n\n### What is \"transport\"?\n\nThis tells ToolHive how to communicate with your server:\n\nFor **container-based servers** (in `packages[].transport.type`):\n\n- `stdio` - Standard input/output (most common)\n- `sse` - Server-sent events\n- `streamable-http` - HTTP streaming\n\nFor **remote servers** (in `remotes[].type`):\n\n- `streamable-http` - HTTP streaming (recommended)\n- `sse` - Server-sent events (deprecated but still supported)\n- **Note:** Remote servers cannot use `stdio`\n\nIf you're not sure, use `stdio` for containers and `streamable-http` for remote servers.\n\n### What is \"tier\"?\n\n- `Official` - Maintained by the MCP team or platform owners\n- `Community` - Created and maintained by the community (most servers)\n\n### What is \"status\"?\n\n- `Active` - Fully functional and maintained\n- `Deprecated` - No longer maintained, will be removed\n\n### What about the \"tools\" field?\n\nList all the tools your server provides in the `_meta` extensions block. If your server's tools aren't knowable until runtime, you can use `[\"set_during_runtime\"]`.\n\n### Do I need a Docker image?\n\n**For container-based servers:** Yes. Your MCP server must be packaged as a Docker image and published to a registry like:\n\n- Docker Hub (`docker.io/username/image`)\n- GitHub Container Registry (`ghcr.io/username/image`)\n- Other public registries\n\n**For remote servers:** No. You just need to provide the URL endpoint where your MCP server is accessible.\n\n### Security Note: Filesystem Permissions\n\n**Important:** Don't specify filesystem paths or volume mounts in your registry entries. Mounting host directories is a security risk and should be configured by users at runtime, not in registry specs. Only network permissions (allowed hosts and ports) should be specified in the `permissions` section.\n\n### How do I test my entry?\n\nAfter adding your entry, you can validate it:\n\n```bash\n# Validate all entries\ntask catalog:validate\n\n# Build the registry files\ntask catalog:build\n```\n\nOr submit a pull request and our automated checks will validate it for you.\n\n## Submitting Your Entry\n\n1. Fork this repository\n2. Add your server entry as described above\n3. Submit a pull request\n4. We'll review and merge your addition\n\n### Registry Inclusion Criteria\n\nWe evaluate submissions based on several criteria to ensure quality and usefulness for the community. Your server should:\n\n- Provide clear value and unique capabilities\n- Be well-documented with accurate tool descriptions\n- Follow security best practices\n- Be actively maintained with recent updates\n\nFor detailed evaluation criteria, see the [Registry Inclusion Criteria](docs/registry-criteria.md),\nincluding [MCP server criteria](docs/server-criteria.md) and\n[skill criteria](docs/skill-criteria.md).\n\n### Before Submitting, Please Ensure\n\nFor **container-based servers**:\n\n- [ ] Your Docker image is publicly accessible\n- [ ] The `description` clearly explains what your server does\n- [ ] You've listed all the tools your server provides\n- [ ] Any required environment variables are documented\n- [ ] Your server works with ToolHive\n\nFor **remote servers**:\n\n- [ ] Your server endpoint is publicly accessible\n- [ ] The `description` clearly explains what your server does\n- [ ] You've listed all the tools your server provides\n- [ ] Any required authentication is documented\n- [ ] The transport is set to `streamable-http` (preferred) or `sse` (not `stdio`)\n- [ ] Your server works with ToolHive's proxy command\n\n## Need Help?\n\n- Check existing entries in `registries/toolhive/servers/` for server examples\n- Check existing entries in `registries/toolhive/skills/` for skill examples\n- Open an issue if you have questions\n- Join our community discussions\n\n## For Maintainers\n\nIf you need to work with the registry programmatically:\n\n```bash\n# Validate all entries\ntask catalog:validate\n\n# Build the registry files (both ToolHive and official MCP formats)\ntask catalog:build\n\n# Update metadata for oldest entries\ntask catalog:update-metadata:oldest\n\n# See all available commands\ntask\n```\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Ftoolhive-catalog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacklok%2Ftoolhive-catalog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Ftoolhive-catalog/lists"}