# Assistente Financeiro (MCP Server)

Servidor [MCP](https://modelcontextprotocol.io) de exemplo, construído com o
SDK `mcp` (`MCPServer`), que expõe:

- **Tool** `adiciona(a, b)` — soma dois números inteiros.
- **Resource** `memory://despesas_mensais` — lê o conteúdo de
  [servers/contas_a_pagar.txt](servers/contas_a_pagar.txt).
- **Prompt** `formatar_dado_cadastral(cpf)` — gera um prompt para formatar um
  CPF no padrão `xxx.xxx.xxx-xx`.

## Pré-requisitos

- **Python 3.11** (o `.venv` deste projeto foi criado com essa versão via
  [pyenv-win](https://github.com/pyenv-win/pyenv-win)).
- **Node.js + npx** — necessários apenas para `mcp dev`, que baixa e executa o
  [MCP Inspector](https://github.com/modelcontextprotocol/inspector) via
  `npx`. Verifique com:

  ```powershell
  node --version
  npx --version
  ```

## Instalação

```powershell
# 1. Criar o ambiente virtual (se ainda não existir)
python -m venv .venv

# 2. Ativar o ambiente virtual
.venv\Scripts\Activate.ps1

# 3. Instalar as dependências
pip install -r requirements.txt
```

> As dependências foram congeladas com `pip freeze` a partir de um ambiente
> compartilhado com outros projetos (Streamlit, OpenAI Agents, pandas, etc.)
> — nem tudo ali é usado por este servidor. O único pacote realmente
> necessário para rodar `servers/server_test.py` é o `mcp` (com o extra
> `cli`, para os comandos `mcp dev`/`mcp run`):
>
> ```powershell
> pip install "mcp[cli]"
> ```

## Executando o servidor

### Opção 1 — Modo desenvolvimento (MCP Inspector)

Sobe o servidor junto com o MCP Inspector (interface web para testar tools,
resources e prompts manualmente):

```powershell
mcp dev servers/server_test.py
```

Isso abre o Inspector em `http://localhost:6274` (o token de sessão aparece
no terminal). Requer Node/npx instalados, conforme os pré-requisitos acima.

### Opção 2 — Execução direta (stdio)

Para rodar o servidor "puro", sem o Inspector — modo usado por clientes MCP
(Claude Desktop, etc.) que já falam o protocolo via stdio:

```powershell
mcp run servers/server_test.py
```

### Opção 3 — Registrar no Claude Desktop

```powershell
mcp install servers/server_test.py
```

## Variáveis de ambiente

Existe um arquivo `.env` na raiz do projeto. O servidor atual
(`server_test.py`) **não lê** essas variáveis (não há `load_dotenv()`),
então ele funciona mesmo sem o `.env`.

> ⚠️ **Atenção:** o `.env` deste repositório contém uma chave real da OpenAI
> em texto puro. Não faça commit desse arquivo e recomenda-se rotacionar a
> chave. Se algum código futuro precisar dela, carregue com
> `python-dotenv`:
> ```python
> from dotenv import load_dotenv
> load_dotenv()
> ```

## Estrutura do projeto

```
mcp-server/
├── .env                       # variáveis de ambiente (não versionar)
├── requirements.txt           # dependências (pip freeze do ambiente)
└── servers/
    ├── server_test.py         # servidor MCP (tool, resource, prompt)
    └── contas_a_pagar.txt     # dados lidos pelo resource despesas_mensais
```

## Observações de compatibilidade

- Este projeto usa `mcp==2.1.1`. Na versão 2.x, `FastMCP` foi renomeado para
  `MCPServer` (`from mcp.server.mcpserver import MCPServer`) — se for
  consultar exemplos antigos do SDK (`FastMCP`), adapte o import.
- O pacote `openai-agents==0.0.14` (presente no `requirements.txt`, mas não
  usado por este servidor) exige `mcp<2`. Isso significa que
  `pip install -r requirements.txt` **falha** do zero por conflito de
  dependências caso ambos sejam instalados juntos. Se você não usa
  `openai-agents` neste projeto, pode removê-lo do `requirements.txt`; caso
  use, atualize-o para `>=0.19` (compatível com `mcp<3,>=1.19.0`).