Демонстрация MCP Agent Harness

Минимальная демонстрация агентской обвязки LLM с использованием протокола Model Context Protocol (MCP).

Этот репозиторий содержит небольшие примеры на Node.js/TypeScript и Python, показывающие, как агент может:

• обнаруживать инструменты MCP-сервера;

• предоставлять эти инструменты LLM;

• позволять модели запрашивать вызовы инструментов;

• выполнять эти вызовы через MCP;

• возвращать результаты инструментов модели;

• продолжать цикл, пока модель не сформирует окончательный ответ.

Важно: Это только демонстрационный код. Он не является производственным кодом и не должен рассматриваться как безопасная, надёжная или полная агентская платформа.

Цель репозитория — сделать механику агентской обвязки на основе MCP легко доступной для изучения.

Архитектура

На высоком уровне:

User
  |
  v
LLM
  |
  | tool request
  v
Agent Harness
  |
  v
MCP Client
  |
  v
MCP Server
  |
  v
Tool Implementation
  |
  v
Tool Result
  |
  +------------------> LLM

Обязанности намеренно разделены:

LLM      - decides what it thinks should happen
Harness  - manages the agent loop and conversation state
MCP      - standardises tool discovery and invocation
Tools    - perform the actual deterministic operations

MCP не решает, какой инструмент следует вызвать.

Выбор инструмента остаётся решением модели, если только окружающее приложение явно не ограничивает или не переопределяет его.

Related MCP server: MCP Server Scaffold

Зачем существует этот репозиторий

Множество терминологии агентских платформ может скрывать то, что на самом деле происходит.

Основной цикл обвязки — это не более чем:

call model
    |
    v
did it request a tool?
    |
   / \
 no   yes
 |     |
answer execute tool
       |
       v
   return result
       |
       +----> call model again

Этот репозиторий сохраняет этот механизм видимым, а не прячет его за большой агентской платформой.

Структура репозитория

Типичная структура:

.
├── node/
│   ├── package.json
│   └── src/
│       ├── agent.ts
│       └── server.ts
│
└── python/
    ├── agent.py
    └── server.py

Точные имена каталогов можно менять без влияния на архитектуру.

Примеры инструментов MCP

Демонстрационный сервер предоставляет три намеренно простых гипотетических инструмента:

get_github_activity
get_site_content
contact_scott

Это только примеры, предназначенные для демонстрации:

• обнаружения инструментов;

• схем инструментов;

• описаний инструментов;

• аргументов;

• выполнения;

• обработки результатов.

Они не предназначены для представления реального бэкенда.

Node.js / TypeScript

Требования

• Node.js 20+

• ключ API OpenAI

Установка зависимостей:

npm install

Установка ключа API:

export OPENAI_API_KEY="sk-..."

Запуск агента:

npm start

MCP-сервер запускается автоматически агентом через транспорт stdio.

Вам не нужно запускать сервер отдельно.

Пример вывода:

MCP tools: [
  'get_github_activity',
  'get_site_content',
  'contact_scott'
]

MODEL REQUESTED TOOL: get_github_activity
ARGUMENTS: {}

MCP RESULT:
...

FINAL ANSWER
------------
Scott has recently been working on...

Python

Требования

• Python 3.10+

• ключ API OpenAI

Создание виртуального окружения:

python3 -m venv .venv
source .venv/bin/activate

Обновление инструментов упаковки:

python3 -m pip install --upgrade pip setuptools wheel

Установка зависимостей:

pip install "mcp>=2,<3" openai

Установка ключа API:

export OPENAI_API_KEY="sk-..."

Запуск:

python3 agent.py

Версия на Python работает как интерактивный чат-бот в командной строке:

MCP tools: ['get_github_activity', 'get_site_content', 'contact_scott']

Chat started.
Type /quit to exit.

You> hello

Assistant> Hello! How can I help?

You> What has Scott been working on?

  [tool] get_github_activity({})
  [result] ...

Assistant> Scott has recently been working on...

Python-клиент сохраняет историю разговора между обращениями и выводит обычные ответы в терминал в потоковом режиме.

Транспорт Stdio

В этих примерах используется MCP через stdio.

Агент запускает MCP-сервер как дочерний процесс:

agent
  |
  +---- stdin/stdout ---- MCP server

Это удобно для локальных экспериментов, так как:

• нет отдельного демона сервера;

• нет HTTP-эндпоинта;

• нет настройки портов;

• нет дополнительного уровня аутентификации.

Одно важное следствие: MCP-сервер stdio не должен выводить произвольную отладочную информацию в stdout.

stdout принадлежит протоколу MCP.

Используйте stderr для диагностики.

Например:

print("debug information", file=sys.stderr)

или на TypeScript:

console.error("debug information");

Агентская обвязка

Основная логика обвязки:

while True:
    response = await model(...)

    calls = find_tool_calls(response)

    if not calls:
        return

    for call in calls:
        result = await mcp.call_tool(
            call.name,
            call.arguments,
        )

        add_result_to_context(result)

Настоящая обвязка может дополнительно реализовывать:

permissions
timeouts
tool allowlists
human approval
rate limits
cost limits
logging
tracing
context pruning
retry policies
authentication
authorization
sandboxing
validation
auditing
error recovery

Эта демонстрация намеренно делает очень мало из этого.

Обнаружение инструментов

Обвязке не нужен жёстко заданный список реализаций.

Вместо этого она запрашивает у MCP-сервера список доступных инструментов.

Концептуально:

MCP server
    |
    | tools/list
    v
Agent harness

Затем обвязка предоставляет модели полученные:

name
description
input schema

Если MCP-сервер позже добавит другой инструмент, обвязка сможет его обнаружить без добавления новой ветки пользовательской диспетчеризации.

Это одно из основных архитектурных преимуществ, которые даёт MCP.

Выбор инструмента не гарантирован

Этот момент важен.

Предположим, сервер предоставляет:

contact_scott

с описанием, что его следует использовать, когда кто-то хочет нанять или связаться со Скоттом.

Пользователь может сказать:

Can I hire Scott for consulting?

Ожидаемое поведение модели:

contact_scott(...)

Но LLM может вместо этого выдать обычный разговорный ответ.

MCP не решает эту проблему.

Решение:

Does this natural-language request imply this tool?

всё ещё является вероятностным выводом модели.

Описания инструментов улучшают поведение маршрутизации, но не создают формальных гарантий.

Если действие должно выполняться детерминированно, это требование следует реализовывать в обычной логике приложения, а не полагаться исключительно на инструкцию LLM.

Почему это важно

Как только модель запрашивает инструмент, остальная часть системы может быть детерминированной:

model requests tool
        |
        v
validate arguments
        |
        v
check permission
        |
        v
execute function
        |
        v
return result

Но первоначальное семантическое решение всё ещё может быть вероятностным.

Это различие особенно важно для действий, имеющих серьёзные последствия, таких как:

sending money
deleting data
changing permissions
submitting legal information
making purchases
sending messages
altering customer records

Производственная система должна размещать явные детерминированные контроли вокруг действий, имеющих значимые последствия.

Потоковая передача

Python CLI использует потоковую передачу, чтобы текст появлялся по мере его генерации.

Без потоковой передачи:

You> explain virtual memory

<wait>

Assistant> Virtual memory is...

С потоковой передачей:

You> explain virtual memory

Assistant> Virtual memory is...

Потоковая передача в первую очередь улучшает воспринимаемую задержку.

Обращения, использующие инструменты, могут занимать больше времени, поскольку могут требовать нескольких запросов к модели:

model request
    |
    v
tool call
    |
    v
MCP execution
    |
    v
tool result
    |
    v
second model request

Демонстрационный код — не производственный

Этот репозиторий намеренно минимален.

Он не предоставляет гарантий безопасности, ожидаемых от производственной агентской системы.

Среди прочего, в производственном коде необходимо учитывать:

• аутентификацию;

• авторизацию;

• управление секретами;

• враждебные входные данные инструментов;

• инъекции подсказок;

• валидацию вывода;

• валидацию результатов инструментов;

• соблюдение схем;

• ограничения ресурсов;

• сетевую изоляцию;

• безопасность подпроцессов;

• подтверждение пользователя для важных операций;

• аудит логирования;

• поведение при повторных попытках;

• восстановление после сбоев;

• контроль затрат;

• рост контекста;

• изменения версий моделей;

• изменения версий API;

• фиксацию зависимостей;

• наблюдаемость;

• тестирование и оценку;

• требования к конфиденциальности и хранению данных.

Не предоставляйте доступ к примеру MCP-сервера напрямую недоверенным пользователям и не используйте шаблон contact_scott для реальных коммуникаций без добавления соответствующей валидации, аутентификации, персистентности, защиты от злоупотреблений и обработки ошибок.

И снова:

Этот репозиторий — демонстрационный код, предназначенный для обучения и экспериментов, а не для производственного развёртывания.

MCP — это не агент

Полезно сохранять разделение слоёв:

MCP
    != LLM

MCP
    != agent

MCP
    != tool-selection logic

MCP
    != security policy

MCP — это протокол, используемый для предоставления и вызова возможностей.

Обвязка управляет циклом модель/инструменты.

Модель выполняет языковой вывод.

Базовые инструменты выполняют фактическую работу.

Полезная ментальная модель:

Agent System
=
Model
+
Harness
+
Tools
+
Context
+
Policy

MCP предоставляет стандартный интерфейс между некоторыми из этих компонентов.

Почему бы просто не вызывать функции напрямую?

Для трёх локальных функций в одном приложении это абсолютно возможно.

Например:

TOOLS = {
    "foo": foo,
    "bar": bar,
}

может быть проще, чем MCP.

MCP становится более интересным, когда возможности должны быть многократно используемыми в нескольких клиентах:

                    MCP Server
                   /    |     \
                  /     |      \
                 /      |       \
            CLI agent  IDE    website

Поставщик инструментов становится независимым от конкретного хоста модели или приложения.

Это основная архитектурная причина для внедрения MCP.

Предлагаемые эксперименты

После того как базовая командная строка заработает, полезные эксперименты включают:

run the same prompt repeatedly
change tool descriptions
change models
change system instructions
record selected tools
measure latency
measure token usage
add approval gates
add deliberately ambiguous prompts
add multiple MCP servers
introduce tool failures
introduce malformed results
limit maximum agent steps

Один особенно полезный тест — записать:

prompt
selected tool
arguments
number of model calls
latency
final response

при повторных запусках.

Это позволяет исследовать, сколько вариаций исходит от модели и насколько поведение может контролироваться обвязкой.

Лицензия

Добавьте лицензию, подходящую для вашего репозитория.

Заключительное замечание

Смысл этого кода не в том, чтобы предоставить ещё одну большую агентскую платформу.

Он в том, чтобы ясно показать механику, чтобы можно было понять основной процесс:

Model proposes.
Harness controls.
MCP connects.
Tools execute.

Всё более сложное строится на этой основе.