Developer Guide - Contributing & Extending the Registry

This page collects pro tips for contributors who want to extend the MCP Registry with high-quality server entries and maintain the docs/site.

Local setup

1. Clone the repo and install dependencies:

git clone git@github.com:Zayan-Mohamed/mcp-registry.git
cd mcp-registry
npm install
python -m pip install --upgrade pip && pip install -r requirements.txt

1. Run validation checks:

npm test            # validates JSON snippets and checks required markdown sections

1. Preview docs locally:

mkdocs serve        # open http://127.0.0.1:8000

Adding a new server entry

Follow INSTRUCTIONS.md and TEMPLATE.md. Short checklist:

• Add a Markdown file under the appropriate category (e.g., vector-stores/new-server.md).
• Include ## Quick-Start and ## Security Profile sections (validator enforces these).
• Add a json fenced block with a claude_desktop_config.json-style snippet (use command, args array, and env placeholders).
• Run npm test locally before opening a PR.

Example JSON snippet pattern

{
  "command": "npx",
  "args": ["some-server", "install", "-y"],
  "env": {
    "API_KEY": "${API_KEY}"
  }
}

Use ${VAR_NAME} placeholders and never hardcode secrets.

Docs & MkDocs tips

• Add new docs pages under docs/ for category overviews or developer-focused content.
• Update mkdocs.yml nav to include new pages for site navigation.
• Run mkdocs build to validate the generated site prior to opening a PR.

CI / Deployment

• The project uses .github/workflows/deploy_mkdocs.yml to build and deploy the site to GitHub Pages.
• If you prefer automation to configure Pages for you, add a repo secret GH_PAGES_TOKEN (PAT with repo access) and I can add a workflow step to call the Pages API (we can add this on request).

Troubleshooting common issues

• Table parsing issues in Markdown often come from unescaped | characters inside table cells; replace them with | or use inline code with backticks and HTML entities.
• If gh-pages exists but the site returns 404: check Pages settings (Settings → Pages) or add the workflow step to enable Pages via the REST API (requires PAT).
• Use npm test to catch most formatting and snippet issues.

Best practices

• Keep descriptions concise but include resource needs (RAM, GPU) for ML servers.
• Add a security rating and short mitigations for each scope (Network / Filesystem / External APIs).
• Prefer examples with docker or npx patterns for reproducibility.

---

Last updated: 2026-01-28