MCP Управление Задачами

Независимый сервер на основе Model Context Protocol (MCP) для интеграции агентов разработки с системой Управления Задачами.

Требования

• Node.js 22.5 или выше;

• доступ к серверу Управления Задачами;

• действительные учётные данные или токен аутентификации.

Related MCP server: Project Manager MCP

Установка

npm install
npm run build

Настройка и аутентификация

Помощник настраивает URL сервера и аутентификацию локально. URL может быть указан через переменную GESTAO_TAREFAS_API_URL, аргумент --api-url или во время выполнения помощника.

npm run setup

Если URL не настроен, помощник запросит:

URL do Gestão de Tarefas:

Также можно указать данные для входа через аргумент:

npm run setup -- \
  --api-url=https://seu-servidor-de-gestao.exemplo \
  --email=seu.email@empresa.gov.br \
  --password=suasenha

Чтобы использовать существующую веб-сессию или токен:

npm run setup -- --api-url=https://seu-servidor-de-gestao.exemplo --token=SEU_TOKEN

Помощник пытается аутентифицироваться через JSON-эндпоинт и, если он недоступен, использует веб-форму с CSRF. Учётные данные не версионируются. Сессия или токен сохраняются в локальном .env и в ~/.gestao-tarefas-mcp/config.json.

Существующая веб-сессия или токен могут быть переданы помощнику или настроены в GESTAO_TAREFAS_API_TOKEN.

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

Файл .env.example содержит эталонную конфигурацию:

GESTAO_TAREFAS_API_URL=https://seu-servidor-de-gestao.exemplo
GESTAO_TAREFAS_API_TOKEN=cole_a_sessao_web_ou_token_aqui
OFFLINE_QUEUE_PATH=~/.gestao-tarefas-mcp/queue.sqlite
REQUEST_TIMEOUT_MS=5000
IGNORE_PREFEITURA=true
IGNORED_PROJECT_PATTERNS=prefeitura,pmsp,pref-,pm-,pm_

Не помещайте токены, пароли или куки в файлы, которые версионируются.

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

Сервер предоставляет инструменты для:

• определения текущего проекта и его связи с системой;

• списка проектов, задач и спринтов;

• создания задач и подзадач;

• обновления подзадач и просмотра деталей задач;

• привязки задач к спринтам;

• работы с офлайн-очередью и последующей синхронизации элементов;

• проверки подключения и состояния аутентификации.

Проекты, отмеченные как внешние или принадлежащие Префектуре, могут быть автоматически проигнорированы. Это поведение управляется через IGNORE_PREFEITURA, IGNORED_PROJECT_PATTERNS и файл .gestaotarefas.json.

Запуск

Сервер использует stdio и должен запускаться из сборки:

npm run build
node dist/index.js

Пример конфигурации для MCP-клиента:

{
  "mcpServers": {
    "gestao-tarefas": {
      "command": "node",
      "args": ["/caminho/para/mcp-gestao-tarefas/dist/index.js"],
      "env": {
        "GESTAO_TAREFAS_API_URL": "https://seu-servidor-de-gestao.exemplo",
        "GESTAO_TAREFAS_API_TOKEN": "CONFIGURADO_LOCALMENTE",
        "OFFLINE_QUEUE_PATH": "~/.gestao-tarefas-mcp/queue.sqlite",
        "IGNORE_PREFEITURA": "true"
      }
    }
  }
}

После изменения кода выполните npm run build и перезапустите MCP-клиент.

Обзор компонентов и потоков приведён в ARCHITECTURE.md.

Настройка через агента разработки

Агент с доступом к рабочей области может настроить сервер, следуя этой последовательности:

Configure o servidor MCP deste projeto.

1. Leia o README.md e identifique o cliente MCP em uso.
2. Use o diretório atual como diretório do projeto.
3. Instale as dependências apenas se necessário.
4. Execute npm run build.
5. Registre o servidor usando node dist/index.js e preserve as demais
   configurações existentes do cliente.
6. Solicite a URL do servidor e a autenticação caso ainda não estejam
   configuradas. Não exiba nem grave tokens ou senhas no chat.
7. Inicie o servidor ou informe que o cliente precisa ser reiniciado.

Агент должен запрашивать подтверждение перед перезаписью существующих конфигураций или установкой зависимостей. Если у агента нет прав на изменение конфигурации клиента, он должен предоставить инструкции для ручного применения.

Конфигурация проекта

Файл .gestaotarefas.json должен быть создан в корне репозитория, который будет интегрирован с Управлением Задач, на том же уровне, что и каталог .git:

meu-projeto/
├── .git/
├── .gestaotarefas.json
├── package.json
└── src/

MCP ищет этот файл, начиная с текущего каталога и поднимаясь по родительским папкам. Таким образом, конфигурация, помещённая в общую папку, также может быть использована несколькими репозиториями. Альтернативное имя .gestao-tarefas.json также принимается.

Чтобы привязать репозиторий к проекту, создайте мой-проект/.gestaotarefas.json с соответствующим идентификатором:

{
  "projeto_id": 1,
  "nome": "Gestão de Tarefas",
  "departamento": "TI"
}

Чтобы отключить MCP только в этом репозитории, используйте тот же файл:

{
  "nome": "Projeto externo",
  "tipo": "externo",
  "ignorado": true,
  "motivo": "Projeto fora do escopo"
}

Тесты

npm test

Набор покрывает аутентификацию, определение контекста, пропуск игнорируемых проектов, HTTP-взаимодействие, офлайн-очередь, синхронизацию и MCP-инструменты.