Aprende TypeScript MCP

Monorepo de aprendizaje para el SDK de TypeScript del Model Context Protocol, construido sobre los workspaces de Bun. Cada tema de aprendizaje vive en su propia aplicación dentro de apps/ — los nuevos temas obtienen un nuevo workspace apps/<topic>.

Para instalar las dependencias de todos los workspaces:

bun install

Aplicación Weather (apps/weather/) — NestJS + MCP

Sigue los tutoriales oficiales del MCP TypeScript SDK "Build your first server" / "Build your first client", usando la API meteorológica real de NWS — alojada dentro de una aplicación NestJS.

• apps/weather/src/main.ts — arranque HTTP de Nest (puerto 3000, bodyParser: false)

• apps/weather/src/stdio.ts — punto de entrada stdio (contexto de aplicación Nest, logger deshabilitado para que stdout permanezca solo con el protocolo)

• apps/weather/src/weather/weather.service.ts — llamadas a la API de NWS (getActiveAlertHeadlines, getForecastPeriods)

• apps/weather/src/weather/weather-mcp.service.ts — construye el McpServer, registra get-alerts / get-forecast, posee el transporte HTTP compartido

• apps/weather/src/weather/mcp.controller.ts — enruta cada método en /mcp hacia el transporte MCP

• apps/weather/src/weather/express-web-bridge.ts — convierte Express req/res ↔ Request/Response estándar web (el transporte v2 del SDK es solo estándar web)

• apps/weather/client.ts — cliente de ejemplo (genera el servidor stdio por sí mismo)

• apps/weather/test/mcp-http.test.ts — bun test arranca la aplicación Nest en un puerto efímero y conecta un cliente MCP HTTP transmisible real

• tutorial/weather-server.ts — shim de compatibilidad para clientes que aún apuntan a la ruta anterior al monorepo (p. ej. una conexión guardada de MCP Inspector); seguro de eliminar una vez que nada lo referencie

Ambas herramientas declaran valores default en sus esquemas de entrada por conveniencia de desarrollo — Inspector rellena su formulario con ellos (state: CA, latitud/longitud: San Francisco), para que puedas pulsar "Run Tool" sin escribir. Los llamadores que pasan sus propios argumentos los anulan; los valores predeterminados solo se aplican cuando se omite un argumento.

Ejecutar el servidor stdio

Cada cliente que se conecta (Claude Code, Inspector, client.ts) genera su propia copia privada de este proceso — no es un servidor compartido.

bun run weather:stdio

Ejecutar el servidor HTTP

Un proceso compartido al que los clientes se conectan a través de la red. Si matas esta terminal, cada cliente conectado pierde la conexión inmediatamente.

bun run weather:http

Ejecutar el cliente de ejemplo

bun run weather:client

Ejecutar las pruebas / typecheck

bun test          # from apps/weather/ (or the repo root)
bun run typecheck # from the repo root — tsc over both apps

Related MCP server: MCP Test Server

Asistente de impuestos (apps/tax-assistant/)

Servidor MCP stdio mínimo con una única herramienta calculate-vat (IVA tailandés 7%):

bun run tax:stdio

Base de conocimiento (apps/knowledge-base/)

Servidor persistente de notas con etiquetas respaldado por bun:sqlite (apps/knowledge-base/src/db.ts, apps/knowledge-base/src/notes.ts). A diferencia de weather/tax-assistant, esta aplicación ejercita las tres primitivas de MCP:

• Herramientas (acciones que un cliente llama explícitamente): add-note, get-note, search-notes, list-notes, delete-note, add-tags, list-tags

• Recursos (datos que un cliente puede traer al contexto sin una llamada de herramienta): kb://notes (índice JSON de cada nota) y la plantilla kb://notes/{id} (una nota como markdown)

• Prompts (plantillas de mensaje reutilizables que un cliente puede mostrar como elemento de menú): summarize-notes-by-tag, que incrusta el contenido de las notas coincidentes en el prompt generado

El archivo SQLite (apps/knowledge-base/knowledge-base.sqlite, más sus sidecars -wal/-shm) se crea en la primera ejecución y está en gitignore — cada clon comienza con una base de conocimiento vacía.

bun run kb:stdio

Inspeccionar/probar con MCP Inspector

bunx @modelcontextprotocol/inspector

Abre una interfaz de navegador (proxy en el puerto 6277, UI en el puerto 6274). En la barra lateral, conéctalo de cualquiera de las dos maneras:

• stdio: Tipo de transporte STDIO, Comando bun, Args apps/weather/src/stdio.ts

• HTTP: Tipo de transporte Streamable HTTP, URL http://localhost:3000/mcp — requiere que el servidor HTTP (bun run weather:http) ya esté en ejecución

Inspector recuerda tu última conexión usada en el navegador y se reconecta automáticamente con ella al cargar/refrescar — siempre verifica el Tipo de transporte/URL de la barra lateral antes de asumir a qué está realmente conectado.

Para cambiar entre los servidores stdio de este repositorio sin volver a escribir Comando/Args cada vez, usa mcp.inspector.json (misma forma de mcpServers que .mcp.json):

bunx @modelcontextprotocol/inspector --config mcp.inspector.json --server knowledge-base
# or --server weather / --server tax-assistant

No hay un menú desplegable en la UI para cambiar de servidores desde un archivo de configuración — elegir uno diferente significa relanzar con un valor --server distinto.

Inspeccionar varios servidores a la vez

Una instancia de Inspector se conecta exactamente a un servidor. Para inspeccionar dos o tres al mismo tiempo, ejecuta instancias separadas en puertos separados (CLIENT_PORT/SERVER_PORT) y abre cada una en su propia pestaña del navegador:

# terminal 1
CLIENT_PORT=6274 SERVER_PORT=6277 bunx @modelcontextprotocol/inspector --config mcp.inspector.json --server weather

# terminal 2
CLIENT_PORT=6280 SERVER_PORT=6281 bunx @modelcontextprotocol/inspector --config mcp.inspector.json --server tax-assistant

# terminal 3
CLIENT_PORT=6282 SERVER_PORT=6283 bunx @modelcontextprotocol/inspector --config mcp.inspector.json --server knowledge-base

Cada una abre su UI en su propio puerto (http://localhost:6274, :6280, :6282) — dejar CLIENT_PORT/SERVER_PORT sin establecer en más de una instancia chocará con los valores predeterminados 6274/6277.

Si obtienes PORT IS IN USE en 6274/6277, una instancia anterior de Inspector no se cerró limpiamente (puede dejar su proceso proxy huérfano incluso después de informar un fallo). Encuéntralo y mátalo antes de reintentar:

lsof -nP -iTCP:6274,6277 -sTCP:LISTEN
kill <PID>

Conectar a Claude Code

.mcp.json registra el servidor weather, apuntando al transporte HTTP — inicia el servidor Nest (bun run weather:http) tú mismo antes de abrir una sesión de Claude Code aquí, o /mcp lo mostrará desconectado.

Notas sobre NestJS en Bun

• No hay paso de compilación nest-cli/webpack — Bun ejecuta los puntos de entrada TypeScript directamente (bun src/main.ts).

• tsconfig.json habilita experimentalDecorators + emitDecoratorMetadata; el transpilador de Bun respeta ambos, lo que hace que la inyección de constructores de Nest funcione.

• Nest todavía usa su adaptador Express internamente; solo el runtime y el gestor de paquetes son Bun.