MCP Documentation Server

Gestión documental local-first y búsqueda semántica para agentes de programación con IA. Sin bases de datos externas, sin APIs en la nube y sin dependencia de proveedor.

A diferencia de otros servidores MCP que son solo CLI, este incluye un panel web completo — explora, busca, sube y gestiona tu base de conocimiento desde el navegador. Cada herramienta MCP también se expone como una API REST, lo que ofrece a los agentes de IA una interfaz ligera y sin esquemas.

• 🏠 Funciona totalmente sin conexión — base de datos vectorial Orama con embeddings de IA locales (Transformers.js)

• 🌐 Interfaz web integrada — se inicia automáticamente en el puerto 3080 junto con el servidor MCP

• 🔍 Búsqueda híbrida — texto completo + similitud vectorial con fragmentación padre-hijo

• 🤖 Búsqueda con IA opcional — Google Gemini para el análisis avanzado de documentos (aporta tu propia clave)

• 📁 Subidas por arrastrar y soltar — compatibilidad con .txt, .md, .pdf

• 📦 Publicado en el MCP Registry — instalable mediante npx, sin necesidad de clonar

Inicio rápido

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

🤖 Habilidad de agente (API REST) — recomendada para agentes de IA

Cada herramienta MCP también es accesible a través de la API REST en ``. Esta es la forma recomendada de interactuar desde agentes de IA (Claude Code, OpenCode, Gemini CLI, Cursor), porque evita cargar los esquemas de las herramientas MCP en el contexto de la conversación — solo el JSON de la respuesta entra en el contexto.

  -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}'

Se incluye una habilidad lista para usar en skills/documentation-server/SKILL.md — enseña a tu agente todos los endpoints con ejemplos. Instálala:

npx skills add https://github.com/Unity-Billal-mesloub/mcp-documentation-server --skill documentation-server

Flujo de trabajo básico

1. Añade documentos con add_document o coloca archivos .txt / .md / .pdf en la carpeta de subidas y llama a process_uploads.

2. Busca en todo con search_all_documents, o dentro de un solo documento con search_documents.

3. Usa get_context_window para obtener los fragmentos vecinos y dar al LLM un contexto más amplio.

Related MCP server: OpenLMlib

Interfaz web

La interfaz web se inicia automáticamente en el puerto 3080 cuando se lanza el servidor MCP. Desde la interfaz web puedes:

• 📊 Panel — visión general de todos los documentos y estadísticas

• 📄 Documentos — explora, visualiza y elimina documentos

• ➕ Añadir documento — crea documentos con título, contenido y metadatos

• 🔍 Buscar en todo — búsqueda semántica en todos los documentos

• 🎯 Buscar en documento — búsqueda dentro de un documento específico

• 🤖 Búsqueda con IA — análisis con Gemini (si GEMINI_API_KEY está definida)

• 📁 Subir archivos — arrastra y suelta archivos y procésalos en la base de conocimiento

• 🪟 Ventana de contexto — explora los fragmentos alrededor de un índice específico

Configurar un cliente MCP

Mínimo

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

Con variables de entorno (todas opcionales)

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@Unity-Billal-mesloub/mcp-documentation-server"],
      "env": {
        "MCP_BASE_DIR": "/path/to/workspace",
        "GEMINI_API_KEY": "your-api-key-here",
        "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
        "START_WEB_UI": "true",
        "WEB_HOST": "127.0.0.1",
        "WEB_PORT": "3080"
      }
    }
  }
}

Todas las variables de entorno son opcionales. Sin GEMINI_API_KEY, solo están disponibles las herramientas de búsqueda basadas en embeddings locales.

Herramientas MCP

El servidor registra las siguientes herramientas (todas validadas con esquemas Zod):

Gestión de documentos

Procesamiento de archivos

Búsqueda

Configuración

Se configura mediante variables de entorno o un archivo .env en la raíz del proyecto:

Estructura de almacenamiento

~/.mcp-documentation-server/     # Or custom path via MCP_BASE_DIR
├── data/
│   ├── orama-chunks.msp         # Orama vector DB (child chunks + embeddings)
│   ├── orama-docs.msp           # Orama document DB (full content + metadata)
│   ├── orama-parents.msp        # Orama parent chunks DB (context sections)
│   ├── migration-complete.flag   # Written after legacy JSON migration
│   └── *.md                     # Markdown copies of documents
└── uploads/                     # Drop .txt, .md, .pdf files here

Modelos de embeddings

Se define mediante MCP_EMBEDDING_MODEL:

Los modelos se descargan la primera vez que se usan (~80–420 MB). La dimensión de los vectores se determina automáticamente a partir del proveedor.

⚠️ Importante: cambiar el modelo de embeddings requiere volver a añadir todos los documentos — los embeddings de diferentes modelos son incompatibles. La base de datos de Orama se recrea automáticamente cuando cambia la dimensión.

Arquitectura

Server (FastMCP, stdio)
  ├─ Web UI (Express, port 3080)
  │    └─ REST API → DocumentManager
  └─ MCP Tools
       └─ DocumentManager
            ├─ OramaStore          — Orama vector DB (chunks DB + docs DB + parents DB), persistence, migration
            ├─ IntelligentChunker  — Parent-child chunking (code, markdown, text, PDF)
            ├─ EmbeddingProvider   — Local embeddings via @xenova/transformers
            │    └─ EmbeddingCache — LRU in-memory cache
            └─ GeminiSearchService — Optional AI search via Google Gemini

• OramaStore gestiona tres instancias de Orama: una para los metadatos/contenido de los documentos, una para los fragmentos secundarios con embeddings vectoriales y otra para los fragmentos principales (secciones de contexto). Todas se guardan en archivos binarios en el disco y se restauran al inicio.

• IntelligentChunker implementa el patrón Parent-Child Chunking: los documentos se dividen primero en fragmentos principales grandes que conservan el contexto completo (secciones, párrafos), y luego cada fragmento principal se subdivide en fragmentos secundarios pequeños para una búsqueda vectorial precisa. En el momento de la consulta, los resultados se deduplican por fragmento principal, de modo que el LLM recibe tanto el fragmento coincidente como el contexto más amplio.

• EmbeddingProvider carga de forma diferida un modelo de Transformers.js para la inferencia local: no se necesitan llamadas a la API.

Desarrollo

git clone https://github.com/Unity-Billal-mesloub/mcp-documentation-server.git
cd mcp-documentation-server
npm install

npm run dev       # FastMCP dev mode with hot reload
npm run build     # TypeScript compilation
npm run inspect   # FastMCP web UI for interactive tool testing
npm start         # Direct tsx execution (MCP server + web UI)
npm run web       # Run only the web UI (development)
npm run web:build # Run only the web UI (compiled)

Contribuciones

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad: git checkout -b feature/name

3. Sigue Conventional Commits para los mensajes

4. Abre una pull request

Soporte

• 📖 Documentación

• 🐛 Informar de problemas

• 💬 Comunidad MCP

• 🤖 Google AI Studio — obtén una clave de API de Gemini

Historial de estrellas

Construido con FastMCP, Orama y TypeScript