MCP Gestão de Tarefas

Servidor independente baseado no Model Context Protocol (MCP) para integrar agentes de desenvolvimento ao sistema de Gestão de Tarefas.

Requisitos

Node.js 22.5 ou superior;
acesso ao servidor de Gestão de Tarefas;
credenciais válidas ou um token de autenticação.

Instalação

npm install
npm run build

Configuração e autenticação

O assistente configura a URL do servidor e a autenticação localmente. A URL pode ser informada pela variável GESTAO_TAREFAS_API_URL, pelo argumento --api-url ou durante a execução do assistente.

npm run setup

Quando a URL não estiver configurada no ambiente, o assistente sugerirá o padrão da Codemar:

URL do Gestão de Tarefas (https://gestaotarefas-codemar.marica.rj.gov.br):

Também é possível informar os dados de acesso por argumento:

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

Para usar uma sessão web ou um token já existente:

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

O assistente tenta autenticar por endpoint JSON e, caso não esteja disponível, usa o formulário web com CSRF. As credenciais não são versionadas. A sessão ou o token são gravados no .env local e em ~/.gestao-tarefas-mcp/config.json.

Uma sessão web ou um token existente pode ser informado ao assistente ou configurado em GESTAO_TAREFAS_API_TOKEN.

Variáveis de ambiente

O arquivo .env.example contém a configuração de referência:

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_EXTERNAL_PROJECTS=true
IGNORED_PROJECT_PATTERNS=pessoal,personal,externo

Não coloque tokens, senhas ou cookies em arquivos versionados.

Funcionalidades

O servidor fornece ferramentas para:

detectar o projeto atual e seu vínculo com o sistema;
listar projetos, demandas e sprints;
criar demandas e subtarefas;
atualizar demandas e subtarefas, e consultar detalhes de demandas;
associar demandas a sprints;
operar com fila offline e sincronizar os itens posteriormente;
verificar a conectividade e o estado da autenticação.

Projetos da Prefeitura permanecem ativos por padrão. Projetos pessoais ou externos podem ser ignorados por padrões configurados em IGNORED_PROJECT_PATTERNS, pela variável IGNORE_EXTERNAL_PROJECTS ou pelo arquivo .gestaotarefas.json. Projetos sem identificação também não podem criar registros, evitando o uso acidental do MCP em outros repositórios.

Execução

O servidor usa stdio e deve ser executado a partir do build:

npm run build
node dist/index.js

Exemplo para o Claude Code (~/.claude.json), Claude Desktop (claude_desktop_config.json), Antigravity CLI e Cursor:

{
  "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_EXTERNAL_PROJECTS": "true"
      }
    }
  }
}

Também é possível adicionar no Claude Code via linha de comando:

claude mcp add --env GESTAO_TAREFAS_API_URL=https://seu-servidor-de-gestao.exemplo \
  --env GESTAO_TAREFAS_API_TOKEN=CONFIGURADO_LOCALMENTE \
  --env OFFLINE_QUEUE_PATH=~/.gestao-tarefas-mcp/queue.sqlite \
  --env IGNORE_EXTERNAL_PROJECTS=true \
  --transport stdio gestao-tarefas -- node /caminho/para/mcp-gestao-tarefas/dist/index.js

Exemplo para o Codex (~/.codex/config.toml):

[mcp_servers.gestao-tarefas]
command = "node"
args = ["/caminho/para/mcp-gestao-tarefas/dist/index.js"]
cwd = "/caminho/para/mcp-gestao-tarefas"

[mcp_servers.gestao-tarefas.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_EXTERNAL_PROJECTS = "true"

Exemplo para o OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "gestao-tarefas": {
      "type": "local",
      "command": ["node", "/caminho/para/mcp-gestao-tarefas/dist/index.js"],
      "enabled": true,
      "environment": {
        "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_EXTERNAL_PROJECTS": "true"
      }
    }
  }
}

Harness Pi

O Pi não possui MCP nativo: o suporte vem do pacote pi-mcp-adapter. O npm run setup detecta o diretório do agente (~/.pi/agent, ou PI_CODING_AGENT_DIR), grava o servidor em ~/.pi/agent/mcp.json, instala a skill em ~/.pi/agent/skills/ e executa pi install npm:pi-mcp-adapter quando o binário pi está disponível. Configuração manual equivalente:

pi install npm:pi-mcp-adapter

{
  "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_EXTERNAL_PROJECTS": "true"
      }
    }
  }
}

Após alterar o código, execute npm run build e reinicie o cliente MCP.

A visão geral dos componentes e dos fluxos está em ARCHITECTURE.md.

Configuração por agente de desenvolvimento

Um agente com acesso ao workspace pode configurar o servidor seguindo esta sequência:

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.

O agente deve pedir confirmação antes de sobrescrever configurações existentes ou instalar dependências. Se não tiver permissão para alterar a configuração do cliente, deve fornecer as instruções para aplicação manual.

Configuração do projeto

O arquivo .gestaotarefas.json deve ser criado na raiz do repositório que será integrado ao Gestão de Tarefas, no mesmo nível do diretório .git:

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

O MCP procura esse arquivo a partir do diretório atual e continua subindo pelas pastas pai. Assim, uma configuração colocada em uma pasta comum também pode ser compartilhada por vários repositórios. O nome alternativo .gestao-tarefas.json também é aceito.

Para vincular o repositório a um projeto, crie meu-projeto/.gestaotarefas.json com o identificador correspondente:

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

Para desativar o MCP somente nesse repositório, use o mesmo arquivo:

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

Testes

npm test

A suíte cobre autenticação, detecção de contexto, bypass de projetos ignorados, comunicação HTTP, fila offline, sincronização e ferramentas MCP.