{"_id":"@contentgrapher-io/mcp-server","name":"@contentgrapher-io/mcp-server","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.1":{"name":"@contentgrapher-io/mcp-server","version":"1.1.1","description":"MCP server for ContentGrapher: structural completeness analysis for web content. Wraps ContentGrapher REST API v1.","license":"MIT","type":"module","engines":{"node":">=20.0.0"},"main":"dist/index.js","bin":{"contentgrapher-mcp":"dist/index.js"},"scripts":{"build":"tsc","prepare":"npm run build","prepublishOnly":"npm run build && npm test","test":"tsx --test tests/*.test.ts","start":"node dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"devDependencies":{"@types/node":"^20.11.0","tsx":"^4.7.0","typescript":"^5.4.0"},"keywords":["mcp","model-context-protocol","contentgrapher","content-analysis","documentation","technical-writing","llm-retrieval","structural-completeness","devrel","docs-as-code"],"repository":{"type":"git","url":"git+https://github.com/contentgrapher/mcp-server.git"},"bugs":{"url":"https://github.com/contentgrapher/mcp-server/issues"},"homepage":"https://contentgrapher.io/docs/mcp","gitHead":"f7eacfecedf38905006381de6e3c09c326bd1764","_id":"@contentgrapher-io/mcp-server@1.1.1","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-FhUF62YFUtfWcXvsPsBacZPxpE13EujUzscuZlsDtHiN49iZEPPgcY8E/erMsgr6Ib8dl8HbSIhnuHEUV0PB3Q==","shasum":"8fb722c596660977fa9d158d67c238e14f8ec521","tarball":"https://registry.npmjs.org/@contentgrapher-io/mcp-server/-/mcp-server-1.1.1.tgz","fileCount":29,"unpackedSize":67825,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCFgCDoeVgw8HMsQ18wGux5Dw6Cmdu0Xcun1UmlnQxPSAIgBDjWNRarw4792IoRV8GXxWHwZ36soUmFV4Ic1+7xS74="}]},"_npmUser":{"name":"danielkcheung","email":"danielkcheung@gmail.com"},"directories":{},"maintainers":[{"name":"danielkcheung","email":"danielkcheung@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_1.1.1_1782789020506_0.34035759383377684"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-30T03:10:20.387Z","1.1.1":"2026-06-30T03:10:20.659Z","modified":"2026-06-30T03:10:20.852Z"},"maintainers":[{"name":"danielkcheung","email":"danielkcheung@gmail.com"}],"description":"MCP server for ContentGrapher: structural completeness analysis for web content. Wraps ContentGrapher REST API v1.","homepage":"https://contentgrapher.io/docs/mcp","keywords":["mcp","model-context-protocol","contentgrapher","content-analysis","documentation","technical-writing","llm-retrieval","structural-completeness","devrel","docs-as-code"],"repository":{"type":"git","url":"git+https://github.com/contentgrapher/mcp-server.git"},"bugs":{"url":"https://github.com/contentgrapher/mcp-server/issues"},"license":"MIT","readme":"# @contentgrapher/mcp-server\n\nModel Context Protocol server for [ContentGrapher](https://contentgrapher.io). Analyze web pages for structural concept completeness from Claude Code, Cursor, Windsurf, or VS Code Copilot.\n\nContentGrapher returns an observed concept map, 8-dimension question coverage, a coverage score (Shallow / Developing / Solid / Complete), and prioritized writing recommendations. Use it to audit documentation, technical writing, and any explanatory content that an LLM needs to retrieve from.\n\n## Requirements\n\n- Node.js **20 or newer** (Node 18 reached end-of-life in April 2025).\n- A ContentGrapher API key from [contentgrapher.io/account](https://contentgrapher.io/account). Generating an API key requires at least one purchased credit pack.\n- An MCP-capable host (Claude Code, Cursor, Windsurf, VS Code Copilot, or any client that speaks the 2025-03-26 protocol over stdio).\n\n## Tools\n\n| Tool | Cost | Returns |\n|---|---|---|\n| `check_credits` | Free | Purchased credits remaining, total purchased, key count, total analyses run |\n| `analyze_url_phase1` | Free | Concept map, 8-question coverage, quality signals, `analysisId` |\n| `complete_analysis` | 1 credit | Coverage score, prioritized recommendations, explanation framework |\n| `analyze_url` | 1 credit | Phase 1 + Phase 2 in one call |\n| `get_analysis` | Free | Retrieve a prior analysis result by ID |\n\nEach tool that returns an analysis also returns an embedded `application/json` resource at `contentgrapher://analyses/{id}` containing the full response body.\n\n## Configuration\n\nGenerate a key at [contentgrapher.io/account](https://contentgrapher.io/account), then add the server to your IDE's MCP config.\n\n### Claude Code\n\n`~/.claude/settings.json` (or project `.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"contentgrapher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@contentgrapher/mcp-server@1\"],\n      \"env\": {\n        \"CONTENTGRAPHER_API_KEY\": \"cgk_your_key_here\"\n      },\n      \"timeout\": 600000\n    }\n  }\n}\n```\n\nThe `timeout: 600000` value (10 minutes in milliseconds) accommodates worst-case combined Phase 1 + Phase 2 latency.\n\n### Cursor\n\n`.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"contentgrapher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@contentgrapher/mcp-server@1\"],\n      \"env\": {\n        \"CONTENTGRAPHER_API_KEY\": \"cgk_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n> **Cursor timeout note:** Cursor does not expose a per-server MCP tool call timeout setting as of mid-2025, and its default timeout does not accommodate worst-case Phase 1 or Phase 2 latency. If you encounter timeout failures in Cursor, use `analyze_url_phase1` followed by `complete_analysis` in separate turns rather than `analyze_url`. Contact Cursor support for updates on configurable MCP timeouts.\n\n### Windsurf\n\n`~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"contentgrapher\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@contentgrapher/mcp-server@1\"],\n      \"env\": {\n        \"CONTENTGRAPHER_API_KEY\": \"${env:CONTENTGRAPHER_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\n### VS Code Copilot\n\n`.vscode/mcp.json` at workspace root:\n\n```json\n{\n  \"servers\": {\n    \"contentgrapher\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@contentgrapher/mcp-server@1\"],\n      \"env\": {\n        \"CONTENTGRAPHER_API_KEY\": \"cgk_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nFor hosts that do not support a per-server timeout field, the host's default must be at least **360 seconds**.\n\n## Quick examples\n\nOnce configured, ask your LLM:\n\n> Run a ContentGrapher analysis on https://your-docs-site.com/getting-started for senior platform engineers.\n\nThe LLM calls `analyze_url` with the URL and audience. After 70-150 seconds you get the analysis ID, coverage score, top 5 recommendations, and remaining credits.\n\nTo preview the concept map without spending a credit:\n\n> Use ContentGrapher Phase 1 on https://your-docs-site.com/getting-started.\n\nTo retrieve a prior result:\n\n> Pull the ContentGrapher analysis with ID 550e8400-e29b-41d4-a716-446655440000.\n\n## API key handling\n\n- The server reads `CONTENTGRAPHER_API_KEY` at startup, validates the format, and deletes it from `process.env`.\n- The key is sent only to `https://contentgrapher.io` over HTTPS. It is never logged.\n- The server is stateless. Analysis results are returned to your MCP host and not persisted by the server beyond a 60-second purchased-credits cache.\n\n### Pinning the version\n\nThe configuration examples above use `@1` to accept all v1.x updates. To pin to an exact version:\n\n```json\n\"args\": [\"-y\", \"@contentgrapher/mcp-server@1.0.0\"]\n```\n\n## Concurrency\n\nThe server allows up to **4 concurrent analyses** per API key, leaving one slot in ContentGrapher's 5-request limit for the web UI and direct REST API access. A 5th in-flight `analyze_url`, `analyze_url_phase1`, or `complete_analysis` call returns a clear error immediately. `check_credits` and `get_analysis` do not consume a concurrency slot.\n\n## Configuration via Smithery or third-party directories\n\n> Your API key is transmitted to and stored by Smithery (or any third-party MCP directory UI) under their own privacy policy and security controls. For maximum key security, configure the server locally via your IDE's config file as shown above, where the key is stored only on your local machine.\n\n## Data retention\n\nContentGrapher MCP is a pass-through. Analysis results are returned to your LLM host and are not stored by the MCP server. Content sent for analysis is stored in ContentGrapher's database and governed by the ContentGrapher Privacy Policy at [contentgrapher.io/legal](https://contentgrapher.io/legal).\n\n## Failure recovery\n\nIf a tool call is interrupted by a network failure or host timeout:\n\n1. Note the `analysisId` from the most recent progress notification or tool response.\n2. Call `get_analysis` with that ID:\n   - `status: \"complete\"` means Phase 2 finished and your credit was used. The full result is in the response.\n   - `status: \"phase1_complete\"` means only Phase 1 finished. Call `complete_analysis` with the same ID to run Phase 2 (this debits 1 credit).\n3. Do not call `analyze_url` again on the same URL without checking the prior `analysisId` first.\n\nCalling `complete_analysis` on an analysis that is already `status: \"complete\"` returns the stored result without debiting a second credit.\n\n## Errors\n\nThe server maps every REST error to a plain-language tool result. Common cases:\n\n- `Authentication failed` — check `CONTENTGRAPHER_API_KEY` is set and starts with `cgk_`.\n- `No purchased credits remaining` — purchase a pack at [contentgrapher.io/pricing](https://contentgrapher.io/pricing). Only purchased credits work via the API; gift and admin credits visible in the web app cannot be debited.\n- `Concurrent request limit reached` — wait for an in-flight request to complete. Stuck slots auto-recover within 15 minutes.\n- `ContentGrapher could not analyze this page (422)` — the URL may be inaccessible, password-protected, JavaScript-heavy, or actively blocking crawlers.\n\n## Version policy\n\nThe major version of this package tracks the ContentGrapher REST API major version:\n\n- v1.x wraps `/api/v1/`.\n- A tool name change, required parameter rename, or output field rename triggers a major version bump.\n- New optional parameters and new tools are minor bumps.\n- Error message refinements are patch bumps.\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Links\n\n- ContentGrapher: [contentgrapher.io](https://contentgrapher.io)\n- Account and key management: [contentgrapher.io/account](https://contentgrapher.io/account)\n- Pricing: [contentgrapher.io/pricing](https://contentgrapher.io/pricing)\n- Docs page for this MCP server: [contentgrapher.io/docs/mcp](https://contentgrapher.io/docs/mcp)\n- Issues: [github.com/contentgrapher/mcp-server/issues](https://github.com/contentgrapher/mcp-server/issues)\n","readmeFilename":"README.md","_rev":"1-15eb0f7b969bf157a31ebad34335e447"}