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

Ejecución

• Modo desarrollo (STDIO):

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

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

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:

Desarrollo

• Compilar TypeScript:

• 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.