sankhya-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcio Nogueira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# sankhya-mcp
+
+> **Projeto em fase inicial — novas versões e funcionalidades em breve.**
+
+Servidor MCP (Model Context Protocol) para documentação do **Sankhya ERP**, com busca semântica local via RAG. Permite que o Claude (VS Code, Claude Desktop, etc.) responda perguntas precisas sobre o sistema Sankhya sem necessidade de chaves de API em runtime.
+
+---
+
+## Como funciona
+
+O conhecimento fica embutido no pacote como um índice vetorial local (`sqlite-vec`). O servidor roda localmente via STDIO e responde às queries do Claude com os trechos de documentação mais relevantes.
+
+```
+Usuário pergunta ao Claude
+        ↓
+Claude chama search_docs (MCP tool)
+        ↓
+Servidor busca no índice local (sem API externa)
+        ↓
+Claude responde com base na documentação do Sankhya
+```
+
+---
+
+## Instalação — VS Code
+
+Adicione ao `.mcp.json` do seu projeto:
+
+```json
+{
+  "mcpServers": {
+    "sankhya-docs": {
+      "command": "npx",
+      "args": ["sankhya-mcp"]
+    }
+  }
+}
+```
+
+## Instalação — Claude Desktop
+
+Adicione ao `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sankhya-docs": {
+      "command": "npx",
+      "args": ["sankhya-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Coleções disponíveis
+
+| Coleção | Descrição |
+|---|---|
+| `boletos-emissao` | Emissão de boletos e exportação de XMLs de NF-e |
+| `dashboards-html5` | Criação e otimização de dashboards HTML5 |
+| `reabertura-ops` | Correção e reabertura de ordens de produção |
+
+---
+
+## Exemplos de perguntas
+
+- *Como exportar XMLs de NF-e no Sankhya?*
+- *Como criar um dashboard HTML5?*
+- *Como otimizar queries para dashboards?*
+- *Como reabrir uma ordem de produção?*
+- *Como corrigir apontamentos de OP com quantidade errada?*
+
+---
+
+## Stack
+
+- Python 3.12+
+- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) + FastMCP
+- [sqlite-vec](https://github.com/asg017/sqlite-vec) — índice vetorial embutido
+- [fastembed](https://github.com/qdrant/fastembed) — embeddings locais (sem API externa)
+- Modelo: `paraphrase-multilingual-MiniLM-L12-v2` (384 dims, multilingual)
+
+---
+
+## Status
+
+Este projeto está em **fase inicial de desenvolvimento**. Em breve:
+
+- Novas coleções de documentação
+- Melhorias na qualidade da busca
+- Publicação no npm para uso via `npx`
+
+Sugestões e contribuições são bem-vindas via [Issues](https://github.com/mfnogueira/sankhya-mcp/issues).

package/bin/sankhya-mcp.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+const { spawn } = require("child_process");
+const path = require("path");
+
+const packageDir = path.join(__dirname, "..");
+const serverScript = path.join(packageDir, "src", "server.py");
+
+const proc = spawn("uv", ["run", "python", serverScript], {
+  cwd: packageDir,
+  stdio: "inherit",
+});
+
+proc.on("error", (err) => {
+  if (err.code === "ENOENT") {
+    process.stderr.write(
+      "Error: 'uv' is required but not installed.\n" +
+      "Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh\n"
+    );
+  } else {
+    process.stderr.write(`Error: ${err.message}\n`);
+  }
+  process.exit(1);
+});
+
+proc.on("exit", (code) => process.exit(code ?? 0));

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "sankhya-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Sankhya ERP documentation — semantic search via sqlite-vec",
+  "license": "MIT",
+  "keywords": ["mcp", "sankhya", "erp", "documentation", "rag"],
+  "homepage": "https://github.com/mfnogueira/sankhya-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mfnogueira/sankhya-mcp.git"
+  },
+  "bin": {
+    "sankhya-mcp": "./bin/sankhya-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "pyproject.toml",
+    "README.md"
+  ]
+}

package/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "sankhya-mcp"
+version = "0.1.0"
+description = "MCP server for Sankhya ERP documentation — semantic search via sqlite-vec"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp[cli]>=1.2.0",
+    "sqlite-vec>=0.1.0",
+    "fastembed>=0.4.0",
+]
+
+[project.optional-dependencies]
+ingest = [
+    "openai>=1.0.0",
+    "python-dotenv>=1.0.0",
+    "tiktoken>=0.7.0",
+    "numpy>=1.26.0",
+]
+
+[project.scripts]
+sankhya-mcp = "src.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.hatch.build.targets.sdist.force-include]
+"src/data/index.db" = "src/data/index.db"
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/data/index.db" = "src/data/index.db"

package/src/server.py

@@ -0,0 +1,183 @@
+"""
+Servidor MCP para documentação do Sankhya — transporte STDIO.
+
+IMPORTANTE: nunca usar print() — corrompe o protocolo JSON-RPC.
+Todo output de log vai para sys.stderr.
+"""
+
+import logging
+import sqlite3
+import struct
+import sys
+from pathlib import Path
+
+import sqlite_vec
+from fastembed import TextEmbedding
+from mcp.server.fastmcp import FastMCP
+
+# ── Logging ──────────────────────────────────────────────────────────────────
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="%(asctime)s  %(name)s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
+# ── Constantes ───────────────────────────────────────────────────────────────
+DB_PATH = Path(__file__).parent / "data" / "index.db"
+MODEL_NAME = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
+EMBEDDING_DIM = 384
+
+# ── Modelo de embedding (carregado sob demanda) ───────────────────────────────
+_model: TextEmbedding | None = None
+
+
+def _get_model() -> TextEmbedding:
+    global _model
+    if _model is None:
+        logger.info(f"Carregando modelo de embedding: {MODEL_NAME}")
+        _model = TextEmbedding(model_name=MODEL_NAME)
+        logger.info("Modelo carregado.")
+    return _model
+
+
+def _embed_query(text: str) -> bytes:
+    """Gera o embedding da query e serializa para bytes (formato sqlite-vec)."""
+    model = _get_model()
+    vectors = list(model.embed([text]))
+    vec = vectors[0].tolist()
+    return struct.pack(f"{len(vec)}f", *vec)
+
+
+def _get_db() -> sqlite3.Connection:
+    con = sqlite3.connect(DB_PATH)
+    con.enable_load_extension(True)
+    sqlite_vec.load(con)
+    con.enable_load_extension(False)
+    return con
+
+
+# ── FastMCP ───────────────────────────────────────────────────────────────────
+mcp = FastMCP("sankhya-docs")
+
+
+@mcp.tool()
+def search_docs(query: str, collection: str | None = None, top_k: int = 5) -> str:
+    """Busca documentação do Sankhya ERP com base em uma query semântica.
+
+    Use esta ferramenta quando o usuário perguntar sobre funcionalidades,
+    configurações, erros, fluxos de trabalho ou qualquer aspecto do sistema
+    Sankhya. Retorna os trechos de documentação mais relevantes.
+
+    Args:
+        query: Pergunta ou termo a buscar (em português ou inglês).
+        collection: Nome da coleção para filtrar resultados (opcional).
+                    Use list_collections() para ver as coleções disponíveis.
+        top_k: Número de resultados a retornar (padrão: 5).
+    """
+    if not DB_PATH.exists():
+        return "Índice de documentação não encontrado. Execute o pipeline de ingestão primeiro."
+
+    logger.info(f"search_docs: query='{query}' collection={collection!r} top_k={top_k}")
+
+    try:
+        query_vec = _embed_query(query)
+    except Exception as exc:
+        logger.error(f"Erro ao gerar embedding: {exc}")
+        return f"Erro ao processar a query: {exc}"
+
+    try:
+        con = _get_db()
+
+        # Busca os k mais próximos (ampliado para filtrar por coleção depois)
+        candidates = top_k * 10 if collection else top_k
+
+        rows = con.execute(
+            """
+            SELECT c.text, c.source_file, c.collection, c.type, e.distance
+            FROM (
+                SELECT rowid, distance
+                FROM embeddings
+                WHERE embedding MATCH ?
+                  AND k = ?
+                ORDER BY distance
+            ) e
+            JOIN chunks c ON c.id = e.rowid
+            """,
+            (query_vec, candidates),
+        ).fetchall()
+
+        con.close()
+    except Exception as exc:
+        logger.error(f"Erro na consulta ao índice: {exc}")
+        return f"Erro ao consultar o índice: {exc}"
+
+    # Filtra por coleção se solicitado
+    if collection:
+        rows = [r for r in rows if r[2] == collection]
+
+    rows = rows[:top_k]
+
+    if not rows:
+        msg = f"Nenhum resultado encontrado para '{query}'"
+        if collection:
+            msg += f" na coleção '{collection}'"
+        return msg
+
+    # Formata a resposta
+    parts: list[str] = [f"## Resultados para: {query}\n"]
+
+    for i, (text, source_file, coll, doc_type, distance) in enumerate(rows, 1):
+        similarity = round((1 - distance) * 100, 1)
+        type_label = "📷 Imagem" if doc_type == "image_description" else "📄 Documento"
+        parts.append(
+            f"### [{i}] {source_file} — {coll} ({type_label}, {similarity}% relevância)\n\n{text}"
+        )
+
+    return "\n\n---\n\n".join(parts)
+
+
+@mcp.tool()
+def list_collections() -> str:
+    """Lista todas as coleções de documentação do Sankhya disponíveis no índice.
+
+    Use esta ferramenta antes de search_docs quando quiser restringir a busca
+    a uma área específica do sistema, ou para dar ao usuário uma visão geral
+    do que está documentado.
+    """
+    if not DB_PATH.exists():
+        return "Índice de documentação não encontrado. Execute o pipeline de ingestão primeiro."
+
+    try:
+        con = sqlite3.connect(DB_PATH)
+        rows = con.execute(
+            "SELECT collection, COUNT(*) as total FROM chunks GROUP BY collection ORDER BY collection"
+        ).fetchall()
+        con.close()
+    except Exception as exc:
+        logger.error(f"Erro ao consultar coleções: {exc}")
+        return f"Erro ao consultar o índice: {exc}"
+
+    if not rows:
+        return "Índice vazio — nenhuma coleção encontrada."
+
+    total_chunks = sum(r[1] for r in rows)
+    lines = ["## Coleções de documentação disponíveis\n"]
+
+    for collection, count in rows:
+        lines.append(f"- **{collection}** — {count} trechos indexados")
+
+    lines.append(f"\n_Total: {total_chunks} trechos em {len(rows)} coleções._")
+
+    return "\n".join(lines)
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+def main() -> None:
+    logger.info(f"Iniciando servidor sankhya-docs (DB: {DB_PATH})")
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()