SurfTracker MCP Server

MCP-сервер (Streamable HTTP) для доступа ИИ-клиентов к проектам и задачам SurfTracker. В отличие от FileManagerMCP/IBP_mcp, у этого сервера нет своего хранилища API-ключей: он проксирует SurfTracker API-ключ (User.apiKey), переданный MCP-клиентом, в каждый вызов POST ${SURFTRACKER_BASE_URL}/api/1/external/* — всю авторизацию и контроль доступа (какие проекты/задачи видны) выполняет сам SurfTracker.

Инструменты

Полное описание параметров каждого метода — в SurfTracker/docs/external-api.md (read-методы задач — разделы 11-14, релизы — 15-19, остальные — 1-10).

Related MCP server: VTrack MCP Server

Требования

• Node.js 18+ (используется встроенный fetch)

• Работающий инстанс SurfTracker, доступный по сети из места запуска сервиса

• SurfTracker API-ключ (User.apiKey) пользователя, от имени которого работает ИИ

Установка

npm install
cp .env.example .env   # указать PORT и SURFTRACKER_BASE_URL

Переменные окружения (.env)

Запуск

npm start        # прод
npm run dev      # с автоперезапуском (--watch)

• MCP endpoint: POST http://<host>:<PORT>/mcp (требует SurfTracker API-ключ)

• Health check: GET http://<host>:<PORT>/health — доступность SURFTRACKER_BASE_URL (не проверяет валидность ключа — ключ есть только у клиента)

Подключение MCP-клиента

{
  "mcpServers": {
    "surftracker": {
      "url": "http://<host>:<PORT>/mcp",
      "headers": { "Authorization": "Bearer <SurfTracker API key>" }
    }
  }
}

Ключ можно передавать и в заголовке X-API-Key. Права ИИ-клиента полностью совпадают с правами пользователя, которому принадлежит ключ (те же проекты и задачи, что видны ему в SurfTracker).

Модель безопасности

1. Ключ не хранится. Сервис не ведёт собственный список ключей/проектов — каждый вызов инструмента дословно пересылает заголовок Authorization в SurfTracker. Скомпрометировать этот сервис отдельно от SurfTracker невозможно: он не видит ничего, что не отдаёт сам SurfTracker по этому ключу.

2. Авторизация и видимость данных — на стороне SurfTracker. ApiInstaller (authenticateByApiKey, Project.hasAccessToTask) решает, какие проекты и задачи доступны конкретному ключу; здесь эта логика не дублируется.

3. Ошибки SurfTracker (success: false) превращаются в isError MCP-результат с тем же сообщением (Unauthorized: Invalid API key, No access to project, ...), без утечки внутренних деталей запроса.

4. Rate limiting на /mcp: до 6000 запросов в час на процесс (MCP-сессии дёргают по одному запросу на каждый вызов инструмента).