# MCP NFS-e (ISSWeb / Fiorilli)

Servidor **MCP** (Model Context Protocol) para **buscar, baixar, consultar e (em breve)
emitir** Notas Fiscais de Serviço eletrônicas (NFS-e) em prefeituras que usam o sistema
**ISSWeb da Fiorilli** — padrão nacional (com IBS/CBS).

**Multiempresa:** cada empresa/escritório configura o **próprio login e senha** e passa a
buscar e baixar suas notas de forma segura e prática. Feito para escritórios de contabilidade
gerenciarem vários clientes. Pode ser acionado por IA (Claude) ou por scripts. Padrão:
**Ariquemes/RO** — adaptável a outras cidades que usem o mesmo sistema.

## Estado atual

| Recurso | Status |
|---|---|
| **Buscar/listar NFS-e por período** (portal) | ✅ Pronto e testado |
| **Baixar XML + DANFSe (PDF)** de uma nota ou de um período inteiro | ✅ Pronto e testado |
| **Consultar dados completos** por chave de acesso (WebService) | ✅ Pronto e testado |
| **Buscar empresa por CNPJ** | ✅ Pronto e testado |
| **Multi-cliente** (vários clientes, cada um com seu login) | ✅ Pronto |
| **Emitir (lançar) NFS-e** | 🚧 Em construção — **modo PREVIEW, nunca salva** |

> 🔒 **Segurança:** tudo é somente leitura. A emissão está sendo construída em **modo preview**
> (preenche os campos mas **não salva** no portal); o salvar real exigirá dupla trava
> (`NFSE_PERMITIR_EMISSAO=true` + `confirmar: true`).

## Como funciona

- **Portal (Playwright):** faz login com usuário/senha e usa a tela de pesquisa para **listar**
  as notas de um período e **baixar** o XML de cada uma e a **DANFSe (PDF)**.
- **WebService Nacional:** consulta **aberta** (sem login) pela **chave de acesso** — devolve o
  XML completo no layout nacional.

## Instalação

```powershell
npm install
npx playwright install chromium
```

## Configuração

### 1 empresa — `.env`
Copie `.env.example` para `.env`:
```
NFSE_USUARIO=seu_usuario_do_portal
NFSE_SENHA=sua_senha_do_portal
NFSE_CNPJ=00000000000000
NFSE_INSCRICAO_MUNICIPAL=
```

### Vários clientes — `clientes.json` (contabilidade)
Copie `clientes.example.json` para `clientes.json` (fica **fora do Git**):
```json
{
  "cliente_a": { "nome": "Empresa A",  "usuario": "...", "senha": "...", "cnpj": "...", "im": "..." },
  "cliente_b": { "nome": "Empresa B",  "usuario": "...", "senha": "...", "cnpj": "...", "im": "..." }
}
```
Depois é só passar `empresa: "cliente_a"` nas ferramentas.

## Ferramentas MCP

| Ferramenta | O que faz |
|---|---|
| `nfse_buscar_notas` | **Lista as NFS-e de um período** (portal) |
| `nfse_baixar_nota` | Baixa **XML + DANFSe (PDF)** de uma nota |
| `nfse_baixar_periodo` | Baixa o XML (e opcionalmente a DANFSe) de **todas** as notas do período |
| `nfse_consultar_por_chave` | Dados completos da nota pela chave (WebService) |
| `nfse_obter_xml` | XML bruto (layout nacional) pela chave |
| `nfse_consultar_por_numero` / `nfse_consultar_por_id_dps` | Consultas alternativas (WebService) |
| `nfse_consultar_cnpj` | Dados cadastrais de uma empresa por CNPJ |
| `nfse_listar_empresas` | Lista os clientes do `clientes.json` |
| `nfse_status` | Testa a conexão com o WebService |

Todas as ferramentas de portal aceitam `empresa` (multi-cliente, opcional).

## Teste rápido (sem MCP)

```powershell
# Listar notas de um período (precisa de login/senha no .env):
node scripts/pesquisar-teste.js 01/08/2026 31/08/2026

# Baixar XML + DANFSe de uma nota:
node scripts/baixar-teste.js 5 2026-08-01 2026-08-31

# Consultar pela chave (WebService, sem login):
node scripts/testar-conexao.js 11000231268076089000103000000000000526085425791624
```

## Uso como MCP

### Claude Desktop — `claude_desktop_config.json`
```json
{
  "mcpServers": {
    "nfse": {
      "command": "node",
      "args": ["CAMINHO_DO_PROJETO/src/index.js"],
      "env": { "NFSE_USUARIO": "usuario", "NFSE_SENHA": "senha" }
    }
  }
}
```

### Claude Code (CLI)
```powershell
claude mcp add nfse --env NFSE_USUARIO=usuario --env NFSE_SENHA=senha -- node "CAMINHO_DO_PROJETO\src\index.js"
```

## Segurança

- Credenciais ficam no `.env`/`clientes.json` de cada instalação — **nunca** vão para o Git.
- Tudo é read-only; a emissão fica travada (preview) até liberação explícita.
- Ferramenta não oficial, sem vínculo com a Prefeitura ou com a Fiorilli.

## Estrutura

```
src/
  index.js            servidor MCP (10 ferramentas)
  config.js           configuração multiempresa
  clientes.js         gestão multi-cliente (clientes.json)
  cnpj.js             busca de empresa por CNPJ
  soap-client.js      cliente SOAP + parser
  nacional.js         envelopes do WebService Nacional
  parse-nfse.js       XML nacional -> JSON limpo
  consultar.js        camada de consulta (WebService)
  portal/
    login.js          login no portal (Playwright)
    pesquisar.js      lista notas por período
    baixar.js         baixa XML + DANFSe (nota ou período)
scripts/
  pesquisar-teste.js  testa a listagem
  baixar-teste.js     testa o download de uma nota
  testar-conexao.js   testa a consulta (WebService)
  testar-mcp.js       smoke test do protocolo MCP
  inspecionar-portal.js  mapeia campos de uma tela do portal
```

## Roadmap

1. **Emissão (preview → real):** preencher a tela de emissão (tomador por CNPJ, serviço,
   valores) e salvar só com a dupla trava de segurança.
2. **Paginação** no download em lote (períodos com muitas notas).
3. **Multicidade:** catálogo de prefeituras ISSWeb/Fiorilli.
```