convez.ai
MCP ServerFinanceiroAvançado
btholath

Annuities Platform — MCP Server

btholath/annuities-platform

MCP server de dados de anuidades com tools e prompts para análise de portfólios

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em Python para gestão de serviços de aposentadoria e anuidades, integrado ao Claude Code. Oferece ferramentas para consulta de contratos, busca multi-critério, cálculos de payout e relatórios de portfólio em tempo real.

Instalação

$npx convez-ai btholath/annuities-platform

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Análise de portfólios de aposentadoria
  • Consulta de contratos de anuidades e suitability
  • Cálculo de projeções de payout e amortização
  • Pesquisa e filtragem multi-campo de clientes
  • Geração de relatórios agregados por risco/produto/região

Veredito

Projeto robusto e educacional que demonstra arquitetura agentic completa (MCP + Claude Code + Flask) em domínio financeiro real. Bem documentado, com setup automatizado e dataset reproduzível; ideal para estudo de integração MCP ou prototipagem de plataformas de análise de investimentos.

README

A tradução para o português deste README ainda está na fila.

annuities-platform

Retirement Services & Annuities — Combined Monorepo Built for the Claude Certified Architect Foundations (CCAF) exam study lab.

annuities-platform/
├── flask_app/          ← RetireWise web UI  (Flask, port 5000)
├── mcp_server/         ← FastMCP server     (Claude Code, stdio)
├── data/               ← Shared 500-row annuities dataset
├── scripts/setup.sh    ← One-command first-time setup
├── Makefile            ← All common tasks
├── CLAUDE.md           ← Root context for Claude Code
└── .vscode/            ← launch.json  mcp.json  settings.json

Quick start

# 1. Unzip and enter the project
cd ~/annuities-platform

# 2. One-command setup  (venv + deps + data + MCP registration + tests)
bash scripts/setup.sh
# — or —
make setup

# 3. Open in VS Code
code .

# 4. Start Flask web app
make flask
# → http://localhost:5000

Day-to-day commands

TaskCommand
Start Flask web appmake flask
Run all 38 testsmake test
Test MCP server standalonemake mcp-test
Re-register MCP with Claude Codemake mcp-add
Regenerate datasetmake data
Install / update depsmake install

Flask web app — pages

URLWhat you see
http://localhost:5000/Portfolio dashboard — stat cards, product/risk/state breakdowns
/clientsPaginated, sortable, filterable list of all 500 clients
/client/CLIENT_0001Full contract detail + suitability assessment + payout projection
/searchMulti-field search form (product, risk, state, rider, premium range)
/api/portfolioJSON portfolio summary
/api/client/CLIENT_0001JSON single contract
/api/clients?risk_profile=AggressiveJSON filtered list

MCP server — tools

ToolWhat it does
get_client(client_id)Full contract for one client
search_clients(...)Filter by product/risk/state/premium
portfolio_summary(group_by)Aggregate stats by any column
calculate_payout(principal, rate, years)Amortized monthly payout
calculate_percentage(value, pct)Simple percentage utility

Prompts: annuity_review, client_summary, portfolio_report Resource: annuities://dataset


Claude Code integration

After make setup or make mcp-add:

claude           # launch Claude Code in this project
/mcp             # → annuities-server ✔ Connected
/memory          # → shows all 3 CLAUDE.md files loaded

# Try it:
"Use the annuities-server to look up CLIENT_0001"
"Give me a portfolio summary grouped by risk_profile"
"Use the annuity_review prompt for CLIENT_0050"

Project structure — full

annuities-platform/
│
├── .env.example               ← Copy to .env and add ANTHROPIC_API_KEY
├── .gitignore
├── Makefile                   ← make setup | flask | test | mcp-test
├── requirements.txt           ← Flask + mcp[cli] + pydantic + pytest
├── CLAUDE.md                  ← Root context (all subfolders inherit)
│
├── .vscode/
│   ├── launch.json            ← F5 to run Flask; also test + data configs
│   ├── mcp.json               ← Wires MCP server into Claude Code / VS Code
│   └── settings.json          ← Python interpreter = .venv, pytest config
│
├── data/
│   ├── annuities.csv          ← 500 synthetic rows (seed=42, reproducible)
│   └── generate_data.py       ← Regenerate: python data/generate_data.py
│
├── scripts/
│   └── setup.sh               ← One-shot: venv + pip + data + MCP + tests
│
├── flask_app/
│   ├── CLAUDE.md              ← Flask-specific rules (inherits root)
│   ├── src/
│   │   ├── app.py             ← create_app() factory + entry point
│   │   ├── models.py          ← AnnuityContract dataclass, load/filter/aggregate
│   │   ├── views.py           ← All routes (HTML + /api/* JSON)
│   │   ├── templates/
│   │   │   ├── layout.html    ← Base: header, nav, footer
│   │   │   ├── index.html     ← Dashboard
│   │   │   ├── clients.html   ← Paginated sortable list
│   │   │   ├── client.html    ← Contract detail + suitability
│   │   │   └── search.html    ← Search/filter form
│   │   └── static/css/
│   │       └── styles.css     ← Responsive dark-header design
│   └── tests/
│       └── test_app.py        ← 38 pytest tests (HTML routes + JSON API + models)
│
└── mcp_server/
    ├── CLAUDE.md              ← MCP-specific rules (inherits root)
    ├── server.py              ← FastMCP server (5 tools + 1 resource + 3 prompts)
    ├── test_client.py         ← Standalone MCP protocol test (no Claude needed)
    └── templates/
        ├── annuity_review/    ← config.yaml + template.md
        ├── client_summary/    ← config.yaml + template.md
        └── portfolio_report/  ← config.yaml + template.md

CCAF exam coverage

File / featureDomain
mcp_server/server.py — 5 tools, 1 resource, 3 promptsDomain 2
stdio transport, claude mcp add with venv pathDomain 2
3-level CLAUDE.md hierarchy (root / flask_app / mcp_server)Domain 3
.vscode/mcp.json + slash commandsDomain 3
flask_app/src/models.py — Pydantic-style typed dataclassDomain 4
JSON API endpoints with structured outputDomain 4
mcp_server/templates/ — YAML-driven prompt templatesDomain 4
Shared data/ — single source of truth across both appsDomain 5

Environment variables

VariableDefaultDescription
ANTHROPIC_API_KEY—Required for Claude Code / Python scripts calling the API
DATA_FILEdata/annuities.csvOverride path to dataset
SECRET_KEYdev-annuities-keyFlask session key — change in production
FLASK_DEBUG1 (in .env)Enable Flask debug mode
Ver o original no GitHub

Bom para

Relacionados