elegroag/backbone-mcp-server

MCP Server: Recursos Markdown de Backbone.js

Servidor MCP (Model Context Protocol) que expone capítulos Markdown de Backbone.js como recursos legibles y añade una tool para búsqueda full‑text sobre dichos capítulos.

Autoría

• name: Edwin Andrés Legro Agudelo
• email: elegroag@estudiante.ibero.edu.co
• GitHub: https://github.com/elegroag

Características

• Recursos por capítulo: cada capítulo Markdown se registra como recurso MCP con nombre y URI estable (backbone://chapter/NN).
• Lectura de contenidos: devuelve el texto plano del capítulo solicitado.
• Búsqueda: tool search-backbone que busca texto en todos los capítulos y devuelve enlaces a los recursos con coincidencias y un extracto.
• Tipado y validación: Zod (v3) para validar argumentos de tools.

Arquitectura

• src/server.ts: arranque del servidor MCP, registro de recursos y tool search-backbone.
• src/mcp-server.ts: utilidades para listar recursos (listResources), leer contenido (readResource) y buscar (searchResources).
• src/markdown-reader.ts: lectura/normalización de archivos Markdown.
• src/types.ts: tipos compartidos (por ejemplo, resultados de búsqueda).
• docs/: capítulos Markdown de Backbone.js.

Requisitos

• Node.js 18+ (recomendado 20+)
• pnpm

Instalación

pnpm install
pnpm build

Ejecución

• Modo desarrollo (STDIO):

pnpm start

Esto lanza tsx ./src/server.ts y expone el servidor por STDIO.

• Con MCP Inspector (UI web) usando STDIO del servidor:

npx @modelcontextprotocol/inspector npx -y tsx ./src/server.ts

Abre el navegador con el Inspector. Desde ahí podrás listar recursos y ejecutar tools.

Recursos expuestos

• Por cada capítulo detectado en docs/:
  • Nombre: backbone-chapter-NN
  • URI: backbone://chapter/NN
  • mimeType: text/markdown (o el deducido por el lector)
• Lectura (readResource): devuelve { contents: [{ uri, text }] } con el contenido del capítulo.

Tools

search-backbone

• title: "Buscar en capítulos Backbone"
• description: Busca texto en los capítulos Markdown y devuelve enlaces a los capítulos con coincidencias.
• inputSchema:
  • query: string (mín. 2)
  • caseSensitive?: boolean
  • maxExcerpts?: number (1–5)
• respuesta:
  • content: lista con un bloque text (resumen) y múltiples resource_link hacia backbone://chapter/NN con un primer extracto como description.

Ejemplo de llamada (Inspector)

• Tool: search-backbone
• Arguments:

{
  "query": "modelo",
  "caseSensitive": false,
  "maxExcerpts": 3
}

Desarrollo

• Compilar TypeScript:

pnpm build

• Ejecutar pruebas manuales desde Inspector o cualquier cliente MCP compatible.
• Configuración TS relevante (tsconfig.json):
  • module: nodenext, strict: true, skipLibCheck: true.

Solución de problemas

• Error MCP error -32603: keyValidator._parse is not a function:
  • Causa: incompatibilidad entre Zod v4 y el SDK/zod-to-json-schema.
  • Solución aplicada: Zod fijado a v3 ("zod": "^3.23.8").
  • Ejecuta pnpm install && pnpm build tras el cambio.

Scripts

• pnpm build — compila TypeScript a dist/.
• pnpm start — ejecuta el servidor MCP por STDIO con tsx.

Buenas prácticas aplicadas

• Diseño modular: separación en server, services/utils (mcp-server.ts), readers, y types.
• Validación a nivel de borde (Zod v3) para inputs de tools.
• Código limpio y responsabilidad única por módulo.

Licencia

• MIT. Ver LICENSE.