Segue o README.md pronto, organizado para repositório corporativo.

Consignado MCP Local

Servidor MCP (Model Context Protocol – HTTP Dispatcher) para orquestração da jornada de empréstimo consignado via agente (ex: WhatsApp).

Este serviço:

• Centraliza regras de fluxo

• Resolve identidade (telefone → CPF → token)

• Impõe consistência de jornada via correlationId

• Aplica validações de segurança

• Implementa idempotência na criação de contrato

Ambiente atual: DEV (in-memory). Produção requer persistência, autenticação forte e proteção de PII.

Arquitetura

WhatsApp Agent
      ↓
  POST /call
      ↓
   MCP Server
      ↓
 Mock Core APIs

O agente nunca chama core direto. Toda regra de negócio e validação de sequência passa pelo MCP.

Conceitos

correlationId

Identifica uma jornada. Tudo que acontece fica vinculado a ele.

Regras:

• O channel não pode mudar no meio da jornada (409).

• O customerRef não pode trocar depois de resolvido (409).

Identity Resolution (WhatsApp)

Fluxo obrigatório no canal whatsapp:

1. lookup por telefone

2. se houver duplicidade → solicitar CPF

3. resolver identidade

4. só então liberar APIs de crédito

Se tentar pular etapa → 403.

CPF Token

• CPF nunca retorna ao agente.

• Após validação, o servidor gera cpfToken.

• get_loan_offers exige esse token.

• O token é validado contra a sessão.

DEV usa SHA256 simples. Produção deve usar HMAC com secret + TTL.

Endpoints

GET /tools

Lista tools disponíveis.

Response

{
  "tools": [
    "lookup_customer_by_phone",
    "resolve_identity_by_cpf",
    "get_identity_context",
    "check_eligibility",
    "get_loan_offers",
    "create_contract",
    "get_formalization_link"
  ]
}

POST /call

Dispatcher principal.

Request padrão

{
  "tool": "string",
  "input": {},
  "context": {
    "correlationId": "string",
    "channel": "app|web|whatsapp|agencia",
    "subject": "opcional"
  }
}

Response padrão

{
  "output": {}
}

GET /_debug/session/{cid} (DEV ONLY)

Retorna estado interno da sessão.

⚠ Remover ou proteger fortemente em produção.

Fluxo Oficial (WhatsApp)

1. lookup_customer_by_phone

2. resolve_identity_by_cpf (se necessário)

3. get_identity_context

4. check_eligibility

5. get_loan_offers

6. create_contract

7. get_formalization_link

Tools

lookup_customer_by_phone

Resolve cliente por telefone.

Input

{ "phone": "+5511999999999" }

Output (não encontrado)

{ "found": false, "reasonCode": "INVALID_PHONE" }

Output (1 cliente)

{ "found": true, "needsCpf": false }

Output (duplicado)

{ "found": true, "needsCpf": true }

Nunca retorna lista de clientes.

resolve_identity_by_cpf

Valida CPF quando há duplicidade.

Input

{ "cpf": "11122233344" }

Output (ok)

{ "resolved": true }

Output (erro)

{ "resolved": false, "reasonCode": "CPF_MISMATCH" }

get_identity_context

Retorna identidade resolvida.

Output (sem identidade)

{ "hasIdentity": false }

Output (com identidade)

{
  "hasIdentity": true,
  "customerRef": "cust_tok_302556",
  "cpfToken": "sha256..."
}

check_eligibility

Input

{
  "customerRef": "cust_tok_302556",
  "channel": "whatsapp"
}

Output

{
  "eligible": true,
  "eligibilityId": "uuid",
  "reasonCode": null
}

Valida:

• identidade resolvida (whatsapp)

• channel consistente

• jornada correta

get_loan_offers

Recebe cpfToken + valor solicitado.

Input

{
  "customerRef": "cust_tok_302556",
  "eligibilityId": "uuid",
  "cpfToken": "sha256...",
  "requestedAmount": 5000
}

Output

{
  "offers": [
    {
      "offerId": "offer-1",
      "requestedAmount": 5000,
      "approvedAmount": 5000,
      "installments": 24
    },
    {
      "offerId": "offer-2",
      "requestedAmount": 5000,
      "approvedAmount": 4500,
      "installments": 36
    }
  ]
}

Valida:

• eligibilityId pertence à jornada

• cpfToken bate com sessão

• requestedAmount > 0

create_contract

Possui idempotência.

Input

{
  "customerRef": "cust_tok_302556",
  "offerId": "offer-1",
  "idempotencyKey": "uuid",
  "acceptance": { "channel": "whatsapp" }
}

Output

{
  "contractId": "uuid",
  "status": "PENDING_VIDEO"
}

Se repetir idempotencyKey → retorna mesma resposta.

get_formalization_link

Input

{
  "customerRef": "cust_tok_302556",
  "contractId": "uuid"
}

Output

{
  "formalizationUrl": "https://video.plataforma.local/<contractId>",
  "expiresAt": "2026-12-31T23:59:59Z"
}

Códigos de Erro

Estados de Sessão

Rodando Local

uvicorn server:app --port 8001 --reload

Requisitos de Produção

1. Persistência externa (Redis/Dynamo)

2. Autenticação forte (JWT + mTLS)

3. HMAC real para cpfToken

4. Auditoria estruturada por tool

5. Rate limit por telefone

6. Proteção total de PII

7. Remoção do endpoint de debug

Observação Final

Este MCP centraliza:

• Controle de jornada

• Segurança de identidade

• Consistência transacional

• Blindagem do core contra chamadas fora de ordem

Ele não é apenas mock de API. É camada de governança de fluxo.