zihin-mcp: Instructions file for Claude Code

CLAUDE.md — @zihin/mcp-server

O que e este projeto

Pacote npm @zihin/mcp-server — proxy stdio-to-HTTP que conecta clientes MCP (Claude Desktop, Cursor, Claude Code, Codex, Windsurf) ao Zihin MCP Server em producao.

Arquitetura

Cliente MCP <-stdio-> [Proxy local (src/index.js)] <-HTTP-> https://llm.zihin.ai/mcp

• src/index.js — proxy principal (~670 linhas), exporta startProxy(), os classificadores de erro (isAuthError/isConnectionError/isProtocolVersionError/isInputRequiredError/isTimeoutError) e resolveCallTimeoutMs()
• src/install-skills.js — subcomando install-skills (skills no formato nativo de cada client)
• bin/zihin-mcp.js — CLI entry point
• Usa MCP SDK v2: Client + StreamableHTTPClientTransport (@modelcontextprotocol/client) e Server low-level + StdioServerTransport (@modelcontextprotocol/server)
• Auth via header X-Api-Key, RBAC enforced server-side

Comandos

# Rodar testes — sem key roda a suite offline; com key roda tambem a integracao (2 chamadas REAIS a chat_with_agent)
npm test
ZIHIN_API_KEY=zhn_live_xxx REQUIRE_INTEGRATION=1 npm test

# Rodar o proxy localmente
ZIHIN_API_KEY=zhn_live_xxx node bin/zihin-mcp.js

# Ressincronizar as skills empacotadas com o BE (passo de release)
npm run sync-skills                              # do checkout irmao ../zihin-agent-builder
ZIHIN_API_KEY=zhn_live_xxx npm run sync-skills -- --from-server

Convencoes

• Idioma: portugues brasileiro para docs, commits e comentarios
• Formato de commit: feat(scope): descricao, sem trailer de coautoria
• Sem emojis
• JS puro, ESM (type: module), Node.js >= 20 (exigido pelo SDK v2)
• Zero devDependencies — testes usam node:test nativo
• Dependencias: @modelcontextprotocol/client + @modelcontextprotocol/server (SDK v2, pacotes divididos)

Estrutura

zihin-mcp/
├── package.json
├── bin/zihin-mcp.js       <- CLI entry point
├── src/index.js           <- Proxy stdio-to-HTTP
├── src/install-skills.js  <- Subcomando install-skills
├── scripts/sync-skills.mjs <- Ressincroniza plugin/skills/ com o BE (release)
├── scripts/registry-publish.sh <- Publica no MCP Registry oficial (apos o latest no npm)
├── scripts/registry-verify.mjs <- Confere nome/versao exatos + isLatest no registry (so leitura)
├── test/proxy.test.js     <- Integracao real contra producao (requer key)
├── test/error-classification.test.js  <- Unit, sem rede
├── test/install-skills.test.js        <- Unit + e2e local, sem rede
├── test/registry-verify.test.js       <- Unit do verificador do registry (fetch injetado, sem rede)
├── test/plugin-manifest.test.js       <- Unit: versoes coerentes (package/server.json/plugin.json/pin do plugin) e README do plugin
├── plugin/                <- Plugin Claude Code (skills empacotadas)
├── .github/workflows/
│   ├── ci.yml             <- Testes OFFLINE em push/PR (sem key — nao queima turnos de agente)
│   └── publish.yml        <- Reexecuta a integracao real (REQUIRE_INTEGRATION=1) em tag v*, DEPOIS do publish manual — nao e o gate; publish e no-op se a versao ja esta no npm
├── README.md
├── CHANGELOG.md
├── LICENSE (MIT)
├── .gitignore
└── .npmignore