MCP Gestión de Tareas

Servidor independiente basado en el Model Context Protocol (MCP) para integrar agentes de desarrollo al sistema de Gestión de Tareas.

Requisitos

• Node.js 22.5 o superior;

• acceso al servidor de Gestión de Tareas;

• credenciales válidas o un token de autenticación.

Related MCP server: Project Manager MCP

Instalación

npm install
npm run build

Configuración y autenticación

El asistente configura la URL del servidor y la autenticación localmente. La URL puede ser informada mediante la variable GESTAO_TAREFAS_API_URL, el argumento --api-url o durante la ejecución del asistente.

npm run setup

Cuando la URL no esté configurada, el asistente solicitará:

URL do Gestão de Tarefas:

También es posible informar los datos de acceso por argumento:

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

Para usar una sesión web o un token ya existente:

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

El asistente intenta autenticar por endpoint JSON y, si no está disponible, usa el formulario web con CSRF. Las credenciales no se versionan. La sesión o el token se guardan en el .env local y en ~/.gestao-tarefas-mcp/config.json.

Una sesión web o un token existente puede informarse al asistente o configurarse en GESTAO_TAREFAS_API_TOKEN.

Variables de entorno

El archivo .env.example contiene la configuración de referencia:

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_

No coloque tokens, contraseñas o cookies en archivos versionados.

Funcionalidades

El servidor proporciona herramientas para:

• detectar el proyecto actual y su vínculo con el sistema;

• listar proyectos, demandas y sprints;

• crear demandas y subtareas;

• actualizar subtareas y consultar detalles de demandas;

• asociar demandas a sprints;

• operar con cola offline y sincronizar los elementos posteriormente;

• verificar la conectividad y el estado de la autenticación.

Los proyectos marcados como externos o pertenecientes a la Prefectura pueden ignorarse automáticamente. Este comportamiento está controlado por IGNORE_PREFEITURA, IGNORED_PROJECT_PATTERNS y el archivo .gestaotarefas.json.

Ejecución

El servidor usa stdio y debe ejecutarse desde el build:

npm run build
node dist/index.js

Ejemplo de configuración para un cliente 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"
      }
    }
  }
}

Después de modificar el código, ejecute npm run build y reinicie el cliente MCP.

La visión general de los componentes y flujos está en ARCHITECTURE.md.

Configuración por agente de desarrollo

Un agente con acceso al workspace puede configurar el servidor siguiendo esta secuencia:

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.

El agente debe pedir confirmación antes de sobrescribir configuraciones existentes o instalar dependencias. Si no tiene permiso para modificar la configuración del cliente, debe proporcionar las instrucciones para su aplicación manual.

Configuración del proyecto

El archivo .gestaotarefas.json debe crearse en la raíz del repositorio que se integrará a Gestión de Tareas, al mismo nivel del directorio .git:

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

El MCP busca este archivo desde el directorio actual y continúa subiendo por las carpetas padre. Así, una configuración colocada en una carpeta común también puede ser compartida por varios repositorios. El nombre alternativo .gestao-tarefas.json también se acepta.

Para vincular el repositorio a un proyecto, cree mi-proyecto/.gestaotarefas.json con el identificador correspondiente:

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

Para desactivar el MCP solo en ese repositorio, use el mismo archivo:

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

Pruebas

npm test

La suite cubre autenticación, detección de contexto, omisión de proyectos ignorados, comunicación HTTP, cola offline, sincronización y herramientas MCP.