MCP-сервер Timelix

Назначение

MCP (Model Context Protocol) endpoint Timelix отдаёт инструменты агенту, IDE и workflow-клиентам. Каждый HTTP-запрос обрабатывается со своим контекстом (userId, agentId, todoListId, опционально timezone), чтобы не было гонок при параллельных вызовах.

Бэкенд: маршрут приложения app/api/agent/[transport]/route.ts с обработчиком handleWithContext.

URL и транспорты

Базовый путь задаётся как /api/agent.

Два способа авторизации

1. Токен

https://<host>/api/agent/mcp?token=<mcp_access_token>

Токен проверяется в БД (mcpAccessTokens). При ошибке Timelix возвращает 401 и JSON-RPC ошибку Invalid or expired MCP token.

Из токена восстанавливаются userId, agentId и todoListId.

2. Legacy query-параметры

https://<host>/api/agent/mcp?userId=<...>&agentId=<...>&todoListId=<...>&timezone=<...>&agentName=<...>

• userId обязателен
• agentId определяет agent-specific набор tools
• todoListId нужен для задач и планов
• timezone передаётся как IANA (Europe/Moscow) или смещение (+03:00)
• agentName используется в логах и части prompt/tool flows

Парсинг выполняется в features/TimelixTools/context.ts (parseSessionContext). После этого userId при необходимости дополнительно резолвится через resolveUserId.

Как MCP решает, какие tools отдать

• Если agentId есть, Timelix загружает agent-specific набор built-in и company/store tools.
• Если agentId нет, сервер регистрирует общий built-in набор из features/TimelixTools/registry.ts: system, todos, epics, metrics, integrations и docs-инструменты, которые реально экспортированы в registry.
• Если загрузка набора агента падает, выполняется fallback на полный built-in набор.

Именно поэтому список инструментов зависит не только от реестра, но и от роли агента. Подробности: Timelix Tools.

Пример для curl

curl -sS -X POST "https://app.example.com/api/agent/mcp?userId=USER_UUID&agentId=ROLE_UUID&todoListId=TODO_BLOCK_UUID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}'

Клиент дальше обычно вызывает цепочку initialize → tools/list → tools/call.

Типичные ошибки

Серверные логи обычно помечаются префиксами [MCP], [MCP-DIAG], [MCP Context].

Связанные разделы

• Задачи и MCP — зачем todoListId и timezone
• Timelix Tools — откуда берётся список tools