{"id":28215946,"url":"https://github.com/arabold/docs-mcp-server","last_synced_at":"2026-05-19T22:01:51.974Z","repository":{"id":284240193,"uuid":"950061990","full_name":"arabold/docs-mcp-server","owner":"arabold","description":"Grounded Docs MCP Server: Open-Source Alternative to Context7, Nia, and Ref.Tools","archived":false,"fork":false,"pushed_at":"2026-05-16T21:05:07.000Z","size":10169,"stargazers_count":1336,"open_issues_count":55,"forks_count":153,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-05-16T21:26:55.575Z","etag":null,"topics":["agentic-ai","copilot","cursor","llm","mcp","vscode","windsurf"],"latest_commit_sha":null,"homepage":"https://grounded.tools","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arabold.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-03-17T15:13:15.000Z","updated_at":"2026-05-16T19:13:04.000Z","dependencies_parsed_at":"2026-01-03T00:02:46.950Z","dependency_job_id":null,"html_url":"https://github.com/arabold/docs-mcp-server","commit_stats":null,"previous_names":["arabold/docs-mcp-server"],"tags_count":69,"template":false,"template_full_name":null,"purl":"pkg:github/arabold/docs-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fdocs-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fdocs-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fdocs-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fdocs-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arabold","download_url":"https://codeload.github.com/arabold/docs-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fdocs-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33153665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T09:28:26.183Z","status":"ssl_error","status_checked_at":"2026-05-17T09:27:52.702Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["agentic-ai","copilot","cursor","llm","mcp","vscode","windsurf"],"created_at":"2025-05-17T22:12:17.935Z","updated_at":"2026-05-19T22:01:51.968Z","avatar_url":"https://github.com/arabold.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Documentation \u0026 Learning Resources","llm","📚 Projects (1974 total)","Search \u0026 Data Extraction","Document Processing","Containerised MCP Servers","🌐 Web Development","MCP Servers"],"sub_categories":["MCP Servers","How to Submit","AI \u0026 Machine Learning","Knowledge \u0026 Memory"],"readme":"# Grounded Docs: Your AI's Up-to-Date Documentation Expert\n\n**Docs MCP Server** solves the problem of AI hallucinations and outdated knowledge by providing a personal, always-current documentation index for your AI coding assistant. It fetches official docs from websites, GitHub, npm, PyPI, and local files, allowing your AI to query the exact version you are using.\n\n![Docs MCP Server Web Interface](docs/docs-mcp-server.png)\n\n## ✨ Why Grounded Docs MCP Server?\n\nThe open-source alternative to **Context7**, **Nia**, and **Ref.Tools**.\n\n-   ✅ **Up-to-Date Context:** Fetches documentation directly from official sources on demand.\n-   🎯 **Version-Specific:** Queries target the exact library versions in your project.\n-   💡 **Reduces Hallucinations:** Grounds LLMs in real documentation.\n-   🔒 **Private \u0026 Local:** Runs entirely on your machine; your code never leaves your network.\n-   🧩 **Broad Compatibility:** Works with any MCP-compatible client (Claude, Cline, etc.).\n-   📁 **Multiple Sources:** Index websites, GitHub repositories, local folders, and zip archives.\n-   📄 **Rich File Support:** Processes HTML, Markdown, PDF, Office documents (Word, Excel, PowerPoint), OpenDocument, RTF, EPUB, Jupyter Notebooks, and [90+ source code languages](docs/concepts/supported-formats.md).\n\n---\n\n## 📄 Supported Formats\n\n| Category | Formats |\n|----------|---------|\n| **Documents** | PDF, Word (.docx/.doc), Excel (.xlsx/.xls), PowerPoint (.pptx/.ppt), OpenDocument (.odt/.ods/.odp), RTF, EPUB, FictionBook, Jupyter Notebooks |\n| **Archives** | ZIP, TAR, gzipped TAR (contents are extracted and processed individually) |\n| **Web** | HTML, XHTML |\n| **Markup** | Markdown, MDX, reStructuredText, AsciiDoc, Org Mode, Textile, R Markdown |\n| **Source Code** | TypeScript, JavaScript, Python, Go, Rust, C/C++, Java, Kotlin, Ruby, PHP, Swift, C#, and [many more](docs/concepts/supported-formats.md#source-code) |\n| **Data** | JSON, YAML, TOML, CSV, XML, SQL, GraphQL, Protocol Buffers |\n| **Config** | Dockerfile, Makefile, Terraform/HCL, INI, dotenv, Bazel |\n\nSee **[Supported Formats](docs/concepts/supported-formats.md)** for the complete reference including MIME types and processing details.\n\n---\n\n## 🚀 Quick Start\n\n### CLI First\n\nFor agents and scripts, the CLI is usually the simplest way to use Grounded Docs.\n\n**1. Index documentation** (requires Node.js 22+):\n\n```bash\nnpx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react\n```\n\nFor hash-routed SPA docs sites, enable hash preservation explicitly:\n\n```bash\nnpx @arabold/docs-mcp-server@latest scrape my-spa https://docs.example.com/#/guide --preserve-hashes\n```\n\n**2. Query the index:**\n\n```bash\nnpx @arabold/docs-mcp-server@latest search react \"useEffect cleanup\" --output yaml\n```\n\n**3. Fetch a single page as Markdown:**\n\n```bash\nnpx @arabold/docs-mcp-server@latest fetch-url https://react.dev/reference/react/useEffect\n```\n\n### Output Behavior\n\n- Structured commands default to clean JSON on stdout in non-interactive runs.\n- Use `--output json|yaml|toon` to pick a structured format.\n- Plain-text commands such as `fetch-url` keep their text payload on stdout.\n- Diagnostics go through the shared logger and are kept off stdout in non-interactive runs.\n- Use `--quiet` to suppress non-error diagnostics or `--verbose` to enable debug output.\n\n### Agent Skills\n\nThe [`skills/`](skills/) directory contains [Agent Skills](https://agentskills.io) that teach AI coding assistants how to use the CLI — covering documentation search, index management, and URL fetching.\n\n### MCP Server\n\nIf you want a long-running MCP endpoint for Claude, Cline, Copilot, Gemini CLI, or other MCP clients:\n\n**1. Start the server:**\n\n```bash\nnpx @arabold/docs-mcp-server@latest\n```\n\n**2. Open the Web UI** at **[http://localhost:6280](http://localhost:6280)** to add documentation.\n\n**3. Connect your AI client** by adding this to your MCP settings (e.g., `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"docs-mcp-server\": {\n      \"type\": \"sse\",\n      \"url\": \"http://localhost:6280/sse\"\n    }\n  }\n}\n```\n\nSee **[Connecting Clients](docs/guides/mcp-clients.md)** for VS Code (Cline, Roo) and other setup options.\n\n`scrape_docs` also accepts `preserveHashes: true` for documentation sites that use hash-based client-side routing.\nUse it only for hash-routed SPAs; normal sites typically use hash fragments for in-page anchors.\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternative: Run with Docker\u003c/summary\u003e\n\n```bash\ndocker run --rm \\\n  -v docs-mcp-data:/data \\\n  -v docs-mcp-config:/config \\\n  -p 6280:6280 \\\n  ghcr.io/arabold/docs-mcp-server:latest \\\n  --protocol http --host 0.0.0.0 --port 6280\n```\n\n\u003c/details\u003e\n\n### 🧠 Configure Embedding Model (Recommended)\n\nUsing an embedding model is **optional** but dramatically improves search quality by enabling semantic vector search.\n\n**Example: Enable OpenAI Embeddings**\n\n```bash\nOPENAI_API_KEY=\"sk-proj-...\" npx @arabold/docs-mcp-server@latest\n```\n\nSee **[Embedding Models](docs/guides/embedding-models.md)** for configuring **Ollama**, **Gemini**, **Azure**, and others.\n\n---\n\n## 📚 Documentation\n\n### Getting Started\n-   **[Installation](docs/setup/installation.md)**: Detailed setup guides for Docker, Node.js (npx), and Embedded mode.\n-   **[Connecting Clients](docs/guides/mcp-clients.md)**: How to connect Claude, VS Code (Cline/Roo), and other MCP clients.\n-   **[Basic Usage](docs/guides/basic-usage.md)**: Using the Web UI, CLI, and scraping local files.\n-   **[Configuration](docs/setup/configuration.md)**: Full reference for config files and environment variables.\n-   **[Supported Formats](docs/concepts/supported-formats.md)**: Complete file format and MIME type reference.\n-   **[Embedding Models](docs/guides/embedding-models.md)**: Configure OpenAI, Ollama, Gemini, and other providers.\n-   **[Search Quality Benchmark](docs/guides/benchmarking.md)**: Measure retrieval quality with IR metrics + LLM-judged scores; prerequisites, how to run, how to interpret results.\n\n### Hash-Routed SPAs\n-   Use `--preserve-hashes`, MCP `preserveHashes`, or the Web UI \"Preserve Hash Routes\" checkbox only for docs sites that route with URLs like `#/guide`.\n-   When enabled with `scrapeMode=fetch`, the scraper automatically upgrades the job to Playwright because plain fetch cannot evaluate client-side hash routes.\n-   Refresh reuses the stored `preserveHashes` setting by default, and CLI/Web refresh entrypoints can override it explicitly.\n\n### Markdown-Optimized Web Scraping\n-   Web scrapes and refreshes automatically probe for `llms.txt` at the documentation subpath and site root before normal crawling. When found, the curated links become additional crawl seeds, and pages discovered this way prefer `.md` URL variants such as `/guide/index.html.md` or `/page.html.md` before falling back to the original page.\n-   Web requests send `Accept: text/markdown, text/html;q=0.9, */*;q=0.8` by default. Servers that support Markdown content negotiation, including Cloudflare Markdown for Agents, can return Markdown directly so the scraper bypasses HTML-to-Markdown conversion for cleaner output.\n-   This behavior is automatic and requires no configuration. Custom `Accept` headers are preserved when provided.\n\n### Key Concepts \u0026 Architecture\n-   **[Deployment Modes](docs/infrastructure/deployment-modes.md)**: Standalone vs. Distributed (Docker Compose).\n-   **[Authentication](docs/infrastructure/authentication.md)**: Securing your server with OAuth2/OIDC.\n-   **[Security](docs/infrastructure/security.md)**: Trust boundaries, deployment hardening, and outbound access controls.\n-   **[Telemetry](docs/infrastructure/telemetry.md)**: Privacy-first usage data collection.\n-   **[Architecture](ARCHITECTURE.md)**: Deep dive into the system design.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see **[CONTRIBUTING.md](CONTRIBUTING.md)** for development guidelines and setup instructions.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farabold%2Fdocs-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farabold%2Fdocs-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farabold%2Fdocs-mcp-server/lists"}