convez.ai
MCP Server
madebyearth

teamstorm-mcp-server

madebyearth/teamstorm-mcp-server

Ver no GitHub
InicialPluginScore · de 0 a 100

С помощью сервера TeamStorm Model Context Protocol вы можете безопасно подключать инструменты и приложения искусственного интеллекта к своему экземпляру TeamStorm. ИИ-помощники, такие как Claude Desktop, Claude Code, Cursor и другие MCP-совместимые инструменты, смогут получать доступ к вашим данным TeamStorm и выполнять действия от вашего имени

Instalação

$npx convez-ai madebyearth/teamstorm-mcp-server

1 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

Estrelas
6
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

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_TOKENPrivateToken для аутентификацииНет (каждый клиент передаёт через 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

Ver o original no GitHub

Bom para

Relacionados