selfnotas-mcp 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +301 -2
- package/dist/client.js +172 -0
- package/dist/config.js +23 -0
- package/dist/index.js +22 -0
- package/dist/municipios.js +88 -0
- package/dist/result.js +28 -0
- package/dist/server.js +21 -0
- package/dist/tools/escrita.js +164 -0
- package/dist/tools/leitura.js +128 -0
- package/dist/version.js +1 -0
- package/package.json +40 -4
package/README.md
CHANGED
|
@@ -1,3 +1,302 @@
|
|
|
1
|
-
#
|
|
1
|
+
# selfnotas-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io) da **SelfNotas**, a API de emissão de NFS-e. Com ele, agentes de IA como Claude Code, Claude Desktop, Codex e Cursor consultam e emitem notas fiscais de serviço direto na conversa.
|
|
4
|
+
|
|
5
|
+
- Consulta notas, links de PDF e XML, numeração da série, dados da empresa e requisitos de cada município.
|
|
6
|
+
- Diz se um município está homologado e como a prefeitura autentica (certificado A1 ou login e senha).
|
|
7
|
+
- Emite e cancela NFS-e, **só se você ligar o modo escrita**.
|
|
8
|
+
|
|
9
|
+
Site: https://selfnotas.com.br · Documentação da API: https://documenter.getpostman.com/view/1137906/2sBYPv2Xqd
|
|
10
|
+
|
|
11
|
+
> **Não existe ambiente de testes.** Cada emissão aprovada é uma nota fiscal válida, com efeito fiscal, e o cancelamento é definitivo. Por isso o servidor começa em modo somente leitura.
|
|
12
|
+
|
|
13
|
+
## Sumário
|
|
14
|
+
|
|
15
|
+
- [Antes de começar](#antes-de-começar)
|
|
16
|
+
- [Instalação](#instalação)
|
|
17
|
+
- [Modo somente leitura e modo escrita](#modo-somente-leitura-e-modo-escrita)
|
|
18
|
+
- [Como usar](#como-usar)
|
|
19
|
+
- [Ferramentas](#ferramentas)
|
|
20
|
+
- [Respostas e erros](#respostas-e-erros)
|
|
21
|
+
- [Variáveis de ambiente](#variáveis-de-ambiente)
|
|
22
|
+
- [Problemas comuns](#problemas-comuns)
|
|
23
|
+
- [Segurança](#segurança)
|
|
24
|
+
- [Desenvolvimento](#desenvolvimento)
|
|
25
|
+
|
|
26
|
+
## Antes de começar
|
|
27
|
+
|
|
28
|
+
Você precisa de:
|
|
29
|
+
|
|
30
|
+
1. **Node.js 18 ou mais novo.** Confira com `node -v`.
|
|
31
|
+
2. **Token de API e id da empresa.** São fornecidos pela SelfNotas. A empresa precisa estar cadastrada com o certificado digital A1.
|
|
32
|
+
|
|
33
|
+
O servidor roda na sua máquina, iniciado pelo cliente MCP com `npx -y selfnotas-mcp`. Não precisa instalar nada além disso.
|
|
34
|
+
|
|
35
|
+
## Instalação
|
|
36
|
+
|
|
37
|
+
Em todos os exemplos, troque `seu_token` e `sua_empresa` pelas suas credenciais.
|
|
38
|
+
|
|
39
|
+
### Claude Code
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
claude mcp add selfnotas --scope user -e SELFNOTAS_TOKEN=seu_token -e SELFNOTAS_COMPANY_ID=sua_empresa -- npx -y selfnotas-mcp
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Confira com `claude mcp list` ou, dentro do Claude Code, com `/mcp`.
|
|
46
|
+
|
|
47
|
+
Para deixar a configuração no projeto sem gravar o token no Git, crie um `.mcp.json` na raiz. Cada pessoa exporta `SELFNOTAS_TOKEN` e `SELFNOTAS_COMPANY_ID` no próprio shell:
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"mcpServers": {
|
|
52
|
+
"selfnotas": {
|
|
53
|
+
"command": "npx",
|
|
54
|
+
"args": ["-y", "selfnotas-mcp"],
|
|
55
|
+
"env": {
|
|
56
|
+
"SELFNOTAS_TOKEN": "${SELFNOTAS_TOKEN}",
|
|
57
|
+
"SELFNOTAS_COMPANY_ID": "${SELFNOTAS_COMPANY_ID}"
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Claude Desktop
|
|
65
|
+
|
|
66
|
+
Abra Settings → Developer → Edit Config e edite o `claude_desktop_config.json`:
|
|
67
|
+
|
|
68
|
+
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
69
|
+
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"mcpServers": {
|
|
74
|
+
"selfnotas": {
|
|
75
|
+
"command": "npx",
|
|
76
|
+
"args": ["-y", "selfnotas-mcp"],
|
|
77
|
+
"env": {
|
|
78
|
+
"SELFNOTAS_TOKEN": "seu_token",
|
|
79
|
+
"SELFNOTAS_COMPANY_ID": "sua_empresa"
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Feche e abra o Claude Desktop. As ferramentas aparecem no ícone de ferramentas da caixa de mensagem.
|
|
87
|
+
|
|
88
|
+
### Codex
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
codex mcp add selfnotas --env SELFNOTAS_TOKEN=seu_token --env SELFNOTAS_COMPANY_ID=sua_empresa -- npx -y selfnotas-mcp
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Ou em `~/.codex/config.toml`:
|
|
95
|
+
|
|
96
|
+
```toml
|
|
97
|
+
[mcp_servers.selfnotas]
|
|
98
|
+
command = "npx"
|
|
99
|
+
args = ["-y", "selfnotas-mcp"]
|
|
100
|
+
|
|
101
|
+
[mcp_servers.selfnotas.env]
|
|
102
|
+
SELFNOTAS_TOKEN = "seu_token"
|
|
103
|
+
SELFNOTAS_COMPANY_ID = "sua_empresa"
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Cursor
|
|
107
|
+
|
|
108
|
+
Em `~/.cursor/mcp.json` (vale para todos os projetos) ou `.cursor/mcp.json` (só o projeto):
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"mcpServers": {
|
|
113
|
+
"selfnotas": {
|
|
114
|
+
"command": "npx",
|
|
115
|
+
"args": ["-y", "selfnotas-mcp"],
|
|
116
|
+
"env": {
|
|
117
|
+
"SELFNOTAS_TOKEN": "seu_token",
|
|
118
|
+
"SELFNOTAS_COMPANY_ID": "sua_empresa"
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Depois ative o servidor em Cursor Settings → MCP. Prefira o arquivo global: um `.cursor/mcp.json` com token não deve ir para o Git.
|
|
126
|
+
|
|
127
|
+
### Outros clientes MCP
|
|
128
|
+
|
|
129
|
+
Qualquer cliente com transporte stdio funciona. Configure:
|
|
130
|
+
|
|
131
|
+
- comando: `npx`
|
|
132
|
+
- argumentos: `-y selfnotas-mcp`
|
|
133
|
+
- variáveis de ambiente: `SELFNOTAS_TOKEN` e `SELFNOTAS_COMPANY_ID`
|
|
134
|
+
|
|
135
|
+
## Modo somente leitura e modo escrita
|
|
136
|
+
|
|
137
|
+
| | Somente leitura (padrão) | Escrita |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| Como ligar | nada a fazer | `SELFNOTAS_ALLOW_WRITE=true` |
|
|
140
|
+
| Ferramentas | 7 consultas | as 7 consultas + `emitir_nfse` e `cancelar_nfse` |
|
|
141
|
+
| Risco | nenhum: nada é emitido nem alterado | cada emissão gera nota real |
|
|
142
|
+
|
|
143
|
+
Sem a flag, as ferramentas de escrita nem são registradas: o agente não as vê e não tem como chamá-las.
|
|
144
|
+
|
|
145
|
+
Com a flag, as duas ferramentas são marcadas como destrutivas (`destructiveHint`). A descrição delas manda o agente pedir sua confirmação antes de cada chamada. Clientes que pedem aprovação para ferramentas destrutivas vão perguntar antes de executar.
|
|
146
|
+
|
|
147
|
+
Para ligar no Claude Code, acrescente `-e SELFNOTAS_ALLOW_WRITE=true` ao comando de instalação. Nos arquivos JSON e TOML, acrescente `"SELFNOTAS_ALLOW_WRITE": "true"` em `env`.
|
|
148
|
+
|
|
149
|
+
Recomendação: deixe a escrita desligada em máquinas de desenvolvimento e em agentes que só precisam consultar. Ligue só onde alguém vai acompanhar as emissões.
|
|
150
|
+
|
|
151
|
+
## Como usar
|
|
152
|
+
|
|
153
|
+
Depois de configurar, peça em linguagem natural. Alguns exemplos:
|
|
154
|
+
|
|
155
|
+
**Conferir se está tudo certo** (não emite nada):
|
|
156
|
+
|
|
157
|
+
> Confira se minhas credenciais da SelfNotas estão funcionando e me diga em qual série estou emitindo.
|
|
158
|
+
|
|
159
|
+
O agente usa `consultar_empresa` e `consultar_serie`.
|
|
160
|
+
|
|
161
|
+
**Ver uma nota e mandar para o cliente:**
|
|
162
|
+
|
|
163
|
+
> Consulte a NFS-e 019a8f2e-6c1d-7b3a-9f10-2d4e5a6b7c8d e me passe os links do PDF e do XML.
|
|
164
|
+
|
|
165
|
+
O agente usa `consultar_nfse` e `links_nfse`. Os links são públicos e podem ser enviados ao cliente.
|
|
166
|
+
|
|
167
|
+
**Ver se dá para emitir numa cidade:**
|
|
168
|
+
|
|
169
|
+
> A SelfNotas atende Maceió? O que preciso cadastrar para emitir lá pelo Padrão Nacional?
|
|
170
|
+
|
|
171
|
+
O agente usa `buscar_municipio_homologado` e `requisitos_municipio` (com o código IBGE 2704302).
|
|
172
|
+
|
|
173
|
+
**Alinhar a numeração ao migrar de outro emissor:**
|
|
174
|
+
|
|
175
|
+
> Qual seria o próximo número da série 1, pela última nota aprovada?
|
|
176
|
+
|
|
177
|
+
O agente usa `sincronizar_serie`. Ela só informa o número; não altera nada.
|
|
178
|
+
|
|
179
|
+
**Emitir** (modo escrita ligado):
|
|
180
|
+
|
|
181
|
+
> Emita uma NFS-e de R$ 180,00 para a Cliente Exemplo Ltda, CNPJ 98765432000110, referente à mensalidade de estacionamento de novembro, item 11.01, alíquota 5%.
|
|
182
|
+
|
|
183
|
+
O agente monta o RPS, mostra os dados para você confirmar e só então chama `emitir_nfse`. A resposta traz número, série, chave e os links de PDF e XML.
|
|
184
|
+
|
|
185
|
+
**Cancelar** (modo escrita ligado):
|
|
186
|
+
|
|
187
|
+
> Cancele a nota 412, o serviço não foi prestado.
|
|
188
|
+
|
|
189
|
+
O agente localiza a nota, confirma com você e chama `cancelar_nfse`. O cancelamento não pode ser desfeito.
|
|
190
|
+
|
|
191
|
+
### Emissão sem nota em dobro
|
|
192
|
+
|
|
193
|
+
Cada item de `rps[]` precisa de um `id` único, gerado pelo seu sistema (um UUID por venda ou serviço). Ele é a chave de idempotência:
|
|
194
|
+
|
|
195
|
+
- Reenviar o mesmo `id` devolve a nota já emitida em vez de criar outra.
|
|
196
|
+
- Em timeout, erro de rede ou erro 500, a ferramenta responde `resultado: "incerto"` e orienta repetir com **os mesmos ids**.
|
|
197
|
+
- Num lote com falha parcial, as notas emitidas vêm em `notas` e os RPS a reenviar vêm em `rps_para_reenviar`.
|
|
198
|
+
|
|
199
|
+
O `id` usado para consultar, pegar links e cancelar é outro: o `id` da SelfNotas, devolvido em `notas[].id` na emissão.
|
|
200
|
+
|
|
201
|
+
## Ferramentas
|
|
202
|
+
|
|
203
|
+
### Somente leitura
|
|
204
|
+
|
|
205
|
+
| Ferramenta | Parâmetros | O que faz |
|
|
206
|
+
|------------|------------|-----------|
|
|
207
|
+
| `consultar_nfse` | `id` | Dados da nota: número, série, chave, status, links |
|
|
208
|
+
| `links_nfse` | `id`, `verificar?` | URLs públicas do PDF (DANFSe) e do XML. Por padrão confere antes se a nota existe; `verificar: false` só monta as URLs |
|
|
209
|
+
| `requisitos_municipio` | `ibge`, `padraoNacional?` | Campos obrigatórios e valores sugeridos para o município. Com `padraoNacional: true`, consulta também a adesão ao emissor nacional |
|
|
210
|
+
| `consultar_serie` | | Série atual e último número usado |
|
|
211
|
+
| `sincronizar_serie` | `serie?` | Próximo número, calculado pela última nota aprovada. Não altera nada |
|
|
212
|
+
| `consultar_empresa` | | Dados cadastrais, sem certificado nem senha |
|
|
213
|
+
| `buscar_municipio_homologado` | `nome`, `uf?` | Procura na lista de municípios homologados, sem diferenciar acentos e maiúsculas, e diz a forma de autenticação na prefeitura |
|
|
214
|
+
|
|
215
|
+
### Escrita (só com `SELFNOTAS_ALLOW_WRITE=true`)
|
|
216
|
+
|
|
217
|
+
| Ferramenta | Parâmetros | O que faz |
|
|
218
|
+
|------------|------------|-----------|
|
|
219
|
+
| `emitir_nfse` | `rps[]`, `url_notificacao?` | Emite até 50 NFS-e por chamada. Cada RPS: `id` (obrigatório), `tomador` (opcional), `servico` com `valor_servicos`, `discriminacao` e `item_lista_servico` ou `codigo_servico` |
|
|
220
|
+
| `cancelar_nfse` | `id`, `motivo` | Cancela a nota. `motivo` com pelo menos 10 caracteres |
|
|
221
|
+
|
|
222
|
+
Os campos completos de `tomador` e `servico` (alíquota, ISS retido, retenções federais, data de competência e outros) estão na [documentação da API](https://documenter.getpostman.com/view/1137906/2sBYPv2Xqd). Campos extras são repassados à API como vierem.
|
|
223
|
+
|
|
224
|
+
## Respostas e erros
|
|
225
|
+
|
|
226
|
+
As ferramentas devolvem JSON. Quando algo dá errado, o resultado vem marcado como erro, com `erro`, `mensagem` e, quando ajuda, `detalhes` e `orientacao` para o agente.
|
|
227
|
+
|
|
228
|
+
| `erro` | Quando | O que fazer |
|
|
229
|
+
|--------|--------|-------------|
|
|
230
|
+
| `business` | A API recusou (dados inválidos, nota não encontrada, certificado vencido...) | Ler `mensagem` e `detalhes` e corrigir os dados |
|
|
231
|
+
| `auth` | Token ou empresa inválidos (HTTP 401) | Conferir as credenciais |
|
|
232
|
+
| `config` | Faltam variáveis de ambiente | Configurar `SELFNOTAS_TOKEN` e `SELFNOTAS_COMPANY_ID` |
|
|
233
|
+
| `rate_limit` | Mais de 60 consultas por minuto (HTTP 429) | Esperar `retry_after_s` segundos |
|
|
234
|
+
| `server` | Erro interno da API (HTTP 5xx) | Tentar de novo em alguns segundos |
|
|
235
|
+
| `timeout` / `network` | Sem resposta ou sem conexão | Tentar de novo; na emissão, com os mesmos ids |
|
|
236
|
+
|
|
237
|
+
Em `emitir_nfse`, o campo `resultado` resume o que aconteceu:
|
|
238
|
+
|
|
239
|
+
| `resultado` | Significado |
|
|
240
|
+
|-------------|-------------|
|
|
241
|
+
| `emitido` | Todas as notas foram emitidas |
|
|
242
|
+
| `parcial` | Parte do lote foi emitida. Guarde `notas` e reenvie só `rps_para_reenviar` |
|
|
243
|
+
| `falhou` | Nada foi emitido |
|
|
244
|
+
| `incerto` | Não dá para saber (timeout, rede, 5xx). Repita com os mesmos ids |
|
|
245
|
+
|
|
246
|
+
## Variáveis de ambiente
|
|
247
|
+
|
|
248
|
+
| Variável | Obrigatória | Padrão | Descrição |
|
|
249
|
+
|----------|-------------|--------|-----------|
|
|
250
|
+
| `SELFNOTAS_TOKEN` | sim* | | Token da API |
|
|
251
|
+
| `SELFNOTAS_COMPANY_ID` | sim* | | Id da empresa |
|
|
252
|
+
| `SELFNOTAS_ALLOW_WRITE` | não | `false` | `true` liga `emitir_nfse` e `cancelar_nfse` |
|
|
253
|
+
| `SELFNOTAS_BASE_URL` | não | `https://api.selfnotas.com.br` | Endereço da API |
|
|
254
|
+
| `SELFNOTAS_MUNICIPIOS_URL` | não | `https://selfnotas.com.br/data/municipios.json` | URL ou caminho local da lista de municípios homologados |
|
|
255
|
+
| `SELFNOTAS_TIMEOUT_MS` | não | `30000` | Timeout das consultas, em ms |
|
|
256
|
+
| `SELFNOTAS_WRITE_TIMEOUT_MS` | não | `90000` | Timeout de emissão e cancelamento, em ms. A API espera a resposta da prefeitura ou da SEFIN |
|
|
257
|
+
|
|
258
|
+
\* Sem token e empresa o servidor sobe mesmo assim, mas só `consultar_nfse`, `links_nfse` e `buscar_municipio_homologado` funcionam.
|
|
259
|
+
|
|
260
|
+
## Problemas comuns
|
|
261
|
+
|
|
262
|
+
**As ferramentas não aparecem no cliente.** Confira `node -v` (precisa ser 18 ou mais novo) e reinicie o cliente depois de mudar a configuração. No Claude Code, `/mcp` mostra o status e o erro do servidor.
|
|
263
|
+
|
|
264
|
+
**`emitir_nfse` e `cancelar_nfse` não aparecem.** É o comportamento padrão. Defina `SELFNOTAS_ALLOW_WRITE=true` e reinicie o cliente.
|
|
265
|
+
|
|
266
|
+
**Erro `auth`.** O token não existe ou não tem acesso à empresa informada. Confira as duas variáveis.
|
|
267
|
+
|
|
268
|
+
**Erro `config`.** O cliente não está passando as variáveis de ambiente para o servidor. Confira o bloco `env` da configuração.
|
|
269
|
+
|
|
270
|
+
**Erro `rate_limit`.** As rotas de consulta aceitam 60 chamadas por minuto por IP. Espere o tempo indicado.
|
|
271
|
+
|
|
272
|
+
**`buscar_municipio_homologado` falha.** A lista não pôde ser baixada. Tente de novo ou aponte `SELFNOTAS_MUNICIPIOS_URL` para uma cópia local do arquivo.
|
|
273
|
+
|
|
274
|
+
**Windows: o servidor não inicia no Claude Desktop.** Use `"command": "cmd"` e `"args": ["/c", "npx", "-y", "selfnotas-mcp"]`.
|
|
275
|
+
|
|
276
|
+
## Segurança
|
|
277
|
+
|
|
278
|
+
- O token só é lido das variáveis de ambiente. O servidor não grava, não loga e não devolve o token nas mensagens.
|
|
279
|
+
- O servidor só fala com a API da SelfNotas e com o endereço da lista de municípios.
|
|
280
|
+
- Logs vão para stderr; stdout é reservado ao protocolo MCP.
|
|
281
|
+
- Não cole o token no chat com o agente. Configure no cliente MCP.
|
|
282
|
+
|
|
283
|
+
## Desenvolvimento
|
|
284
|
+
|
|
285
|
+
O código fica na pasta `mcp/` do repositório da API SelfNotas.
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
cd mcp
|
|
289
|
+
npm install
|
|
290
|
+
npm run build # compila para dist/
|
|
291
|
+
npm test # testes com fetch falso; nenhum teste chama a API real
|
|
292
|
+
npm run typecheck
|
|
293
|
+
npm run inspector # abre o MCP Inspector com dist/index.js
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Para usar a versão local num cliente, troque `npx -y selfnotas-mcp` por `node /caminho/para/selfnotas/mcp/dist/index.js`.
|
|
297
|
+
|
|
298
|
+
Para testar contra a API rodando localmente, use `SELFNOTAS_BASE_URL=http://localhost:3001`. A API local também emite em produção: não chame `emitir_nfse` para testar.
|
|
299
|
+
|
|
300
|
+
Ao mudar a API (campos, rotas, mensagens), atualize também o guia `site/public/ai/selfnotas.md` e a collection do Postman.
|
|
301
|
+
|
|
302
|
+
Para publicar uma versão nova: atualize `version` no `package.json` e em `src/version.ts` (um teste confere que as duas batem) e rode `npm publish`, que compila e testa antes.
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
export class SelfNotasClient {
|
|
2
|
+
config;
|
|
3
|
+
fetchImpl;
|
|
4
|
+
constructor(config, fetchImpl) {
|
|
5
|
+
this.config = config;
|
|
6
|
+
this.fetchImpl = fetchImpl ?? ((input, init) => fetch(input, init));
|
|
7
|
+
}
|
|
8
|
+
get baseUrl() {
|
|
9
|
+
return this.config.baseUrl;
|
|
10
|
+
}
|
|
11
|
+
url(path, query) {
|
|
12
|
+
const u = new URL(this.config.baseUrl + path);
|
|
13
|
+
for (const [k, v] of Object.entries(query ?? {})) {
|
|
14
|
+
if (v !== undefined && v !== "")
|
|
15
|
+
u.searchParams.set(k, String(v));
|
|
16
|
+
}
|
|
17
|
+
return u.toString();
|
|
18
|
+
}
|
|
19
|
+
/** Remove o token de qualquer texto que possa ir para o cliente MCP ou para logs. */
|
|
20
|
+
redact(text) {
|
|
21
|
+
const token = this.config.token;
|
|
22
|
+
return token ? text.split(token).join("***") : text;
|
|
23
|
+
}
|
|
24
|
+
async request(path, opts = {}) {
|
|
25
|
+
const auth = opts.auth ?? "required";
|
|
26
|
+
const headers = { Accept: "application/json" };
|
|
27
|
+
if (auth !== "none") {
|
|
28
|
+
const { token, companyId } = this.config;
|
|
29
|
+
if (token && companyId) {
|
|
30
|
+
headers.Authorization = `Bearer ${token}`;
|
|
31
|
+
headers["x-company-id"] = companyId;
|
|
32
|
+
}
|
|
33
|
+
else if (auth === "required") {
|
|
34
|
+
const faltando = [!token && "SELFNOTAS_TOKEN", !companyId && "SELFNOTAS_COMPANY_ID"]
|
|
35
|
+
.filter(Boolean)
|
|
36
|
+
.join(" e ");
|
|
37
|
+
return {
|
|
38
|
+
ok: false,
|
|
39
|
+
kind: "config",
|
|
40
|
+
message: `Credenciais não configuradas: defina ${faltando} nas variáveis de ambiente do servidor MCP.`,
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
let payload;
|
|
45
|
+
if (opts.body !== undefined) {
|
|
46
|
+
headers["Content-Type"] = "application/json";
|
|
47
|
+
payload = JSON.stringify(opts.body);
|
|
48
|
+
}
|
|
49
|
+
const timeoutMs = opts.timeoutMs ?? this.config.timeoutMs;
|
|
50
|
+
let res;
|
|
51
|
+
try {
|
|
52
|
+
res = await this.fetchImpl(this.url(path, opts.query), {
|
|
53
|
+
method: opts.method ?? "GET",
|
|
54
|
+
headers,
|
|
55
|
+
body: payload,
|
|
56
|
+
signal: AbortSignal.timeout(timeoutMs),
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
catch (err) {
|
|
60
|
+
const e = err;
|
|
61
|
+
if (e?.name === "TimeoutError" || e?.name === "AbortError") {
|
|
62
|
+
return {
|
|
63
|
+
ok: false,
|
|
64
|
+
kind: "timeout",
|
|
65
|
+
message: `Sem resposta da API em ${Math.round(timeoutMs / 1000)} s.`,
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
return {
|
|
69
|
+
ok: false,
|
|
70
|
+
kind: "network",
|
|
71
|
+
message: this.redact(`Falha de rede ao chamar a API: ${e?.message ?? String(err)}`),
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
const text = await res.text().catch(() => "");
|
|
75
|
+
if (res.status === 401) {
|
|
76
|
+
return {
|
|
77
|
+
ok: false,
|
|
78
|
+
kind: "auth",
|
|
79
|
+
status: 401,
|
|
80
|
+
message: "Credenciais inválidas (HTTP 401). Confira SELFNOTAS_TOKEN e SELFNOTAS_COMPANY_ID: o token precisa ter acesso à empresa.",
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
const body = parseJson(text);
|
|
84
|
+
if (res.status === 429) {
|
|
85
|
+
const retryAfter = parseRetryAfter(res.headers.get("retry-after"));
|
|
86
|
+
return {
|
|
87
|
+
ok: false,
|
|
88
|
+
kind: "rate_limit",
|
|
89
|
+
status: 429,
|
|
90
|
+
retryAfter,
|
|
91
|
+
body,
|
|
92
|
+
message: `Limite de consultas atingido (HTTP 429). Tente de novo em ${retryAfter ?? 60} s.`,
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
if (res.status >= 500) {
|
|
96
|
+
return {
|
|
97
|
+
ok: false,
|
|
98
|
+
kind: "server",
|
|
99
|
+
status: res.status,
|
|
100
|
+
body,
|
|
101
|
+
message: `Erro interno da API (HTTP ${res.status}).`,
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
if (res.status < 200 || res.status >= 300) {
|
|
105
|
+
return {
|
|
106
|
+
ok: false,
|
|
107
|
+
kind: "http",
|
|
108
|
+
status: res.status,
|
|
109
|
+
body,
|
|
110
|
+
message: `Resposta inesperada da API (HTTP ${res.status}): ${this.redact(snippet(body?.message ?? text))}`,
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
if (!body) {
|
|
114
|
+
return {
|
|
115
|
+
ok: false,
|
|
116
|
+
kind: "invalid_response",
|
|
117
|
+
status: res.status,
|
|
118
|
+
message: `A API respondeu algo que não é JSON: ${this.redact(snippet(text))}`,
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
if (body.success === false) {
|
|
122
|
+
return {
|
|
123
|
+
ok: false,
|
|
124
|
+
kind: "business",
|
|
125
|
+
status: res.status,
|
|
126
|
+
body,
|
|
127
|
+
message: describeBusinessError(body),
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
return { ok: true, status: res.status, body };
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
function parseJson(text) {
|
|
134
|
+
if (!text)
|
|
135
|
+
return undefined;
|
|
136
|
+
try {
|
|
137
|
+
const v = JSON.parse(text);
|
|
138
|
+
return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
|
|
139
|
+
}
|
|
140
|
+
catch {
|
|
141
|
+
return undefined;
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
function parseRetryAfter(value) {
|
|
145
|
+
if (!value)
|
|
146
|
+
return undefined;
|
|
147
|
+
const secs = Number(value);
|
|
148
|
+
if (Number.isFinite(secs) && secs >= 0)
|
|
149
|
+
return Math.ceil(secs);
|
|
150
|
+
const date = Date.parse(value);
|
|
151
|
+
if (Number.isFinite(date))
|
|
152
|
+
return Math.max(0, Math.ceil((date - Date.now()) / 1000));
|
|
153
|
+
return undefined;
|
|
154
|
+
}
|
|
155
|
+
function snippet(text, max = 300) {
|
|
156
|
+
const t = text.trim();
|
|
157
|
+
return t.length > max ? `${t.slice(0, max)}…` : t;
|
|
158
|
+
}
|
|
159
|
+
export function describeBusinessError(body) {
|
|
160
|
+
const parts = [];
|
|
161
|
+
if (body.message)
|
|
162
|
+
parts.push(body.message);
|
|
163
|
+
else if (body.error)
|
|
164
|
+
parts.push(body.error);
|
|
165
|
+
if (Array.isArray(body.detalhes) && body.detalhes.length) {
|
|
166
|
+
parts.push(body.detalhes.map(String).join("; "));
|
|
167
|
+
}
|
|
168
|
+
else if (typeof body.detalhes === "string" && body.detalhes) {
|
|
169
|
+
parts.push(body.detalhes);
|
|
170
|
+
}
|
|
171
|
+
return parts.join(" — ") || "A API recusou a operação (success: false).";
|
|
172
|
+
}
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export const DEFAULT_BASE_URL = "https://api.selfnotas.com.br";
|
|
2
|
+
export const DEFAULT_MUNICIPIOS_URL = "https://selfnotas.com.br/data/municipios.json";
|
|
3
|
+
function parsePositiveInt(value, fallback) {
|
|
4
|
+
if (!value)
|
|
5
|
+
return fallback;
|
|
6
|
+
const n = Number.parseInt(value, 10);
|
|
7
|
+
return Number.isFinite(n) && n > 0 ? n : fallback;
|
|
8
|
+
}
|
|
9
|
+
function clean(value) {
|
|
10
|
+
const v = value?.trim();
|
|
11
|
+
return v ? v : undefined;
|
|
12
|
+
}
|
|
13
|
+
export function loadConfig(env = process.env) {
|
|
14
|
+
return {
|
|
15
|
+
token: clean(env.SELFNOTAS_TOKEN),
|
|
16
|
+
companyId: clean(env.SELFNOTAS_COMPANY_ID),
|
|
17
|
+
baseUrl: (clean(env.SELFNOTAS_BASE_URL) ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
|
|
18
|
+
allowWrite: clean(env.SELFNOTAS_ALLOW_WRITE)?.toLowerCase() === "true",
|
|
19
|
+
municipiosUrl: clean(env.SELFNOTAS_MUNICIPIOS_URL) ?? DEFAULT_MUNICIPIOS_URL,
|
|
20
|
+
timeoutMs: parsePositiveInt(env.SELFNOTAS_TIMEOUT_MS, 30_000),
|
|
21
|
+
writeTimeoutMs: parsePositiveInt(env.SELFNOTAS_WRITE_TIMEOUT_MS, 90_000),
|
|
22
|
+
};
|
|
23
|
+
}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
3
|
+
import { loadConfig } from "./config.js";
|
|
4
|
+
import { createServer } from "./server.js";
|
|
5
|
+
// stdout é o canal do protocolo MCP: qualquer log vai para stderr. Nunca logar o token.
|
|
6
|
+
async function main() {
|
|
7
|
+
const config = loadConfig();
|
|
8
|
+
const avisos = [];
|
|
9
|
+
if (!config.token || !config.companyId) {
|
|
10
|
+
avisos.push("SELFNOTAS_TOKEN/SELFNOTAS_COMPANY_ID não definidos: só as consultas públicas vão funcionar.");
|
|
11
|
+
}
|
|
12
|
+
const modo = config.allowWrite ? "LEITURA E ESCRITA (emissão real habilitada)" : "somente leitura";
|
|
13
|
+
console.error(`[selfnotas-mcp] ${config.baseUrl} — modo ${modo}`);
|
|
14
|
+
for (const a of avisos)
|
|
15
|
+
console.error(`[selfnotas-mcp] aviso: ${a}`);
|
|
16
|
+
const server = createServer(config);
|
|
17
|
+
await server.connect(new StdioServerTransport());
|
|
18
|
+
}
|
|
19
|
+
main().catch((err) => {
|
|
20
|
+
console.error(`[selfnotas-mcp] erro fatal: ${err?.message ?? String(err)}`);
|
|
21
|
+
process.exit(1);
|
|
22
|
+
});
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { readFile } from "node:fs/promises";
|
|
2
|
+
import { fileURLToPath } from "node:url";
|
|
3
|
+
const CACHE_TTL_MS = 60 * 60 * 1000;
|
|
4
|
+
export function normalizar(s) {
|
|
5
|
+
return s
|
|
6
|
+
.normalize("NFD")
|
|
7
|
+
.replace(/\p{Diacritic}/gu, "")
|
|
8
|
+
.replace(/[''`´]/g, "")
|
|
9
|
+
.replace(/\s+/g, " ")
|
|
10
|
+
.trim()
|
|
11
|
+
.toLowerCase();
|
|
12
|
+
}
|
|
13
|
+
function descreverAutenticacao(a) {
|
|
14
|
+
if (a === "A1")
|
|
15
|
+
return { autenticacao: "certificado_a1", autenticacao_descricao: "Certificado digital A1 (e-CNPJ)" };
|
|
16
|
+
if (a === "LOGIN")
|
|
17
|
+
return { autenticacao: "login_senha", autenticacao_descricao: "Login e senha da prefeitura" };
|
|
18
|
+
return { autenticacao: a, autenticacao_descricao: a };
|
|
19
|
+
}
|
|
20
|
+
export class MunicipiosRepo {
|
|
21
|
+
source;
|
|
22
|
+
fetchImpl;
|
|
23
|
+
timeoutMs;
|
|
24
|
+
now;
|
|
25
|
+
cache;
|
|
26
|
+
constructor(source, fetchImpl, timeoutMs, now = Date.now) {
|
|
27
|
+
this.source = source;
|
|
28
|
+
this.fetchImpl = fetchImpl;
|
|
29
|
+
this.timeoutMs = timeoutMs;
|
|
30
|
+
this.now = now;
|
|
31
|
+
}
|
|
32
|
+
async load() {
|
|
33
|
+
if (this.cache && this.now() - this.cache.at < CACHE_TTL_MS)
|
|
34
|
+
return this.cache.data;
|
|
35
|
+
const raw = await this.read();
|
|
36
|
+
const data = JSON.parse(raw);
|
|
37
|
+
if (!data || !Array.isArray(data.municipios)) {
|
|
38
|
+
throw new Error("Arquivo de municípios sem o array `municipios`.");
|
|
39
|
+
}
|
|
40
|
+
this.cache = { at: this.now(), data };
|
|
41
|
+
return data;
|
|
42
|
+
}
|
|
43
|
+
async read() {
|
|
44
|
+
const src = this.source;
|
|
45
|
+
if (/^https?:\/\//i.test(src)) {
|
|
46
|
+
const res = await this.fetchImpl(src, {
|
|
47
|
+
headers: { Accept: "application/json" },
|
|
48
|
+
signal: AbortSignal.timeout(this.timeoutMs),
|
|
49
|
+
});
|
|
50
|
+
if (!res.ok)
|
|
51
|
+
throw new Error(`HTTP ${res.status} ao baixar ${src}`);
|
|
52
|
+
return res.text();
|
|
53
|
+
}
|
|
54
|
+
const path = src.startsWith("file:") ? fileURLToPath(src) : src;
|
|
55
|
+
return readFile(path, "utf8");
|
|
56
|
+
}
|
|
57
|
+
async buscar(nome, uf, limite = 20) {
|
|
58
|
+
const data = await this.load();
|
|
59
|
+
const alvo = normalizar(nome);
|
|
60
|
+
const ufAlvo = uf?.trim().toUpperCase();
|
|
61
|
+
const candidatos = data.municipios.filter((m) => !ufAlvo || m.uf.toUpperCase() === ufAlvo);
|
|
62
|
+
const exatos = [];
|
|
63
|
+
const comeca = [];
|
|
64
|
+
const contem = [];
|
|
65
|
+
for (const m of candidatos) {
|
|
66
|
+
const n = normalizar(m.n);
|
|
67
|
+
if (n === alvo)
|
|
68
|
+
exatos.push(m);
|
|
69
|
+
else if (n.startsWith(alvo))
|
|
70
|
+
comeca.push(m);
|
|
71
|
+
else if (n.includes(alvo))
|
|
72
|
+
contem.push(m);
|
|
73
|
+
}
|
|
74
|
+
const todos = [...exatos, ...comeca, ...contem];
|
|
75
|
+
const resultados = todos.slice(0, limite).map((m) => ({
|
|
76
|
+
nome: m.n,
|
|
77
|
+
uf: m.uf,
|
|
78
|
+
...descreverAutenticacao(m.a),
|
|
79
|
+
}));
|
|
80
|
+
return {
|
|
81
|
+
homologado: exatos.length > 0,
|
|
82
|
+
total_encontrados: todos.length,
|
|
83
|
+
resultados,
|
|
84
|
+
lista_atualizada_em: data.atualizado,
|
|
85
|
+
total_homologados: data.total ?? data.municipios.length,
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
}
|
package/dist/result.js
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
export function ok(data) {
|
|
2
|
+
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
3
|
+
}
|
|
4
|
+
export function fail(data) {
|
|
5
|
+
return { isError: true, content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
6
|
+
}
|
|
7
|
+
const ORIENTACAO = {
|
|
8
|
+
config: "Peça ao usuário para configurar as variáveis de ambiente do servidor MCP. Não peça o token no chat.",
|
|
9
|
+
auth: "Não repita a chamada. Peça ao usuário para conferir o token e a empresa.",
|
|
10
|
+
rate_limit: "Espere o tempo de retry_after_s antes de consultar de novo.",
|
|
11
|
+
business: "A API recusou a operação. Mostre a mensagem ao usuário; corrija os dados antes de repetir.",
|
|
12
|
+
};
|
|
13
|
+
/** Converte uma falha da API num resultado de ferramenta com `isError: true`. */
|
|
14
|
+
export function apiFailure(r, extra = {}) {
|
|
15
|
+
const out = { erro: r.kind, mensagem: r.message };
|
|
16
|
+
if (r.status !== undefined)
|
|
17
|
+
out.http_status = r.status;
|
|
18
|
+
if (r.retryAfter !== undefined)
|
|
19
|
+
out.retry_after_s = r.retryAfter;
|
|
20
|
+
if (r.body?.detalhes !== undefined)
|
|
21
|
+
out.detalhes = r.body.detalhes;
|
|
22
|
+
if (r.body?.data !== undefined)
|
|
23
|
+
out.data = r.body.data;
|
|
24
|
+
const orientacao = ORIENTACAO[r.kind];
|
|
25
|
+
if (orientacao)
|
|
26
|
+
out.orientacao = orientacao;
|
|
27
|
+
return fail({ ...out, ...extra });
|
|
28
|
+
}
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
|
+
import { SelfNotasClient } from "./client.js";
|
|
3
|
+
import { MunicipiosRepo } from "./municipios.js";
|
|
4
|
+
import { registerWriteTools } from "./tools/escrita.js";
|
|
5
|
+
import { registerReadTools } from "./tools/leitura.js";
|
|
6
|
+
import { VERSION } from "./version.js";
|
|
7
|
+
const INSTRUCOES_BASE = "Servidor MCP da API SelfNotas (NFS-e no Brasil). Não existe ambiente de testes: toda emissão gera nota fiscal real. " +
|
|
8
|
+
"Para conferir credenciais sem emitir nada, use consultar_empresa ou consultar_serie. " +
|
|
9
|
+
"O id usado em consultar_nfse, links_nfse e cancelar_nfse é o id devolvido em data.notas[].id, não o rps[].id.";
|
|
10
|
+
export function createServer(config, deps = {}) {
|
|
11
|
+
const client = new SelfNotasClient(config, deps.fetch);
|
|
12
|
+
const municipios = new MunicipiosRepo(config.municipiosUrl, deps.fetch ?? ((i, init) => fetch(i, init)), config.timeoutMs);
|
|
13
|
+
const instructions = config.allowWrite
|
|
14
|
+
? `${INSTRUCOES_BASE} As ferramentas emitir_nfse e cancelar_nfse estão ATIVAS: peça confirmação explícita do usuário antes de cada chamada e nunca as use para testar.`
|
|
15
|
+
: `${INSTRUCOES_BASE} Emissão e cancelamento estão desligados (modo somente leitura). Para ativar, o usuário precisa definir SELFNOTAS_ALLOW_WRITE=true.`;
|
|
16
|
+
const server = new McpServer({ name: "selfnotas", version: VERSION }, { instructions });
|
|
17
|
+
registerReadTools(server, client, municipios);
|
|
18
|
+
if (config.allowWrite)
|
|
19
|
+
registerWriteTools(server, client, config.writeTimeoutMs);
|
|
20
|
+
return server;
|
|
21
|
+
}
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { apiFailure, fail, ok } from "../result.js";
|
|
3
|
+
import { notaIdSchema } from "./leitura.js";
|
|
4
|
+
export const MAX_RPS_POR_LOTE = 50;
|
|
5
|
+
const AVISO_REAL = "ATENÇÃO: gera documento fiscal REAL, com efeito fiscal. A SelfNotas não tem ambiente de testes. " +
|
|
6
|
+
"Só chame depois de o usuário confirmar explicitamente os dados desta chamada. Nunca use para testar.";
|
|
7
|
+
const tomadorSchema = z
|
|
8
|
+
.looseObject({
|
|
9
|
+
cpf_cnpj: z.string().optional().describe("Só dígitos. Se informado, exige razao_social (ou nome / nome_completo)."),
|
|
10
|
+
razao_social: z.string().optional(),
|
|
11
|
+
nome_completo: z.string().optional(),
|
|
12
|
+
email: z.string().optional(),
|
|
13
|
+
endereco: z.string().optional(),
|
|
14
|
+
numero: z.union([z.string(), z.number()]).optional(),
|
|
15
|
+
complemento: z.string().optional(),
|
|
16
|
+
bairro: z.string().optional(),
|
|
17
|
+
cidade: z.string().optional(),
|
|
18
|
+
uf: z.string().optional(),
|
|
19
|
+
codigo_municipio: z.string().optional().describe("IBGE, 7 dígitos."),
|
|
20
|
+
cep: z.string().optional().describe("Só dígitos."),
|
|
21
|
+
})
|
|
22
|
+
.describe("Cliente. Pode ser omitido para consumidor não identificado.");
|
|
23
|
+
const servicoSchema = z
|
|
24
|
+
.looseObject({
|
|
25
|
+
valor_servicos: z.number().positive().describe("Valor bruto, maior que zero."),
|
|
26
|
+
discriminacao: z.string().trim().min(1).describe("Descrição do serviço."),
|
|
27
|
+
item_lista_servico: z.string().optional().describe('Item da LC 116 (ex.: "11.01"). Informe este ou codigo_servico.'),
|
|
28
|
+
codigo_servico: z.string().optional().describe('Código de tributação nacional (ex.: "110101"). Informe este ou item_lista_servico.'),
|
|
29
|
+
aliquota: z.number().nonnegative().optional().describe("Alíquota do ISS em %. Exigida no Padrão Nacional."),
|
|
30
|
+
iss_retido: z.boolean().optional(),
|
|
31
|
+
valor_deducoes: z.number().nonnegative().optional(),
|
|
32
|
+
codigo_municipio: z.string().optional().describe("IBGE do local da prestação. Padrão: município da empresa."),
|
|
33
|
+
codigo_nbs: z.string().optional(),
|
|
34
|
+
data_competencia: z
|
|
35
|
+
.string()
|
|
36
|
+
.regex(/^\d{4}-\d{2}-\d{2}$/, "use YYYY-MM-DD")
|
|
37
|
+
.optional()
|
|
38
|
+
.describe("YYYY-MM-DD. Padrão: data da emissão."),
|
|
39
|
+
})
|
|
40
|
+
.refine((s) => Boolean(s.item_lista_servico || s.codigo_servico), {
|
|
41
|
+
message: "informe item_lista_servico ou codigo_servico",
|
|
42
|
+
})
|
|
43
|
+
.describe("Serviço prestado. Campos extras aceitos pela API (retenções, pTotTrib*) são repassados.");
|
|
44
|
+
const rpsSchema = z.looseObject({
|
|
45
|
+
id: z
|
|
46
|
+
.string()
|
|
47
|
+
.trim()
|
|
48
|
+
.min(1, "cada RPS precisa de id")
|
|
49
|
+
.max(100)
|
|
50
|
+
.describe("Chave de idempotência, gerada pelo seu sistema (UUID). Reenviar o mesmo id devolve a nota já emitida em vez de criar outra. " +
|
|
51
|
+
"Em timeout ou erro de rede, repita com o MESMO id."),
|
|
52
|
+
tomador: tomadorSchema.optional(),
|
|
53
|
+
servico: servicoSchema,
|
|
54
|
+
});
|
|
55
|
+
export function registerWriteTools(server, client, timeoutMs) {
|
|
56
|
+
server.registerTool("emitir_nfse", {
|
|
57
|
+
title: "Emitir NFS-e (documento fiscal real)",
|
|
58
|
+
description: `${AVISO_REAL} Emite uma ou mais NFS-e (até ${MAX_RPS_POR_LOTE} RPS por chamada). A emissão é síncrona. ` +
|
|
59
|
+
"Cada rps[].id é obrigatório e funciona como chave de idempotência. " +
|
|
60
|
+
"Em lote parcial, as notas em `notas` foram emitidas e só os itens de `erros` devem ser reenviados (com o mesmo id).",
|
|
61
|
+
inputSchema: {
|
|
62
|
+
rps: z
|
|
63
|
+
.array(rpsSchema)
|
|
64
|
+
.min(1)
|
|
65
|
+
.max(MAX_RPS_POR_LOTE)
|
|
66
|
+
.refine((l) => new Set(l.map((r) => r.id)).size === l.length, { message: "rps[].id repetido no mesmo lote" })
|
|
67
|
+
.describe("Lista de RPS; cada item vira uma nota."),
|
|
68
|
+
url_notificacao: z.url().optional().describe("Webhook opcional para notificações da nota."),
|
|
69
|
+
},
|
|
70
|
+
annotations: {
|
|
71
|
+
title: "Emitir NFS-e (documento fiscal real)",
|
|
72
|
+
readOnlyHint: false,
|
|
73
|
+
destructiveHint: true,
|
|
74
|
+
idempotentHint: true,
|
|
75
|
+
openWorldHint: true,
|
|
76
|
+
},
|
|
77
|
+
}, async ({ rps, url_notificacao }) => {
|
|
78
|
+
const ids = rps.map((r) => r.id);
|
|
79
|
+
const body = { rps };
|
|
80
|
+
if (url_notificacao)
|
|
81
|
+
body.url_notificacao = url_notificacao;
|
|
82
|
+
const r = await client.request("/v1/nfse/emitir", { method: "POST", body, timeoutMs });
|
|
83
|
+
if (r.ok) {
|
|
84
|
+
const data = (r.body.data ?? {});
|
|
85
|
+
return ok({
|
|
86
|
+
resultado: "emitido",
|
|
87
|
+
mensagem: r.body.message,
|
|
88
|
+
notas: data.notas ?? [],
|
|
89
|
+
erros: data.erros ?? [],
|
|
90
|
+
resumo: { total: data.total, sucesso: data.sucesso, falhas: data.falhas },
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
if (r.kind === "business" && r.body?.data && typeof r.body.data === "object") {
|
|
94
|
+
const data = r.body.data;
|
|
95
|
+
const notas = data.notas ?? [];
|
|
96
|
+
const erros = data.erros ?? [];
|
|
97
|
+
const emitidos = new Set(notas.map((n) => n.rpsId));
|
|
98
|
+
const pendentes = erros.map((e) => e.rpsId).filter((id) => Boolean(id) && !emitidos.has(id));
|
|
99
|
+
const out = {
|
|
100
|
+
resultado: notas.length > 0 ? "parcial" : "falhou",
|
|
101
|
+
mensagem: r.message,
|
|
102
|
+
notas,
|
|
103
|
+
erros,
|
|
104
|
+
rps_para_reenviar: pendentes,
|
|
105
|
+
resumo: { total: data.total, sucesso: data.sucesso, falhas: data.falhas },
|
|
106
|
+
orientacao: notas.length > 0
|
|
107
|
+
? "As notas em `notas` FORAM emitidas: guarde-as e não as reenvie como novas. Corrija e reenvie só os RPS de `rps_para_reenviar`, com o mesmo id."
|
|
108
|
+
: "Nenhuma nota foi emitida. Mostre `erros[].erro` ao usuário e corrija antes de reenviar com o mesmo id.",
|
|
109
|
+
};
|
|
110
|
+
return notas.length > 0 ? ok(out) : fail(out);
|
|
111
|
+
}
|
|
112
|
+
if (r.kind === "timeout" || r.kind === "network" || r.kind === "server") {
|
|
113
|
+
return apiFailure(r, {
|
|
114
|
+
resultado: "incerto",
|
|
115
|
+
rps_ids: ids,
|
|
116
|
+
orientacao: "Não dá para saber se as notas foram emitidas. Repita emitir_nfse com os MESMOS rps[].id (a API devolve a nota já emitida em vez de criar outra). Nunca gere ids novos para repetir.",
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
if (r.kind === "business") {
|
|
120
|
+
return apiFailure(r, {
|
|
121
|
+
resultado: "falhou",
|
|
122
|
+
orientacao: "Nada foi emitido. Corrija os dados indicados e chame de novo com os mesmos rps[].id.",
|
|
123
|
+
});
|
|
124
|
+
}
|
|
125
|
+
return apiFailure(r, { resultado: "falhou" });
|
|
126
|
+
});
|
|
127
|
+
server.registerTool("cancelar_nfse", {
|
|
128
|
+
title: "Cancelar NFS-e (irreversível)",
|
|
129
|
+
description: "ATENÇÃO: cancela uma NFS-e REAL. O cancelamento é definitivo e não pode ser desfeito. " +
|
|
130
|
+
"Só chame depois de o usuário confirmar explicitamente a nota (id e número) e o motivo. Nunca use para testar.",
|
|
131
|
+
inputSchema: {
|
|
132
|
+
id: notaIdSchema,
|
|
133
|
+
motivo: z
|
|
134
|
+
.string()
|
|
135
|
+
.trim()
|
|
136
|
+
.min(10, "motivo precisa de pelo menos 10 caracteres")
|
|
137
|
+
.max(255)
|
|
138
|
+
.describe("Motivo do cancelamento, pelo menos 10 caracteres."),
|
|
139
|
+
},
|
|
140
|
+
annotations: {
|
|
141
|
+
title: "Cancelar NFS-e (irreversível)",
|
|
142
|
+
readOnlyHint: false,
|
|
143
|
+
destructiveHint: true,
|
|
144
|
+
idempotentHint: false,
|
|
145
|
+
openWorldHint: true,
|
|
146
|
+
},
|
|
147
|
+
}, async ({ id, motivo }) => {
|
|
148
|
+
const r = await client.request(`/v1/nfse/cancelar/${encodeURIComponent(id)}`, {
|
|
149
|
+
method: "POST",
|
|
150
|
+
body: { motivo },
|
|
151
|
+
timeoutMs,
|
|
152
|
+
});
|
|
153
|
+
if (r.ok) {
|
|
154
|
+
return ok({ resultado: "cancelado", mensagem: r.body.message, data: r.body.data });
|
|
155
|
+
}
|
|
156
|
+
if (r.kind === "timeout" || r.kind === "network" || r.kind === "server") {
|
|
157
|
+
return apiFailure(r, {
|
|
158
|
+
resultado: "incerto",
|
|
159
|
+
orientacao: "Não dá para saber se a nota foi cancelada. Use consultar_nfse para ver o status antes de tentar de novo.",
|
|
160
|
+
});
|
|
161
|
+
}
|
|
162
|
+
return apiFailure(r, { resultado: "falhou" });
|
|
163
|
+
});
|
|
164
|
+
}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { apiFailure, fail, ok } from "../result.js";
|
|
3
|
+
export const notaIdSchema = z
|
|
4
|
+
.string()
|
|
5
|
+
.trim()
|
|
6
|
+
.min(1)
|
|
7
|
+
.max(100)
|
|
8
|
+
.regex(/^[A-Za-z0-9_-]+$/, "id inválido: use o id devolvido em data.notas[].id")
|
|
9
|
+
.describe("id da nota na SelfNotas (UUID v7 devolvido em data.notas[].id na emissão). Não é o rps[].id do seu sistema.");
|
|
10
|
+
const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
|
|
11
|
+
export function registerReadTools(server, client, municipios) {
|
|
12
|
+
server.registerTool("consultar_nfse", {
|
|
13
|
+
title: "Consultar NFS-e",
|
|
14
|
+
description: "Consulta uma NFS-e pelo id da SelfNotas e devolve os dados da nota (número, série, chave, status, links). Somente leitura.",
|
|
15
|
+
inputSchema: { id: notaIdSchema },
|
|
16
|
+
annotations: READ_ONLY,
|
|
17
|
+
}, async ({ id }) => {
|
|
18
|
+
const r = await client.request(`/v1/nfse/consultar/${encodeURIComponent(id)}`, { auth: "optional" });
|
|
19
|
+
return r.ok ? ok(r.body.data) : apiFailure(r);
|
|
20
|
+
});
|
|
21
|
+
server.registerTool("links_nfse", {
|
|
22
|
+
title: "Links de PDF e XML da NFS-e",
|
|
23
|
+
description: "Devolve as URLs públicas do PDF (DANFSe) e do XML de uma NFS-e. As URLs podem ser enviadas ao cliente final. " +
|
|
24
|
+
"Por padrão confere antes se a nota existe; use verificar=false para só montar as URLs.",
|
|
25
|
+
inputSchema: {
|
|
26
|
+
id: notaIdSchema,
|
|
27
|
+
verificar: z.boolean().optional().describe("Consulta a nota antes de devolver os links (padrão: true)."),
|
|
28
|
+
},
|
|
29
|
+
annotations: READ_ONLY,
|
|
30
|
+
}, async ({ id, verificar }) => {
|
|
31
|
+
const enc = encodeURIComponent(id);
|
|
32
|
+
const links = {
|
|
33
|
+
id,
|
|
34
|
+
pdf: client.url(`/v1/nfse/consultar/pdf/${enc}`),
|
|
35
|
+
xml: client.url(`/v1/nfse/consultar/xml/${enc}`),
|
|
36
|
+
observacao: "Para notas do Padrão Nacional o link pode abrir uma página que redireciona ao portal oficial da NFS-e.",
|
|
37
|
+
};
|
|
38
|
+
if (verificar === false)
|
|
39
|
+
return ok(links);
|
|
40
|
+
const r = await client.request(`/v1/nfse/consultar/${enc}`, { auth: "optional" });
|
|
41
|
+
if (!r.ok)
|
|
42
|
+
return apiFailure(r);
|
|
43
|
+
const nota = (r.body.data ?? {});
|
|
44
|
+
return ok({
|
|
45
|
+
...links,
|
|
46
|
+
pdf: typeof nota.pdf_nfse === "string" && nota.pdf_nfse ? nota.pdf_nfse : links.pdf,
|
|
47
|
+
xml: typeof nota.xml_nfse === "string" && nota.xml_nfse ? nota.xml_nfse : links.xml,
|
|
48
|
+
numero: nota.numero,
|
|
49
|
+
serie: nota.serie,
|
|
50
|
+
status: nota.status,
|
|
51
|
+
});
|
|
52
|
+
});
|
|
53
|
+
server.registerTool("requisitos_municipio", {
|
|
54
|
+
title: "Requisitos de emissão do município",
|
|
55
|
+
description: "Lista os campos obrigatórios e valores sugeridos para emitir NFS-e num município (código IBGE). " +
|
|
56
|
+
"Com padraoNacional=true, consulta também a adesão do município ao emissor nacional. Não emite nada.",
|
|
57
|
+
inputSchema: {
|
|
58
|
+
ibge: z.string().trim().regex(/^\d{7}$/, "ibge deve ter 7 dígitos").describe("Código IBGE do município, 7 dígitos (ex.: 3550308)."),
|
|
59
|
+
padraoNacional: z.boolean().optional().describe("Considera o Padrão Nacional (SEFIN / gov.br)."),
|
|
60
|
+
},
|
|
61
|
+
annotations: READ_ONLY,
|
|
62
|
+
}, async ({ ibge, padraoNacional }) => {
|
|
63
|
+
const r = await client.request(`/v1/nfse/municipio/${ibge}/requisitos`, {
|
|
64
|
+
query: { padraoNacional: padraoNacional === undefined ? undefined : String(padraoNacional) },
|
|
65
|
+
});
|
|
66
|
+
return r.ok ? ok(r.body.data) : apiFailure(r);
|
|
67
|
+
});
|
|
68
|
+
server.registerTool("consultar_serie", {
|
|
69
|
+
title: "Consultar série e numeração da NFS-e",
|
|
70
|
+
description: "Mostra a série de RPS/DPS atual da empresa e o último número usado. Somente leitura.",
|
|
71
|
+
annotations: READ_ONLY,
|
|
72
|
+
}, async () => {
|
|
73
|
+
const r = await client.request("/v1/nfse/series");
|
|
74
|
+
return r.ok ? ok(r.body.data) : apiFailure(r);
|
|
75
|
+
});
|
|
76
|
+
server.registerTool("sincronizar_serie", {
|
|
77
|
+
title: "Calcular próximo número da série",
|
|
78
|
+
description: "Calcula o próximo número da série a partir da última nota aprovada. Não altera nada: " +
|
|
79
|
+
"só informa o número (para mudar a numeração, use o painel ou POST /v1/nfse/series).",
|
|
80
|
+
inputSchema: {
|
|
81
|
+
serie: z.string().trim().min(1).max(10).optional().describe("Série a verificar. Padrão: a série cadastrada na empresa."),
|
|
82
|
+
},
|
|
83
|
+
annotations: READ_ONLY,
|
|
84
|
+
}, async ({ serie }) => {
|
|
85
|
+
const r = await client.request("/v1/nfse/series/sincronizar", { query: { serie } });
|
|
86
|
+
return r.ok ? ok(r.body.data) : apiFailure(r);
|
|
87
|
+
});
|
|
88
|
+
server.registerTool("consultar_empresa", {
|
|
89
|
+
title: "Consultar empresa",
|
|
90
|
+
description: "Dados cadastrais da empresa configurada (sem certificado nem senha). Útil para conferir se as credenciais estão certas sem emitir nada.",
|
|
91
|
+
annotations: READ_ONLY,
|
|
92
|
+
}, async () => {
|
|
93
|
+
const r = await client.request("/v1/empresas");
|
|
94
|
+
return r.ok ? ok(r.body.data) : apiFailure(r);
|
|
95
|
+
});
|
|
96
|
+
server.registerTool("buscar_municipio_homologado", {
|
|
97
|
+
title: "Buscar município homologado",
|
|
98
|
+
description: "Procura um município na lista de municípios homologados pela SelfNotas e diz a forma de autenticação na prefeitura " +
|
|
99
|
+
"(certificado A1 ou login e senha). Busca sem acento e sem diferenciar maiúsculas. Não precisa de credenciais.",
|
|
100
|
+
inputSchema: {
|
|
101
|
+
nome: z.string().trim().min(2).max(100).describe("Nome do município, completo ou parcial."),
|
|
102
|
+
uf: z
|
|
103
|
+
.string()
|
|
104
|
+
.trim()
|
|
105
|
+
.regex(/^[A-Za-z]{2}$/, "uf deve ter 2 letras")
|
|
106
|
+
.optional()
|
|
107
|
+
.describe("Sigla do estado (ex.: SP)."),
|
|
108
|
+
},
|
|
109
|
+
annotations: { ...READ_ONLY, openWorldHint: true },
|
|
110
|
+
}, async ({ nome, uf }) => {
|
|
111
|
+
try {
|
|
112
|
+
const r = await municipios.buscar(nome, uf);
|
|
113
|
+
return ok({
|
|
114
|
+
...r,
|
|
115
|
+
observacao: r.homologado
|
|
116
|
+
? undefined
|
|
117
|
+
: "Nenhum município com esse nome exato na lista. Se ele não aparecer em resultados, consulte requisitos_municipio pelo IBGE ou fale com a SelfNotas.",
|
|
118
|
+
});
|
|
119
|
+
}
|
|
120
|
+
catch (err) {
|
|
121
|
+
return fail({
|
|
122
|
+
erro: "municipios_indisponivel",
|
|
123
|
+
mensagem: `Não foi possível ler a lista de municípios: ${err.message}`,
|
|
124
|
+
orientacao: "Confira SELFNOTAS_MUNICIPIOS_URL ou tente mais tarde.",
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
});
|
|
128
|
+
}
|
package/dist/version.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const VERSION = "1.0.0";
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "selfnotas-mcp",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Servidor MCP (Model Context Protocol) para a API SelfNotas de emissão de NFS-e",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"mcp",
|
|
7
|
+
"model-context-protocol",
|
|
8
|
+
"nfse",
|
|
9
|
+
"nota-fiscal",
|
|
10
|
+
"selfnotas"
|
|
11
|
+
],
|
|
12
|
+
"homepage": "https://selfnotas.com.br",
|
|
13
|
+
"type": "module",
|
|
14
|
+
"license": "UNLICENSED",
|
|
15
|
+
"bin": {
|
|
16
|
+
"selfnotas-mcp": "dist/index.js"
|
|
17
|
+
},
|
|
18
|
+
"files": [
|
|
19
|
+
"dist",
|
|
20
|
+
"README.md"
|
|
21
|
+
],
|
|
22
|
+
"engines": {
|
|
23
|
+
"node": ">=18"
|
|
24
|
+
},
|
|
25
|
+
"scripts": {
|
|
26
|
+
"build": "tsc -p tsconfig.build.json",
|
|
27
|
+
"prepublishOnly": "npm run build && npm test",
|
|
28
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
29
|
+
"test": "vitest run",
|
|
30
|
+
"start": "node dist/index.js",
|
|
31
|
+
"inspector": "npx @modelcontextprotocol/inspector node dist/index.js"
|
|
32
|
+
},
|
|
33
|
+
"dependencies": {
|
|
34
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
35
|
+
"zod": "^4.1.0"
|
|
36
|
+
},
|
|
37
|
+
"devDependencies": {
|
|
38
|
+
"@types/node": "^22.0.0",
|
|
39
|
+
"typescript": "^5.9.0",
|
|
40
|
+
"vitest": "^4.0.0"
|
|
41
|
+
}
|
|
42
|
+
}
|