# MCP Spreadsheet PoC

PoC em Python de um servidor MCP que expoe **resources**, **tools** e **prompts** para trabalhar com arquivos `.xlsx` em um diretorio isolado.

## Arquitetura

- **Host**: Claude Desktop, VS Code/Copilot ou MCP Inspector.
- **Client**: cliente MCP embutido no host.
- **Server**: este projeto, executado via `stdio`.
- **Resources**: catalogo, metadados e aba em JSON, todos somente leitura.
- **Tools**: leitura de intervalo, criacao, inclusao de linhas, atualizacao de celula e resumo numerico.
- **Prompt**: roteiro reutilizavel para analise de vendas.

## Seguranca da PoC

- acesso restrito a `MCP_SPREADSHEET_DATA_DIR`;
- somente `.xlsx`;
- bloqueio de path traversal;
- escrita desligavel por variavel de ambiente;
- sem sobrescrita na criacao;
- backup automatico antes de alteracoes;
- limite de linhas por operacao;
- nenhuma formula, macro ou comando e executado pelo servidor.

## Inicio rapido no PowerShell

```powershell
cd .\mcp_spreadsheet_poc
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[dev]"
python .\scripts\create_demo.py
mcp dev .\src\mcp_spreadsheet\server.py
```

O comando `mcp dev` abre o MCP Inspector e requer Node.js/npx no PATH. No Inspector, experimente:

1. Resource `spreadsheet://catalog`.
2. Tool `read_range` com `vendas_demo.xlsx`, `Vendas`, `A1:F5`.
3. Tool `summarize_column` com coluna `D`.
4. Prompt `analyze_sales`.

## Execucao direta por stdio

```powershell
$env:MCP_SPREADSHEET_DATA_DIR = (Resolve-Path .\data)
$env:MCP_SPREADSHEET_ALLOW_WRITE = "true"
mcp-spreadsheet
```

Copie e adapte `mcp.json` para o formato de configuracao aceito pelo host escolhido. Prefira caminho absoluto no campo `MCP_SPREADSHEET_DATA_DIR`.

## Testes e qualidade

```powershell
pytest
ruff check .
mypy src
```

## Cenarios de demonstracao

- Pergunta: "Quais planilhas estao disponiveis?" O host consulta o resource de catalogo.
- Leitura: "Mostre as vendas A1:F5." O modelo chama `read_range`.
- Analise: "Qual a media de quantidade?" O modelo chama `summarize_column`.
- Escrita: "Adicione uma venda." O host deve solicitar aprovacao humana e entao chamar `append_rows`.

## Limites intencionais

Esta PoC nao processa `.xlsm`, nao preserva macros, nao recalcula formulas como o Excel, nao implementa autenticacao para transporte remoto e nao oferece transacoes concorrentes. Para producao, use Streamable HTTP com autenticacao/autorizacao, trilha de auditoria, controle de concorrencia, allowlist de operacoes e aprovacao humana para escrita.