teamstorm-mcp-server
madebyearth/teamstorm-mcp-server
С помощью сервера TeamStorm Model Context Protocol вы можете безопасно подключать инструменты и приложения искусственного интеллекта к своему экземпляру TeamStorm. ИИ-помощники, такие как Claude Desktop, Claude Code, Cursor и другие MCP-совместимые инструменты, смогут получать доступ к вашим данным TeamStorm и выполнять действия от вашего имени
Instalação
npx convez-ai madebyearth/teamstorm-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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.
Примечание: Переменная
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: Bearer ваш_токен"
Примечание:
Bearerтокен — это ваш персональный токен TeamStorm. Он передаётся с каждым запросом и используется для аутентификации на стороне API.
3. Интеграция с Cursor
Создайте файл .cursor/mcp.json в корне проекта (или глобально в ~/.cursor/mcp.json):
{
"mcpServers": {
"teamstorm": {
"command": "curl",
"args": [
"-s",
"-X",
"POST",
"-H",
"Authorization: Bearer ваш_токен",
"-H",
"Content-Type: application/json",
"http://localhost:3001/mcp"
]
}
}
}
Примечание: Замени
ваш_токенна реальныйBearerтокен 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