MCP Sphinx Docs

Un servidor MCP (Model Context Protocol) que convierte documentación de Sphinx a Markdown optimizado para consumo por LLMs.

🚀 Instalación y uso rápido

Como herramienta de línea de comandos

# Convertir documentación desde una URL
npx @zk-armor/mcp-sphinx-docs convert-url https://btrfs.readthedocs.io/en/latest/ ./converted-docs

# Convertir archivos locales
npx @zk-armor/mcp-sphinx-docs convert-local ./docs ./markdown-docs

Como servidor MCP

Agrega a tu configuración MCP (ej. Claude Desktop):

{
  "mcpServers": {
    "mcp-sphinx-docs": {
      "command": "npx",
      "args": ["@zk-armor/mcp-sphinx-docs"]
    }
  }
}

Related MCP server: Documentation MCP Server

🚀 Características

• Conversión RST a Markdown: Convierte archivos reStructuredText de Sphinx a Markdown limpio

• Optimización para LLMs: Aplica transformaciones específicas para mejorar el consumo por modelos de lenguaje

• Procesamiento por lotes: Convierte directorios completos de documentación

• Chunking inteligente: Divide documentos grandes en chunks apropiados para LLMs

• Preservación de referencias: Mantiene enlaces internos y referencias cruzadas

• Análisis de estructura: Analiza la estructura de proyectos Sphinx

📦 Instalación

Como dependencia local

npm install
npm run build

Como paquete global (para usar con npx)

npm install -g .
# O directamente desde este directorio:
npm link

🛠️ Uso

Como servidor MCP

El servidor MCP proporciona las siguientes herramientas:

1. convert_sphinx_file

Convierte un archivo RST individual a Markdown.

Parámetros:

• sourcePath (string, requerido): Ruta al archivo RST

• outputPath (string, opcional): Ruta de salida para el archivo Markdown

• options (object, opcional):

  • optimize (boolean, default: true): Aplicar optimizaciones para LLM

  • chunkSize (number, default: 4000): Tamaño máximo de chunk

  • preserveReferences (boolean, default: true): Preservar referencias internas

2. convert_sphinx_directory

Convierte un directorio completo de documentación Sphinx.

Parámetros:

• sourcePath (string, requerido): Ruta al directorio de documentación Sphinx

• outputPath (string, requerido): Directorio de salida para archivos Markdown

• options (object, opcional):

  • recursive (boolean, default: true): Procesar subdirectorios

  • optimize (boolean, default: true): Aplicar optimizaciones para LLM

  • chunkSize (number, default: 4000): Tamaño máximo de chunk

  • preserveStructure (boolean, default: true): Preservar estructura de directorios

3. analyze_sphinx_structure

Analiza la estructura de un proyecto de documentación Sphinx.

Parámetros:

• sourcePath (string, requerido): Ruta al directorio de documentación

• depth (number, default: 3): Profundidad máxima de análisis

Como CLI (futuro)

# Convertir un archivo
npx sphinx-to-llm-markdown convert file.rst output.md

# Convertir un directorio
npx sphinx-to-llm-markdown convert ./docs ./markdown-docs

# Analizar estructura
npx sphinx-to-llm-markdown analyze ./docs

🏗️ Arquitectura

src/
├── index.ts              # Servidor MCP principal
├── converters/
│   └── sphinx-converter.ts  # Lógica de conversión RST → Markdown
├── optimizers/
│   └── llm-optimizer.ts     # Optimizaciones específicas para LLMs
└── utils/
    └── file-handler.ts      # Utilidades para manejo de archivos

Componentes principales

• SphinxConverter: Parsea RST y convierte a Markdown

  • Maneja directivas Sphinx (toctree, note, warning, etc.)

  • Convierte referencias cruzadas

  • Preserva estructura de documentos

• LLMOptimizer: Optimiza el Markdown para LLMs

  • Simplifica estructura (máximo 4 niveles de headers)

  • Elimina redundancias

  • Añade contexto a secciones

  • Implementa chunking inteligente

• FileHandler: Maneja operaciones de archivos

  • Búsqueda recursiva de archivos RST

  • Análisis de estructura de directorios

  • Operaciones de E/S con manejo de errores

🧪 Ejemplo de uso

Probar con documentación BTRFS

# Clonar la documentación de BTRFS (ejemplo)
git clone https://github.com/kdave/btrfs-progs.git
cd btrfs-progs/Documentation

# Usar el servidor MCP para convertir
# (desde el cliente MCP, como Claude Desktop)

Estructura de entrada típica (Sphinx)

docs/
├── conf.py
├── index.rst
├── introduction.rst
├── features/
│   ├── compression.rst
│   └── snapshots.rst
└── _static/

Estructura de salida (Markdown optimizado)

markdown-docs/
├── index.md
├── introduction.md
└── features/
    ├── compression.md
    └── snapshots.md

🔧 Configuración para VS Code

El proyecto incluye configuración para depurar el servidor MCP:

1. .vscode/mcp.json: Configuración del servidor MCP

2. .vscode/tasks.json: Tareas de build y watch

3. .github/copilot-instructions.md: Instrucciones para GitHub Copilot

Depuración

# Compilar en modo watch
npm run watch

# En otra terminal, ejecutar el servidor
npm start

📝 Formatos soportados

Entrada (RST/Sphinx)

• ✅ Headers con subrayado (=, -, ~, etc.)

• ✅ Listas con bullets y numeración

• ✅ Bloques de código con ::

• ✅ Directivas básicas (note, warning, tip)

• ✅ Referencias doc (:doc:reference`)

• ✅ Referencias internas (:ref:reference`)

• ✅ Enlaces externos

• ✅ Énfasis y texto fuerte

• ⚠️ Tablas simples

• ⚠️ Autodoc (básico)

Salida (Markdown optimizado)

• ✅ Headers normalizados (máximo 4 niveles)

• ✅ Listas con bullets consistentes

• ✅ Bloques de código con hints de lenguaje

• ✅ Blockquotes para notas/warnings

• ✅ Enlaces con texto descriptivo

• ✅ Separadores de sección

• ✅ Contexto agregado para secciones profundas

🛣️ Roadmap

Fase actual: MVP ✅

• Conversión básica RST → Markdown

• Servidor MCP funcional

• Optimizaciones básicas para LLM

• Manejo de archivos y directorios

Próximas características

• CLI independiente

• Soporte mejorado para tablas complejas

• Procesamiento de autodoc más sofisticado

• Configuración personalizable

• Tests automatizados

• Publicación en NPM

Futuro

• Soporte para otros formatos de documentación

• Integración con APIs de LLM para validación

• Dashboard web para conversiones

• Plugins para diferentes frameworks de documentación

🤝 Contribución

1. Fork el proyecto

2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)

3. Commit tus cambios (git commit -m 'Add amazing feature')

4. Push a la rama (git push origin feature/amazing-feature)

5. Abre un Pull Request

📄 Licencia

ISC License - ver archivo LICENSE para detalles.

🔗 Enlaces útiles

• Model Context Protocol

• Sphinx Documentation

• reStructuredText Primer

• BTRFS Documentation (ejemplo de prueba)