Skip to content
Back to search

mcp-documentation-server

MCP Documentation Server - Bridge the AI Knowledge Gap. ✨ Features: Document management • Gemini integration • AI-powered semantic search • File uploads • Smart chunking • Multilingual support • Zero-setup 🎯 Perfect for: New frameworks • API docs • Internal guides

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/andrea9293--mcp-documentation-server/badge.svg)](/listings/andrea9293--mcp-documentation-server)

HTML

<a href="/listings/andrea9293--mcp-documentation-server"><img src="/api/listings/andrea9293--mcp-documentation-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/mcp-documentation-server"]
    }
  }
}

Open your browser at `http://localhost:3080` — the web UI starts automatically.

🤖 Agent Skill (REST API) — recommended for AI agents

Every MCP tool is also accessible via the **REST API** on `http://127.0.0.1:3080/api/`. This is the recommended way to interact from AI agents (Claude Code, OpenCode, Gemini CLI, Cursor) because it avoids loading MCP tool schemas into the conversation context — only the response JSON enters.

curl -s http://127.0.0.1:3080/api/config
curl -s http://127.0.0.1:3080/api/documents
curl -s -X POST http://127.0.0.1:3080/api/search-all \
  -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}'

A ready-to-use skill is included at `skills/documentation-server/SKILL.md` — it teaches your agent every endpoint with examples. Install it:

npx skills add https://github.com/andrea9293/mcp-documentation-server --skill documentation-server

Basic workflow

1. Add documents using `add_document` or place `.txt` / `.md` / `.pdf` files in the uploads folder and call `process_uploads`. 2. Search across everything with `search_all_documents`, or within a single document with `search_documents`. 3. Use `get_context_window` to fetch neighboring chunks and give the LLM broader context.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 244 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-published-blue)](https://registry.modelcontextprotocol.io/servers/io.github.andrea9293/mcp-documentation-server)
  2. [![npm version](https://badge.fury.io/js/@andrea9293%2Fmcp-documentation-server.svg)](https://badge.fury.io/js/@andrea9293%2Fmcp-documentation-server)
  3. [![GitHub Stars](https://img.shields.io/github/stars/andrea9293/mcp-documentation-server?style=social)](https://github.com/andrea9293/mcp-documentation-server)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/andrea9293/mcp-documentation-server)
  6. [![Donate with PayPal](https://i.ibb.co/SX4qQBfm/paypal-donate-button171.png)](https://www.paypal.com/donate/?hosted_button_id=HXATGECV8HUJN)
  7. [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/andrea.bravaccino)
  8. # MCP Documentation Server
  9. **Local-first document management and semantic search for AI coding agents.** No external databases, no cloud APIs, no vendor lock-in.
  10. Unlike other MCP servers that are CLI-only, this one ships with a **full web dashboard** — browse, search, upload, and manage your knowledge base from your browser. Every MCP tool is also exposed as a REST API, giving AI agents a lean, schema-free interface.
  11. - **🏠 Runs fully offline** — Orama vector DB with local AI embeddings (Transformers.js)
  12. - **🌐 Built-in Web UI** — starts automatically on port 3080 alongside the MCP server
  13. - **🔍 Hybrid search** — full-text + vector similarity with parent-child chunking
  14. - **🤖 Optional AI search** — Google Gemini for advanced document analysis (bring your own key)
  15. - **📁 Drag & drop uploads** — `.txt`, `.md`, `.pdf` support
  16. - **📦 Published on the [MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.andrea9293/mcp-documentation-server)** — installable via npx, no clone needed
  17. ## Quick Start
  18. ```json
  19. {
  20. "mcpServers": {
  21. "documentation": {
  22. "command": "npx",
  23. "args": ["-y", "@andrea9293/mcp-documentation-server"]
  24. }
  25. }
  26. }
  27. ```
  28. Open your browser at `http://localhost:3080` — the web UI starts automatically.
  29. ### 🤖 Agent Skill (REST API) — recommended for AI agents
  30. Every MCP tool is also accessible via the **REST API** on `http://127.0.0.1:3080/api/`. This is the recommended way to interact from AI agents (Claude Code, OpenCode, Gemini CLI, Cursor) because it avoids loading MCP tool schemas into the conversation context — only the response JSON enters.
  31. ```bash
  32. curl -s http://127.0.0.1:3080/api/config
  33. curl -s http://127.0.0.1:3080/api/documents
  34. curl -s -X POST http://127.0.0.1:3080/api/search-all \
  35. -H "Content-Type: application/json" \
  36. -d '{"query": "your search", "limit": 5}'
  37. ```
  38. A ready-to-use skill is included at `skills/documentation-server/SKILL.md` — it teaches your agent every endpoint with examples. Install it:
  39. ```bash
  40. npx skills add https://github.com/andrea9293/mcp-documentation-server --skill documentation-server
  41. ```
  42. ### Basic workflow
  43. 1. Add documents using `add_document` or place `.txt` / `.md` / `.pdf` files in the uploads folder and call `process_uploads`.
  44. 2. Search across everything with `search_all_documents`, or within a single document with `search_documents`.
  45. 3. Use `get_context_window` to fetch neighboring chunks and give the LLM broader context.
  46. ## Web UI
  47. The web interface starts automatically on port **3080** when the MCP server launches. From the web UI you can:
  48. - 📊 **Dashboard** — overview of all documents and stats
  49. - 📄 **Documents** — browse, view, and delete documents
  50. - ➕ **Add Document** — create documents with title, content, and metadata
  51. - 🔍 **Search All** — semantic search across all documents
  52. - 🎯 **Search in Doc** — search within a specific document
  53. - 🤖 **AI Search** — Gemini-powered analysis (if `GEMINI_API_KEY` is set)
  54. - 📁 **Upload Files** — drag & drop files and process them into the knowledge base
  55. - 🪟 **Context Window** — explore chunks around a specific index
  56. ## Configure an MCP client
  57. #### Minimal
  58. ```json
  59. {
  60. "mcpServers": {
  61. "documentation": {
  62. "command": "npx",
  63. "args": ["-y", "@andrea9293/mcp-documentation-server"]
  64. }
  65. }
  66. }
  67. ```
  68. #### With environment variables (all optional)
  69. ```json
  70. {
  71. "mcpServers": {
  72. "documentation": {
  73. "command": "npx",
  74. "args": ["-y", "@andrea9293/mcp-documentation-server"],
  75. "env": {
  76. "MCP_BASE_DIR": "/path/to/workspace",
  77. "GEMINI_API_KEY": "your-api-key-here",
  78. "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
  79. "START_WEB_UI": "true",
  80. "WEB_HOST": "127.0.0.1",
  81. "WEB_PORT": "3080"
  82. }
  83. }
  84. }
  85. }
  86. ```
  87. All environment variables are optional. Without `GEMINI_API_KEY`, only the local embedding-based search tools are available.
  88. ## MCP Tools
  89. The server registers the following tools (all validated with Zod schemas):
  90. ### 📄 Document Management
  91. | Tool | Description |
  92. | --- | --- |
  93. | `add_document` | Add a document (title, content, optional metadata) |
  94. | `list_documents` | List all documents with metadata and content preview |
  95. | `get_document` | Retrieve the full content of a document by ID |
  96. | `delete_document` | Remove a document, its chunks, database entries, and associated files |
  97. ### 📁 File Processing
  98. | Tool | Description |
  99. | --- | --- |
  100. | `process_uploads` | Process all files in the uploads folder (chunking + embeddings) |
  101. | `get_uploads_path` | Returns the absolute path to the uploads folder |
  102. | `list_uploads_files` | Lists files in the uploads folder with size and format info |
  103. | `get_ui_url` | Returns the Web UI URL (e.g. http://localhost:3080) — useful to open the dashboard or to locate the uploads folder from the browser |
  104. ### 🔍 Search
  105. | Tool | Description |
  106. | --- | --- |
  107. | `search_documents` | Semantic vector search within a specific document |
  108. | `search_all_documents` | Hybrid (full-text + vector) cross-document search |
  109. | `get_context_window` | Returns a window of chunks around a given chunk index |
  110. | `search_documents_with_ai` | 🤖 AI-powered search using Gemini (requires `GEMINI_API_KEY`) |
  111. ## Configuration
  112. Configure via environment variables or a `.env` file in the project root:
  113. | Variable | Default | Description |
  114. | --- | --- | --- |
  115. | `MCP_BASE_DIR` | `~/.mcp-documentation-server` | Base directory for data storage |
  116. | `MCP_EMBEDDING_MODEL` | `Xenova/all-MiniLM-L6-v2` | Embedding model name |
  117. | `GEMINI_API_KEY` | — | Google Gemini API key (enables `search_documents_with_ai`) |
  118. | `MCP_CACHE_ENABLED` | `true` | Enable/disable LRU embedding cache |
  119. | `START_WEB_UI` | `true` | Set to `false` to disable the built-in web interface |
  120. | `WEB_HOST` | `127.0.0.1` | Bind address for the web UI (use `0.0.0.0` to expose on all interfaces) |
  121. | `WEB_PORT` | `3080` | Port for the web UI |
  122. | `MCP_STREAMING_ENABLED` | `true` | Enable streaming reads for large files |
  123. | `MCP_STREAM_CHUNK_SIZE` | `65536` | Streaming buffer size in bytes (64KB) |
  124. | `MCP_STREAM_FILE_SIZE_LIMIT` | `10485760` | Threshold to switch to streaming (10MB) |
  125. ### Storage layout
  126. ```
  127. ~/.mcp-documentation-server/ # Or custom path via MCP_BASE_DIR
  128. ├── data/
  129. │ ├── orama-chunks.msp # Orama vector DB (child chunks + embeddings)
  130. │ ├── orama-docs.msp # Orama document DB (full content + metadata)
  131. │ ├── orama-parents.msp # Orama parent chunks DB (context sections)
  132. │ ├── migration-complete.flag # Written after legacy JSON migration
  133. │ └── *.md # Markdown copies of documents
  134. └── uploads/ # Drop .txt, .md, .pdf files here
  135. ```
  136. ### Embedding Models
  137. Set via `MCP_EMBEDDING_MODEL`:
  138. | Model | Dimensions | Notes |
  139. | --- | --- | --- |
  140. | `Xenova/all-MiniLM-L6-v2` | 384 | Default — fast, good quality |
  141. | `Xenova/paraphrase-multilingual-mpnet-base-v2` | 768 | Recommended — best quality, multilingual |
  142. Models are downloaded on first use (~80–420 MB). The vector dimension is determined automatically from the provider.
  143. ⚠️ **Important**: Changing the embedding model requires re-adding all documents — embeddings from different models are incompatible. The Orama database is recreated automatically when the dimension changes.
  144. ## Architecture
  145. ```
  146. Server (FastMCP, stdio)
  147. ├─ Web UI (Express, port 3080)
  148. │ └─ REST API → DocumentManager
  149. └─ MCP Tools
  150. └─ DocumentManager
  151. ├─ OramaStore — Orama vector DB (chunks DB + docs DB + parents DB), persistence, migration
  152. ├─ IntelligentChunker — Parent-child chunking (code, markdown, text, PDF)
  153. ├─ EmbeddingProvider — Local embeddings via @xenova/transformers
  154. │ └─ EmbeddingCache — LRU in-memory cache
  155. └─ GeminiSearchService — Optional AI search via Google Gemini
  156. ```
  157. - **OramaStore** manages three Orama instances: one for document metadata/content, one for child chunks with vector embeddings, and one for parent chunks (context sections). All are persisted to binary files on disk and restored on startup.
  158. - **IntelligentChunker** implements the Parent-Child Chunking pattern: documents are first split into large parent chunks that preserve full context (sections, paragraphs), then each parent is further split into small child chunks for precise vector search. At query time, results are deduplicated by parent so that the LLM receives both the matched fragment and the broader context.
  159. - **EmbeddingProvider** lazily loads a Transformers.js model for local inference — no API calls needed.
  160. ## Development
  161. ```bash
  162. git clone https://github.com/andrea9293/mcp-documentation-server.git
  163. cd mcp-documentation-server
  164. npm install
  165. ```
  166. ```bash
  167. npm run dev # FastMCP dev mode with hot reload
  168. npm run build # TypeScript compilation
  169. npm run inspect # FastMCP web UI for interactive tool testing
  170. npm start # Direct tsx execution (MCP server + web UI)
  171. npm run web # Run only the web UI (development)
  172. npm run web:build # Run only the web UI (compiled)
  173. ```
  174. ## Contributing
  175. 1. Fork the repository
  176. 2. Create a feature branch: `git checkout -b feature/name`
  177. 3. Follow [Conventional Commits](https://conventionalcommits.org/) for messages
  178. 4. Open a pull request
  179. ## License
  180. MIT — see [LICENSE](LICENSE)
  181. ## Support
  182. - 📖 [Documentation](https://github.com/andrea9293/mcp-documentation-server)
  183. - 🐛 [Report Issues](https://github.com/andrea9293/mcp-documentation-server/issues)
  184. - 💬 [MCP Community](https://modelcontextprotocol.io/)
  185. - 🤖 [Google AI Studio](https://aistudio.google.com/app/apikey) — get a Gemini API key
  186. ---
  187. ## Star History
  188. [![Star History Chart](https://star-history.dera.page/svg?repos=andrea9293/mcp-documentation-server&type=Date)](https://star-history.dera.page/#andrea9293/mcp-documentation-server&Date)
  189. **Built with [FastMCP](https://github.com/punkpeye/fastmcp), [Orama](https://orama.com/), and TypeScript**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.