harness-mcp

Harnessエンジニアリングを念頭に置いた、MCPサーバー構築のための独断的なTypeScriptボイラープレートです。

Harnessエンジニアリングとは、LLMエージェントを取り巻く足場（ツール、説明、エラー、コンテキスト）を設計し、エージェントが実際に正しい動作をするようにするための規律です。ほとんどのMCPボイラープレートはプロトコルを教えるだけですが、これはプロトコルと実践の両方を教えます。

含まれているもの

• defineTool() — 1つのZodスキーマで、MCP SDK、OpenAIの関数呼び出しAPI、およびランタイムハンドラーに供給します。バリデーションとエラーのラップは自動的に行われます。

• 両方のトランスポート — Claude Codeスタイルのローカルクライアント用のstdio (src/index.ts) と、リモート/Webクライアント用のストリーミング可能なHTTP (src/http.ts)。どちらも1つの createServer() を共有します。

• 構造化された AgentError — すべてのエラーには、モデル向けに書かれた code、message、および hint が含まれます（例：「有効なIDを見つけるために、まず items_list を呼び出してください」）。曖昧なエラーはターンを無駄にします。これは型レベルでそれを修正します。

• 本格的な評価ハーネス — Vitestベース。ユニットテストはCIで自由に実行でき、tests/mcp/echo.test.ts はメモリ内トランスポートペアを介してMCPサーバーを通じて実際のOpenAIモデルを駆動し、結果として得られるツール呼び出しトレースをアサートします。

• シンプルなCRUDの例 — items_create / list / read / update / delete に加え、echo ツール。メモリ内ストアを実際のバックエンドに置き換えても、形状は維持されます。

クイックスタート

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

モデル・イン・ザ・ループの評価を実行するには：

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

Claude Codeへの組み込み

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

レイアウト

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

設計思想

1. ツールの説明はプロンプトエンジニアリングである。 すべての説明は USE WHEN ... で始まり、モデルが混同する可能性のある兄弟ツールに対しては DO NOT USE WHEN ... を含めます。スモークテストはこの慣習を強制します。

2. エラーは教えるためのもの。 すべての AgentError は hint フィールドを持ちます。エラーメッセージをエージェントになったつもりで読んでみてください。次に何をすべきか分かりますか？分からなければ、書き直してください。

3. リストエンドポイントはページネーションする。 items_list は { items, nextCursor } を返します。デフォルトの制限は20、ハードキャップは100です。制限のないデータをコンテキストに流し込まないでください。

4. 破壊的操作は dryRun を受け入れる。 items_delete は、確信が持てない場合に何が起こるかを事前に教えてくれます。

5. 1つのZod、3つのコンシューマー。 Zodと並行してJSON Schemaを手動で管理しないでください。defineTool が両方を導出します。

6. 評価はテストである。 ツール呼び出しのトレースはアサート可能です。説明の回帰によってモデルの動作が壊れた場合、テストがそれを検知します。

ライセンス

MIT。