AI-интеграция MassFarmer GraphQL API

Два нативных канала для AI-ассистентов: Apollo MCP Server (вызов API) и llms.txt (контекст документации).

1. Apollo MCP Server (рекомендуется для агентов)

Apollo MCP Server — официальный мост GraphQL→MCP. Каждая публичная операция из списка разрешённых становится инструментом MCP.

Локальный запуск

pnpm docs:api    # schema + operations + docs
pnpm mcp:run     # Docker на http://127.0.0.1:8000/mcp

Артефакты: docs/reference/schema/mcp/ (mcp-config.yaml, schema.graphql, operations/*.graphql).

Cursor

1. Запустите pnpm mcp:run локально или укажите ниже URL рабочего окружения.
2. Скопируйте docs/reference/schema/ai/cursor-mcp.example.json в настройки MCP Cursor (или добавьте сервер вручную).
3. При вызове инструментов передайте заголовки X-API-KEY и X-TEAM-ID (ключ из ЛК → API).

Claude Desktop

См. docs/reference/schema/ai/claude-desktop-mcp.example.json.

MCP в рабочем окружении

Публичная конечная точка: https://massfarmer.com/mcp

В Cursor/Claude замените URL в mcp-remote на https://massfarmer.com/mcp. Контейнер massfarmer-mcp в кластере использует mcp-config.k8s.yaml (внутренний GraphQL: http://massfarmer/api/graphql).

В конфигурации включены инструменты интроспекции (search, validate, execute) для разовых запросов в рамках публичной схемы.

2. llms.txt (контекст для чата)

Стандарт llmstxt.org:

Cursor: добавьте https://massfarmer.com/api/llms-full.txt в раздел документации или контекст @.

ChatGPT / Claude (чат): вставьте URL в системный промпт или загрузите llms-full.txt.

Генерация: pnpm docs:api → scripts/generate-llms-txt.mjs.

3. HTML-документация

Статическая справка для людей, детерминированно генерируемая из публичной SDL: https://massfarmer.com/api/docs

Аутентификация

Только X-API-KEY + X-TEAM-ID. Куки и браузерная сессия не используются.

MCP: ключи пробрасывает клиент через forward_headers (см. mcp-config.yaml), не храните их в репозитории.