--- name: MCP Server Research & Documentation slug: mcp-server-research description: How to research, verify, and write comprehensive documentation pages for MCP servers. Covers finding the real source, extracting tools/capabilities, and writing setup guides from verified information only. category: content --- # MCP Server Research & Documentation This skill produces complete, accurate documentation pages for MCP (Model Context Protocol) servers. Every fact must come from a verified source - the actual GitHub README, official documentation, or the npm/PyPI package page. Nothing is fabricated. ## Research process For each MCP server, follow this exact sequence: ### Step 1: Find the real source There are two types of MCP servers: **A. Provider-hosted (remote servers):** Major providers like HubSpot, Cloudflare, and Browserbase host the MCP server themselves. There is no GitHub repo to clone. The user just points their MCP client at a URL (e.g. `https://developers.hubspot.com/mcp`). For these: 1. Search for `"{server_name} MCP server" site:{provider_domain}` to find the official docs page 2. Use WebFetch on the official docs page to get setup instructions and capabilities 3. Do NOT link to third-party GitHub repos (e.g. random community forks). If the provider doesn't have their own repo, set github_url to empty. **B. Open-source (GitHub repos):** Some servers are open-source repos you self-host. For these: 1. Search for `"{server_name} MCP server" site:github.com` to find the official repo 2. Verify the repo is the official/canonical one: org ownership matches the provider, star count, recent commits 3. Be careful to distinguish official repos from community forks. If the provider is "Stripe" but the repo is from "random-user/stripe-mcp", that's community, not official. Note this clearly. **How to tell which type:** - If the provider has a docs page with a server URL (like `https://mcp.something.com`), it's provider-hosted - If the provider has an official GitHub org with the repo, it's open-source official - If only random users have GitHub repos, there is no official server - only community implementations. Note this. ### Step 2: Read the source docs For provider-hosted: Use WebFetch on the official docs page. For GitHub repos: Use WebFetch on the GitHub README (raw.githubusercontent.com URL). This is your primary source. Extract: - **What it does** (the first paragraph of the README, usually) - **Tools/endpoints exposed** (look for a tools table, function list, or capabilities section) - **Authentication method** (OAuth2, API key, Bearer token, none) - **Setup/installation** (npm install, pip install, Docker, config JSON) - **Configuration options** (env vars, CLI flags, config file) - **Prerequisites** (API keys needed, accounts required, paid plans) - **Links** (docs, website, npm, PyPI) ### Step 3: Extract the tools table MCP servers expose specific tools. Find them in the README - they're usually in a table or list format. For each tool capture: - Tool name (the exact function/method name) - Description (what it does) - Input parameters (if documented) If the README doesn't list tools explicitly, check the source code: look for `@tool` decorators, `server.tool()` calls, or a tools array in the main file. ### Step 4: Verify before writing Before writing any content, verify: - [ ] The GitHub URL is real and accessible - [ ] The provider/org matches who you'd expect - [ ] The tools listed actually exist in the repo - [ ] The setup instructions match the actual README - [ ] Any API key requirements are accurate - [ ] The auth type matches the actual implementation ## Output structure The enrichment agent produces these fields: ### full_description (markdown) 2-3 paragraphs covering: - What the server does and who it's for - Key capabilities (summarize the tools) - What makes it notable (official vs community, completeness, unique features) Do NOT pad with filler. If the server is simple, the description should be short. ### setup_guide (markdown) The actual setup instructions from the README, reformatted for clarity: - Installation command (npm/pip/docker) - Config JSON for Claude Desktop / Cursor / VS Code - Required env vars with descriptions - Any prerequisites (accounts, API keys, paid plans) Include the real config JSON block. If the README has one, use it. If not, construct one from the documented server command and env vars. ### use_cases (markdown) 3-5 bullet points of real use cases. These should be specific and practical: - BAD: "Manage your CRM data" (too vague) - GOOD: "Auto-create HubSpot contacts from inbound form submissions and enrich with Clearbit data" Derive use cases from the actual tools the server exposes, not from generic marketing copy. ### example_prompts (markdown) 3-5 example prompts a user would give to an AI agent using this MCP server: - "Show me my top 10 pages by sessions in the last 7 days" - "Find all contacts at Acme Corp in HubSpot and add a note about the Q3 renewal" - "Pause any Google Ads campaign with ROAS below 2x" These must be realistic and match the actual tools available. ### pros (markdown) 2-4 bullet points. Real strengths: - Official/maintained by the provider (if true) - Comprehensive tool coverage - Good documentation - Specific notable features ### cons (markdown) 2-3 bullet points. Real limitations: - Missing tools that users would expect - Requires paid API plan - No write capabilities (read-only) - Limited documentation - Community-maintained (if applicable) ### alternatives (markdown) List 1-3 alternative MCP servers or tools that serve a similar purpose. Only mention ones that actually exist. ## Hard rules - **No fabricated URLs.** Every URL must be verified via WebFetch or WebSearch. - **No invented tool names.** Only list tools that exist in the actual codebase. - **No fake stats.** Don't claim "10,000 users" or "99.9% uptime" unless sourced. - **No marketing fluff.** Write like a developer writing docs, not a marketer writing landing pages. - **Cite the source.** If a fact comes from the README, the setup guide text should match it. - **Admit gaps.** If the README is sparse, say "Documentation is limited" in cons. Don't fill gaps with guesses. - **No em dashes.** Use commas, periods, or colons.