docs2mcp

{"type": "text"}# docs2mcp

Convierte un directorio de archivos Markdown, HTML o TXT en un servidor MCP remoto de solo lectura al que cualquier cliente o agente MCP compatible pueda conectarse para recuperar documentación. Esto incluye AskMesh, integraciones de Claude, Codex y clientes MCP personalizados.

Inicio rápido

uvx docs2mcp serve ./docs \
  --base-url https://docs.example.com/docs \
  --host 0.0.0.0 \
  --port 8765

uvx crea un entorno aislado desde PyPI y ejecuta la CLI publicada de docs2mcp sin necesidad de instalación manual. Para desarrollo local desde un checkout, usa python -m docs2mcp.runtime en su lugar.

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --watch \
  --sync-interval 30

Habilita la sincronización incremental con vigilancia de archivos y reconciliación periódica:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --allowed-host 'docs.example.com:*'

El primer inicio escanea todo el directorio. Los cambios posteriores se aplican por documento: los archivos nuevos se insertan, los modificados se reindexan, los eliminados se quitan y los sin cambios se omiten. El vigilante usa una ventana de debounce corta y el escaneo periódico proporciona un respaldo para sistemas de archivos que no emiten eventos de manera confiable.

Al vincularse a una dirección pública específica con protección contra rebinding de DNS habilitada, permite explícitamente la cabecera Host entrante:

{
  "endpoint": "http://127.0.0.1:8765/mcp",
  "auth_type": "none",
  "token": null,
  "search_tool": "search_docs",
  "read_tool": "get_document",
  "contract_version": "agent-qa.docs/v1"
}

Usa el mismo intérprete de Python para la instalación y el inicio. docs2mcp requiere el SDK oficial de MCP para Python mcp>=1.27.0,<2; un paquete más antiguo o no relacionado llamado mcp no proporciona mcp.server.fastmcp.

El comando heredado doc2mcp sigue disponible como alias de compatibilidad.

El proceso imprime la configuración de conexión MCP al inicio. La autenticación es opcional: pasa --token para habilitar la autenticación Bearer, u omítelo para ejecutarlo sin autenticación.

{
  "endpoint": "http://127.0.0.1:8765/mcp",
  "auth_type": "none",
  "token": null,
  "search_tool": "search_docs",
  "read_tool": "get_document",
  "contract_version": "agent-qa.docs/v1"
}

Introduce los valores de endpoint, modo de autenticación, search_docs y get_document en la configuración de tu cliente MCP. Cuando auth_type sea none, selecciona sin autenticación y deja el token vacío. Los clientes que soporten Streamable HTTP pueden conectarse al mismo endpoint sin un adaptador específico de AskMesh.

GET /readyz informa el recuento de documentos y los últimos contadores de sincronización, incluidos añadidos, actualizados, eliminados, omitidos, fallidos, duración y el último error.

Related MCP server: Synapse

Formatos admitidos

El MVP admite .md, .markdown, .txt, .html y .htm. La indexación usa SQLite FTS5, por lo que no se requiere una base de datos vectorial separada.

Contrato MCP

El servidor implementa el contrato de documentos interoperable agent-qa.docs/v1 y expone dos herramientas de solo lectura:

• search_docs(query, limit): devuelve route, title, url, snippet y score.

• get_document(route, max_characters): devuelve el contenido del documento, secciones y una URL de cita.

search_docs.query usa sintaxis SQLite FTS5. El espacio en blanco es una consulta AND, OR coincide con cualquiera de los términos, el texto entre comillas busca una frase exacta, NOT excluye un término y * habilita la coincidencia de prefijos. No es búsqueda semántica en lenguaje natural; los clientes deben mostrar esta sintaxis a los usuarios.

Conéctate desde cualquier cliente MCP

Usa el endpoint Streamable HTTP y los dos nombres de herramientas en cualquier cliente que admita conexiones MCP remotas. AskMesh es una integración compatible; los clientes basados en Claude, Codex y agentes personalizados pueden usar el mismo endpoint y contrato de solo lectura.

Limitaciones actuales

Esta versión es un MVP de un solo host: los documentos se importan desde un directorio local y el índice se almacena en SQLite. La sincronización con Git, el análisis de PDF, el almacenamiento de objetos, la búsqueda vectorial y un plano de control multiinquilino están planificados para versiones posteriores.