harness-mcp

Шаблон на TypeScript с собственным подходом к созданию MCP-серверов, ориентированный на harness engineering.

Harness engineering — это дисциплина проектирования каркаса вокруг LLM-агента (инструменты, описания, ошибки, контекст), чтобы агент действительно выполнял нужные действия. Большинство шаблонов MCP обучают вас протоколу. Этот шаблон обучает вас и протоколу, и практике.

Что внутри

• defineTool() — одна схема Zod обеспечивает работу SDK MCP, API вызова функций OpenAI и обработчика времени выполнения. Валидация и обертывание ошибок происходят автоматически.

• Оба транспорта — stdio (src/index.ts) для локальных клиентов в стиле Claude Code, потоковый 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. Описания инструментов — это промпт-инжиниринг. Каждое описание начинается с USE WHEN ... и включает DO NOT USE WHEN ... для похожих инструментов, с которыми модель может их перепутать. Дымовое тестирование обеспечивает соблюдение этого правила.

2. Ошибки обучают. Каждый AgentError содержит поле hint. Читайте свои сообщения об ошибках так, будто вы — агент: поняли бы вы, что делать дальше? Если нет, перепишите их.

3. Эндпоинты списка используют пагинацию. items_list возвращает { items, nextCursor }. Лимит по умолчанию 20, жесткий лимит 100. Не выгружайте неограниченные данные в контекст.

4. Деструктивные операции поддерживают dryRun. items_delete сообщит вам, что произошло бы, если вы не уверены в действии.

5. Один Zod, три потребителя. Не поддерживайте JSON Schema вручную параллельно с Zod — defineTool выводит оба варианта.

6. Оценки — это тесты. Трассировки вызовов инструментов можно проверять утверждениями (assert). Когда регрессия в описании нарушает поведение модели, ваш тест это обнаружит.

Лицензия

MIT.