Backbone.js Documentation 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:
• GitHub:

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.