TeamStorm MCP Server

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

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
src		src
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

TeamStorm MCP Server

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

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

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

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

4. Проверка

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

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

Файл .env

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

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

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

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

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

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

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

Разработка

Архитектура

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

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

Задачи

Комментарии

Атрибуты

Вложения

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

Связи

Справочники

Время

Лицензия

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages