🛡️ ShadowShield MCP

Verschwenderische LLM-Tokens kappen, bevor sie dein Kontextfenster erreichen.

Ein lokaler Model Context Protocol (MCP)-Server, der den LLM-Tokenverbrauch für Entwickler reduziert, die Claude Desktop, Cursor oder Claude Code verwenden.

npx shadowshield-mcp install

Keine Konten. Kein gehostetes Backend. Keine Workflow-Änderungen.

📖 Inhaltsverzeichnis

• Warum ShadowShield?

• Hauptfunktionen

• Schnellstart

• So funktioniert es

• Lokal zuerst – von Grund auf

• Technologie-Stack

• Repository-Struktur

• Entwicklung

• Design-Prinzipien

• Roadmap

• Mitwirken

• Sicherheit

• Lizenz

Related MCP server: Refract

🤔 Warum ShadowShield?

Moderne KI-Agenten verbrauchen nicht nur Tokens für das, was du tippst – sie verbrennen Kontext still und leise im Hintergrund, bei jedem Tool-Aufruf.

Während langer agentischer Sitzungen tun sie regelmäßig Folgendes:

• 🔁 Dateien erneut lesen, die sie bereits gesehen haben

• 🔁 Denselben Tool-Aufruf zweimal ausführen

• 📦 Übergroße API-Antworten voller Rauschen erhalten

• 🗂️ Aufgeblähte Prompts und Ausgaben durch das Kontextfenster schleppen

• 🧹 Tokens für Nullwerte, tote Metadaten und doppelte Informationen verschwenden

AI Agent
   │
   ├── list_issues() ───────► 3,000 tokens
   │
   ├── read(config.py) ─────► 1,200 tokens
   │
   ├── read(config.py) ─────► 1,200 tokens  (again 🙃)
   │
   └── large tool response ─► 4,000 tokens

Hier ist nichts kaputt – aber dein Kontextfenster füllt sich schneller, Anfragen werden größer, und du zahlst für Tokens, die du nie gebraucht hast.

ShadowShield MCP sitzt transparent zwischen deinem KI-Client und anderen MCP-Tools (GitHub, Dateisystem, Websuche und mehr), fängt Kontextverkehr ab, dedupliziert, komprimiert und optimiert ihn – ohne dass du deinen normalen Workflow ändern musst.

⚡ Hauptfunktionen

🧠 Intelligenter Dedup-Cache

Berechnet deterministische Fingerabdrücke für jeden MCP-Tool-Aufruf. Wenn dasselbe Tool innerhalb eines rollierenden Sitzungsfensters erneut mit identischen Argumenten aufgerufen wird, liefert ShadowShield die gecachte Antwort, statt die Operation erneut auszuführen.

First request                          Repeated request

Agent → Tool Call → MCP Server         Agent → Tool Call → ShadowShield Cache
             │                                        │
             ▼                                        ▼
           Cache                                   Response ⚡

• Vermeidet wiederholte Tool-Ausführung

• Reduziert doppelten Kontext

• Senkt unnötigen Tokenverbrauch

• Verbessert die Antwortlatenz bei Cache-Treffern

✂️ Intelligenter Ausgabe-Kompressor

Ein regelbasierter Trimmer, der Tool-Antworten bereinigt, bevor sie überhaupt in den Kontext des Modells gelangen.

• Entfernt Null- und Leereigenschaften

• Kürzt überdimensionale Textfelder

• Entfernt redundante Metadaten

• Wendet Whitelist-Schlüsselfilterung an

• Reduziert unnötig ausführliche strukturierte Antworten

// Before
{
  "id": 4812,
  "title": "Authentication bug",
  "body": "...very large response...",
  "metadata": null,
  "unused_field": "",
  "internal_data": "..."
}

// After
{
  "id": 4812,
  "title": "Authentication bug",
  "body": "...trimmed, relevant content..."
}

Sende dem Modell nützliche Informationen – kein strukturelles Rauschen.

🔧 Code- & Prompt-Optimierer

Schreibt überdimensionale Prompts oder Dateien automatisch um, um ihren Token-Fußabdruck zu minimieren – unterstützt durch lokale Embedding-Kosinus-Ähnlichkeitsvalidierung (all-MiniLM-L6-v2), um sicherzustellen, dass die semantische Bedeutung erhalten bleibt, bevor eine Änderung akzeptiert wird.

Original Content
      │
      ▼
  Optimization
      │
      ▼
 Candidate Output
      │
      ▼
Local Embedding Verification
      │
      ├── Similar enough ──► ✅ Accept
      │
      └── Unsafe change ───► ❌ Reject

Sicherheitsprinzipien:

• Originaldateien werden niemals stillschweigend überschrieben

• Optimierte Versionen können separat zur Überprüfung geschrieben werden

• Transformationen mit geringer Konfidenz werden automatisch abgelehnt

• Die Optimierung konzentriert sich auf Redundanz – nicht auf das Umschreiben der Absicht deines Codes

📊 Lokales Spar-Dashboard in einer einzigen Datei

Ein leichtgewichtiges, statisches dashboard.html – kein Konto, kein Backend, kein Analysedienst – das Folgendes anzeigt:

• 💰 Gesamte gesparte Tokens

• 🔁 Einsparungen durch Deduplizierung

• ✂️ Einsparungen durch Komprimierung

• 🔧 Einsparungen durch Optimierung

• 📈 Tägliche Einsparungstrends

• 🕒 Letzte Optimierungsereignisse

~/.shadowshield/dashboard.html

🧰 Null-Konfigurations-Installer

Ein einziger Befehl findet deine MCP-Client-Konfiguration, registriert ShadowShield und erhält jeden vorhandenen Servereintrag – kein manuelles Bearbeiten von JSON erforderlich.

🚀 Schnellstart

Voraussetzungen

• Node.js (v18+)

• npm

• Ein unterstützter MCP-kompatibler Client (Claude Desktop, Cursor, Claude Code)

1. Installieren

npx shadowshield-mcp install

Oder aus dem Quellcode erstellen:

git clone <your-repository-url>
cd shadowshield-mcp
npm install
npm run build
node bin/install.js

Der Installer wird:

1. Deine unterstützte MCP-Client-Konfiguration finden

2. ShadowShield als MCP-Server registrieren

3. Alle vorhandenen MCP-Servereinträge erhalten

4. Das lokale Datenverzeichnis ~/.shadowshield/ erstellen

5. Die erforderlichen Laufzeitpfade konfigurieren

2. Starte deinen KI-Client neu

Starte Claude Desktop, Cursor oder deine Claude-Code-Umgebung neu. ShadowShield verbindet sich automatisch und stellt Folgendes bereit:

shadowshield_dedup_cache
shadowshield_compress_output
shadowshield_optimize

3. Nutze deine KI einfach – wie gewohnt

Es gibt keinen separaten ShadowShield-Workflow, den du lernen müsstest.

You
 │
 ▼
AI Client
 │
 ▼
ShadowShield
 │
 ├── Deduplication
 ├── Compression
 └── Optimization
 │
 ▼
MCP Tools / Context

4. Prüfe deine Einsparungen

Öffne das Dashboard in einem beliebigen Browser:

~/.shadowshield/dashboard.html

🏗️ So funktioniert es

┌──────────────────────────┐
│     Claude / Cursor      │
│       / MCP Client       │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│     ShadowShield MCP     │
│                          │
│  ┌────────────────────┐  │
│  │ Dedup Cache        │  │
│  ├────────────────────┤  │
│  │ Output Compressor  │  │
│  ├────────────────────┤  │
│  │ Prompt Optimizer   │  │
│  └────────────────────┘  │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│       MCP Tools          │
│                          │
│ GitHub · Filesystem      │
│ Search · APIs · etc.     │
└──────────────────────────┘

Jedes Optimierungsereignis wird lokal gemessen und protokolliert, sodass du immer genau weißt, woher deine Einsparungen stammen.

🔒 Lokal zuerst – von Grund auf

Dein Entwicklungskontext sollte unter deiner Kontrolle bleiben.

~/.shadowshield/
├── cache.db
├── savings-log.jsonl
└── dashboard.html

ShadowShield erfordert keine:

• ❌ Ein ShadowShield-Konto

• ❌ Eine gehostete ShadowShield-Datenbank

• ❌ Ein separates Analyse-Backend

• ❌ Dashboard-Authentifizierung

• ❌ Das Hochladen deines Einsparungsverlaufs

Dein Cache, deine Protokolle, deine Token-Abrechnung, deine Embedding-Überprüfung und deine Dashboard-Daten bleiben vollständig auf deinem Rechner.

Jede externe Modellinteraktion, die von der konfigurierten Optimierungsfunktionalität genutzt wird, hängt von deiner eigenen Modell-/Anbieter-Einrichtung ab.

🧰 Technologie-Stack

📁 Repository-Struktur

shadowshield-mcp/
│
├── bin/
│   └── install.js              # npx installer entry point
│
├── src/
│   ├── server.ts                # MCP server entry point
│   │
│   ├── tools/
│   │   ├── dedupCache.ts        # Tool call deduplication cache logic
│   │   ├── outputCompressor.ts  # Rule-based tool output compressor
│   │   └── optimizer.ts         # Prompt & code optimizer with embedding verification
│   │
│   ├── storage/
│   │   ├── sqlite.ts            # SQLite cache database (~/.shadowshield/cache.db)
│   │   └── logger.ts            # Append-only logger (~/.shadowshield/savings-log.jsonl)
│   │
│   └── utils/
│       ├── tokenCount.ts        # tiktoken token counter wrapper
│       └── embeddings.ts        # Local feature extraction & cosine similarity wrapper
│
├── dashboard.html               # Static savings visualization dashboard
├── downstream.example.json
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

🛠️ Entwicklung

Klone das Repository und installiere die Abhängigkeiten:

git clone (https://github.com/Mahesh8214/ShadowShield-MCP)
cd shadowshield-mcp
npm install

Erstelle das Projekt:

npm run build

Führe den Installer lokal aus:

node bin/install.js

Prüfe das Paket vor der Veröffentlichung:

npm pack --dry-run

🎯 Design-Prinzipien

ShadowShield folgt vier Kernprinzipien:

🗺️ Roadmap

• VS-Code-Erweiterung für Inline-Optimierungsvorschläge

• Token-Einsparungsanalysen pro Projekt

• Zusätzliche MCP-Client-Integrationen

• Verbesserte toolspezifische Komprimierungsstrategien

• Konfigurierbare Optimierungsschwellenwerte

• Wöchentliche lokale Einsparungszusammenfassungen

• Bessere Einsparungszuordnung und Berichterstattung

🤝 Mitwirken

Beiträge sind willkommen! 🎉

Wenn du einen Fehler gefunden hast, eine Optimierungsidee hast oder die Unterstützung für einen anderen MCP-Client oder ein anderes Tool verbessern möchtest:

1. Prüfe zuerst vorhandene Issues

2. Eröffne ein neues Issue, das das Problem oder die Idee beschreibt

3. Öffne bei bedeutenden architektonischen Änderungen ein Issue, bevor du einen PR einreichst, damit der Ansatz besprochen werden kann

🔐 Sicherheit

Wenn du eine Sicherheitslücke entdeckst, veröffentliche bitte keine Exploit-Details in einem öffentlichen Issue.

Melde sie stattdessen privat über den konfigurierten Sicherheitskanal des Repositorys.

📄 Lizenz

Veröffentlicht unter der MIT-Lizenz. Vollständige Details findest du in LICENSE.

🛡️ ShadowShield MCP

Weniger redundanter Kontext. Weniger verschwendete Tokens. Gleicher Workflow.

npx shadowshield-mcp install

Entwickelt für Entwickler, die möchten, dass ihre KI-Tools Kontext effizienter nutzen.

⭐ Wenn ShadowShield dir Tokens spart, erwäge, dem Repository einen Stern zu geben!