{"type": "text"}

Tarea del Agente MCP

Un sistema MCP (Model Context Protocol) en TypeScript construido para la tarea en MCP_HOMEWORK_SKILL.md: un Host de Agente que carga una Habilidad de Agente (SKILL.md), se conecta a tres servidores MCP a través de los tres transportes requeridos, descubre/agrega sus herramientas, y permite que Gemini seleccione y llame a la herramienta correcta en el servidor correcto.

Arquitectura

                          Agent Host (src/host)
                     skill-loader + connection-manager
                       + tool-bridge + gemini-client
                                 |
              +------------------+------------------+
              |                  |                   |
              v                  v                   v
        stdio server       local HTTP server    public HTTP server
     (src/servers/stdio-  (src/servers/http-   (same http-server.ts,
        server.ts)          server.ts, no auth)   API-key protected)
              |                  |                   |
              +------------------+-------------------+
                                 |
              shared tool logic (src/servers/shared/tools.ts)
       3 tools (calculator, text_stats, unit_convert) + 1 resource + 1 prompt

• src/servers/shared/tools.ts — la implementación única de las 3 herramientas, 1 recurso y 1 prompt, registrados de forma idéntica en cada servidor para que la misma lógica se reutilice en todas partes (sin lógica de negocio duplicada).

• src/servers/stdio-server.ts — MCP sobre stdio (lanzado como proceso hijo).

• src/servers/http-server.ts — MCP sobre HTTP Streamable. El mismo archivo/código exacto ejecuta los servidores "local" y "público"; la única diferencia es la configuración (PORT, PUBLIC_MCP_API_KEY).

• src/host/connection-manager.ts — el Host MCP: se conecta a cada servidor configurado, descubre herramientas/recursos/prompts, asigna a los nombres de las herramientas el espacio de nombres <namespace>__<tool> para evitar colisiones, y envía las llamadas de herramientas de vuelta al servidor propietario.

• src/host/tool-bridge.ts — convierte las herramientas MCP descubiertas en declaraciones de funciones de Gemini.

• src/host/gemini-client.ts — el bucle de llamada a herramientas de Gemini (enviar mensaje → leer llamadas a funciones → enviar a través del gestor de conexiones → enviar respuestas de funciones de vuelta → repetir hasta obtener el texto final).

• src/host/skill-loader.ts — carga SKILL.md y lo inyecta como instrucción de sistema del modelo, de modo que la habilidad da forma activamente al uso de herramientas.

• src/host/agent-host.ts — conecta lo anterior a partir de config/servers.json.

• src/host/cli.ts — punto de entrada de la CLI (interactivo o --demo).

Related MCP server: mcp-tools-server

Configuración

npm install

Los secretos viven en api.env (ya en gitignore):

API_KEY=your-gemini-api-key
# Optional, only needed once you deploy the public server:
# PUBLIC_MCP_URL=https://your-app.onrender.com/mcp
# PUBLIC_MCP_API_KEY=some-strong-random-key

Ejecutar cada componente

Servidor stdio (20 puntos)

npm run server:stdio            # run directly
npm run inspector:stdio         # open MCP Inspector against it

Inspector descubrirá 3 herramientas (calculator, text_stats, unit_convert), 1 recurso (docs://unit-conversions) y 1 prompt (explain-tool-result), y puede ejecutar/leer todos ellos.

Servidor HTTP local

npm run server:http             # listens on http://127.0.0.1:8787/mcp, no auth
npm run inspector:http          # then connect Inspector to that URL

Servidor HTTP público (15 puntos)

El mismo http-server.ts se convierte en el servidor "público" una vez que PUBLIC_MCP_API_KEY está configurada — cada solicitud requiere entonces una cabecera x-api-key coincidente; las claves ausentes o no válidas reciben 401 Unauthorized.

$env:PORT=8788; $env:PUBLIC_MCP_API_KEY="a-strong-secret"; npm run server:http

Desplegándolo públicamente (Render.com, usando el render.yaml incluido):

1. git init && git add -A && git commit -m "MCP homework" y luego haz push a un repositorio de GitHub que poseas.

2. En Render: New + → Blueprint → selecciona el repositorio (lee render.yaml automáticamente), o crea un Web Service manualmente con:

   • Comando de compilación: npm install && npm run build

   • Comando de inicio: npm run start:http

   • Ruta de comprobación de salud: /health

3. En el panel de Render, establece la variable de entorno PUBLIC_MCP_API_KEY a un secreto fuerte (nunca lo confirmes en el repositorio).

4. Una vez desplegado, coloca la URL resultante + clave en api.env: PUBLIC_MCP_URL=https://<your-service>.onrender.com/mcp y PUBLIC_MCP_API_KEY=<mismo secreto>.

5. Valida con Inspector:

   • Sin clave → rechazado: curl -X POST https://<url>/mcp -H "Content-Type: application/json" -d "{...}" devuelve 401.

   • Con clave → funciona: pasa --header "x-api-key: <secreto>" a npx @modelcontextprotocol/inspector --cli <url> --method tools/list.

Host de Agente

npm run agent          # interactive CLI
npm run agent:demo      # runs a scripted set of demo queries

Al iniciarse, el host:

1. Carga SKILL.md como instrucción de sistema.

2. Lee config/servers.json y se conecta al servidor stdio (lanzado automáticamente), al servidor HTTP local (debe estar ya en ejecución) y al servidor HTTP público (se omite automáticamente si PUBLIC_MCP_URL/PUBLIC_MCP_API_KEY no están configuradas — es opcional para que la demo funcione sin un despliegue en vivo).

3. Descubre y asigna espacio de nombres a cada herramienta, se las entrega a Gemini y envía cada llamada de herramienta que Gemini hace al servidor MCP correcto.

Configuración

El registro de servidores se basa en datos a través de config/servers.json — añade/elimina servidores allí en lugar de editar el código del host. ${VAR} en una url se resuelve desde process.env en el momento de la conexión; apiKeyEnv nombra la variable de entorno cuyo valor se envía como x-api-key.

Habilidad del Agente

SKILL.md instruye al agente a preferir llamar a las herramientas en lugar de adivinar en aritmética/conversiones/estadísticas de texto, a elegir una herramienta con espacio de nombres por solicitud lógica, a consultar el recurso docs://unit-conversions cuando no esté seguro sobre las conversiones admitidas, y a explicar los resultados en lenguaje sencillo. Se carga textualmente en la instrucción de sistema de Gemini en cada ejecución (ver src/host/skill-loader.ts), por lo que sus reglas afectan directamente a la selección de herramientas y al estilo de respuesta — observable en la salida de la demo (p. ej., el agente siempre llama a una herramienta para la aritmética en lugar de calcularla él mismo).

Notas de seguridad

• No se confirman secretos; api.env está en gitignore y el servidor público solo lee PUBLIC_MCP_API_KEY del entorno.

• El servidor HTTP público rechaza cualquier solicitud sin una cabecera x-api-key coincidente (401), y acepta solicitudes una vez que se proporciona una clave válida.