Winsig MCP Server

Hub MCP multi-sistema que liga modelos de IA (Claude, ChatGPT, Gemini ou qualquer cliente compatível com o protocolo) a vários sistemas de gestão — hoje o Cegid PHC CS e o Factorial (RH), amanhã Sage, Primavera, SAP, Odoo ou outra solução Winsig — com autenticação por integração, permissões granulares e auditoria de cada pedido, num único ponto de entrada.

Inspirado no posicionamento do TOTAL MCP Server da Totalsoft — a IA nunca acede diretamente à base de dados do ERP, só através deste hub — mas desenhado desde a base para não ficar preso a um único fornecedor: um hub, muitos sistemas ligados, um só modelo de segurança. É essa a principal diferenciação que estamos a construir.

Onde é que isto está "alojado"? Em lado nenhum, por agora. Isto é código-fonte neste repositório (branch claude/total-mcp-server-improved-j4auhb) — não há nenhum servidor público a correr. Para o testares, corres o hub na tua própria máquina (ou num servidor que controles) seguindo as instruções abaixo. Isso é também intencional: um dos pontos de venda deste tipo de produto é que corre dentro da infraestrutura da empresa, nunca num serviço externo.

Teste rápido (± 5 minutos, sem experiência de programação)

Isto arranca o servidor e abre uma página no browser com botões para cada ferramenta — não precisas de saber usar curl nem git.

Passo 1 — Instalar o Node.js (só uma vez, se ainda não tiveres) Vai a nodejs.org, descarrega a versão LTS para o teu sistema e instala-a como qualquer outro programa (Seguinte → Seguinte → Concluir).

Passo 2 — Descarregar o código deste projeto No GitHub, abre este repositório, muda para o branch claude/total-mcp-server-improved-j4auhb (menu à esquerda onde diz "main"), clica no botão verde Code e escolhe Download ZIP. Descompacta o ficheiro .zip — vais ter uma pasta chamada algo como WIN-MCP-JO-claude-total-mcp-server-improved-j4auhb.

Passo 3 — Abrir um terminal nessa pasta

• Windows: abre a pasta no Explorador de Ficheiros, clica na barra de endereço no topo, escreve cmd e carrega Enter.

• Mac: abre o Terminal (Spotlight: Cmd+Espaço, escreve "Terminal", Enter), escreve cd (com um espaço a seguir) e depois arrasta a pasta do projeto para dentro da janela do Terminal — o caminho preenche-se sozinho — e carrega Enter.

Passo 4 — Correr estes comandos, um de cada vez (copia e cola, Enter a seguir a cada um)

npm install

Copia o ficheiro de configuração de demonstração (já vem com uma chave de teste pronta a usar):

# Mac/Linux:
cp config/integrations.demo.json config/integrations.json
# Windows (cmd):
copy config\integrations.demo.json config\integrations.json

Depois:

npm run build
npm run dev:http

Vais ver algo como Hub HTTP a correr em http://127.0.0.1:3000/mcp. Deixa este terminal aberto — é o servidor a correr.

Passo 5 — Abrir a consola de testes Abre o browser em http://localhost:3000. No campo "API key da integração" escreve:

chave-demo-teste

Clica Ligar e depois experimenta os botões: "Listar clientes" (pesquisa por ferragens, por exemplo), "Consultar cliente" (código C0001), "Criar encomenda" (cliente C0001, artigo ART001, quantidade 2) — e também a secção Factorial (RH), um segundo sistema ligado ao mesmo hub, com "Listar colaboradores" (pesquisa por engenharia, por exemplo). Cada pedido e resposta aparece no painel preto em baixo.

⚠️ A chave chave-demo-teste e o ficheiro integrations.demo.json são só para este teste local — nunca usar em produção. Para criar as tuas próprias integrações/chaves, ver a secção "Como correr localmente" abaixo.

Para parar o servidor, volta ao terminal onde ele ficou a correr e carrega Ctrl+C.

Related MCP server: Enterprise MCP Server

Porquê esta arquitetura

Nota importante: ainda não há acesso à API do PHC Web / PHC CS (nem à API do Factorial) neste projeto. Por isso, todo o acesso a dados passa por interfaces abstratas (PhcConnector, FactorialConnector) com implementações mock que devolvem dados fictícios realistas. Isto permite construir e testar o hub completo — auth, permissões, auditoria, ferramentas MCP, múltiplos conectores — já, e trocar cada mock pela integração real à medida que o acesso a cada sistema for ficando disponível, sem tocar nas outras camadas.

Modelo de IA A ──┐                          Modelo de IA B ──┐
  (stdio, 1      │                            (HTTP, sessão  │
  integração)    ▼                            própria)       ▼
          ┌───────────────────┐        ┌───────────────────┐
          │  processo stdio   │        │  sessão HTTP B     │
          │  (identidade fixa)│        │  (identidade B)    │
          └─────────┬─────────┘        └─────────┬─────────┘
                     │                            │
                     ▼                            ▼
              1. Auth        → CredentialStore (por sessão/processo)
              2. Permissões  → requireScope() — scopes prefixados por sistema
              3. Ferramentas → um ConnectorModule por sistema ligado
                     ├── phc.*        (5 ferramentas, scope "phc:...")
                     └── factorial.*  (2 ferramentas, scope "factorial:...")
              4. Auditoria   → AuditSink (partilhado, todos os sistemas)
                     │
        ┌────────────┴────────────┐
        ▼                         ▼
  PhcConnector              FactorialConnector
  (mock por agora)          (mock por agora)
        │                         │
        ▼                         ▼
  Cegid PHC CS /             Factorial
  API PHC Web                (API real)

Nenhuma ferramenta MCP fala diretamente com um sistema de gestão: passa sempre por requireScope (permissões) e é sempre registada no AuditSink (auditoria), com sucesso ou falha. No transporte HTTP, cada sessão autentica-se com a sua própria API key e fica isolada das restantes — mas todas partilham os mesmos conectores (as mesmas fontes de dados) e o mesmo auditSink (o mesmo registo de auditoria), tal como um hub multi-integração real.

O hub em si (server.ts) não sabe nada sobre PHC ou Factorial especificamente — só sabe iterar uma lista de ConnectorModule. Ver a secção "Arquitetura multi-conector" abaixo para o que isso significa na prática ao adicionar Sage, Primavera, SAP ou Odoo.

Estrutura do projeto

src/
  auth/              Credenciais por integração (API key → identidade + scopes + attributes)
  permissions/       Scopes agregados de todos os conectores, perfis (roles.ts) + verificação de acesso
  audit/             Registo append-only de cada pedido
  tools/helpers.ts   runTool/textResult/errorResult — genéricos, usados por qualquer conector
  connectors/
    registry.ts      ConnectorModule — o "plugue" que qualquer sistema tem de implementar
    phc/             Conector Cegid PHC CS
      types.ts             Tipos de domínio + interface PhcConnector
      mockConnector.ts     MockPhcConnector (dados fictícios)
      sqlConfig.ts         Configuração segura de ligação ao SQL Server real (a partir de env vars)
      sqlServerConnector.ts PhcSqlServerConnector — conector real (ver "Ligar ao PHC real")
      inspectSchemaCli.ts  Script de introspeção do esquema real (só catálogo, nunca dados)
      scopes.ts            PHC_SCOPES ("phc:clients:read", "phc:orders:write", ...)
      tools/               Ferramentas MCP (phc.list_clients, phc.create_order, ...)
      module.ts            Junta tudo num ConnectorModule
    factorial/       Conector Factorial (RH) — mesmo padrão do PHC, prova o conceito
      types.ts, mockConnector.ts, scopes.ts, rowLevel.ts, tools/, module.ts
  modules.ts         Escolhe mock vs. real (WINSIG_PHC_MODE) e lista os conectores ligados ao hub
  server.ts          Monta o McpServer (identidade + lista de módulos + auditSink)
  index.ts           Ponto de entrada — transporte stdio (1 processo = 1 integração)
  httpServer.ts      Hub HTTP multi-tenant (Streamable HTTP) — várias integrações
                      em simultâneo, cada uma com a sua sessão e a sua API key
  httpIndex.ts       Ponto de entrada — transporte HTTP
public/
  console.html       Consola de testes servida em GET / pelo hub HTTP
config/
  integrations.example.json   Modelo de configuração (a preencher com as tuas chaves)
  integrations.demo.json      Configuração de demonstração para o "Teste rápido"
.env.example         Modelo de variáveis de ambiente (ligação ao SQL Server real, etc.)
test/                Testes unitários e de integração (node:test, via tsx)

Como correr localmente

npm install

# 1. Criar a configuração de integrações a partir do exemplo
cp config/integrations.example.json config/integrations.json

# 2. Gerar o hash de uma API key à escolha e colocá-lo no ficheiro acima
npm run hash-key -- "uma-api-key-secreta-para-esta-integracao"

Há dois transportes — usa o que fizer sentido para o que estás a testar:

Opção A — stdio (um processo por integração)

É assim que clientes MCP locais como o Claude Desktop arrancam servidores: lançam um processo com uma API key fixa no ambiente.

WINSIG_MCP_API_KEY="uma-api-key-secreta-para-esta-integracao" npm run dev

Para inspecionar interativamente as ferramentas, usa o MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector -- node dist/index.js

Opção B — HTTP (hub multi-tenant, várias integrações em simultâneo)

npm run dev:http
# [winsig-mcp-server] Hub HTTP a correr em http://127.0.0.1:3000/mcp

Cada cliente autentica-se com Authorization: Bearer <api-key> no pedido initialize; a partir daí usa o mcp-session-id que o servidor devolve. Três formas de testar:

• Consola no browser (a mais simples): abre http://127.0.0.1:3000 — é a página usada no "Teste rápido" acima.

• curl: ver a secção "Como testar o hub HTTP com curl" abaixo.

• MCP Inspector: npx @modelcontextprotocol/inspector, escolhe "Streamable HTTP", cola o URL (http://127.0.0.1:3000/mcp) e o header Authorization: Bearer <api-key>.

Variáveis de ambiente

Variáveis podem vir de um ficheiro .env na raiz do projeto (copia .env.example) em vez de exportadas manualmente — carregado automaticamente (dotenv).

Como testar o hub HTTP com curl

Depois de npm run build e npm run dev:http (ou node dist/httpIndex.js) num terminal:

# 1. Verificação de saúde (sem autenticação)
curl http://127.0.0.1:3000/healthz
# {"status":"ok","activeSessions":0}

# 2. Abrir sessão — envia "initialize" com a API key no header
curl -i -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer uma-api-key-secreta-para-esta-integracao" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-demo","version":"0.0.1"}}}'
# A resposta traz o header "mcp-session-id: <uuid>" — guarda esse valor.

# 3. Confirmar a inicialização (obrigatório antes de chamar ferramentas)
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer uma-api-key-secreta-para-esta-integracao" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <uuid-do-passo-2>" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 4. Listar ferramentas disponíveis
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer uma-api-key-secreta-para-esta-integracao" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <uuid-do-passo-2>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 5. Chamar uma ferramenta
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer uma-api-key-secreta-para-esta-integracao" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <uuid-do-passo-2>" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"phc.list_clients","arguments":{"search":"ferragens"}}}'

Abre um segundo terminal e repete os passos 2-5 com uma API key diferente (com scopes diferentes) para veres duas sessões em simultâneo, isoladas uma da outra — é exatamente isto que o teste automático test/httpServer.test.ts verifica.

Isto foi validado de ponta a ponta neste ambiente (sessão, notifications/initialized, tools/list, tools/call, com o pedido a aparecer no logs/audit.log).

Testes

npm test

Cobre: resolução e revogação de credenciais, perfis (roles) e restrição ao nível da linha, verificação de permissões (incluindo scopes de conectores diferentes), o MockPhcConnector, o registo de auditoria (sucesso e falha), o fluxo completo de uma ferramenta (runTool) — incluindo o caso de pedido negado por falta de scope — e o hub HTTP de ponta a ponta: autenticação por sessão, duas sessões concorrentes com scopes diferentes isoladas uma da outra, os conectores partilhados a manter estado entre sessões independentes, um segundo conector (Factorial) a funcionar lado a lado com o PHC no mesmo hub, e dois colaboradores diferentes a só conseguirem ver o seu próprio registo de RH, nunca o um do outro.

Perfis de utilizador (roles)

Definidos em src/permissions/roles.ts — pacotes nomeados de scopes, para não teres de listar scopes um a um em cada integração. Uma integração usa "role": "..." em vez de (ou a somar a) "scopes": [...] em config/integrations.json:

Ver config/integrations.example.json para os seis exemplos completos (um por perfil, mais um caso com scopes explícitos sem perfil).

Scopes disponíveis e restrição ao nível da linha

Agregados em src/permissions/scopes.ts a partir de cada conector — sempre prefixados com o id do sistema, para nunca colidirem entre si:

Cegid PHC CS (src/connectors/phc/scopes.ts)

• phc:clients:read — consultar clientes

• phc:stock:read — consultar stocks/artigos

• phc:invoices:read — consultar faturas

• phc:orders:write — criar encomendas

Factorial (src/connectors/factorial/scopes.ts)

• factorial:employees:read — consultar qualquer colaborador

• factorial:employees:read:self — consultar só o próprio registo (restrição ao nível da linha, não só ao nível da ferramenta)

O scope :self é diferente dos outros: não basta ter ou não ter a ferramenta — o resultado é filtrado por quem está a perguntar. Uma integração com este scope tem um attributes.factorialEmployeeId (ver config/integrations.example.json, integrações colaborador-ana/colaborador-bruno) que identifica o seu próprio registo; phc.list_employees/phc.get_employee usam-no para: (1) nunca devolver a lista completa, só o próprio registo, e (2) recusar um pedido a get_employee por um código que não seja o seu. Isto está implementado em src/connectors/factorial/tools/ (não no conector — o mock/real de dados nem sabe que esta regra existe) e testado em test/httpServer.test.ts com dois colaboradores diferentes.

Cada integração (cada API key) só usa as ferramentas cujo scope tenha atribuído em config/integrations.json — de um ou de vários sistemas ao mesmo tempo, se fizer sentido (ex: uma integração com phc:clients:read + factorial:employees:read). Um pedido sem o scope necessário é recusado e continua a ficar registado na auditoria, com o motivo da recusa.

Ferramentas MCP disponíveis

Arquitetura multi-conector — como adicionar um novo sistema

Isto é o que diferencia este hub de um MCP-por-ERP: o servidor não sabe nada sobre nenhum sistema em concreto. server.ts só percorre uma lista de ConnectorModule (src/connectors/registry.ts) e pede a cada um para registar as suas ferramentas. O PHC e o Factorial são dois exemplos desse padrão — não casos especiais.

Para ligar um sistema novo (Sage, Primavera, SAP, Odoo, ou outro), a receita é sempre a mesma — usar src/connectors/factorial/ como modelo, por ser o mais pequeno:

1. types.ts — tipos de domínio (ex: Product, Order) + uma interface abstrata (ex: SageConnector) com os métodos que queres expor.

2. mockConnector.ts — uma implementação com dados fictícios, para desenvolver e testar sem acesso à API real do sistema. Mais tarde, um SageApiConnector que implemente a mesma interface substitui-o sem tocar em mais nada.

3. scopes.ts — os scopes deste sistema, sempre prefixados com o seu id (ex: sage:invoices:read).

4. tools/*.ts — uma ferramenta MCP por operação, cada uma a chamar runTool(...) de src/tools/helpers.ts (o mesmo helper genérico que o PHC e o Factorial já usam — verifica o scope e regista na auditoria automaticamente).

5. module.ts — junta tudo num ConnectorModule { id, label, registerTools }.

6. Acrescentar o novo módulo à lista em src/modules.ts.

7. Juntar os novos scopes aos existentes em src/permissions/scopes.ts (uma linha).

Nenhum destes passos mexe em auth, permissões, auditoria, nos transportes (stdio/HTTP) ou na consola de testes — todos continuam genéricos e já funcionam com qualquer número de conectores.

Ligar ao PHC real (SQL Server)

⚠️ Isto liga o hub a uma base de dados PHC verdadeira. Lê este guia todo antes de correr o que quer que seja, e faz o primeiro teste contra uma cópia/backup da base de dados, não a produção viva — sobretudo antes de ativares escrita.

Modelo de segurança

• Ligação cifrada por default (encrypt: true). trustServerCertificate só fica ligado se pedires explicitamente — necessário para um SQL Server local de teste com certificado autoassinado, mas nunca em produção.

• Credenciais nunca no código nem no git — vêm de .env (que está no .gitignore) ou de variáveis de ambiente do sistema. Usa .env.example como modelo.

• Login SQL dedicado, nunca sa ou o admin do PHC. Pede a quem administra o SQL Server para criar um login só de leitura (ou leitura + escrita nas tabelas específicas, se e quando ativares escrita), algo como:

  CREATE LOGIN winsig_mcp_readonly WITH PASSWORD = 'uma-password-forte-aqui';
  USE NomeDaBaseDeDadosDoPHC;
  CREATE USER winsig_mcp_readonly FOR LOGIN winsig_mcp_readonly;
  GRANT SELECT ON dbo.cl TO winsig_mcp_readonly;   -- clientes
  GRANT SELECT ON dbo.st TO winsig_mcp_readonly;   -- stocks
  GRANT SELECT ON dbo.ft TO winsig_mcp_readonly;   -- faturas (cabeçalho)
  GRANT SELECT ON dbo.fi TO winsig_mcp_readonly;   -- faturas (linhas)
  -- (nomes de tabela a confirmar — ver "Descobrir o esquema real" abaixo)

• Escritas desligadas por default (WINSIG_PHC_ALLOW_WRITES=false). Mesmo ligadas, phc.create_order recusa-se a correr (WriteNotImplementedError) até alguém confirmar as regras reais de numeração/documentos do PHC — ver "Sobre a escrita" abaixo.

• Queries sempre parametrizadas (request.input(...), nunca concatenação de texto do utilizador) — o de sempre contra SQL injection.

• Auditoria já cobre isto sem mudanças — cada pedido a phc.* continua a ficar registado em logs/audit.log, agora com dados reais em vez de mock.

Passo 1 — Configurar a ligação

cp .env.example .env

Edita o .env: WINSIG_PHC_MODE=real, mais WINSIG_PHC_DB_HOST, WINSIG_PHC_DB_NAME, WINSIG_PHC_DB_USER, WINSIG_PHC_DB_PASSWORD (ver comentários no próprio ficheiro — inclui notas sobre porta vs. instância nomeada, e sobre PHC estar noutra máquina da rede se este hub correr num Mac/Linux).

Passo 2 — Descobrir o esquema real (obrigatório antes de confiares em resultados)

npm run inspect-phc-schema                    # lista todas as tabelas
npm run inspect-phc-schema -- cl              # colunas da tabela "cl" (ex: clientes)

Isto só lê o catálogo do SQL Server (nomes/tipos) — nunca uma linha de dados de negócio. src/connectors/phc/sqlServerConnector.ts tem uma melhor tentativa de mapeamento (tabelas cl/st/ft/fi, convenção comum do PHC CS) marcada com comentários // PHC: — confirma/ajusta esses nomes contra o que a introspeção mostrar antes de confiar nos resultados.

Passo 3 — Testar leitura

npm run build
npm run dev:http

Usa a consola (http://localhost:3000) ou o curl como já fizeste com os dados mock — agora com uma API key real de config/integrations.json (WINSIG_PHC_MODE=real não muda nada na autenticação/scopes/perfis, só a fonte dos dados).

Sobre a escrita (phc.create_order)

Deliberadamente não implementei a query de escrita real. Ler dados errados é um problema recuperável (repara-se); escrever numa tabela errada, ou sem respeitar a numeração/triggers que o PHC normalmente garante, pode corromper dados reais de forma não trivial de reverter. Antes de implementar:

1. Confirma com quem administra o PHC como são criados documentos de venda (tabela de tipos de documento, sequência de numeração, triggers de atualização de stock).

2. Testa a query de escrita contra uma cópia/backup, nunca a produção, primeiro.

3. Só depois preencher PhcSqlServerConnector.createOrder() e ativar WINSIG_PHC_ALLOW_WRITES=true.

Roteiro / próximos passos

1. Conector real do PHC (leitura) — feito: PhcSqlServerConnector liga por SQL Server direto (WINSIG_PHC_MODE=real); queries por confirmar contra o esquema real com npm run inspect-phc-schema. Falta ainda: FactorialApiConnector real, e a escrita real de phc.create_order (ver "Sobre a escrita" acima).

2. Transporte HTTP multi-tenant — feito: src/httpServer.ts (Streamable HTTP), uma sessão por ligação, identidade resolvida por Authorization: Bearer no initialize.

3. Arquitetura multi-conector — feito: ConnectorModule (src/connectors/registry.ts), PHC e Factorial como dois conectores independentes no mesmo hub, com scopes e ferramentas prefixados.

4. Perfis de utilizador + restrição ao nível da linha — feito: src/permissions/roles.ts (consultor/vendas/rh-admin/colaborador) e o scope factorial:employees:read:self (um colaborador só vê o seu próprio registo).

5. Mais conectores — Sage, Primavera, SAP, Odoo, seguindo a receita acima. Cada um é trabalho isolado; não há dependências entre conectores.

6. Deploy real — hoje só corre localmente (npm run dev:http). Falta empacotar (Docker), colocar atrás de TLS/reverse proxy, e decidir onde corre dentro da infraestrutura Winsig/cliente.

7. Mapeamento aos perfis reais de cada sistema — hoje os perfis (roles.ts) são definidos manualmente; o objetivo é herdá-los diretamente dos perfis e permissões já configurados em cada ERP/plataforma (ex: perfis do PHC CS, grupos do Factorial).

8. Restrição ao nível da linha noutros conectores — o padrão :self do Factorial (scope + identity.attributes + filtragem dentro da ferramenta) é reutilizável para qualquer dado "pessoal" — ex: um vendedor só ver as suas próprias faturas no PHC.

9. Ferramentas que atravessam conectores — ex: "cria a despesa no Factorial e concilia com a fatura no PHC"; só é possível porque ambos já correm no mesmo hub, com a mesma auditoria.

10. Aprovação humana para escritas sensíveis — um nível extra de confiança que os concorrentes de ERP único não oferecem: ex. encomendas acima de X€ ficam pendentes até confirmação humana.

11. Armazenamento de credenciais e auditoria em base de dados própria — trocar o ficheiro JSON e o log local por uma base de dados dedicada ao hub, com consola de administração para emitir/revogar credenciais e consultar auditoria.

12. Expiração/renovação de sessões HTTP — hoje as sessões ficam em memória sem limite de tempo; adicionar um timeout de inatividade.