Sankhya Ajuda MCP

Status: ✅ Em produção · Versão: 1.5.6 · Endpoint padrão: http://<host>:3105/mcp · Tools: 11 · Resources: 6 · Prompts: 4 · Desenvolvido por: Skills IT

Servidor MCP (Model Context Protocol) que torna pesquisáveis duas bases públicas do ERP Sankhya — o help center (6.125 artigos, ajuda.sankhya.com.br) e a comunidade (7.619 posts de Q&A em 33 espaços, community.sankhya.com.br) — via busca híbrida (Reciprocal Rank Fusion sobre pgvector + FTS PT-BR com unaccent), incluindo busca unificada source-aware sobre as duas fontes.

---

📋 Índice

1. Visão Geral
2. Por que desenvolvemos este MCP?
3. Arquitetura
4. Instalação Rápida
5. Configuração nos Clientes MCP
6. Tools, Resources e Prompts
7. Exemplos de Uso
8. Embeddings: provider toggle
9. Segurança e Autenticação
10. Operação e Monitoramento
11. Troubleshooting
12. Stack Técnico
13. Disclaimer
14. Documentação Relacionada
15. Links Úteis

---

Visão Geral

O Sankhya Ajuda MCP é um servidor desenvolvido internamente pela Skills IT que implementa o Model Context Protocol (MCP) para tornar pesquisáveis as bases de conhecimento públicas do ERP Sankhya (sistema brasileiro líder em gestão empresarial).

Indexa duas fontes complementares em um único banco PostgreSQL+pgvector:

• 📚 Help center (ajuda.sankhya.com.br, Zendesk) — 6.125 artigos oficiais em 14 categorias / 230 seções
• 💬 Comunidade (community.sankhya.com.br, Bettermode) — 7.619 posts de Q&A (pergunta + respostas) em 33 espaços públicos

Este servidor permite que assistentes de IA (Claude Desktop, Claude Code, Cursor, VS Code Copilot, ChatGPT/OpenAI Responses API, e qualquer cliente MCP compatível) façam consultas estruturadas sobre as duas bases, retornando:

• 🔍 Busca híbrida com ranking de relevância (semântica + keyword) em cada fonte
• 🔗 Busca unificada source-aware (sankhya_ajuda_search_knowledge_unified) — combina help center + comunidade com RRF por fonte, dedup por título e rótulo de origem oficial
• 📖 Conteúdo completo de artigos e threads de Q&A em Markdown limpo
• 🗂️ Hierarquia de categorias e seções (14 + 230 + 59 subseções) e espaços da comunidade (33)
• 🤖 Workflows nomeados para troubleshooting, lookup, explicação de módulos e comparativos
• 📊 Estado da sincronização (das duas fontes) via endpoint público /health

Casos de Uso

Perfil	Benefício
Suporte Técnico N1/N2	Busca rápida de soluções, códigos de erro, procedimentos
Consultores	Explicação estruturada de módulos para reuniões e treinamentos
Novos colaboradores	Roteiro de onboarding com artigos oficiais em ordem didática
Analistas	Comparativos entre artigos, auditoria de conteúdo obsoleto
Bots/Integrações	API uniforme MCP para integrar com Slack/Teams/CrewAI/LangChain

---

Por que desenvolvemos este MCP?

A ferramenta oficial de IA do Sankhya (BIA — Business Intelligence Assistant) tem limitações de qualidade e cobertura. Este MCP foi desenvolvido para:

Característica	BIA (oficial)	Sankhya Ajuda MCP (Skills IT)
Cobertura de conteúdo	Limitada	✅ 6.125 artigos (help center) + 7.619 posts (comunidade) indexados
Busca unificada (help + comunidade)	❌	✅ sankhya_ajuda_search_knowledge_unified com RRF por fonte + dedup + rótulo de origem
Busca semântica	Restrita	✅ pgvector + Qwen3 / OpenAI (mutuamente exclusivos)
Busca por código de erro	Imprecisa	✅ FTS PT-BR com unaccent
Acessível via IA externa	❌	✅ Claude, ChatGPT, Cursor, Copilot, etc.
Histórico/cache local	❌	✅ PostgreSQL próprio
Atualização	?	✅ Cron diário (help center 03:00 + comunidade 04:00, SHA256 change detection)
Sem custo recorrente	❌ (B.I.A é parte do plano)	✅ Opção EMBEDDING_PROVIDER=none zero cost
Auto-hospedado	❌	✅ Docker ou PM2 nativo

Funcionalidades Exclusivas

1. Busca Híbrida RRF — Reciprocal Rank Fusion (k=60) combinando similaridade semântica e FTS PT-BR
2. Guardrail Cross-Model — detecta automaticamente quando provider de embeddings não bate com modelo do índice e degrada com aviso visível (v1.5.4)
3. Modos de fallback transparentes — keyword_fallback, keyword_index_mismatch com label visível na resposta
4. Toggle EMBEDDING_PROVIDER — vllm (local), openai (cloud) ou none (FTS-only, sem custo)
5. Tools-bridge — adaptadores que expõem resources/* e prompts/* como tools regulares, para máxima compatibilidade
6. 4 Prompts pré-configurados — workflows guiados (troubleshoot, quick_lookup, explain_module, compare_articles)
7. Calibração empírica — defaults limit=15, max_body_chars=8000 baseados em distribuição real do corpus (P50-P99) e densidade de categorias (64% em 2 categorias)
8. Dupla fonte com busca unificada — help center (Zendesk) + comunidade (Bettermode/GraphQL) no mesmo banco; sankhya_ajuda_search_knowledge_unified funde as duas com RRF por fonte, dedup por título e rótulo de origem oficial (impede que posts coloquiais "soterrem" os artigos oficiais)
9. Sync escalonado e resiliente — ETLs independentes (help 03:00, comunidade 04:00) com flock compartilhado que serializa o acesso a Postgres+vLLM; estado de sync separado por fonte (sync_state / community_sync_state)

---

Arquitetura

O projeto é composto por duas fases desacopladas, conversando apenas via schema PostgreSQL.

┌─────────────────────────────────────────────────────────────────────────┐
│  Cliente IA (Claude, ChatGPT, Cursor, Copilot, scripts...)              │
│                                                                          │
│  Streamable HTTP + Bearer (Authorization header) + MCP-Protocol-Version │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ MCP 2025-11-25
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  Sankhya Ajuda MCP Server (FASE 2 — Node 22 + TypeScript 5)             │
│  Default port :3105                                                      │
│                                                                          │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │
│  │  7 tools     │ │  4 bridge    │ │  6 resources │ │  4 prompts     │ │
│  │  (domínio +  │ │  tools       │ │  sankhya-    │ │  workflows     │ │
│  │  comunidade) │ │              │ │  ajuda://    │ │  nomeados      │ │
│  └──────────────┘ └──────────────┘ └──────────────┘ └────────────────┘ │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │  Auth (timingSafeEqual)  │  /health público  │  OAuth 404 JSON     │ │
│  │  Session lifecycle (30 min idle)  │  Response cap 400 KB           │ │
│  │  Guardrail cross-model index/provider (v1.5.4)                     │ │
│  └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │  SQL (pgvector + FTS)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  PostgreSQL 16+ com pgvector + unaccent + pg_trgm                       │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  Help Center (Zendesk):                                          │  │
│  │  categories (14)  │  sections (230, 59 aninhadas)                │  │
│  │  articles (6.125) │  embedding HALFVEC(2560) + tsvector FTS PT-BR │  │
│  │  sync_state       │  skipped_articles  │  article_breadcrumb VIEW │  │
│  │                                                                    │  │
│  │  Comunidade (Bettermode):                                        │  │
│  │  community_spaces (33 públicos)  │  community_posts (7.619)      │  │
│  │  community_sync_state            │  community_skipped_posts      │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│         Índices: HNSW pgvector + GIN FTS + btree partial outdated       │
└─────────────────────────────────────────────────────────────────────────┘
                                    ▲
                                    │  Sync diário 03:00 (SHA256 detection)
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│  ETL Sankhya Ajuda (FASE 1 — Python 3.13)                               │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Help Center (sync.sync 03:00)                                  │    │
│  │  Zendesk Help Center API (público, sem auth)                    │    │
│  │    → httpx → BeautifulSoup (HTML strip)                         │    │
│  │    → SHA256 diff → vLLM/OpenAI embedding → PostgreSQL upsert   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  Comunidade (sync.community_sync 04:00)                         │    │
│  │  Bettermode GraphQL (guest token em runtime, sem API key)      │    │
│  │    → httpx → Q&A thread composition + markdown                  │    │
│  │    → SHA256 diff → vLLM/OpenAI embedding → PostgreSQL upsert   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    ▲
                                    │
                    https://ajuda.sankhya.com.br (Help)
                 https://community.sankhya.com.br (Comunidade)

Componentes

Componente	Função	Tecnologia
Fase 1 — ETL	Scraping diário, geração de embeddings, popula banco	Python 3.13, httpx, psycopg, pgvector, beautifulsoup4, structlog
Fase 2 — MCP Server	Expõe tools/resources/prompts MCP via HTTP	Node 22 LTS, TypeScript 5, MCP SDK ≥ 1.18, Express, zod, pino, pg
Banco	Schema dedicado sankhya_ajuda	PostgreSQL 16+ + pgvector (halfvec 2560d) + unaccent + pg_trgm
Embeddings	Geração de vetores em índice e em query	vLLM (Qwen3-Embedding-4B) ou OpenAI text-embedding-3-large @ 2560
Transporte	Streamable HTTP MCP 2025-11-25	Bearer auth com crypto.timingSafeEqual, S