swapi_mcp

Небольшой сквозной эталонный проект для создания наблюдаемого ИИ-агента: MCP-сервер, оборачивающий Star Wars API, агент Claude, который им управляет, и веб-интерфейс чата — всё инструментировано с помощью OpenTelemetry и Grafana Cloud (распределённые трассировки, RED-метрики, фронтенд RUM и наблюдаемость ИИ/агентов).

Он создан, чтобы на одной работающей кодовой базе показать, как части сочетаются друг с другом: граница инструментов MCP, цикл использования инструментов агентом и сквозная трассировка от клика в браузере до вышестоящего HTTP-вызова и обратно.

Что внутри

Две части, которые общаются друг с другом через MCP (stdio):

• mcpClient.ts — запускает собранный сервер через stdio и подключается как MCP-клиент.

• agent.ts — ручной цикл использования инструментов: отправляет вопрос и инструменты сервера в Claude, выполняет каждый запрошенный инструмент через MCP, возвращает результаты и повторяет, пока задача не будет завершена.

• main.ts — точка входа CLI.

• server.ts + public/index.html — HTTP-сервер и одностраничный чат-интерфейс.

Related MCP server: SWAPI MCP Server

Наблюдаемость

Всё нижеперечисленное необязательно и управляется переменными окружения — агент отлично работает и без этого.

• Распределённая трассировка (OpenTelemetry → Tempo): одна трасса охватывает browser → POST /ask → agent.turn → llm.request / tool.call → tool.execute → swapi.fetch в трёх сервисах (swapi-web, swapi-agent, swapi-mcp-server). Контекст трассы передаётся через границу MCP через _meta запроса.

• RED-метрики (→ Mimir): гистограммы частоты запросов / ошибок / длительности для каждого инструмента и каждого вызова LLM, плюс счётчик использования токенов для оценки стоимости, с тегами model, error и error.type.

• Фронтенд RUM (Grafana Faro): Web Vitals, ошибки JS и распространение трассы из браузера в бэкенд.

• Наблюдаемость ИИ / агентов (@grafana/agent-o11y): нормализованные генерации LLM и выполнения инструментов.

• Демонстрационная инъекция сбоев (src/chaos.ts): опционально заставляет один ресурс возвращать имитируемую ошибку 503, а другой — работать на 50 % медленнее, чтобы на дашбордах были реальные сигналы ошибок и задержек.

Предварительные требования

• Node.js 22+ (использует --env-file)

• Yarn 4 (через Corepack)

• Ключ API Anthropic (для агента)

• Аккаунт Grafana Cloud (необязательно — только для функций наблюдаемости)

Установка

yarn install
yarn build

Использование MCP-сервера напрямую (например, Claude Desktop)

Направьте ваш MCP-клиент на собранный сервер:

{
  "mcpServers": {
    "swapi": { "command": "node", "args": ["/absolute/path/to/swapi_mcp/build/index.js"] }
  }
}

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

Создайте файл .env (игнорируется git) как минимум с вашим ключом Anthropic:

ANTHROPIC_API_KEY=sk-ant-...

Затем:

yarn dev                              # build + serve the web UI at http://localhost:8787
yarn ask "Who is Luke's homeworld?"   # one-shot CLI

Переменные окружения

Примечания

Это учебный / демонстрационный проект. Данные берутся из статического зеркала SWAPI, которое моделирует связи (персонаж «появляется в» фильме), а не действия — поэтому ответы формулируются соответствующим образом.

Лицензия

MIT