epa-testeprojetoia 0.1.0

package/.idea/epa_mcp.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/epa_mcp.iml" filepath="$PROJECT_DIR$/.idea/epa_mcp.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/php.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MessDetectorOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PHPCSFixerOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PHPCodeSnifferOptionsConfiguration">
+    <option name="highlightLevel" value="WARNING" />
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PhpStanOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PsalmOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/AGENTS.md

@@ -0,0 +1,10 @@
+# AGENTS.md
+
+## Documentation policy
+
+- Sempre que houver mudanca importante no projeto (novas tools, renomeacao de contratos publicos, mudanca de comandos, fluxo de setup/execucao/teste), atualize o `README.md` no mesmo trabalho.
+- Nao finalize alteracoes que impactem uso do projeto sem revisar consistencia entre codigo e README.
+- Priorize manter no README:
+  - comandos reais do `package.json`
+  - nomes atuais das tools MCP
+  - pre-requisitos de configuracao

package/README.md

@@ -0,0 +1,339 @@
+# 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:
+
+```text
+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
+
+```text
+src/
+  agent/
+  api/
+  cli/
+  config/
+  core/
+  services/
+  tools/
+  tests/
+  utils/
+```
+
+## Tools ativas
+
+Solicitacoes:
+
+- `requests.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.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":
+
+```json
+{
+  "assignee_name": "suporte.simeon",
+  "period": "last_12_months"
+}
+```
+
+## Instalacao
+
+```bash
+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`.
+
+Exemplo:
+
+```json
+{
+  "epaApiUrl": "https://dev.sysepa.com.br/epa",
+  "epaApiToken": "SEU_TOKEN",
+  "epaApiTimeoutMs": 15000
+}
+```
+
+Para uso da CLI, voce tambem pode executar o setup:
+
+```bash
+npm run dev setup
+```
+
+Esse comando configura a URL da API. Para login/token EPA da CLI:
+
+```bash
+npm run dev login
+```
+
+Os dados sao salvos em `.env` (se existir) ou `config/config.json`.
+
+Arquivos de configuracao usados:
+
+```text
+config/config.json
+```
+
+## Execucao
+
+Iniciar MCP Server em desenvolvimento:
+
+```bash
+npm run dev server
+```
+
+Iniciar agente OpenAI conectado ao MCP (CLI):
+
+```bash
+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:
+
+```bash
+npm.cmd run dev agent
+```
+
+Se o ambiente bloquear `spawn` (erro `EPERM`, comum em ambientes restritos), use:
+
+```bash
+npm run build
+node dist/cli/index.js agent
+```
+
+Build de producao:
+
+```bash
+npm run build
+```
+
+Executar CLI compilada:
+
+```bash
+npm run start -- server
+```
+
+## Testes
+
+```bash
+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`:
+
+```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:
+
+```bash
+npm run dev sql "SELECT * FROM sua_tabela LIMIT 10"
+```
+
+Para validar a ideia de linguagem natural com apoio da LLM:
+
+```bash
+npm run dev sql-agent "quero listar os usuarios"
+```
+
+Voce tambem pode orientar melhor a geracao com pistas explicitas, por exemplo:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+npm install
+```
+
+2. Configure credenciais:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+npm run build
+```
+
+2. Configure o `claude_desktop_config.json` para executar o entrypoint MCP direto:
+
+```json
+{
+  "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
+
+```bash
+npx epa-mcp
+```
+
+CLI como extra (opcional):
+
+```bash
+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.

package/dist/agent/agentHelpers.js

@@ -0,0 +1,21 @@
+import { buildToolNameMaps as buildBaseToolNameMaps } from "../utils/toolNameMaps.js";
+export function buildToolNameMaps(toolNames) {
+    const { internalToExternal, externalToInternal } = buildBaseToolNameMaps(toolNames);
+    return {
+        mcpToOpenAi: internalToExternal,
+        openAiToMcp: externalToInternal
+    };
+}
+export function isSpawnPermissionError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const maybeCode = error.code;
+    return maybeCode === "EPERM" && error.message.includes("spawn");
+}
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/agent/openaiAgent.js

@@ -0,0 +1,170 @@
+import OpenAI from "openai";
+import readline from "readline";
+import path from "path";
+import { fileURLToPath } from "url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { loadConfig } from "../config/loadConfig.js";
+import { ensureCliAuth } from "../config/ensureCliAuth.js";
+import { createMcpServer } from "../server/server.js";
+import { applySlidingWindow } from "./slidingWindow.js";
+import { buildToolNameMaps, getErrorMessage, isSpawnPermissionError } from "./agentHelpers.js";
+const DEFAULT_MAX_NON_SYSTEM_MESSAGES = 30;
+export async function startAgent() {
+    await ensureCliAuth();
+    const config = loadConfig();
+    const apiKey = process.env.OPENAI_API_KEY || config.openaiApiKey;
+    if (!apiKey) {
+        throw new Error("OpenAI API key nao encontrada. Defina OPENAI_API_KEY ou configure via setup.");
+    }
+    const openai = new OpenAI({ apiKey });
+    const currentFilePath = fileURLToPath(import.meta.url);
+    const isDevRuntime = currentFilePath.endsWith(".ts");
+    const cliEntry = path.resolve(path.dirname(currentFilePath), "..", "cli", isDevRuntime ? "index.ts" : "index.js");
+    const client = new Client({
+        name: "epa-agent",
+        version: "0.1.0"
+    }, { capabilities: {} });
+    try {
+        const transport = new StdioClientTransport(isDevRuntime
+            ? {
+                command: process.execPath,
+                args: ["--import", "tsx", cliEntry, "server"]
+            }
+            : {
+                command: process.execPath,
+                args: [cliEntry, "server"]
+            });
+        await client.connect(transport);
+    }
+    catch (error) {
+        if (!isSpawnPermissionError(error)) {
+            throw error;
+        }
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        const server = await createMcpServer();
+        await server.connect(serverTransport);
+        await client.connect(clientTransport);
+        console.log("Aviso: modo in-memory ativado por restricao de spawn no ambiente.");
+    }
+    const toolsResponse = await client.listTools();
+    const toolNames = toolsResponse.tools.map((tool) => tool.name);
+    const { mcpToOpenAi, openAiToMcp } = buildToolNameMaps(toolNames);
+    const tools = toolsResponse.tools.map((tool) => ({
+        type: "function",
+        function: {
+            name: mcpToOpenAi.get(tool.name) ?? tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema
+        }
+    }));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    console.log("EPA Agent iniciado");
+    const messages = [
+        {
+            role: "system",
+            content: `
+Voce e um assistente que opera o sistema EPA.
+
+Sempre utilize as ferramentas disponiveis quando necessario.
+
+Fluxo recomendado para criar solicitacoes:
+
+1. consultar requests.types
+2. consultar requests.services
+3. consultar requests.priorities/requests.assignees/requests.clients
+4. executar requests.create
+
+Para listar solicitacoes por usuario e periodo, prefira requests.list com:
+- assignee_name (ex: suporte.simeon)
+- period=last_12_months para "ultimo ano"
+
+Regra para analise:
+- Se voce ja recebeu uma lista de solicitacoes no contexto atual, faca a analise diretamente desses dados.
+- Nao chame analytics.teamReport para analisar dados que ja estao no contexto.
+- So use analytics.teamReport quando o usuario pedir explicitamente para buscar analise de um usuario especifico ou da equipe (ex: "analise da equipe", "relatorio do usuario X").
+- Se analytics.teamReport nao for necessario, responda sem chamar tools.
+`
+        }
+    ];
+    const configuredMax = Number(process.env.AGENT_MAX_CONTEXT_MESSAGES);
+    const maxNonSystemMessages = Number.isFinite(configuredMax) && configuredMax > 0
+        ? configuredMax
+        : DEFAULT_MAX_NON_SYSTEM_MESSAGES;
+    rl.on("line", async (input) => {
+        try {
+            messages.push({
+                role: "user",
+                content: input
+            });
+            applySlidingWindow(messages, maxNonSystemMessages);
+            let running = true;
+            while (running) {
+                const completion = await openai.chat.completions.create({
+                    model: "gpt-4o-mini",
+                    messages,
+                    tools,
+                    tool_choice: "auto"
+                });
+                const message = completion.choices[0].message;
+                messages.push(message);
+                applySlidingWindow(messages, maxNonSystemMessages);
+                if (!message.tool_calls) {
+                    console.log("\n[agent]", message.content, "\n");
+                    running = false;
+                    break;
+                }
+                for (const toolCall of message.tool_calls) {
+                    const openAiToolName = toolCall.function.name;
+                    const toolName = openAiToMcp.get(openAiToolName) ?? openAiToolName;
+                    let args;
+                    try {
+                        args = JSON.parse(toolCall.function.arguments || "{}");
+                    }
+                    catch (error) {
+                        const errorMessage = getErrorMessage(error);
+                        console.error(`\n[erro] Argumentos invalidos para ${toolName}: ${errorMessage}\n`);
+                        messages.push({
+                            role: "tool",
+                            tool_call_id: toolCall.id,
+                            content: JSON.stringify([{ type: "text", text: `Erro: argumentos invalidos (${errorMessage})` }])
+                        });
+                        applySlidingWindow(messages, maxNonSystemMessages);
+                        continue;
+                    }
+                    console.log(`\n[tool] Executando: ${toolName}`);
+                    try {
+                        const result = await client.callTool({
+                            name: toolName,
+                            arguments: args
+                        });
+                        messages.push({
+                            role: "tool",
+                            tool_call_id: toolCall.id,
+                            content: JSON.stringify(result.content)
+                        });
+                        applySlidingWindow(messages, maxNonSystemMessages);
+                    }
+                    catch (error) {
+                        const errorMessage = getErrorMessage(error);
+                        console.error(`\n[erro] Falha ao executar ${toolName}: ${errorMessage}\n`);
+                        messages.push({
+                            role: "tool",
+                            tool_call_id: toolCall.id,
+                            content: JSON.stringify([{ type: "text", text: `Erro ao executar tool: ${errorMessage}` }])
+                        });
+                        applySlidingWindow(messages, maxNonSystemMessages);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const errorMessage = getErrorMessage(error);
+            console.error(`\n[erro] Falha no processamento da mensagem: ${errorMessage}\n`);
+        }
+    });
+}

package/dist/agent/slidingWindow.js

@@ -0,0 +1,13 @@
+export function applySlidingWindow(messages, maxNonSystemMessages) {
+    if (!Number.isFinite(maxNonSystemMessages) || maxNonSystemMessages < 1) {
+        return;
+    }
+    const systemMessage = messages.find((message) => message?.role === "system");
+    const nonSystemMessages = messages.filter((message) => message?.role !== "system");
+    const trimmedNonSystem = nonSystemMessages.slice(-maxNonSystemMessages);
+    messages.length = 0;
+    if (systemMessage) {
+        messages.push(systemMessage);
+    }
+    messages.push(...trimmedNonSystem);
+}

package/dist/api/epaApiClient.js

@@ -0,0 +1,59 @@
+import axios from "axios";
+import { loadConfig } from "../config/loadConfig.js";
+export class EpaApiClient {
+    client;
+    constructor() {
+        const config = loadConfig();
+        const timeoutMs = Number(config.epaApiTimeoutMs ??
+            process.env.EPA_API_TIMEOUT_MS ??
+            15000);
+        this.client = axios.create({
+            baseURL: config.epaApiUrl,
+            timeout: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 15000,
+            headers: {
+                Authorization: `Bearer ${config.epaApiToken}`
+            }
+        });
+    }
+    async get(endpoint, params) {
+        try {
+            const response = await this.client.get(endpoint, { params });
+            return response.data;
+        }
+        catch (error) {
+            throw this.formatError(error, "GET", endpoint);
+        }
+    }
+    async post(endpoint, body = {}, params) {
+        try {
+            const response = await this.client.post(endpoint, body, { params });
+            return response.data;
+        }
+        catch (error) {
+            throw this.formatError(error, "POST", endpoint);
+        }
+    }
+    formatError(error, method, endpoint) {
+        if (axios.isAxiosError(error)) {
+            const status = error.response?.status;
+            const apiMessage = this.extractApiMessage(error.response?.data);
+            const suffix = status ? `status ${status}` : "sem status HTTP";
+            return new Error(`[EPA API] ${method} ${endpoint} falhou (${suffix}): ${apiMessage}`);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return new Error(`[EPA API] ${method} ${endpoint} falhou: ${message}`);
+    }
+    extractApiMessage(data) {
+        if (typeof data === "string" && data.trim()) {
+            return data;
+        }
+        if (data && typeof data === "object") {
+            const maybeMessage = data.message ?? data.error;
+            if (typeof maybeMessage === "string" && maybeMessage.trim()) {
+                return maybeMessage;
+            }
+            return JSON.stringify(data);
+        }
+        return "erro sem detalhes retornados pela API";
+    }
+}