MCP Sienge Node

Port em Node.js do MCP Sienge (Python/FastMCP) — servidor MCP para a API do Sienge.

JavaScript puro (ESM), sem etapa de build. node src/index.js e pronto.

Estado

Fase 1 de 4 — módulo nucleo completo. 10 das 131 tools portadas, com paridade de interface verificada contra o servidor Python.

Durante a transição os dois servidores rodam lado a lado: use SIENGE_PROFILE no servidor Python para desligar os módulos que este já cobre.

Related MCP server: MCP Server Node

Uso

npm install
cp .env.example .env   # preencha as credenciais
npm start

Registro no cliente MCP: ver .mcp.json.

Verificação

npm run parity

Sobe o servidor em memória, pede tools/list e compara com contract/tools-python.json — o contrato das 131 tools exportado do FastMCP. Confere nome, descrição, tipo, obrigatoriedade, default e descrição de cada parâmetro. Não gasta cota da API.

npm run parity -- --pendentes lista o que ainda falta portar, por módulo.

npm test

Comportamento, com fetch dublado: política de retry, tradução de erro, diagnóstico de 429, recorte por módulos, licenciamento e as tools de descoberta. Também não toca a API.

Portando um módulo novo

O contrato já contém schema e descrição de todas as tools. O esqueleto sai pronto:

node scripts/generate-schemas.js cadastros --out src/tools/cadastros.js

Isso gera as 24 tools de cadastros com os schemas Zod completos, os defaults e as descrições idênticas às do Python — restam os handlers, marcados com TODO. Depois de portá-los, npm run parity confirma que a interface não divergiu.

node scripts/generate-schemas.js --list mostra os módulos disponíveis.

Estrutura

src/
├── index.js            bootstrap stdio + perfil estático
├── config.js           credenciais e resolução de auth
├── registry.js         registro de tools: licença, auditoria, tags, envelope MCP
├── modules.js          catálogo dos 8 módulos e as 131 tools
├── confirmation.js     gate de confirmação para operações de alto impacto
├── licensing.js        validação Ed25519 offline (node:crypto, sem dependência)
├── http/
│   ├── client.js       núcleo HTTP: retry, backoff, 429, auditoria
│   ├── errors.js       catálogo de erros conhecidos do Sienge
│   ├── cache.js        TTL em memória
│   └── paginate.js     varredura limit/offset
├── utils/
│   ├── paths.js        ~/.sienge-mcp
│   ├── logger.js       diagnóstico (nunca em stdout)
│   ├── audit.js        trilha de escritas (AsyncLocalStorage)
│   └── apiQuota.js     cotas REST/BULK diárias
├── api/
│   ├── _restHelpers.js padrões de listagem e cache
│   └── entities.js     as 5 consultas de que o núcleo depende
├── workflows/
│   └── discovery.js    busca, catálogo e paginação
├── knowledge/          processo de compras (conhecimento, não API)
└── tools/
    └── nucleo.js       as 10 tools do módulo nucleo

Divergências

Diferenças em relação ao servidor Python estão em docs/divergencias.md — inclusive um bug do Python corrigido aqui (busca de títulos sempre vazia). Divergência não anotada é bug.

Licença

PolyForm Noncommercial 1.0.0 — mesma do servidor Python. As licenças já emitidas valem nos dois: a chave pública Ed25519 e o formato do token são os mesmos.