harness-mcp

**하네스 엔지니어링(harness engineering)**을 염두에 두고 MCP 서버를 구축하기 위한 독자적인 TypeScript 보일러플레이트입니다.

하네스 엔지니어링은 LLM 에이전트 주변의 스캐폴딩(도구, 설명, 오류, 컨텍스트 등)을 설계하여 에이전트가 실제로 올바른 작업을 수행하도록 만드는 학문입니다. 대부분의 MCP 보일러플레이트는 프로토콜만 가르치지만, 이 보일러플레이트는 프로토콜과 실무를 모두 가르칩니다.

포함된 기능

• defineTool() — 하나의 Zod 스키마가 MCP SDK, OpenAI의 함수 호출 API 및 런타임 핸들러에 공급됩니다. 유효성 검사와 오류 래핑이 자동으로 수행됩니다.

• 두 가지 전송 방식 지원 — Claude Code 스타일의 로컬 클라이언트를 위한 stdio(src/index.ts)와 원격/웹 클라이언트를 위한 스트리밍 HTTP(src/http.ts)를 모두 지원합니다. 둘 다 하나의 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. 하나의 Zod, 세 명의 소비자. Zod와 함께 JSON 스키마를 수동으로 유지 관리하지 마세요. defineTool이 둘 다 파생합니다.

6. 평가는 테스트입니다. 도구 호출 추적은 검증 가능합니다. 설명 변경으로 인해 모델의 동작이 저하되면 테스트가 이를 포착합니다.

라이선스

MIT.