harness-mcp

Ein meinungsstarkes TypeScript-Boilerplate für die Erstellung von MCP-Servern mit Fokus auf Harness Engineering.

Harness Engineering ist die Disziplin, das Gerüst um einen LLM-Agenten herum zu entwerfen – Tools, Beschreibungen, Fehler, Kontext –, damit der Agent tatsächlich das Richtige tut. Die meisten MCP-Boilerplates bringen einem das Protokoll bei. Dieses hier bringt einem das Protokoll und die Praxis bei.

Was ist enthalten

• defineTool() — ein Zod-Schema speist das MCP-SDK, die Function-Calling-API von OpenAI und den Runtime-Handler. Validierung und Fehler-Wrapping erfolgen automatisch.

• Beide Transporte — stdio (src/index.ts) für lokale Clients im Claude-Code-Stil, Streamable HTTP (src/http.ts) für Remote-/Web-Clients. Beide teilen sich ein createServer().

• Strukturierte AgentErrors — jeder Fehler hat einen code, eine message und einen hint, der für das Modell geschrieben wurde: "call items_list first to find a valid id." Vage Fehlermeldungen verschwenden Turns; dies behebt das auf Type-Ebene.

• Ein echtes Eval-Harness — Vitest-basiert. Unit-Tests laufen frei in der CI; tests/mcp/echo.test.ts steuert ein echtes OpenAI-Modell durch den MCP-Server über ein In-Memory-Transportpaar und führt Assertions auf dem resultierenden Tool-Call-Trace durch.

• Ein einfaches CRUD-Beispiel — items_create / list / read / update / delete plus ein echo-Tool. Ersetzen Sie den In-Memory-Speicher durch Ihr echtes Backend; behalten Sie die Struktur bei.

Schnellstart

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

Um die Model-in-the-Loop-Evals auszuführen:

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

In Claude Code einbinden

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

Layout

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

Die Meinungen

1. Tool-Beschreibungen sind Prompt Engineering. Jede Beschreibung beginnt mit USE WHEN ... und enthält DO NOT USE WHEN ... für verwandte Tools, mit denen das Modell dieses verwechseln könnte. Der Smoke-Test erzwingt diese Konvention.

2. Fehler lehren. Jeder AgentError enthält ein hint-Feld. Lesen Sie Ihre Fehlermeldungen, als wären Sie der Agent – wüssten Sie, was als Nächstes zu tun ist? Wenn nicht, schreiben Sie sie um.

3. Listen-Endpunkte paginieren. items_list gibt { items, nextCursor } zurück. Standardlimit 20, hartes Limit 100. Schütten Sie keine unbegrenzten Daten in den Kontext.

4. Destruktive Operationen akzeptieren dryRun. items_delete sagt Ihnen, was passieren würde, wenn Sie sich nicht sicher sind.

5. Ein Zod, drei Konsumenten. Pflegen Sie JSON-Schema nicht manuell neben Zod – defineTool leitet beides ab.

6. Evals sind Tests. Tool-Call-Traces sind assertierbar. Wenn eine Regression in der Beschreibung das Verhalten des Modells beeinträchtigt, fängt Ihr Test dies ab.

Lizenz

MIT.