# mdia-feegow-mcp

Servidor **MCP (Model Context Protocol)** para a **API do Feegow** — sistema de
gestão de clínicas e consultórios. Expõe ~97 ferramentas (agendamentos, pacientes,
prontuário, financeiro, estoque, cartão de benefício, faturamento, convênios,
procedimentos, profissionais, propostas, laudos, relatórios e mais) que qualquer
cliente MCP (Claude Desktop, Claude Code, Cursor…) pode usar para operar a API do
Feegow com o **token da sua própria licença**.

> **Não oficial.** Este projeto não é afiliado ao Feegow. É um wrapper
> comunitário sobre a API pública, para uso com agentes/LLMs. A fonte oficial é
> sempre a documentação e o suporte do Feegow.

> ⚠️ **Dados de saúde (LGPD).** A API do Feegow trafega dados sensíveis de
> pacientes. Rode este servidor apenas em ambiente sob seu controle, nunca exponha
> seu `FEEGOW_TOKEN`, e mantenha as operações de escrita desabilitadas até
> precisar delas.

## Requisitos

- **Node.js 18+** (usa `fetch` nativo)
- Um **token de licença Feegow** (header `x-access-token`)

## Instalação rápida

Não precisa clonar nada — rode direto do GitHub via `npx`:

```bash
FEEGOW_TOKEN=seu-token npx -y github:mdiaoficial/mdia-feegow-mcp
```

(Depois de publicado no npm, também funcionará como `npx -y mdia-feegow-mcp`.)

## Configuração nos clientes MCP

### Claude Desktop

Edite `claude_desktop_config.json` (menu **Settings → Developer → Edit Config**):

```json
{
  "mcpServers": {
    "feegow": {
      "command": "npx",
      "args": ["-y", "github:mdiaoficial/mdia-feegow-mcp"],
      "env": {
        "FEEGOW_TOKEN": "seu-token-aqui"
      }
    }
  }
}
```

Reinicie o Claude Desktop. As ferramentas `feegow_*` ficam disponíveis.

### Claude Code

```bash
claude mcp add feegow -e FEEGOW_TOKEN=seu-token -- npx -y github:mdiaoficial/mdia-feegow-mcp
```

### Cursor / outros

Mesma ideia: `command` = `npx`, `args` = `["-y", "github:mdiaoficial/mdia-feegow-mcp"]`,
e `FEEGOW_TOKEN` no ambiente.

## Variáveis de ambiente

| Variável | Obrigatória | Padrão | Descrição |
|---|---|---|---|
| `FEEGOW_TOKEN` | **sim** | — | Token da licença, enviado como `x-access-token`. |
| `FEEGOW_BASE_URL` | não | `https://api.feegow.com/v1/api` | Base da API (troque para homologação/BR se preciso). |
| `FEEGOW_ALLOW_WRITES` | não | `false` | `true` habilita as ferramentas de **escrita**. |

## Segurança: leitura vs. escrita

Por padrão o servidor é **somente leitura**. Ferramentas que criam, editam,
cancelam, remarcam ou emitem algo (agendamentos, pacientes, invoices, laudos,
uploads, propostas, senhas de fila) ficam **desabilitadas** e só funcionam com
`FEEGOW_ALLOW_WRITES=true`. Elas aparecem marcadas com `[ESCRITA]` na descrição.

O token nunca é logado; toda saída de diagnóstico vai para `stderr` (o protocolo
MCP usa `stdout`).

## Ferramentas

Cada ferramenta mapeia um endpoint. Nomes seguem o padrão `feegow_<ação>`.
Exemplos por área:

- **Agendamentos:** `feegow_list_appointments`, `feegow_available_schedule`,
  `feegow_get_price`, `feegow_create_appointment` *(escrita)*,
  `feegow_cancel_appointment` *(escrita)*, `feegow_reschedule_appointment` *(escrita)*.
- **Pacientes:** `feegow_list_patients`, `feegow_search_patient`,
  `feegow_patient_exam_requests`, `feegow_create_patient` *(escrita)*,
  `feegow_edit_patient` *(escrita)*.
- **Profissionais:** `feegow_list_professionals`, `feegow_professional_agenda`,
  `feegow_search_professional`.
- **Procedimentos / Especialidades / Convênios / Empresas:**
  `feegow_list_procedures`, `feegow_list_specialties`, `feegow_list_insurances`,
  `feegow_list_units`.
- **Financeiro:** `feegow_list_invoices`, `feegow_list_sales`, `feegow_list_vouchers`,
  `feegow_dmed`, `feegow_list_cost_centers`, `feegow_create_voucher` *(escrita)*,
  `feegow_create_invoice` *(escrita)*, `feegow_remove_invoice` *(escrita)*.
- **Estoque:** `feegow_list_products`, `feegow_get_product_position`,
  `feegow_list_product_locations`, `feegow_entry_product` *(escrita)*,
  `feegow_exit_product` *(escrita)*, `feegow_movement_product` *(escrita)*.
- **Cartão de Benefício:** `feegow_list_benefit_contracts`, `feegow_list_benefit_plans`,
  `feegow_create_benefit_contract` *(escrita)*.
- **Faturamento:** `feegow_get_billing_guide`, `feegow_insert_billing_guide` *(escrita)*,
  `feegow_edit_billing_guide` *(escrita)*.
- **Prontuário:** `feegow_list_diagnoses`, `feegow_list_prescriptions`,
  `feegow_medical_record_timeline`.
- **Propostas / Relatórios:** `feegow_list_proposals`, `feegow_generate_report`,
  `feegow_list_reports`.
- **Outros:** `feegow_list_blocks` (bloqueios de agenda), `feegow_list_employees`
  (funcionários).

> **Multi-host.** Alguns endpoints ficam em outros hosts do Feegow
> (ex.: movimentações de estoque em `core.feegow.com.br`, cartão de benefício em
> `cartao-beneficios.feegow.com`). O servidor cuida disso automaticamente via
> `baseOverride` na definição do endpoint — transparente para quem chama.

### Escape hatch: `feegow_request`

Para qualquer endpoint não coberto por uma ferramenta específica:

```
feegow_request(method="GET", path="/appoints/search", query={ "data_start": "2024-05-06" })
```

Métodos diferentes de `GET` também respeitam `FEEGOW_ALLOW_WRITES`.

> A referência completa dos endpoints (parâmetros, corpo e exemplos de resposta)
> está na skill-companheira: **[mdia-feegow-api](https://github.com/mdiaoficial/mdia-feegow-api)**.

## Desenvolvimento

```bash
git clone https://github.com/mdiaoficial/mdia-feegow-mcp.git
cd mdia-feegow-mcp
npm install          # também compila (script prepare)
npm run dev          # roda via tsx (sem build)
npm run build        # gera dist/
```

## Publicação no npm (mantenedor)

```bash
npm login
npm publish --access public
```

O script `prepare` garante o build antes de publicar. Um workflow em
`.github/workflows/publish.yml` também publica automaticamente ao criar um
release no GitHub (requer o secret `NPM_TOKEN`).

## Licença

[MIT](LICENSE) — código do wrapper. A documentação/estrutura da API pertence ao
Feegow.