MCP Documentation Server

Un servidor para la gestión de documentos y búsqueda semántica utilizando embeddings de IA, con almacenamiento local en JSON.

GitHub

342

Prueba este MCPPatrocinado

Documentación

Servidor de Documentación MCP

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

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 tu navegador. Cada herramienta MCP también está expuesta como una API REST, brindando a los agentes de IA una interfaz ligera y sin esquemas.

🏠 Funciona completamente 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 — similitud de texto completo + vectorial con fragmentación padre-hijo
🤖 Búsqueda de IA opcional — Google Gemini para análisis avanzado de documentos (trae tu propia clave)
📁 Subidas por arrastrar y soltar — soporte para .txt, .md, .pdf
📦 Publicado en el Registro MCP — instalable vía npx, sin necesidad de clonar

Inicio rápido

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

Abre tu navegador en http://localhost:3080 — la interfaz web se inicia automáticamente.

🤖 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 http://127.0.0.1:3080/api/. 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 respuesta entra.

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}'

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

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

Flujo de trabajo básico

Añade documentos usando add_document o coloca archivos .txt / .md / .pdf en la carpeta de subidas y llama a process_uploads.
Busca en todo con search_all_documents, o dentro de un solo documento con search_documents.
Usa get_context_window para obtener fragmentos vecinos y dar al LLM un contexto más amplio.

Interfaz web

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

📊 Panel — vista 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 todo — búsqueda semántica en todos los documentos
🎯 Buscar en documento — búsqueda dentro de un documento específico
🤖 Búsqueda de IA — análisis impulsado por Gemini (si GEMINI_API_KEY está configurado)
📁 Subir archivos — arrastra y suelta archivos y procésalos en la base de conocimiento
🪟 Ventana de contexto — explora fragmentos alrededor de un índice específico

Configurar un cliente MCP

Mínimo

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

Con variables de entorno (todas opcionales)

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/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

Herramienta	Descripción
`add_document`	Añade un documento (título, contenido, metadatos opcionales)
`list_documents`	Lista todos los documentos con metadatos y vista previa del contenido
`get_document`	Recupera el contenido completo de un documento por ID
`delete_document`	Elimina un documento, sus fragmentos, entradas de base de datos y archivos asociados

📁 Procesamiento de archivos

Herramienta	Descripción
`process_uploads`	Procesa todos los archivos en la carpeta de subidas (fragmentación + embeddings)
`get_uploads_path`	Devuelve la ruta absoluta a la carpeta de subidas
`list_uploads_files`	Lista archivos en la carpeta de subidas con información de tamaño y formato
`get_ui_url`	Devuelve la URL de la interfaz web (p. ej., http://localhost:3080) — útil para abrir el panel o localizar la carpeta de subidas desde el navegador

🔍 Búsqueda

Herramienta	Descripción
`search_documents`	Búsqueda vectorial semántica dentro de un documento específico
`search_all_documents`	Búsqueda híbrida (texto completo + vectorial) entre documentos
`get_context_window`	Devuelve una ventana de fragmentos alrededor de un índice de fragmento dado
`search_documents_with_ai`	🤖 Búsqueda impulsada por IA usando Gemini (requiere `GEMINI_API_KEY`)

Configuración

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

Variable	Predeterminado	Descripción
`MCP_BASE_DIR`	`~/.mcp-documentation-server`	Directorio base para el almacenamiento de datos
`MCP_EMBEDDING_MODEL`	`Xenova/all-MiniLM-L6-v2`	Nombre del modelo de embeddings
`GEMINI_API_KEY`	—	Clave API de Google Gemini (habilita `search_documents_with_ai`)
`MCP_CACHE_ENABLED`	`true`	Habilita/deshabilita la caché de embeddings LRU
`START_WEB_UI`	`true`	Establecer a `false` para deshabilitar la interfaz web integrada
`WEB_HOST`	`127.0.0.1`	Dirección de enlace para la interfaz web (usa `0.0.0.0` para exponer en todas las interfaces)
`WEB_PORT`	`3080`	Puerto para la interfaz web
`MCP_STREAMING_ENABLED`	`true`	Habilita lecturas en streaming para archivos grandes
`MCP_STREAM_CHUNK_SIZE`	`65536`	Tamaño del búfer de streaming en bytes (64KB)
`MCP_STREAM_FILE_SIZE_LIMIT`	`10485760`	Umbral para cambiar a streaming (10MB)

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

Configura mediante MCP_EMBEDDING_MODEL:

Modelo	Dimensiones	Notas
`Xenova/all-MiniLM-L6-v2`	384	Predeterminado — rápido, buena calidad
`Xenova/paraphrase-multilingual-mpnet-base-v2`	768	Recomendado — mejor calidad, multilingüe

Los modelos se descargan en el primer uso (~80–420 MB). La dimensión del vector se determina automáticamente desde el 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 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 metadatos/contenido de documentos, una para fragmentos hijos con embeddings vectoriales, y una para fragmentos padres (secciones de contexto). Todas se persisten en archivos binarios en disco y se restauran al inicio.
IntelligentChunker implementa el patrón de fragmentación padre-hijo: los documentos se dividen primero en fragmentos padres grandes que preservan el contexto completo (secciones, párrafos), luego cada padre se divide en fragmentos hijos pequeños para una búsqueda vectorial precisa. En el momento de la consulta, los resultados se deduplican por padre para que el LLM reciba tanto el fragmento coincidente como el contexto más amplio.
EmbeddingProvider carga de forma diferida un modelo Transformers.js para inferencia local — sin necesidad de llamadas API.

Desarrollo

git clone https://github.com/andrea9293/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

Haz un fork del repositorio
Crea una rama de características: git checkout -b feature/name
Sigue Conventional Commits para los mensajes
Abre una solicitud de extracción

Licencia

MIT — consulta LICENSE

Soporte

📖 Documentación
🐛 Reportar problemas
💬 Comunidad MCP
🤖 Google AI Studio — obtén una clave API de Gemini

Historial de estrellas

Construido con FastMCP, Orama y TypeScript