Bank of Sajo

Entidade banco da cidade GTA7 Lab. Guarda as contas e o histórico de transações da cidade — PIX, cartão, maquininha de comerciante, empréstimo, câmbio e ações — e expõe consulta de saldo, busca de transações, PIX e simulação de crédito como MCP tools.

Projeto Next.js independente, sem banco de dados. Repo proprio dentro da org GTA7-Lab; a cidade em GTA7-Lab/gta7-lab consome esta entidade pelo endpoint MCP publicado.

Rodar localmente

git clone https://github.com/GTA7-Lab/bank-of-sajo.git
cd bank-of-sajo
npm install
npm run dev


UI	http://localhost:3000 — página institucional, sem dados
MCP	`POST /api/mcp` (streamable HTTP) — única porta de acesso aos dados
Manifesto	`GET /api/manifest` — só metadados da entidade

MCP tools

As respostas são escritas para gente ler — conversa, sem jargão. Os dados vão junto em structuredContent, que é o que o Core Orchestrator consome.

Clientes (CRUD completo)

tool	o que faz
`create_customer`	cadastra pessoa ou empresa
`get_customer`	dados do cliente e as contas dele
`list_customers`	lista, com filtro por nome, bairro ou perfil
`update_customer`	muda nome, bairro, perfil ou gerente
`delete_customer`	encerra o cadastro; recusa se houver saldo

Contas e dinheiro

tool	o que faz
`open_account`	abre conta corrente, poupança, empresarial ou de investimento
`get_account_balance`	saldo, titular e últimas movimentações
`search_transactions`	busca por conta, tipo, valor, período ou descrição
`send_pix`	PIX entre contas, conferindo o saldo
`pay_bill`	paga contas e boletos — credita o destinatário se ele for da cidade
`charge_customer`	maquininha: o negócio cobra um cliente por PIX, débito ou crédito
`issue_card`	emite cartão de débito ou crédito

Catálogo — restrito pela palavra mágica

create_product, update_product, delete_product, create_service, update_service, delete_service mexem no que o banco oferece, então só rodam com o parâmetro magicWord. Sem ele — ou com a palavra errada — a tool recusa educadamente, sem erro técnico.

A palavra padrão é abre-te-sajo. Para trocar, defina a variável de ambiente BANK_MAGIC_WORD no projeto da Vercel. Vale dizer o que isso é e o que não é: uma trava contra alteração acidental do catálogo, não autenticação — o endpoint é público e a palavra viaja como parâmetro comum.

Comércio da cidade

charge_customer é a maquininha do banco: o restaurante, o cinema ou o supermercado cobram um morador e o dinheiro cai na conta na hora, já descontada a taxa do lojista — PIX sem taxa, débito 1,5%, crédito 3,5% (em merchantFees, no JSON).

pay_bill fecha o outro lado: quando quem recebe também tem conta aqui, o valor entra de verdade na conta dele; fornecedor de fora do banco fica só como saída.

Todas as tools que pedem uma conta aceitam número (ACC-1004), chave PIX ou o nome do cliente — então "cobre a Carla pela Padaria Pão da Vila" funciona sem ninguém decorar número de conta.

Produtos

tool	o que faz
`list_services`	os 21 serviços do banco, por categoria
`list_products`	linhas de crédito e opções de investimento
`simulate_loan`	simula a parcela, sem contratar
`request_loan`	contrata financiamento de imóvel, veículo, solar, pessoal ou empresarial
`invest`	aplica em poupança, CDB, fundo de ações ou FIDC

Testar todas contra um servidor rodando:

npm run test:mcp                                          # localhost:3000
MCP_URL=https://<dominio>/api/mcp npm run test:mcp         # deploy

Conectar no Claude Code (a pasta já traz .mcp.json apontando para localhost):

claude mcp add --transport http bank-of-sajo http://localhost:3000/api/mcp

Os dados só saem por MCP

Não existe endpoint HTTP que devolva conta, cliente, saldo ou transação, e a página não lista nada disso — é institucional. Quem quiser os dados usa as tools, onde as regras do banco valem: saldo conferido antes de um PIX, cadastro que não se encerra com dinheiro em conta, catálogo protegido por palavra mágica.

/api/accounts e /api/transactions existiram e foram removidos por essa razão.

Dados

Tudo em data/bank.json: clientes, contas, transações, cartões, produtos de crédito e investimento, ações e parceiros da cidade.

O JSON não guarda saldo. Ele é derivado — openingBalance + créditos − débitos — em getBalance(), então saldo e extrato nunca divergem, inclusive depois de um send_pix.

Transações escritas por send_pix ficam em memória: o disco é somente leitura em serverless, então elas se perdem quando a instância recicla. Suficiente para a demo, e é o primeiro ponto a trocar quando a cidade precisar de persistência real.

Integração com o Core

A entidade se descreve em manifest.json (id, nome, transporte, tools) e serve o mesmo conteúdo em GET /api/manifest.

A entidade está registrada em core/data/entities.json sob a tag finance, cujas palavras-chave vivem em core/src/lexicon.ts — banco, saldo, extrato, pix, boleto, empréstimo, câmbio, investimento e afins.

Só search_transactions entra como kind: "search", que é o único tipo que o Core chama por conta própria. get_account_balance, simulate_loan e principalmente send_pix ficam como other: movimentar dinheiro precisa de conta de origem, destino e valor explícitos, não de uma frase solta interpretada pelo orquestrador.

Como o Core manda a frase inteira do pedido como termo de busca, searchTransactions aceita tanto a expressão completa quanto qualquer palavra relevante dela — é o que faz "ver o extrato de pix da cidade" devolver as transações de PIX em vez de nada.

Deploy

Projeto Next.js padrão, sem variáveis de ambiente. Na Vercel, o Root Directory é a raiz do repo. Em produção: https://gta7-lab-bank-tbone3.vercel.app — o MCP fica em /api/mcp, que é o endpoint registrado no Core.

Arquivos

data/bank.json           dados da entidade
lib/bank.ts              consultas, saldo derivado, PIX e simulação de crédito
app/api/mcp/route.ts     servidor MCP (mcp-handler)
app/api/*/route.ts       REST: accounts, transactions, manifest
app/page.tsx             UI: contas e extrato filtrável
scripts/test-mcp.mjs     cliente de teste das tools

bank-of-sajo