Skip to main content
Glama
MCP Gestão de Tarefas

MCP Gestão de Tarefas

by bcosta19

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: Cherry Studio Task Board

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.

Available Tools

14 tools
associar_demanda_sprintA

Associa uma demanda existente a uma sprint. A API rejeita a operação se a demanda já estiver em outra sprint.

Inputs: sprint_id (required), demanda_id (required).

atualizar_demandaA

Atualiza campos de uma demanda existente (projeto, título, descrição, prioridade, status, responsável, sprint, datas, classificação ITIL, estimativa, solicitante).

Inputs: demanda_id (required), projeto_id (required), status, titulo, +12 more.

atualizar_subtarefaC

Atualiza campos de uma subtarefa (título, descrição, status ou data limite) ou atualiza múltiplos IDs em lote.

Inputs: status, titulo, descricao, data_limite, +2 more.

concluir_subtarefasA

Conclui ou altera o status de múltiplas subtarefas em uma única operação (passando uma lista de subtarefa_ids ou o demanda_id para concluir todas as pendentes daquela demanda).

Inputs: status, demanda_id, subtarefa_ids.

criar_demandaA

Registra uma nova demanda no sistema de Gestão de Tarefas. A operação é bloqueada para projetos não identificados ou explicitamente ignorados. Se a rede estiver offline, salva na fila local.

Inputs: titulo (required), descricao (required), prioridade (required), projeto_id (required), +11 more.

criar_subtarefaA

Cria uma subtarefa técnica vinculada a uma demanda existente. A operação é bloqueada para projetos não identificados ou explicitamente ignorados. Se offline, armazena na fila local para posterior envio.

Inputs: titulo (required), demanda_id (required), descricao, data_limite, +2 more.

listar_demandas_ativasB

Lista as demandas abertas ou em andamento de um projeto para análise de contexto e vínculo de subtarefas.

Inputs: projeto_id (required), status, responsavel_id.

listar_projetosC

Lista todos os projetos cadastrados no sistema de Gestão de Tarefas.

Inputs: status.

listar_sprintsA

Lista as sprints visíveis, em ordem da mais recente para a mais antiga.

Inputs: no named parameters.

obter_contexto_projetoA

Identifica o projeto ativo com base no diretório de trabalho atual (via .gestaotarefas.json ou Git), verificando se o MCP deve operar ou se está desativado para projetos externos ou não identificados.

Inputs: diretorio_path.

obter_detalhes_demandaB

Consulta os detalhes completos de uma demanda específica, incluindo suas subtarefas e responsáveis.

Inputs: demanda_id (required).

renovar_sessaoB

Renova a sessão de autenticação do Gestão de Tarefas utilizando as credenciais salvas ou novas credenciais informadas.

Inputs: email, password.

sincronizar_fila_offlineB

Força o envio de todas as demandas e subtarefas que foram geradas localmente enquanto desconectado da VPN/intranet.

Inputs: no named parameters.

verificar_status_conexaoA

Informa o estado da conexão com a API da intranet, a validade do token de autenticação e a quantidade de itens na fila offline pendente.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools target distinct resources and actions, e.g. project context vs project listing, demand details vs active demand list. Some boundary ambiguity exists between atualizar_subtarefa and concluir_subtarefas, since both can change subtask statuses in bulk, but their primary intents are distinguishable.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in Portuguese snake_case (obter_, listar_, criar_, atualizar_, concluir_, etc.). There are no mixed conventions or inconsistent verb styles.

    Tool Count5/5

    14 tools is well within the appropriate range for a task-management MCP server. Each tool addresses a distinct workflow area: project context, demand lifecycle, subtask management, sprints, and offline/session handling.

    Completeness4/5

    The core demand/subtask lifecycle is covered: create, read, update, list, bulk conclude, and sprint association. Minor gaps exist such as no delete/archive operations and no all-demand listing beyond active demands, but these are workable.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers