harness-mcp

Un boilerplate de TypeScript con opinión propia para crear servidores MCP teniendo en mente la ingeniería de arnés (harness engineering).

La ingeniería de arnés es la disciplina de diseñar el andamiaje alrededor de un agente LLM —herramientas, descripciones, errores, contexto— para que el agente realmente haga lo correcto. La mayoría de los boilerplates de MCP te enseñan el protocolo. Este te enseña el protocolo y la práctica.

¿Qué incluye?

• defineTool() — un esquema de Zod alimenta al SDK de MCP, a la API de llamadas a funciones de OpenAI y al manejador en tiempo de ejecución. La validación y el envoltorio de errores son automáticos.

• Ambos transportes — stdio (src/index.ts) para clientes locales al estilo de Claude Code, HTTP transmitible (src/http.ts) para clientes remotos/web. Ambos comparten un único createServer().

• AgentErrors estructurados — cada error tiene un code, un message y una hint escrita para el modelo: "llama a items_list primero para encontrar un id válido". Los errores vagos desperdician turnos; esto lo soluciona a nivel de tipo.

• Un arnés de evaluación real — basado en Vitest. Las pruebas unitarias se ejecutan libremente en CI; tests/mcp/echo.test.ts dirige un modelo real de OpenAI a través del servidor MCP mediante un par de transporte en memoria y realiza aserciones sobre el rastro de llamadas a herramientas resultante.

• Un ejemplo simple de CRUD — items_create / list / read / update / delete además de una herramienta echo. Reemplaza el almacenamiento en memoria con tu backend real; mantén la estructura.

Inicio rápido

bun install
bun test              # unit tests, no API key needed
bun run start         # stdio server on stdin/stdout
bun run start:http    # HTTP server on http://localhost:3000/mcp

Para ejecutar las evaluaciones con el modelo en el bucle:

cp .env.example .env
# add OPENAI_API_KEY
bun run test:mcp

Conectar a Claude Code

{
  "mcpServers": {
    "harness-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/harness/mcp/src/index.ts"]
    }
  }
}

Estructura

src/
  index.ts              stdio entry
  http.ts               streamable-http entry
  core/
    server.ts           createServer() — shared by both transports
    tool.ts             defineTool() wrapper
    errors.ts           AgentError
    store.ts            replace with your backend
  tools/
    echo.ts             smoke-test tool
    items-*.ts          CRUD example tools
    index.ts            registry

tests/
  unit/                 fast, no API key
    tool.test.ts
    store.test.ts
  mcp/                  protocol + model-in-the-loop
    setup.ts            in-memory client + runWithModel() helper
    smoke.test.ts       no model
    echo.test.ts        gpt-4o-mini, skipped without OPENAI_API_KEY

Las opiniones

1. Las descripciones de las herramientas son ingeniería de prompts. Cada descripción comienza con USE WHEN ... (USAR CUANDO...) e incluye DO NOT USE WHEN ... (NO USAR CUANDO...) para herramientas hermanas con las que el modelo podría confundirla. La prueba de humo impone la convención.

2. Los errores enseñan. Cada AgentError lleva un campo hint. Lee tus mensajes de error como si fueras el agente: ¿sabrías qué hacer a continuación? Si no, reescríbelo.

3. Los endpoints de lista se paginan. items_list devuelve { items, nextCursor }. Límite predeterminado 20, límite máximo 100. No vuelques datos ilimitados en el contexto.

4. Las operaciones destructivas aceptan dryRun. items_delete te dirá qué sucedería si no estuvieras seguro.

5. Un Zod, tres consumidores. No mantengas el esquema JSON a mano junto con Zod: defineTool deriva ambos.

6. Las evaluaciones son pruebas. Los rastros de llamadas a herramientas son comprobables. Cuando una regresión en la descripción rompe el comportamiento del modelo, tu prueba lo detecta.

Licencia

MIT.