convez.ai
MCP ServerIntegração & APIsIntermediário
Maximus1

Semantik MCP Server

Maximus1/semantik-mcp

Compressão semântica de documentação para economizar tokens em LLMs

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que comprime textos e documentações para LLMs através de análise semântica automática e substituição de termos frequentes por canonicals. Reduz consumo de tokens em 50-85% mantendo fidelidade informacional, ideal para agentes de IA que recarregam contexto repetidamente.

Instalação

$npx convez-ai Maximus1/semantik-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Reduzir custos de tokens em agentes Claude/Cline que recarregam documentação
  • Otimizar prompts longos com terminologia repetida via canonicals
  • Compactar bases de conhecimento para contexto limitado de LLMs

Veredito

Ferramenta técnica legítima para otimização de tokens em workflows com LLMs, com abordagem criativa via canonicals. Produção-ready com 145 testes passando, mas requer compreensão profunda de MCP e compressão semântica para máxima efetividade.

README

A tradução para o português deste README ainda está na fila.

Semantik MCP Server – Token-Kompression für LLM-Dokumentation

Python 3.10+ MCP Tests


Warum? (Sinnstiftung)

Das Problem

LLMs haben begrenzte Kontextfenster. Jedes Token kostet Geld und Speicher. Wenn ein LLM bei jedem Start seine gesamte Projektdokumentation neu laden muss, fressen lange Fachbegriffe und wiederkehrende Satzteile wertvollen Kontext – ohne Informationsgewinn.

Beispiel: Der Satz "Die Dokumentation beschreibt die Funktionsweise der Installation" enthält 68 Zeichen. Mit Canonicals: "Die *-DOKU beschreibt die *-FKT der *-INST" – nur 44 Zeichen. 35% weniger Tokens – bei gleichem Informationsgehalt.

Die Lösung

Dieser MCP-Server analysiert automatisch alle Texte, die durch ihn verarbeitet werden, erkennt häufige Wörter und Satzteile und ersetzt sie durch kurze Canonical-Platzhalter (*-PRÄFIX). Der LLM kann dieselbe Dokumentation mit 50-85% weniger Tokens lesen – und beim ersten Start expandieren wir die Canonicals zurück zur Vollform.

Für wen?

  • LLM-Agenten (Cline, Claude Desktop, Continue), die bei jedem Neustart Doku laden müssen
  • Prompt-Ingenieure, die maximale Token-Effizienz aus ihren Prompt-Templates holen wollen
  • Teams, die LLM-basierte Dokumentationssysteme betreiben und Token-Kosten sparen möchten

Was? (Information)

Die 16 Tools im Überblick

KategorieToolFunktion
Textanalysetool_map_textNormiert Fachbegriffe, zählt Wörter für Lernen
tool_summarize_textFasst Texte zusammen (Term-Häufigkeit)
tool_compare_versionsVergleicht zwei Textversionen
tool_extract_entitiesExtrahiert erkannte Fachbegriffe
tool_detect_languageErkennt Deutsch/Englisch
tool_translate_textÜbersetzt via Google Translate
tool_optimize_codeFormatiert Code sicher (AST-Whitelist)
Mappingtool_get_mappingsZeigt alle Terminologiemappings
tool_approve_learningBestätigt Mapping-Kandidaten
tool_get_learning_statsZeigt Wort-Frequenzen und Kandidaten
Canonicaltool_get_prompt_contextGibt kompakte Canonical-Zeichenkette
tool_save_llm_dokuSchreibt Doku mit Canonical-Kompression
tool_expand_dokuExpandiert Canonicals zurück zur Vollform
Konfigurationtool_configureLLM-Provider einrichten
tool_configure_trackerLimits und Schwellen zur Laufzeit anpassen
tool_config_llm_dokuPfad zur LLM-Dokumentation konfigurieren

Die 3 Kompressionsebenen

Ebene 1: Einzelwort           *-DOKUMENTATION → Dokumentation    (spart ~60%)
Ebene 2: Satzteil             *-ZUMBEISPIEL  → zum Beispiel      (spart ~65%)
Ebene 3: Zusammensetzung      **-MOFA        → *-MOT+*-FAH       (spart ~75%)

Architektur

┌─────────────────────────────────────────────────────────┐
│                   MCP-Client (Cline/Claude/VSCode)       │
└────────────────────────┬────────────────────────────────┘
                         │ Stdio (JSON-RPC)
┌────────────────────────▼────────────────────────────────┐
│                   Semantik MCP Server                    │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ 15 Tools  │  │   Tracker    │  │  Canonical Engine  │  │
│  │ (MCP API) │──│ (Zählung +   │──│ (*-PRÄFIX-Gen.)    │  │
│  │           │  │  Auto-Canon.)│  │                    │  │
│  └──────────┘  └──────┬───────┘  └───────────────────┘  │
│                        │                                 │
│               ┌───────▼────────┐                         │
│               │  Idle-Persistenz│                         │
│               │  (30s, mappings.json)│                    │
│               └────────────────┘                          │
└──────────────────────────────────────────────────────────┘

Sicherheitsarchitektur

SchutzMechanismus
Memory-DoSWort-Limits: 10.000/20.000/5.000 (einstellbar)
ReDoSre.escape() + Längenbegrenzung auf 200 Patterns
SSRFHost-Whitelist (localhost, openrouter.ai)
Path Traversalis_relative_to() + is_absolute()
AST-InjectionWhitelist erlaubter AST-Knoten
Thread-Safetythreading.RLock für alle Zugriffe
Canonical-KollisionMaximal 999 Versuche (keine Endlosschleife)

Wie? (Anwendung)

Installation

# Mit uv (empfohlen)
uv sync

# Oder mit pip
pip install -r requirements.txt

MCP-Konfiguration (einmalig)

Cline (VS Code)

Öffne die Cline-Einstellungen unter: File → Preferences → Settings → Extensions → Cline → Edit in settings.json

Füge den semantik-Server in cline_mcp_settings.json hinzu:

{
  "mcpServers": {
    "semantik": {
      "autoApprove": [
        "tool_map_text", "tool_summarize_text", "tool_compare_versions",
        "tool_extract_entities", "tool_detect_language", "tool_get_mappings",
        "tool_optimize_code", "tool_translate_text", "tool_configure",
        "tool_configure_tracker", "tool_get_learning_stats", "tool_approve_learning",
        "tool_get_prompt_context", "tool_save_llm_doku", "tool_expand_doku",
        "tool_config_llm_doku"
      ],
      "disabled": false,
      "timeout": 60,
      "command": "uv",
      "args": ["run", "--directory", "G:/Programmierung/semantik MCP", "mcp_server/main.py"],
      "env": {
        "LLM_PROVIDER": "openrouter",
        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
        "LLM_MODEL": "openai/gpt-oss-120b:free",
        "LLM_API_KEY": "DEIN_OPENROUTER_API_KEY"
      },
      "type": "stdio"
    }
  }
}

Wichtig: Ersetze DEIN_OPENROUTER_API_KEY durch deinen persönlichen OpenRouter-API-Key. Den Key erhältst du unter https://openrouter.ai/keys. Den Key niemals in Git-Repositories oder öffentlichen Config-Dateien speichern!

Alternative Provider (lokal ohne API-Key):

"env": {
  "LLM_PROVIDER": "ollama",
  "LLM_BASE_URL": "http://localhost:11434",
  "LLM_MODEL": "llama3.2"
}

Alternative Provider (LM Studio):

"env": {
  "LLM_PROVIDER": "lmstudio",
  "LLM_BASE_URL": "http://localhost:1234/v1",
  "LLM_MODEL": "local-model"
}

Nach dem Speichern: VS Code neu starten (Ctrl+Shift+P → "Developer: Reload Window").

Erste Schritte

1. Provider konfigurieren (einmalig):

tool_configure(provider="ollama", model="llama3.2")

2. Texte analysieren lassen – jeder Aufruf zählt automatisch Wörter:

tool_map_text(text="Die Dokumentation beschreibt die Funktionsweise der Installation")

3. Auto-Canonical läuft im Hintergrund – nach 5 Vorkommen eines Wortes generiert der Server automatisch ein *-PRÄFIX-Mapping:

→ *-DOKU für "Dokumentation"
→ *-FKT für "Funktionsweise"
→ *-INST für "Installation"

4. Prompt-Kontext abrufen – kompakte Zeichenkette für deinen LLM-Prompt:

tool_get_prompt_context()
→ *-DOKU→Dokumentation|*-FKT→Funktionsweise|*-INST→Installation

5. LLM-Doku speichern – mit Canonical-Kompression:

tool_save_llm_doku(
    path="G:/Programmierung/MeinProjekt/llm-doku.md",
    text="Die Dokumentation beschreibt die Funktionsweise der Installation."
)
→ Ersparnis: 35%

6. Doku beim Neustart expandieren:

tool_expand_doku(path="G:/Programmierung/MeinProjekt/llm-doku.md")
→ "Die Dokumentation beschreibt die Funktionsweise der Installation."

Limits anpassen

Standardwerte für die meisten Fälle ausreichend. Anpassung nur bei Bedarf:

tool_configure_tracker(
    threshold=10,       // Canonical erst ab 10 Vorkommen
    max_all_words=50000 // Mehr Wörter im Tracking
)

Entwickler-Runner mit Hot-Reload

python scripts/run_server.py

Tests ausführen

pytest                    # 145 Tests
pytest --cov=mcp_server   # Mit Coverage

Was wäre, wenn? (Adaption)

Erweiterungsmöglichkeiten

1. Eigene Domänen-Mappings einspielen:
Lege in protected_terms.json Fachbegriffe fest, die nie ersetzt werden:

{
  "terms": ["def", "class", "import"],
  "phrases": ["zum Beispiel", "in der Regel"]
}

2. Blacklist für Canonicals erweitern:
Füge in protected_terms.json unter "phrases" Satzteile hinzu, die als Canonical zu ungenau wären.

3. Doku aus anderen Tools generieren:
Nutze die MCP-Resource config://status um den Server-Zustand in deine Doku einzubinden.

Best Practices

SituationEmpfehlung
Viele kurze WörterThreshold erhöhen (z.B. 10)
Wenige lange FachbegriffeThreshold senken (z.B. 3)
Server läuft dauerhaftLimits großzügig (50k/100k)
Server startet oft neusave_llm_doku + expand_doku Workflow
API-Key-SicherheitSEMANTIK_MASTER_KEY statt Datei

Bekannte Grenzen

  • Canonicals nur für Wörter ≥ 4 Buchstaben – kürzere Wörter sparen nichts
  • Maximal 999 Kollisionen pro Prefix – bei extrem vielen ähnlichen Wörtern wird abgebrochen
  • Bigramm-Canonicals nur wenn beide Einzelwörter Canonicals haben – kein direktes Mapping ohne Vorstufe
  • Kein automatisches Rate-Limiting – für SaaS-Betrieb bitte einen API-Gateway vorschalten

Migration

Das Format der mappings.json ist abwärtskompatibel:

  • Bestehende Mappings ("Kühlung": ["kühlung", ...]) bleiben unverändert
  • Canonical-Mappings werden als zusätzliche Einträge hinzugefügt ("*-KÜHL": ["kühlung"])
  • Beim nächsten Start werden beide Formate geladen

Lizenz: MIT
Repository: github.com/Maximus1/semantik-mcp

Ver o original no GitHub

Bom para

Relacionados