# Servidor MCP de actions do Pipefy iPaaS

Este serviço expõe as actions das conexões já existentes no Pipefy iPaaS como tools MCP diretas. O upstream real é:

```text
https://ipaas.pipefy.com/mcp
```

Quando o Pipefy Agent chama `tools/list`, o servidor:

1. usa a sessão autenticada do `pipefy` CLI para obter um token iPaaS temporário;
2. lista somente as conexões ativas do pipe configurado;
3. descobre todas as actions de cada conexão;
4. monta imediatamente os schemas básicos, sem aguardar dropdowns autenticados;
5. retorna uma tool separada para cada combinação conexão + action;
6. em background, enriquece dropdowns e campos dinâmicos usando a conexão vinculada e guarda esses schemas em cache local.

Exemplo de tool materializada:

```text
conn_google_calendar_self__create_event__8f42d3a921
```

O título exibido é semelhante a `Google Calendar Self — Create Event`. A conexão fica vinculada internamente à tool: o agente fornece somente os campos da action e não pode trocar o `connectionExternalId`.

As tools genéricas do Activepieces, como `ap_list_connections`, `ap_research_pieces` e `ap_run_action`, não são expostas ao Pipefy Agent. Ao chamar uma tool materializada, o servidor a traduz internamente para uma execução única de `ap_run_action`. Nenhum flow é criado ou salvo.

## Executar localmente

1. Autentique o CLI no host com `pipefy auth login`.
2. Garanta que `uv` esteja no `PATH` e que `PIPEFY_TOOLKIT_DIR` aponte para o checkout do Pipefy Toolkit.
3. Copie `.env.example` para `.env`, escolha o pipe em `PIPEFY_IPAAS_PIPE_ID` e crie um valor longo e aleatório para `PROXY_MCP_TOKEN`. No Windows, mantenha `PIPEFY_KEYCHAIN_BACKEND=file` para usar a sessão já autenticada pelo CLI.
4. Inicie o servidor:

```sh
npm run start
```

O health check é `GET /healthz`. O endpoint MCP local é:

```text
http://localhost:8080/mcp
```

## Configuração no Pipefy Agent

Cadastre o endpoint MCP e passe o token do proxy no header:

```json
{
  "url": "http://localhost:8080/mcp",
  "headers": {
    "Authorization": "Bearer <PROXY_MCP_TOKEN>"
  }
}
```

Ao mapear o servidor, o Pipefy verá diretamente as actions agrupadas pelo nome da conexão. Se conexões ou actions mudarem, refaça o mapeamento para atualizar a seleção disponível ao usuário.

Na primeira descoberta, campos dinâmicos podem aparecer sem uma lista completa de opções. O enriquecimento continua em background; depois de concluído, um novo mapeamento reutiliza os schemas enriquecidos persistidos e inclui as opções resolvidas sem colocá-las no caminho crítico da requisição.

## Configuração

- `PIPEFY_IPAAS_PIPE_ID`: pipe que define o workspace iPaaS e suas conexões.
- `PIPEFY_TOOLKIT_DIR`: checkout local do Pipefy Toolkit, onde a sessão do CLI está autenticada.
- `PROXY_MCP_TOKEN`: única credencial enviada pelo cliente ao servidor.
- `PIPEFY_MCP_URL`: opcional; por padrão, `https://ipaas.pipefy.com/mcp`.
- `CATALOG_CONCURRENCY`: opcional; quantidade de schemas básicos resolvidos em paralelo, padrão `4`.
- `CATALOG_TTL_SECONDS`: opcional; tempo do catálogo em memória usado para reconhecer chamadas, padrão `300`. Cada `tools/list` sempre faz uma descoberta nova.
- `ENRICHMENT_CONCURRENCY`: opcional; quantidade de schemas autenticados enriquecidos em paralelo, padrão `4`.
- `ENRICHED_SCHEMA_TTL_SECONDS`: opcional; validade dos schemas enriquecidos persistidos, padrão `86400` (24 horas).
- `SCHEMA_CACHE_PATH`: opcional; arquivo do cache local, padrão `.cache/ipaas-schema-cache.json`.

O usuário não fornece token do Pipefy no `.env`. O servidor obtém credenciais temporárias a partir da sessão autenticada do CLI e nunca as retorna ao cliente ou grava em arquivo.

O cache persiste somente metadados de schema, incluindo possíveis nomes e IDs de opções pertencentes às conexões. Ele não contém tokens nem argumentos usados em actions, fica ignorado pelo Git e pelo Docker e deve permanecer protegido no host do serviço.

## Hospedagem

Este modo deve rodar no mesmo host em que `pipefy auth login` foi concluído. Para uma hospedagem remota ou multiusuário, use uma identidade própria de serviço e um modelo de autorização por requisição; não compartilhe a sessão pessoal de um desenvolvedor.

Em produção, publique `/mcp` com HTTPS, mantenha `PROXY_MCP_TOKEN` obrigatório e nunca exponha credenciais do Pipefy em configuração, logs ou respostas.