SkillAgentSearch skills...

nfse-sdk

SDK TypeScript para emitir, consultar e gerenciar NFS-e Nacional.

Install / Use

claude mcp add useinvio -- npx -y github:useinvio/nfse-sdk

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

71/100

Supported Platforms

Claude Code
Claude Desktop

Our assessment of nfse-sdk

nfse-sdk scores 71/100 on our quality scale, 3864th of 4,704 Development & Engineering skills we index.

Its MCP Server is 6.1 KB long, well organised into 9 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.

It has 3 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
3/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 4 days ago, so nfse-sdk is actively maintained.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 87/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

nfse-sdk compared with similar skills

All 4 of these similar skills score higher than nfse-sdk; compare them before choosing.

SkillScoreStarsUpdatedFormat
nfse-sdk (this skill)by useinvio7134d agoMCP Server
taste-skillby Leonxlnx100117.0k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.4k9d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.9ktodayCLAUDE.md

Frequently asked questions

How do I install nfse-sdk?
Run claude mcp add useinvio -- npx -y github:useinvio/nfse-sdk. The install tabs above show the steps for each supported agent.
Which AI agents does nfse-sdk work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is nfse-sdk safe to use?
It is MIT-licensed and scores 87/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is nfse-sdk still maintained?
The repository was last updated 4 days ago, so nfse-sdk is actively maintained.

@useinvio/nfse-sdk

npm version CI Node.js License: MIT

Website · Playground · Documentação · English

<img width="959" height="296" alt="NFS-e SDK" src="https://github.com/user-attachments/assets/d6c45737-e7ca-4ea7-a06f-d93b7c16e4f0" />

Emita, consulte e cancele NFS-e Nacional em TypeScript, sem escrever XML fiscal na mão.

Você descreve a nota em JSON; o SDK monta a DPS, valida contra o XSD oficial, assina com o certificado A1, compacta, envia por mTLS para a SEFIN e devolve a resposta oficial em formato estruturado. Sem binários nativos e sem xmllint.

O que ele faz

| Operação | Função | No NfseClient | |---|---|---| | Emitir a partir de JSON ou XML | emitirNfse | invoices.create | | Validar sem enviar (JSON + XSD) | validateDpsJsonRequest, buildDpsFromJson | invoices.buildDpsJson | | Consultar com resultado tipado | obterNfse | invoices.retrieve | | Recuperar uma emissão após timeout | recuperarNfsePorDps | invoices.recover | | Cancelar / cancelar por substituição | cancelarNfse, cancelarNfsePorSubstituicao | invoices.cancel, invoices.cancelBySubstitution | | Baixar o DANFSe em PDF | baixarDanfse | invoices.danfse | | Distribuição por NSU e parâmetros municipais (ADN) | distribuirDfePorNsu, consultarAliquota… | distribution, municipalParameters | | Explicar rejeições com o texto oficial | explicarRejeicao, explicarErros, uma página por código | – | | Usar pelo terminal | npx nfse init, doctor, validate, emit, explain | – | | Testar sem certificado nem rede | @useinvio/nfse-sdk/testing | – | | Servidor MCP e ferramentas para agentes de IA | npx -y @useinvio/nfse-mcp, @useinvio/nfse-sdk/agent | – |

Instalação

npm install @useinvio/nfse-sdk

Node.js 20 ou mais recente. Nada para instalar no sistema: a validação XSD roda em WebAssembly.

Em 60 segundos

NFSE_CERT_PATH=./certificado.pfx
NFSE_CERT_PASSWORD=sua-senha
import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';

const certificado = NfseCertificate.fromEnv(); // a chave privada nunca aparece em logs

const nota = {
  ambiente: 'restrita' as const, // produção restrita: o sandbox oficial
  prestador: {
    cnpj: '12345678000195',
    cLocEmi: '4106902',
    serie: '1601',
    opSimpNac: '1',
    regEspTrib: '0',
  },
  servico: {
    cTribNac: '010201',
    xDescServ: 'Desenvolvimento de software',
    cLocPrestacao: '4106902',
    cNBS: '115022000',
  },
  emissao: {
    nDPS: '1',
    dhEmi: '2026-06-15T10:30:00-03:00',
    dCompet: '2026-06-01',
    valores: { vServ: '1500.00' },
    tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
    tributacaoFederal: { piscofins: { CST: '07' } },
    totTrib: { pTotTribFed: '0.00', pTotTribEst: '0.00', pTotTribMun: '5.00' },
  },
};

try {
  const { chaveAcesso, nfseXml } = await emitirNfse(nota, certificado);
  console.log(chaveAcesso); // chave de 50 dígitos
} catch (error) {
  if (!(error instanceof EmitirNotaError)) throw error;
  for (const rejeicao of error.erros) console.error(rejeicao.Codigo, rejeicao.Descricao);
}

Primeira vez? Siga o tutorial: emitir, consultar, baixar o PDF e cancelar na produção restrita, do zero. Ou experimente sem certificado, pelo terminal:

npx nfse init && npx nfse emit nota.json --mock

Documentação

| Guia | | |---|---| | Certificado A1 | Variáveis de ambiente, cofres de segredo, vários emitentes. | | Emitir | JSON, NfseClient, XML pronto, série e número. | | Consultar e DANFSe | Resultado tipado e PDF. | | Recuperar após timeout | Sem notas duplicadas quando a conexão cai. | | Cancelar | e101101 e substituição (e105102). | | Erros e rejeições | O que cada erro significa e o que fazer. | | Linha de comando | nfse doctor, emit, cancel, explain. | | Testar sem certificado | SEFIN simulada para o seu CI. | | Agentes de IA e MCP | Servidor MCP, plugin do Claude Code, ferramentas para o seu agente. | | Referência da API | Todas as funções. | | Mapeamento do JSON | Cada campo de DpsJsonRequest. |

Exemplos executáveis em examples/.

Com agentes de IA

Emita uma NFS-e conversando com o Claude. Para experimentar sem certificado, o modo de teste usa uma SEFIN simulada:

claude mcp add nfse --env NFSE_MCP_MOCK=1 --env NFSE_MCP_ALLOW_WRITE=1 -- npx -y @useinvio/nfse-mcp

Ou instale o plugin do Claude Code, que inclui o servidor e uma skill com o fluxo:

/plugin install nfse-nacional --marketplace useinvio/nfse-sdk

Emitir e cancelar sempre passam por um resumo que você aprova antes do envio, e o certificado nunca chega ao modelo. Veja o guia de agentes e MCP. Para assistentes de código, o pacote inclui llms.txt.

O que fica com a sua aplicação

O SDK cuida do protocolo; ele não é um motor fiscal. Códigos de serviço, CST, alíquotas, retenções, regime tributário e a numeração da DPS são decisões da sua aplicação e de quem cuida da parte tributária. Campos fiscais obrigatórios nunca recebem valores padrão silenciosos. O grupo IBS/CBS da reforma tributária ainda não é suportado.

Contribuir

Issues e PRs são bem-vindos. Veja CONTRIBUTING.md e o CHANGELOG.

Licença

MIT © Invio

Related Skills

View on GitHub
GitHub Stars3
CategoryDevelopment
Updated4d ago
Forks0

Languages

TypeScript

Trust signals

87/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

2 low
nfse-sdk — MCP Server: Install & Safety Check | SkillAgent