harness-mcp

一个以**工程化约束（harness engineering）**为核心理念构建 MCP 服务器的 TypeScript 样板。

工程化约束是一门围绕 LLM 代理设计脚手架（工具、描述、错误、上下文）的学科，旨在确保代理能够真正执行正确的操作。大多数 MCP 样板只教你协议，而这个样板既教你协议，也教你实践。

包含内容

• defineTool() — 一个 Zod 模式即可同时服务于 MCP SDK、OpenAI 函数调用 API 和运行时处理器。验证和错误包装均为自动完成。

• 两种传输方式 — 用于 Claude Code 风格本地客户端的 stdio (src/index.ts)，以及用于远程/Web 客户端的可流式 HTTP (src/http.ts)。两者共享同一个 createServer()。

• 结构化的 AgentError — 每个错误都包含一个 code、一个 message 和一个专门为模型编写的 hint（提示）：例如“请先调用 items_list 以获取有效的 ID”。模糊的错误会浪费轮次；此方案在类型层面解决了该问题。

• 真实的评估工具（eval harness） — 基于 Vitest。单元测试可在 CI 中自由运行；tests/mcp/echo.test.ts 通过内存传输对，驱动真实的 OpenAI 模型调用 MCP 服务器，并对生成的工具调用轨迹进行断言。

• 简单的 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. 工具描述即提示工程（Prompt Engineering）。 每个描述都以 USE WHEN ... 开头，并包含 DO NOT USE WHEN ...，以区分模型可能混淆的同类工具。冒烟测试强制执行此约定。

2. 错误即教学。 每个 AgentError 都携带一个 hint 字段。请以代理的视角阅读你的错误信息——你会知道下一步该做什么吗？如果不知道，请重写。

3. 列表接口需分页。 items_list 返回 { items, nextCursor }。默认限制为 20 条，硬上限为 100 条。不要将无限制的数据倾倒到上下文中。

4. 破坏性操作支持 dryRun。 items_delete 会告诉你如果执行操作会发生什么，以防你不确定后果。

5. 一个 Zod，三个消费者。 不要手动维护与 Zod 并行的 JSON Schema —— defineTool 会自动推导两者。

6. 评估即测试。 工具调用轨迹是可断言的。当描述的回归导致模型行为异常时，你的测试会捕获它。

许可证

MIT。