@conflaro/mcp
v1.13.0
Published
Servidor MCP da Conflaro — emissão fiscal (NF-e, NFC-e, NFS-e) por IA
Readme
@conflaro/mcp
Servidor MCP da Conflaro (ex-conflaro-mcp e @conttrole/mcp) — expõe a API
pública de emissão fiscal (NF-e, NFC-e, NFS-e) como ferramentas para agentes de
IA (Claude Desktop, Cursor, Claude Code).
Roda localmente (stdio) — não precisa hospedar nada. Autentica com a sua
chave de API e fala com https://api.conflaro.com por HTTPS.
Uso
{
"mcpServers": {
"conflaro": {
"command": "npx",
"args": ["-y", "@conflaro/mcp"],
"env": { "CONFLARO_API_KEY": "ck_live_xxxxxxxx" }
}
}
}| Variável | Obrigatória | Default |
| --- | --- | --- |
| CONFLARO_API_KEY | sim | — (ck_live_... da empresa, ou ok_live_... do escritório no modo contador) |
| CONFLARO_API_URL | não | https://api.conflaro.com |
CONTTROLE_API_KEY/CONTTROLE_API_URL continuam aceitas (nome antigo do pacote).
Desenvolvimento
pnpm install
pnpm build # compila para dist/
pnpm dev # roda do fonte (tsx)Ferramentas (as MESMAS do servidor remoto — ver o guard em
__tests__/services/mcp-superficie-unica.test.ts):
- Empresa:
get_company - Documentos fiscais:
list_fiscal_documents,get_fiscal_document,create_fiscal_document,emit_fiscal_document,cancel_fiscal_document,correct_fiscal_document,get_fiscal_document_xml - GNRE (guias de DIFAL/FCP/ICMS-ST para outra UF):
get_fiscal_document_gnre,generate_fiscal_document_gnre,refresh_fiscal_document_gnre,list_gnre_guides—documents:read/documents:write; gerar e listar exigem o módulo GNRE contratado - Produtos:
list_products,get_product,create_product,update_product - Financeiro (AP/AR):
list_finance_titles,get_finance_title,get_finance_summary,create_finance_title,settle_finance_installment,list_overdue_receivables,top_delinquent_clients,cashflow_projection— exigem o escopofinance:read/finance:writena chave e o módulo Financeiro contratado - Notas recebidas (DF-e):
list_received_documents,get_received_document,get_received_document_xml,manifest_received_document,sync_received_documents,get_received_documents_distribution,get_received_documents_export_link(o mês inteiro num ZIP, entregue como link de 15 min) — exigemreceived-documents:read(e:writepara manifestar); com a chave do escritório, informecompanyId - Consulta de CPF/CNPJ:
lookup_document— nome, endereço e inscrição estadual para preencher um cadastro (gasta a franquia de consultas do plano; escopodocument-lookup:read). - Simples Nacional:
get_simples_estimate— a estimativa do DAS do mês, com a memória de cálculo; exigesimples:read. ComcompanyId(chave do escritório), de uma empresa da carteira;simulate_simples_ibscbs_regime(IBS/CBS dentro × fora do DAS a partir de 2027),get_simples_das_forecast(previsão do mês e da faixa seguinte) eget_product_tax_in_price(imposto no preço e preço mínimo) - Notas suspeitas:
list_suspicious_received_documents— NF-e recebidas de fornecedor novo com valor ou mercadoria fora do padrão (exigereceived-documents:read) - Modo contador (chave do escritório
ok_):get_accounting_office,list_portfolio_companies,list_portfolio_das_estimates,list_closing_eligible_companies,request_fiscal_closings,list_fiscal_closings,get_fiscal_closing_download - Regras e webhooks:
list_tax_rules,list_webhooks,create_webhook
Documentação completa: https://docs.conttrole.io/mcp
Publicação no registro oficial do MCP
O server.json desta pasta descreve o servidor para o
registro oficial com as duas formas
de uso: este pacote (stdio) e o servidor remoto (https://mcp.conttrole.io/mcp,
OAuth). O nome é io.conttrole/mcp, e o namespace io.conttrole é provado
por um registro TXT no DNS de conttrole.io.
Quem publica é o CI (.github/workflows/mcp-publish.yml): basta subir a
versão e commitar na main. Ele publica no npm e depois no registro, e pula o
que já estiver lá — então rodar de novo depois de uma falha completa o que
faltou, sem erro de versão duplicada.
🔴 A versão mora em TRÊS lugares que precisam bater: o version do
package.json e os dois version do server.json. O guard
apps/web/__tests__/services/mcp-registro-versao.test.ts e o próprio workflow
recusam quando divergem. O servidor lê a dele do package.json.
O npm publica por Trusted Publisher (OIDC): o vínculo é com
conflaro/app + mcp-publish.yml, configurado nas Settings do pacote no
npmjs.com. Renomear o workflow quebra a publicação.
🔴 Pacote novo não aceita Trusted Publisher antes de existir: a 1ª versão do
@conflaro/mcp sai à mão (npm publish no terminal, com a passkey), que depois é apagado (ver o
cabeçalho do mcp-publish.yml). O único secret é
MCP_REGISTRY_PRIVATE_KEY (a chave Ed25519 do namespace, em hex); o par
público dela é o TXT na raiz de conttrole.io, e trocar a chave exige trocar
o TXT junto.
Publicação à mão, só se o CI estiver fora (o mcp-publisher é o binário das
releases de modelcontextprotocol/registry, não o pacote npm homônimo,
que é um servidor MCP e fica parado esperando no stdin):
pnpm --filter @conflaro/mcp publish
mcp-publisher login dns --domain conttrole.io \
--private-key "$(openssl pkey -in ~/.config/conttrole/mcp-key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
mcp-publisher publish # de dentro de apps/mcpConferência: curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.conttrole".
