# MCP Officegest

Servidor [MCP](https://modelcontextprotocol.io) que expõe a
[API Officegest v2](https://api.officegest.com/docs/officegest-api/v2) a clientes
de IA como o **Claude Code** e o **Claude Desktop**.

A API tem 460 endpoints (inventário completo em [endpoints-v2.txt](endpoints-v2.txt));
este servidor expõe um subconjunto curado de **22 tools** com CRUD para três áreas:
**Clientes/Entidades**, **Vendas** e **Stocks**.

## Requisitos

- Python 3.12 (ver [.python-version](.python-version); o projeto usa `pyenv` + `venv`, não `uv`)
- Uma conta Officegest com acesso à API v2

## Instalação

```bash
pyenv local 3.12.1
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Configuração

```bash
cp .env.example .env
```

Edita o `.env`:

```ini
OFFICEGEST_BASE_URL=https://A-TUA-EMPRESA.officegest.com/api/v2
OFFICEGEST_USERNAME=o-teu-utilizador
OFFICEGEST_PASSWORD=a-tua-password
```

> ⚠️ O `.env` contém credenciais e está no `.gitignore` — nunca o commites.

### Autenticação

A API usa Bearer token no header `Authorization`. Com `OFFICEGEST_USERNAME` e
`OFFICEGEST_PASSWORD` definidos, o servidor **autentica-se sozinho** na primeira
chamada (`POST /auth/login`) e renova o token automaticamente se expirar (resposta
`401`). Em alternativa, podes colar um token já obtido em `OFFICEGEST_TOKEN`.

> Nota: a API devolve o token em `data.access_token` (a documentação diz `data.token`,
> mas está desatualizada). O servidor aceita ambos.

## Testar (MCP Inspector)

Este projeto usa `pyenv` + `venv`, por isso **não** uses `mcp dev` (arranca o servidor
com `uv`, que não está instalado). Lança o Inspector apontando ao Python do venv:

```bash
npx @modelcontextprotocol/inspector .venv/bin/python server.py
```

Abre o link, faz **Connect** → **Tools** → **List Tools** e experimenta as tools.

## Usar no Claude Code

A partir do projeto onde queres usar o MCP:

```bash
claude mcp add officegest -- /CAMINHO/ABSOLUTO/.venv/bin/python /CAMINHO/ABSOLUTO/server.py
```

O Claude Code passa a arrancar o servidor sozinho em cada sessão — não precisas de o
correr à mão. Verifica com `claude mcp list` ou `/mcp` dentro da sessão.

Depois de **alterares** o `server.py`, rearranca o servidor (reabre o Claude Code ou
`/mcp` → reconnect) para as mudanças serem lidas.

## Tools disponíveis

| Área | Tools |
|------|-------|
| Clientes | `listar_clientes`, `procurar_clientes`, `obter_cliente`, `obter_saldo_cliente`, `criar_cliente`, `atualizar_cliente` |
| Vendas | `listar_tipos_documento`, `listar_documentos_venda`, `obter_documento_venda`, `criar_documento_venda`, `atualizar_documento_venda`, `estado_documento_venda`, `atualizar_estado_documento`, `pagamentos_pendentes` |
| Stocks | `listar_artigos`, `criar_artigo`, `obter_artigo`, `atualizar_artigo`, `eliminar_artigo`, `consultar_stock`, `listar_familias`, `movimentos_stock` |

> A API Officegest **não tem** delete para clientes nem documentos de venda (só
> artigos), por isso essas tools não existem — não é limitação deste servidor.

## Adicionar mais endpoints

Cada tool é uma função `async` decorada com `@mcp.tool()`. Para expor outro endpoint,
copia o padrão de uma tool existente e ajusta o caminho/parâmetros a partir de
[endpoints-v2.txt](endpoints-v2.txt). A docstring é o que o modelo lê para decidir
quando usar a tool — descreve bem os parâmetros.