selfnotas-mcp 0.0.0-stage → 0.1.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 CHANGED
@@ -1,3 +1,212 @@
1
- # Temporary Holding Version
1
+ # SelfNotas MCP
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io) para a API SelfNotas de NFS-e. Com ele, Claude Code, Claude Desktop, Codex, Cursor e outros clientes MCP consultam notas, séries, requisitos de município e dados da empresa direto pela API.
4
+
5
+ - Cliente fino da API REST pública (`https://api.selfnotas.com.br`). Não acessa banco nem código interno.
6
+ - Transporte stdio: o cliente MCP inicia o processo localmente.
7
+ - **Somente leitura por padrão.** Emissão e cancelamento só aparecem com `SELFNOTAS_ALLOW_WRITE=true`.
8
+ - NFC-e (beta) fica de fora desta versão.
9
+
10
+ Documentação da API: https://documenter.getpostman.com/view/1137906/2sBYPv2Xqd
11
+
12
+ ## Atenção: não existe ambiente de testes
13
+
14
+ Toda emissão aprovada pela API gera uma nota fiscal válida, com efeito fiscal, e o cancelamento é definitivo. Por isso:
15
+
16
+ - `emitir_nfse` e `cancelar_nfse` não são registradas a menos que `SELFNOTAS_ALLOW_WRITE=true`. Sem a flag, o agente nem vê essas ferramentas.
17
+ - As duas são marcadas com `destructiveHint: true`, e a descrição diz ao agente que o documento é real e exige confirmação do usuário. Clientes que pedem aprovação para ferramentas destrutivas vão pedir aqui.
18
+ - Deixe a escrita desligada em máquinas de desenvolvimento e em agentes que só precisam consultar.
19
+
20
+ ## Ferramentas
21
+
22
+ | Ferramenta | Tipo | O que faz | Rota |
23
+ |------------|------|-----------|------|
24
+ | `consultar_nfse(id)` | leitura | Dados da nota pelo id da SelfNotas | `GET /v1/nfse/consultar/:id` |
25
+ | `links_nfse(id, verificar?)` | leitura | URLs do PDF (DANFSe) e do XML. Por padrão confere antes se a nota existe | `GET /v1/nfse/consultar/:id` |
26
+ | `requisitos_municipio(ibge, padraoNacional?)` | leitura | Campos obrigatórios e valores sugeridos do município | `GET /v1/nfse/municipio/:ibge/requisitos` |
27
+ | `consultar_serie()` | leitura | Série e último número usados | `GET /v1/nfse/series` |
28
+ | `sincronizar_serie(serie?)` | leitura | Próximo número a partir da última nota aprovada. Não altera nada | `GET /v1/nfse/series/sincronizar` |
29
+ | `consultar_empresa()` | leitura | Dados cadastrais (sem certificado nem senha). Bom para conferir credenciais | `GET /v1/empresas` |
30
+ | `buscar_municipio_homologado(nome, uf?)` | leitura | Procura na lista de municípios homologados e diz se a prefeitura usa certificado A1 ou login e senha | JSON do site |
31
+ | `emitir_nfse(rps[], url_notificacao?)` | **escrita** | Emite NFS-e real. `rps[].id` é obrigatório e é a chave de idempotência | `POST /v1/nfse/emitir` |
32
+ | `cancelar_nfse(id, motivo)` | **escrita** | Cancela NFS-e real. `motivo` com pelo menos 10 caracteres | `POST /v1/nfse/cancelar/:id` |
33
+
34
+ O `id` de `consultar_nfse`, `links_nfse` e `cancelar_nfse` é o `id` devolvido em `data.notas[].id` na emissão, não o `rps[].id` do seu sistema.
35
+
36
+ ### Como as respostas chegam ao agente
37
+
38
+ A API devolve erros de negócio com HTTP 200 e `success: false`. O servidor converte isso num resultado de ferramenta com `isError: true` e um JSON com `erro`, `mensagem` e, quando houver, `detalhes` e `orientacao`:
39
+
40
+ | Situação na API | `erro` | Observação |
41
+ |-----------------|--------|------------|
42
+ | HTTP 200, `success: false` | `business` | Mensagem e `detalhes` da API |
43
+ | HTTP 401 (texto `Unauthorized`) | `auth` | Token ou empresa errados |
44
+ | HTTP 429 | `rate_limit` | `retry_after_s` vem do header `Retry-After` |
45
+ | HTTP 5xx | `server` | |
46
+ | Sem resposta no prazo | `timeout` | |
47
+ | Falha de conexão | `network` | |
48
+ | Variáveis de ambiente faltando | `config` | Nenhuma chamada é feita |
49
+
50
+ Em `emitir_nfse`:
51
+
52
+ - **Lote parcial** (`success: false` com `data.notas` e `data.erros`): o resultado traz `resultado: "parcial"`, as notas emitidas, os erros e `rps_para_reenviar`. Não vem como `isError`, porque há notas emitidas que precisam ser guardadas.
53
+ - **Nenhuma nota emitida**: `resultado: "falhou"` e `isError: true`.
54
+ - **Timeout, erro de rede ou 5xx**: `resultado: "incerto"`, com os `rps_ids` enviados e a orientação de repetir com os mesmos ids. A API devolve a nota já emitida em vez de criar outra.
55
+
56
+ O token nunca é logado nem devolvido nas mensagens. Os logs do servidor vão para stderr (stdout é o canal do protocolo).
57
+
58
+ ## Variáveis de ambiente
59
+
60
+ | Variável | Obrigatória | Padrão | Descrição |
61
+ |----------|-------------|--------|-----------|
62
+ | `SELFNOTAS_TOKEN` | sim* | | Token da API (`Authorization: Bearer`) |
63
+ | `SELFNOTAS_COMPANY_ID` | sim* | | Empresa (`x-company-id`) |
64
+ | `SELFNOTAS_BASE_URL` | não | `https://api.selfnotas.com.br` | Ex.: `http://localhost:3001` para a API local |
65
+ | `SELFNOTAS_ALLOW_WRITE` | não | `false` | `true` registra `emitir_nfse` e `cancelar_nfse` |
66
+ | `SELFNOTAS_MUNICIPIOS_URL` | não | `https://selfnotas.com.br/data/municipios.json` | URL (`http`, `https`, `file://`) ou caminho local do JSON de municípios homologados |
67
+ | `SELFNOTAS_TIMEOUT_MS` | não | `30000` | Timeout das consultas |
68
+ | `SELFNOTAS_WRITE_TIMEOUT_MS` | não | `90000` | Timeout de emissão e cancelamento (a API espera a SEFIN) |
69
+
70
+ \* Sem token e empresa o servidor sobe mesmo assim. Só `consultar_nfse`, `links_nfse` e `buscar_municipio_homologado` funcionam, porque as consultas de nota são públicas.
71
+
72
+ ## Instalação
73
+
74
+ Depois de publicado no npm, o comando dos clientes vira `npx -y selfnotas-mcp` no lugar de `node /caminho/para/selfnotas/mcp/dist/index.js`. Por enquanto, compile a partir deste repositório:
75
+
76
+ ```bash
77
+ cd mcp
78
+ npm install
79
+ npm run build
80
+ ```
81
+
82
+ O executável fica em `mcp/dist/index.js`. Nos exemplos abaixo, troque `/caminho/para/selfnotas` pelo caminho do repositório na sua máquina e use as suas credenciais.
83
+
84
+ ## Configuração nos clientes
85
+
86
+ ### Claude Code
87
+
88
+ Somente leitura:
89
+
90
+ ```bash
91
+ claude mcp add selfnotas --scope user -e SELFNOTAS_TOKEN=seu_token -e SELFNOTAS_COMPANY_ID=sua_empresa -- node /caminho/para/selfnotas/mcp/dist/index.js
92
+ ```
93
+
94
+ Com emissão e cancelamento habilitados:
95
+
96
+ ```bash
97
+ claude mcp add selfnotas --scope user -e SELFNOTAS_TOKEN=seu_token -e SELFNOTAS_COMPANY_ID=sua_empresa -e SELFNOTAS_ALLOW_WRITE=true -- node /caminho/para/selfnotas/mcp/dist/index.js
98
+ ```
99
+
100
+ Confira com `claude mcp list` e, dentro do Claude Code, com `/mcp`.
101
+
102
+ Para compartilhar a configuração num projeto sem gravar o token, use `.mcp.json` com expansão de variáveis (cada pessoa exporta as suas no shell):
103
+
104
+ ```json
105
+ {
106
+ "mcpServers": {
107
+ "selfnotas": {
108
+ "command": "node",
109
+ "args": ["/caminho/para/selfnotas/mcp/dist/index.js"],
110
+ "env": {
111
+ "SELFNOTAS_TOKEN": "${SELFNOTAS_TOKEN}",
112
+ "SELFNOTAS_COMPANY_ID": "${SELFNOTAS_COMPANY_ID}"
113
+ }
114
+ }
115
+ }
116
+ }
117
+ ```
118
+
119
+ ### Claude Desktop
120
+
121
+ Em Settings → Developer → Edit Config, edite `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
122
+
123
+ ```json
124
+ {
125
+ "mcpServers": {
126
+ "selfnotas": {
127
+ "command": "node",
128
+ "args": ["/caminho/para/selfnotas/mcp/dist/index.js"],
129
+ "env": {
130
+ "SELFNOTAS_TOKEN": "seu_token",
131
+ "SELFNOTAS_COMPANY_ID": "sua_empresa"
132
+ }
133
+ }
134
+ }
135
+ }
136
+ ```
137
+
138
+ Reinicie o Claude Desktop. Para habilitar a escrita, acrescente `"SELFNOTAS_ALLOW_WRITE": "true"` em `env`.
139
+
140
+ ### Codex
141
+
142
+ Pela linha de comando:
143
+
144
+ ```bash
145
+ codex mcp add selfnotas --env SELFNOTAS_TOKEN=seu_token --env SELFNOTAS_COMPANY_ID=sua_empresa -- node /caminho/para/selfnotas/mcp/dist/index.js
146
+ ```
147
+
148
+ Ou em `~/.codex/config.toml`:
149
+
150
+ ```toml
151
+ [mcp_servers.selfnotas]
152
+ command = "node"
153
+ args = ["/caminho/para/selfnotas/mcp/dist/index.js"]
154
+
155
+ [mcp_servers.selfnotas.env]
156
+ SELFNOTAS_TOKEN = "seu_token"
157
+ SELFNOTAS_COMPANY_ID = "sua_empresa"
158
+ # SELFNOTAS_ALLOW_WRITE = "true"
159
+ ```
160
+
161
+ ### Cursor
162
+
163
+ Em `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (projeto):
164
+
165
+ ```json
166
+ {
167
+ "mcpServers": {
168
+ "selfnotas": {
169
+ "command": "node",
170
+ "args": ["/caminho/para/selfnotas/mcp/dist/index.js"],
171
+ "env": {
172
+ "SELFNOTAS_TOKEN": "seu_token",
173
+ "SELFNOTAS_COMPANY_ID": "sua_empresa"
174
+ }
175
+ }
176
+ }
177
+ }
178
+ ```
179
+
180
+ Prefira o arquivo global: um `.cursor/mcp.json` com token não deve ir para o Git. Depois de salvar, ative o servidor em Cursor Settings → MCP.
181
+
182
+ ## Desenvolvimento
183
+
184
+ ```bash
185
+ npm run build # compila para dist/
186
+ npm test # testes (vitest), com fetch falso: nenhum teste chama a API real
187
+ npm run typecheck # checa tipos de src/ e test/
188
+ npm run inspector # abre o MCP Inspector apontando para dist/index.js
189
+ ```
190
+
191
+ No Inspector, passe as variáveis de ambiente na tela de conexão. Sem `SELFNOTAS_ALLOW_WRITE=true` a lista mostra 7 ferramentas; com a flag, 9.
192
+
193
+ Para testar contra a API rodando localmente, use `SELFNOTAS_BASE_URL=http://localhost:3001`. Lembre que a API local também emite em produção (`tpAmb` fixo): não chame `emitir_nfse` para testar.
194
+
195
+ ### Estrutura
196
+
197
+ ```
198
+ mcp/
199
+ ├── src/
200
+ │ ├── index.ts entrada stdio
201
+ │ ├── server.ts cria o McpServer e registra as ferramentas
202
+ │ ├── config.ts variáveis de ambiente
203
+ │ ├── client.ts cliente HTTP (headers, timeout, 401/429/5xx, success:false)
204
+ │ ├── result.ts formato dos resultados de ferramenta
205
+ │ ├── municipios.ts leitura e busca da lista de municípios homologados
206
+ │ └── tools/
207
+ │ ├── leitura.ts ferramentas somente leitura
208
+ │ └── escrita.ts emitir_nfse e cancelar_nfse
209
+ └── test/ testes com fetch falso e cliente MCP em memória
210
+ ```
211
+
212
+ Ao mudar a API (campos, rotas, mensagens), atualize também o guia `site/public/ai/selfnotas.md` e a collection do Postman.
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
+ }
@@ -0,0 +1 @@
1
+ export const VERSION = "0.1.0";
package/package.json CHANGED
@@ -1,6 +1,42 @@
1
1
  {
2
2
  "name": "selfnotas-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.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
+ }