Teamstorm

MCP-сервер для интеграции AI-агентов (Claude Code, Cursor) с TeamStorm API. Предоставляет 26 инструментов для работы с задачами, комментариями, атрибутами, вложениями, правами доступа, связями, пользователями, спринтами, workflow и списанием времени.

Быстрый старт

1. Запустите контейнер

docker compose up -d --build

Для полной чистой сборки (без кеша):

docker compose build --no-cache && docker compose up -d

Сервер будет доступен на http://localhost:3001/mcp, health-check — на http://localhost:3002/health.

Доступ по сети (Linux-сервер): При запуске на Linux-сервере в локальной сети сервер автоматически доступен по IP-адресу сервера: http://192.168.x.x:3001/mcp. Используйте этот адрес вместо localhost при настройке Claude Code или Cursor на другой машине. Порт открывается на всех сетевых интерфейсах (0.0.0.0) автоматически — дополнительная настройка не требуется.

Примечание: Переменная TEAMSTORM_API_TOKEN в .env не обязательна — в HTTP-режиме каждый клиент передаёт свой токен через заголовок Authorization. TEAMSTORM_API_URL можно передать через apiUrl в инструменте (автоматически дополняется до http://<host>/cwm/public/api/v1), но обычно URL предконфигурирован на сервере и параметр не требуется.

2. Интеграция с Claude Code

Сервер уже запущен (см. шаг 1). Добавьте его в Claude Code:

claude mcp add --scope user --transport http teamstorm http://localhost:3001/mcp \
  -H "Authorization: PrivateToken ваш_токен"

Примечание: PrivateToken — это ваш персональный токен TeamStorm. Он передаётся с каждым запросом и используется для аутентификации на стороне API.

3. Интеграция с Cursor

Создайте файл .cursor/mcp.json в корне проекта (или глобально в ~/.cursor/mcp.json):

{
  "mcpServers": {
    "teamstorm": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "PrivateToken ваш_токен"
      }
    }
  }
}

Примечание: Замени ваш_токен на реальный PrivateToken TeamStorm. После добавления перезапустите Cursor — инструменты появятся в боковой панели MCP.

4. Проверка

После добавления перезапустите IDE и проверьте:

Покажи список пространств TeamStorm

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

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

Переменная	Описание	Обязательность	Пример
TEAMSTORM_API_URL	Базовый URL TeamStorm API	Нет (URL предконфигурирован на сервере; можно переопределить через apiUrl в инструменте)	http://teamstorm.local/cwm/public/api/v1
TEAMSTORM_API_TOKEN	PrivateToken для аутентификации	Нет (каждый клиент передаёт через Authorization заголовок)	your_token_here
PORT	Порт для MCP сервера	Нет (по умолчанию 3001)	3001
TRUST_PROXY	Доверять заголовку X-Forwarded-For (только за reverse-proxy)	Нет (по умолчанию false)	false

TEAMSTORM_API_URL задаётся глобально через .env. При необходимости можно переопределить через параметр apiUrl в отдельном инструменте — сервер автоматически дополняет URL до полного формата http://<host>/cwm/public/api/v1.

Файл .env

cp .env.example .env

Использование

После интеграции с IDE вы можете использовать команды.

Примечание: Параметр workspace обязателен во всех инструментах. Если установлена переменная окружения TEAMSTORM_WORKSPACE в .env, можно передавать workspace опционально — он подставится автоматически. Иначе указывайте его явно: "в пространстве TS".

Получить список задач:

Покажи список задач в пространстве TS

Получить задачу по ID:

Найди задачу TS-13 в пространстве TS

Создать задачу:

Создай задачу "Исправить баг" в пространстве TS
с типом "Дефект", исполнителем "ivan.ivanov" и папкой "разработка"

Работа с комментариями

Покажи комментарии к задаче TS-671 в пространстве TS
Добавь комментарий к задаче TS-671: "Готово к слиянию"

Работа с атрибутами

Покажи атрибуты задачи TS-671 в пространстве TS
Какие атрибуты есть в пространстве TS?

Работа с вложениями

Загрузить файл:

curl -X POST http://localhost:3001/upload \
  -H "Authorization: PrivateToken ваш_токен" \
  -F "file=@/path/to/file.pdf"

После загрузки получите uploadId. Прикрепите файл:

Прикрепи файл с ID abc-123 к задаче TS-100 в пространстве TS

Списания времени

Добавь списание 2ч 30м к задаче TS-671 в пространстве TS
Покажи списания времени по задаче TS-671

Работа с несколькими инстансами

Покажи задачи TS-100 в пространстве TS с URL http://teamstorm-staging.local/cwm/public/api/v1

Примечание: При передаче apiUrl можно указать только домен (http://teamstorm-staging.local) — сервер автоматически добавит суффикс /cwm/public/api/v1.

Безопасность загрузки файлов

Endpoint POST /upload (Out-of-Band загрузка):

• Аутентификация — требуется PrivateToken или Bearer в Authorization
• Rate limiting — 10 запросов/мин на IP (с учётом TRUST_PROXY)
• Ограничение размера — макс. 50 МБ
• TTL — файлы удаляются через 1 час
• Права — только владелец (система) имеет доступ к файлу

Разработка

npm install
npm run dev       # hot reload
npm run build     # tsc → dist/
npm run test:run  # тесты
npm run lint      # ESLint

Архитектура

• src/index.ts — точка входа: HTTP-сервер (порт 3001) + health-check (3002) + OOB upload. Каждый MCP-запрос создаёт новый McpServer.
• src/client/teamstorm.ts — TeamStormClient: axios-клиент с setBaseUrl() для переключения URL в рантайме (автоматически дополняет неполные URL до /cwm/public/api/v1).
• src/tools/ — 26 инструментов по доменам. Каждый: Zod-схема с apiUrl + execute → клиент → Markdown.
• src/utils/ — Pino-логгер (с redact и ленивым NODE_ENV) + форматтеры (task, bytes, duration).

Структура проекта

teamstorm-mcp-server/
├── src/
│   ├── client/
│   │   ├── teamstorm.ts      # Единый axios-клиент: запросы к TeamStorm REST API,
│   │   │                      # rate-limit interceptors, санитизация заголовков в логах
│   │   └── types.ts          # Полные TS-интерфейсы всех сущностей TeamStorm
│   ├── tools/
│   │   ├── tasks/            # Инструменты для работы с задачами
│   │   │   ├── list.ts, get.ts, create.ts, update.ts, count.ts
│   │   │   ├── list-by-parent.ts, list-updated.ts
│   │   ├── comments/         # Инструменты для комментариев
│   │   │   ├── list.ts, create.ts, visibility.ts
│   │   ├── attributes/       # Инструменты для атрибутов
│   │   │   ├── get.ts, list.ts
│   │   ├── attachments/      # Инструменты для вложений
│   │   │   ├── list.ts, get.ts, versions-list.ts, version-get.ts, oob-upload.ts
│   │   ├── permissions/      # Инструменты для прав доступа
│   │   │   └── get.ts
│   │   ├── links/            # Инструменты для связей
│   │   │   └── get.ts
│   │   ├── users/            # Пользователи пространства
│   │   │   └── list.ts
│   │   ├── sprints/          # Спринты с фильтром по статусу
│   │   │   └── list.ts
│   │   ├── workflows/        # Доступные процессы
│   │   │   └── list.ts
│   │   ├── types/            # Типы задач
│   │   │   └── list.ts
│   │   ├── workspaces/       # Доступные пространства
│   │   │   └── list.ts
│   │   └── time-tracking/    # Списания времени
│   │       ├── create.ts, list.ts
│   ├── utils/
│   │   ├── formatters.ts     # Markdown-форматтеры: задачи, байты, длительность
│   │   └── logger.ts         # Pino-логгер: redact полей, ленивый NODE_ENV, pretty в dev
│   ├── config.ts             # Zod-валидация env, ленивый singleton (без process.exit на импорте)
│   └── index.ts              # Точка входа: HTTP (3001) + health-check (3002) + OOB upload
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md

Функциональность

Инструменты сгруппированы по доменам:

Задачи

Инструмент	Описание
teamstorm_list_tasks	Список задач с фильтрацией и пагинацией
teamstorm_get_task	Полная информация о задаче по ID
teamstorm_create_task	Создание задачи с указанием типа, исполнителя, папки, спринта
teamstorm_update_task	Обновление параметров задачи
teamstorm_get_task_count	Общее количество задач в пространстве
teamstorm_list_tasks_by_parent	Задачи по родительскому элементу (папка или задача)
teamstorm_list_updated_tasks	Задачи, изменённые за указанный период

Комментарии

Инструмент	Описание
teamstorm_list_task_comments	Все комментарии к задаче
teamstorm_create_task_comment	Добавление комментария к задаче
teamstorm_get_comment_visibility	Уровень доступа к комментарию (кто может видеть)

Атрибуты

Инструмент	Описание
teamstorm_get_task_attributes	Значения атрибутов конкретной задачи
teamstorm_list_attributes	Список пользовательских атрибутов пространства

Вложения

Инструмент	Описание
teamstorm_list_task_attachments	Список вложений задачи
teamstorm_get_task_attachment	Метаданные конкретного вложения
teamstorm_list_attachment_versions	Все версии вложений задачи
teamstorm_get_attachment_version	Метаданные конкретной версии вложения
teamstorm_attach_uploaded	Прикрепление загруженного файла к задаче (после POST /upload)

Управление доступом

Инструмент	Описание
teamstorm_get_task_permissions	Правила доступа к задаче

Связи

Инструмент	Описание
teamstorm_get_task_links	Связи задачи (связанные задачи)

Справочники

Инструмент	Описание
teamstorm_list_users	Пользователи пространства (с поиском)
teamstorm_list_sprints	Спринты с фильтром по статусу (active/completed/future)
teamstorm_list_workflows	Доступные процессы (workflows)
teamstorm_list_task_types	Типы задач
teamstorm_list_workspaces	Доступные пространства (workspaces)

Время

Инструмент	Описание
teamstorm_create_time_entry	Добавление списания времени (трудозатраты)
teamstorm_list_time_entries	История списаний времени по задаче

---

Лицензия

MIT