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
• requests.pending

Planejamento:

• planning.stages

Indicadores:

• indicators.list

Permissoes:

• permissions.list

Dados auxiliares:

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

Endpoints reais configurados

• 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>
• requests.pending
  • 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>

requests.list (filtros recomendados)

• assignee_id (opcional): ID do responsavel
• assignee_name (opcional): nome/login (ex: suporte.simeon)
• period (opcional): current_year (padrao) ou last_12_months

Exemplo para "listar as solicitacoes do usuario suporte.simeon do ultimo ano":

{
  "assignee_name": "suporte.simeon",
  "period": "last_12_months"
}

requests.pending

Busca as pendencias atrasadas do usuario autenticado no calendario do EPA. Nao recebe parametros.

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.

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 requests.pending 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.