README.md•3.62 kB
# 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
```bash
pnpm install
pnpm build
```
## Ejecución
- Modo desarrollo (STDIO):
```bash
pnpm start
```
Esto lanza `tsx ./src/server.ts` y expone el servidor por STDIO.
- Con MCP Inspector (UI web) usando STDIO del servidor:
```bash
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:
```json
{
"query": "modelo",
"caseSensitive": false,
"maxExcerpts": 3
}
```
## Desarrollo
- Compilar TypeScript:
```bash
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`.