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 implementadas

Solicitacoes:

• requests.list
• requests.view
• requests.create

Dados auxiliares:

• requests.types
• requests.services
• requests.priorities
• requests.assignees
• requests.clients
• requests.units

Analitico:

• analytics.teamReport

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.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"
}

Instalacao

npm install

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)

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

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

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 solicitações
• quais são os tipos disponíveis?
• crie uma solicitação 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"
      }
    }
  }
}

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.