Домашнее задание MCP Agent

Система TypeScript MCP (Model Context Protocol), созданная для задания в MCP_HOMEWORK_SKILL.md: Agent Host, который загружает Agent Skill (SKILL.md), подключается к трём MCP-серверам через все три требуемых транспорта, обнаруживает/агрегирует их инструменты и позволяет Gemini выбирать и вызывать нужный инструмент на нужном сервере.

Архитектура

                          Agent Host (src/host)
                     skill-loader + connection-manager
                       + tool-bridge + gemini-client
                                 |
              +------------------+------------------+
              |                  |                   |
              v                  v                   v
        stdio server       local HTTP server    public HTTP server
     (src/servers/stdio-  (src/servers/http-   (same http-server.ts,
        server.ts)          server.ts, no auth)   API-key protected)
              |                  |                   |
              +------------------+-------------------+
                                 |
              shared tool logic (src/servers/shared/tools.ts)
       3 tools (calculator, text_stats, unit_convert) + 1 resource + 1 prompt

• src/servers/shared/tools.ts — единственная реализация 3 инструментов, 1 ресурса и 1 промпта, зарегистрированных одинаково на каждом сервере, чтобы одна и та же логика переиспользовалась везде (без дублирования бизнес-логики).

• src/servers/stdio-server.ts — MCP через stdio (запускается как дочерний процесс).

• src/servers/http-server.ts — MCP через Streamable HTTP. Один и тот же файл/код запускает и «локальный», и «публичный» серверы; разница только в конфигурации (PORT, PUBLIC_MCP_API_KEY).

• src/host/connection-manager.ts — MCP Host: подключается к каждому настроенному серверу, обнаруживает инструменты/ресурсы/промпты, разносит имена инструментов по пространствам имён как <namespace>__<tool> во избежание коллизий и направляет вызовы инструментов обратно на владеющий сервер.

• src/host/tool-bridge.ts — преобразует обнаруженные MCP-инструменты в объявления функций Gemini.

• src/host/gemini-client.ts — цикл вызова инструментов Gemini (отправка сообщения → чтение вызовов функций → диспетчеризация через connection manager → отправка ответов функций обратно → повтор до финального текста).

• src/host/skill-loader.ts — загружает SKILL.md и внедряет его как системную инструкцию модели, так что скилл активно формирует использование инструментов.

• src/host/agent-host.ts — связывает всё вышеперечисленное на основе config/servers.json.

• src/host/cli.ts — точка входа CLI (интерактивный режим или --demo).

Related MCP server: mcp-tools-server

Настройка

npm install

Секреты хранятся в api.env (уже в gitignore):

API_KEY=your-gemini-api-key
# Optional, only needed once you deploy the public server:
# PUBLIC_MCP_URL=https://your-app.onrender.com/mcp
# PUBLIC_MCP_API_KEY=some-strong-random-key

Запуск каждого компонента

stdio-сервер (20 баллов)

npm run server:stdio            # run directly
npm run inspector:stdio         # open MCP Inspector against it

Inspector обнаружит 3 инструмента (calculator, text_stats, unit_convert), 1 ресурс (docs://unit-conversions) и 1 промпт (explain-tool-result) и сможет выполнить/прочитать их все.

Локальный HTTP-сервер

npm run server:http             # listens on http://127.0.0.1:8787/mcp, no auth
npm run inspector:http          # then connect Inspector to that URL

Публичный HTTP-сервер (15 баллов)

Тот же http-server.ts становится «публичным» сервером, как только задан PUBLIC_MCP_API_KEY — каждый запрос теперь требует соответствующий заголовок x-api-key; при отсутствии/неверном ключе возвращается 401 Unauthorized.

$env:PORT=8788; $env:PUBLIC_MCP_API_KEY="a-strong-secret"; npm run server:http

Публичное развёртывание (Render.com, с использованием приложенного render.yaml):

1. git init && git add -A && git commit -m "MCP homework", затем запушьте в ваш собственный репозиторий GitHub.

2. В Render: New + → Blueprint → выберите репозиторий (он читает render.yaml автоматически) или создайте Web Service вручную с:

   • Команда сборки: npm install && npm run build

   • Команда запуска: npm run start:http

   • Путь проверки здоровья: /health

3. В панели Render задайте переменную окружения PUBLIC_MCP_API_KEY как надёжный секрет (никогда не коммитьте его).

4. После развёртывания поместите полученный URL + ключ в api.env: PUBLIC_MCP_URL=https://<your-service>.onrender.com/mcp и PUBLIC_MCP_API_KEY=<тот же секрет>.

5. Проверьте с помощью Inspector:

   • Без ключа → отклонено: curl -X POST https://<url>/mcp -H "Content-Type: application/json" -d "{...}" возвращает 401.

   • С ключом → работает: передайте --header "x-api-key: <secret>" в npx @modelcontextprotocol/inspector --cli <url> --method tools/list.

Agent Host

npm run agent          # interactive CLI
npm run agent:demo      # runs a scripted set of demo queries

При запуске хост:

1. Загружает SKILL.md как системную инструкцию.

2. Читает config/servers.json и подключается к stdio-серверу (запускается автоматически), локальному HTTP-серверу (должен уже работать) и публичному HTTP-серверу (пропускается автоматически, если PUBLIC_MCP_URL/PUBLIC_MCP_API_KEY не заданы — он опционален, чтобы демо работало и без живого развёртывания).

3. Обнаруживает и разносит по пространствам имён каждый инструмент, передаёт их Gemini и направляет каждый вызов инструмента, сделанный Gemini, на правильный MCP-сервер.

Конфигурация

Регистрация серверов управляется данными через config/servers.json — добавляйте/удаляйте серверы там, а не редактируйте код хоста. ${VAR} в url разрешается из process.env в момент подключения; apiKeyEnv задаёт имя переменной окружения, значение которой отправляется как x-api-key.

Agent Skill

SKILL.md инструктирует агента предпочитать вызов инструментов угадыванию при арифметике/конвертациях/текстовой статистике, выбирать один инструмент с пространством имён на каждый логический запрос, обращаться к ресурсу docs://unit-conversions при неуверенности в поддерживаемых конвертациях и объяснять результаты простым языком. Он загружается дословно в системную инструкцию Gemini при каждом запуске (см. src/host/skill-loader.ts), так что его правила напрямую влияют на выбор инструментов и стиль ответов — это видно в выводе демо (например, агент всегда вызывает инструмент для арифметики, а не вычисляет сам).

Замечания по безопасности

• Секреты не коммитятся; api.env в gitignore, и публичный сервер читает PUBLIC_MCP_API_KEY только из окружения.

• Публичный HTTP-сервер отклоняет любой запрос без соответствующего заголовка x-api-key (401) и принимает запросы при наличии действительного ключа.