EPA MCP

Servidor MCP (Model Context Protocol) para integracao do sistema EPA com modelos de linguagem (LLMs).

Este projeto permite que assistentes de IA interajam com o EPA por meio de ferramentas estruturadas. O objetivo e permitir que usuarios utilizem linguagem natural para operar o sistema EPA.

Arquitetura

Fluxo principal:

Tool -> Service -> API Client -> EPA API

Camadas:

• CLI: interface de execucao local
• Server: servidor MCP
• Tools: ferramentas expostas ao agente
• Services: regras de negocio
• API Client: comunicacao com a API do EPA

Estrutura do projeto

src/
  agent/
  api/
  cli/
  config/
  core/
  services/
  tools/
  tests/
  utils/

Tools ativas

Solicitacoes:

• requests.list

Atividades:

• activities.list

Planejamento:

• planning.stages

Indicadores:

• indicators.list

Permissoes:

• permissions.list

Dados auxiliares:

• requests.types
• requests.priorities
• requests.assignees

Ocorrencias:

• occurrences.list

Riscos:

• risks.list

Planos de Acao:

• action_plans.list

Projetos:

• projects.list

Endpoints reais configurados

• requests.list
  • POST /api/api/os/listar
  • Query params enviados: ia=1, responsavel=<user>, data_inclusao=<ano corrente> (omitido se ids for informado)
  • Query params opcionais: data_inclusao, ids, with
• requests.types
  • GET /epa_os/ajax.php
  • Query params: action=get, controller=TipoSolicitacao
• requests.priorities
  • GET /api/api/prioridade
• requests.assignees
  • GET /api/api/usuarios/search
  • Query params obrigatorios: term, _type=query, q
  • Filtro opcional preparado: filters[unidade_gerencial][type]=pertenco e filters[unidade_gerencial][value]=<id>
• activities.list
  • GET /epa_principal/ajax.php
  • Query params: opcao=getCalendario, atrasadas=1
  • Header: Cookie: PHPSESSID=<EPA_PHP_SESSION_ID>
• planning.stages
  • GET /api/etapas-planejamento
  • Header: Authorization: Bearer <EPA_API_TOKEN>
• indicators.list
  • GET /indicadores-mcp.php
  • Query params opcionais: etapa=<id>, listar_indicadores=1, indicadores=<codigos separados por virgula>
  • Header: Cookie: PHPSESSID=<EPA_PHP_SESSION_ID>
• permissions.list
  • GET /api/api/check_permissoes
  • Header: Authorization: Bearer <EPA_API_TOKEN>
• occurrences.list
  • GET /api/api/ocorrencias
  • Query params enviados: details=1, per_page=500, page=1 e data_inclusao=<ano corrente>
  • Query params opcionais: status, whereHasSugestaoTitulo=1, titulo_ocorrencia, responsavel, per_page, page, data_inclusao, data_ocorrencia, ids, with
  • Header: Authorization: Bearer <EPA_API_TOKEN>
• risks.list
  • POST /api/api/riscos/riscos/grid/MatrizRiscos
  • Query params enviados: withControllers=1
  • Header: Authorization: Bearer <EPA_API_TOKEN>
• action_plans.list
  • GET /api/planos-de-acoes/listar
  • Header: API-TOKEN: <EPA_API_TOKEN> e Authorization: Bearer <EPA_API_TOKEN>
  • Query params opcionais: usuario_responsavel, usuario_inclusao, unidades, datainicio, datafim, datainicioprevista, datafimprevista, atrasada, status, with
• projects.list
  • GET /api/projetos
  • Header: API-TOKEN: <EPA_API_TOKEN> e Authorization: Bearer <EPA_API_TOKEN>
  • Query params enviados: lidar_com_permissoes=1
  • Query params opcionais: with (relacionamentos separados por vírgula)

requests.list (parâmetros)

• user (obrigatório): ID do usuário logado no EPA
• data_inclusao (opcional): período de datas no formato YYYY-MM-DDtoYYYY-MM-DD (ex: '2026-01-01to2026-12-31'). Se omisso (e ids não informado), filtra pelo ano corrente.
• ids (opcional): string com os IDs selecionados separados por vírgula (ex: '1,2,3'). Caso enviado (sem data_inclusao), o filtro de data padrão é ignorado.
• with (opcional): string com os relacionamentos a incluir no retorno separados por vírgula (osAcompanhamentos, osEncaminhamentos).

Exemplo para "listar as solicitações do usuário logado no ano de 2026":

{
  "user": 123,
  "data_inclusao": "2026-01-01to2026-12-31"
}

activities.list

Busca as atividades do usuário no EPA e salva os resultados em um banco de dados SQLite local temporário.

• user (obrigatório): ID do usuário logado no EPA que solicitou os dados.

A tool armazena os dados recebidos em um arquivo SQLite e retorna a referência dataset_id identificando o usuário nos metadados para reuso da LLM via execute_sqlite_query. Essa tool exige a variavel de ambiente EPA_PHP_SESSION_ID. O valor deve ser apenas o ID da sessao PHP; a requisicao envia o header:

Cookie: PHPSESSID=<EPA_PHP_SESSION_ID>

planning.stages

Busca as etapas de planejamento configuradas no EPA. Nao recebe parametros.

indicators.list

Busca os valores dos indicadores do EPA.

• etapa (opcional): ID da etapa retornado por planning.stages
• listar_indicadores (opcional): use 1 para retornar a lista de indicadores disponiveis para o usuario
• indicadores (opcional): string com os codigos dos indicadores separados por virgula

Quando etapa nao e informado, o EPA usa a etapa ativa, que corresponde ao mes atual. Quando indicadores e informado, o EPA filtra e retorna apenas os indicadores selecionados aos quais o usuario tem acesso. Essa tool exige a variavel de ambiente EPA_PHP_SESSION_ID e envia o cookie da sessao PHP.

permissions.list

Busca as permissoes do usuario autenticado no EPA. Nao recebe parametros. Essa tool usa o token da API do EPA configurado em EPA_API_TOKEN ou epaApiToken.

occurrences.list

Busca as ocorrencias do EPA.

• status (opcional): Concluido ou Em Andamento
• titulo_ocorrencia (opcional): texto a ser buscado no titulo da ocorrencia
• responsavel (opcional): ID do responsavel pela ocorrencia no EPA
• per_page (opcional): quantidade por pagina; padrao 500
• page (opcional): numero da pagina; padrao 1
• data_inclusao (opcional): periodo no formato YYYY-mm-dd_YYYY-mm-dd; padrao e o mes corrente (omitido se ids for informado)
• data_ocorrencia (opcional): periodo no formato YYYY-mm-dd_YYYY-mm-dd; nao e enviado quando omitido
• ids (opcional): string com os IDs de ocorrências separados por vírgula (ex: '1,2,3')
• with (opcional): string com relacionamentos a incluir separados por vírgula (rPlanosAcao, rOcorrenciaTipo)

A tool sempre envia details=1. Caso o parâmetro ids seja preenchido, o filtro padrão de data_inclusao é omitido para permitir a busca global por IDs. Quando titulo_ocorrencia e informado, tambem envia whereHasSugestaoTitulo=1. O retorno inclui has_next_page, que informa se existe uma proxima pagina. Essa tool usa o token da API do EPA configurado em EPA_API_TOKEN ou epaApiToken.

risks.list

Busca a matriz de riscos do EPA e salva os resultados em um banco de dados SQLite local temporário.

• user (obrigatório): ID do usuário logado no EPA
• withControllers (opcional): envia 1 para incluir os controladores dos riscos (enviado sempre como 1 por padrão na requisição)
• status (opcional): status do risco
• titulo (opcional): texto a ser buscado no título ou descrição do risco
• unidade_gerencial (opcional): ID da unidade gerencial
• per_page (opcional): quantidade por página; padrão 5000
• page (opcional): número da página; padrão 1

A tool sempre envia withControllers=1 na requisição à API do EPA. Armazena os dados recebidos em um arquivo SQLite e retorna a referência dataset_id para reuso da LLM via execute_sqlite_query. Essa tool usa o token da API do EPA configurado em EPA_API_TOKEN ou epaApiToken.

action_plans.list

Busca a lista de planos de ação do EPA na rota /api/planos-de-acoes/listar e salva os resultados em um banco de dados SQLite local temporário.

• usuario_responsavel (opcional): filtra pelo ID/usuário responsável
• usuario_inclusao (opcional): filtra pelo ID/usuário que incluiu
• unidades (opcional): string com IDs de unidades separados por vírgula (ex: '1,2,3')
• datainicio (opcional): data de início no formato d/m/Y (ex: '01/01/2026')
• datafim (opcional): data de fim no formato d/m/Y (ex: '31/12/2026')
• datainicioprevista (opcional): data de início prevista no formato d/m/Y (ex: '01/01/2026')
• datafimprevista (opcional): data de fim prevista no formato d/m/Y (ex: '31/12/2026')
• atrasada (opcional): envie 1 para filtrar pelos planos atrasados
• status (opcional): status do plano de ação ("Planejado", "Em Andamento" ou "Concluido")
• with (opcional): string com os relacionamentos a incluir no retorno separados por vírgula (usuarioResponsavel, unidadesGerenciais, objetivoEstrategico, indicadorBscDesc, acompanhamentos, acoesEstrategicas, tarefas)

A tool garante o envio do header API-TOKEN com o token da API configurado em EPA_API_TOKEN ou epaApiToken e retorna a referência dataset_id para reuso via execute_sqlite_query.

projects.list

Busca a lista de projetos do EPA na rota /api/projetos e salva os resultados em um banco de dados SQLite local temporário.

• with (opcional): string com os relacionamentos a incluir no retorno separados por vírgula. Possíveis valores:
  • unidadeGerencial: Traz a unidade gerencial do projeto
  • planosDeAcao: Traz os planos de ação vinculados ao projeto
  • gestor: Traz o gestor do projeto no campo r_gestor
  • metas: Traz as fases do projeto
  • metas.responsavel: Traz o responsável pela fase do projeto
  • metas.tarefas: Traz as tarefas vinculadas às fases do projeto
  • metas.tarefas.responsavel: Traz o responsável pelas tarefas vinculadas à fase do projeto

A tool sempre envia lidar_com_permissoes=1 na requisição e inclui o header API-TOKEN / Authorization: Bearer. Armazena os dados recebidos em um arquivo SQLite e retorna a referência dataset_id para reuso da LLM via execute_sqlite_query.

Instalacao

npm install

Observacao:

• este projeto usa legacy-peer-deps=true em .npmrc para contornar o conflito de peer dependency entre openai e zod durante a instalacao

Configuracao

Para clientes MCP (ex: Claude Desktop), configure as variaveis de ambiente:

• epaApiUrl (ou EPA_API_URL)
• epaApiToken (ou EPA_API_TOKEN)
• epaApiTimeoutMs (ou EPA_API_TIMEOUT_MS, opcional)
• EPA_PHP_SESSION_ID (obrigatorio para activities.list e indicators.list)

Opcionalmente, voce pode usar arquivo local config/config.json.

Exemplo:

{
  "epaApiUrl": "https://dev.sysepa.com.br/epa",
  "epaApiToken": "SEU_TOKEN",
  "epaApiTimeoutMs": 15000
}

Para uso da CLI, voce tambem pode executar o setup:

npm run dev setup

Esse comando configura a URL da API. Para login/token EPA da CLI:

npm run dev login

Os dados sao salvos em .env (se existir) ou config/config.json.

Arquivos de configuracao usados:

config/config.json

Execucao

Iniciar MCP Server em desenvolvimento:

npm run dev server

Iniciar agente OpenAI conectado ao MCP (CLI):

npm run dev agent

Ao iniciar o agent, a CLI valida se URL/token EPA estao configurados e se o token ainda e valido. Se estiver ausente/invalido, ela solicita login e senha para gerar novo token automaticamente.

No Windows (PowerShell com policy restritiva), use:

npm.cmd run dev agent

Se o ambiente bloquear spawn (erro EPERM, comum em ambientes restritos), use:

npm run build
node dist/cli/index.js agent

Build de producao:

npm run build

Executar CLI compilada:

npm run start -- server

Testes

npm test

SQL tecnico via CLI

Para validar consultas tecnicas em MySQL/MariaDB de forma isolada do MCP padrao, a CLI suporta um modo read-only.

Variaveis necessarias:

• DB_HOST
• DB_PORT (opcional, padrao 3306)
• DB_NAME
• DB_USER
• DB_PASSWORD
• DB_SSL (opcional, true ou false)

Alternativamente, essas credenciais podem ficar em config/config.json:

{
  "epaApiUrl": "https://dev.sysepa.com.br/epa",
  "epaApiToken": "SEU_TOKEN",
  "epaApiTimeoutMs": 15000,
  "sql": {
    "host": "127.0.0.1",
    "port": 3306,
    "database": "nome_do_banco",
    "user": "usuario",
    "password": "senha",
    "ssl": false
  }
}

Exemplo:

npm run dev sql "SELECT * FROM sua_tabela LIMIT 10"

Para validar a ideia de linguagem natural com apoio da LLM:

npm run dev sql-agent "quero listar os usuarios"

Voce tambem pode orientar melhor a geracao com pistas explicitas, por exemplo:

npm run dev sql-agent "quero listar os planos de acoes tabela: iniciativa5w2h e trazer nome do usuario que e o campo: quem e deve vincular com tabela clientes"

Tambem e possivel informar filtros, ordenacao e limite explicitamente:

npm run dev sql-agent "listar usuarios tabela: clientes filtro: ativo = 1 ordenar por: nome asc limite: 20"

Nesse modo, a CLI:

• le um resumo do schema do banco
• tenta identificar as tabelas mais provaveis para a pergunta
• respeita pistas explicitas como tabela:, campo: e vincular com tabela
• respeita pistas explicitas como filtro:, ordenar por: e limite:
• quando houver ambiguidade, pergunta qual tabela deve ser usada
• se a tabela correta nao aparecer na lista, permite informar o nome manualmente
• pede para a LLM montar um plano antes da SQL
• permite aprovar, corrigir ou cancelar esse plano
• so depois gera a SQL final
• valida a SQL (somente SELECT)
• executa a consulta
• mostra a pergunta, a SQL gerada e o resultado

Se a consulta nao for informada no comando, a CLI pede interativamente.

Regras atuais desse modo:

• aceita somente SELECT
• bloqueia comandos de escrita/DDL
• aceita apenas uma consulta por vez

Uso do Agent CLI

1. Instale dependencias:

npm install

2. Configure credenciais:

npm run dev setup
npm run dev login

No fluxo de login da CLI, informe:

• login EPA
• senha EPA
• OpenAI API KEY (somente para CLI/agent, se ainda nao estiver definida)

3. Inicie o agent:

npm run dev agent

4. Interaja no terminal com linguagem natural. Exemplos:

• liste minhas solicitacoes
• quais sao os tipos disponiveis?
• crie uma solicitacao para ...

O agent escolhe e executa automaticamente as tools MCP (requests.list, requests.types, requests.create, etc.) conforme o contexto da conversa.

Observacao de contexto:

• O agent usa janela deslizante para limitar o historico enviado ao modelo.
• Valor padrao: 30 mensagens nao-system.
• Para ajustar: defina a variavel AGENT_MAX_CONTEXT_MESSAGES.

Uso com Claude Desktop

Local (sem publicar no npm)

1. Gere o build:

npm run build

2. Configure o claude_desktop_config.json para executar o entrypoint MCP direto:

{
  "mcpServers": {
    "epa-local": {
      "command": "node",
      "args": [
        "C:\\Users\\renat\\OneDrive\\Documentos\\projetos\\epa_mcp\\dist\\server\\stdioServer.js"
      ],
      "env": {
        "epaApiUrl": "https://dev.sysepa.com.br/epa",
        "epaApiToken": "SEU_TOKEN",
        "epaApiTimeoutMs": "15000",
        "EPA_PHP_SESSION_ID": "SEU_ID_DE_SESSAO_PHP"
      }
    }
  }
}

3. Reinicie o Claude Desktop.

Publicado no npm

npx epa-mcp

CLI como extra (opcional):

npx epa-mcp-cli setup
npx epa-mcp-cli agent

Observacoes

• Os textos de prompt e mensagens do projeto permanecem em portugues.
• Os identificadores tecnicos (arquivos, diretorios, classes e nomes de tools) seguem padrao em ingles.