🛡️ ShadowShield MCP

Recorta los tokens de LLM desperdiciados antes de que lleguen a tu ventana de contexto.

Un servidor local-first del Protocolo de Contexto de Modelo (MCP) que reduce el uso de tokens de LLM para desarrolladores que usan Claude Desktop, Cursor o Claude Code.

npx shadowshield-mcp install

Sin cuentas. Sin backend alojado. Sin cambios en el flujo de trabajo.

📖 Tabla de Contenidos

• ¿Por qué ShadowShield?

• Características Clave

• Inicio Rápido

• Cómo Funciona

• Local-First por Diseño

• Stack Tecnológico

• Estructura del Repositorio

• Desarrollo

• Principios de Diseño

• Hoja de Ruta

• Contribuciones

• Seguridad

• Licencia

Related MCP server: Refract

🤔 ¿Por qué ShadowShield?

Los agentes de IA modernos no solo consumen tokens de lo que escribes — queman contexto silenciosamente, en segundo plano, durante cada llamada de herramienta.

Durante sesiones largas de agente, rutinariamente:

• 🔁 Releen archivos que ya han visto

• 🔁 Ejecutan exactamente la misma llamada de herramienta dos veces

• 📦 Reciben respuestas de API sobredimensionadas llenas de ruido

• 🗂️ Llevan prompts y salidas inflados a través de la ventana de contexto

• 🧹 Desperdician tokens en valores nulos, metadatos muertos e información duplicada

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

Nada aquí está roto — pero tu ventana de contexto se llena más rápido, las solicitudes se vuelven más grandes y pagas por tokens que nunca necesitaste.

ShadowShield MCP se sitúa de forma transparente entre tu cliente de IA y otras herramientas MCP (GitHub, sistema de archivos, búsqueda web y más), interceptando, deduplicando, comprimiendo y optimizando el tráfico de contexto — sin requerir ningún cambio en tu flujo de trabajo normal.

⚡ Características Clave

🧠 Caché de Deduplicación Inteligente

Calcula huellas digitales deterministas para cada llamada de herramienta MCP. Cuando la misma herramienta se invoca de nuevo con argumentos idénticos dentro de una ventana de sesión móvil, ShadowShield sirve la respuesta en caché en lugar de volver a ejecutar la operación.

First request                          Repeated request

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

• Evita la ejecución repetida de herramientas

• Elimina contexto duplicado

• Reduce el uso innecesario de tokens

• Mejora la latencia de respuesta en aciertos de caché

✂️ Compresor de Salida Inteligente

Un recortador basado en reglas que limpia las respuestas de las herramientas antes de que entren en el contexto del modelo.

• Elimina propiedades nulas y vacías

• Trunca campos de texto sobredimensionados

• Elimina metadatos redundantes

• Aplica filtrado de claves en lista blanca

• Reduce respuestas estructuradas innecesariamente verbosas

// 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..."
}

Envía información útil al modelo — no ruido estructural.

🔧 Optimizador de Código y Prompts

Reescribe automáticamente prompts o archivos sobredimensionados para minimizar su huella de tokens — respaldado por validación de similitud coseno con embeddings locales (all-MiniLM-L6-v2) para ayudar a garantizar que el significado semántico se preserve antes de aceptar cualquier cambio.

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

Principios de seguridad:

• Los archivos originales nunca se sobrescriben silenciosamente

• Las versiones optimizadas se pueden escribir por separado para revisión

• Las transformaciones de baja confianza se rechazan automáticamente

• La optimización se centra en la redundancia — no en reescribir la intención de tu código

📊 Panel de Ahorros Local de Archivo Único

Un dashboard.html estático y ligero — sin cuenta, sin backend, sin servicio de análisis — que muestra:

• 💰 Total de tokens ahorrados

• 🔁 Ahorros por deduplicación

• ✂️ Ahorros por compresión

• 🔧 Ahorros por optimización

• 📈 Tendencias diarias de ahorro

• 🕒 Eventos de optimización recientes

~/.shadowshield/dashboard.html

🧰 Instalador de Configuración Cero

Un comando localiza la configuración de tu cliente MCP, registra ShadowShield y preserva cada entrada de servidor existente — sin necesidad de editar JSON manualmente.

🚀 Inicio Rápido

Requisitos

• Node.js (v18+)

• npm

• Un cliente compatible con MCP (Claude Desktop, Cursor, Claude Code)

1. Instalación

npx shadowshield-mcp install

O compilar desde el código fuente:

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

El instalador:

1. Localizará la configuración de tu cliente MCP compatible

2. Registrará ShadowShield como servidor MCP

3. Preservará todas las entradas de servidor MCP existentes

4. Creará el directorio de datos local ~/.shadowshield/

5. Configurará las rutas de ejecución necesarias

2. Reinicia tu Cliente de IA

Reinicia Claude Desktop, Cursor o tu entorno de Claude Code. ShadowShield se conecta automáticamente y expone:

shadowshield_dedup_cache
shadowshield_compress_output
shadowshield_optimize

3. Simplemente Usa tu IA — Como Siempre

No hay un flujo de trabajo separado de ShadowShield que aprender.

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

4. Revisa tus Ahorros

Abre el panel en cualquier navegador:

~/.shadowshield/dashboard.html

🏗️ Cómo Funciona

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

Cada evento de optimización se mide y registra localmente, para que siempre sepas exactamente de dónde provienen tus ahorros.

🔒 Local-First por Diseño

Tu contexto de desarrollo debe permanecer bajo tu control.

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

ShadowShield no requiere:

• ❌ Una cuenta de ShadowShield

• ❌ Una base de datos alojada de ShadowShield

• ❌ Un backend de análisis separado

• ❌ Autenticación del panel

• ❌ Subir tu historial de ahorros a ningún lugar

Tu caché, registros, contabilidad de tokens, verificación de embeddings y datos del panel permanecen completamente en tu máquina.

Cualquier interacción con modelos externos utilizada por la funcionalidad de optimización configurada depende de tu propia configuración de modelo/proveedor.

🧰 Stack Tecnológico

📁 Estructura del Repositorio

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

🛠️ Desarrollo

Clona el repositorio e instala las dependencias:

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

Compila el proyecto:

npm run build

Ejecuta el instalador localmente:

node bin/install.js

Verifica el paquete antes de publicar:

npm pack --dry-run

🎯 Principios de Diseño

ShadowShield sigue cuatro principios fundamentales:

🗺️ Hoja de Ruta

• Extensión de VS Code para sugerencias de optimización en línea

• Análisis de ahorro de tokens por proyecto

• Integraciones adicionales de clientes MCP

• Estrategias de compresión mejoradas específicas para herramientas

• Umbrales de optimización configurables

• Resúmenes semanales de ahorro local

• Mejor atribución y reporte de ahorros

🤝 Contribuciones

¡Las contribuciones son bienvenidas! 🎉

Si has encontrado un error, tienes una idea de optimización o quieres mejorar el soporte para otro cliente o herramienta MCP:

1. Revisa primero los issues existentes

2. Abre un nuevo issue describiendo el problema o la idea

3. Para cambios arquitectónicos significativos, abre un issue antes de enviar un PR para que el enfoque pueda discutirse

🔐 Seguridad

Si descubres una vulnerabilidad de seguridad, no publiques detalles de explotación en un issue público.

En su lugar, repórtala de forma privada a través del canal de seguridad configurado del repositorio.

📄 Licencia

Publicado bajo la Licencia MIT. Consulta LICENSE para obtener todos los detalles.

🛡️ ShadowShield MCP

Menos contexto redundante. Menos tokens desperdiciados. Mismo flujo de trabajo.

npx shadowshield-mcp install

Construido para desarrolladores que quieren que sus herramientas de IA usen el contexto de manera más eficiente.

⭐ Si ShadowShield te ahorra tokens, ¡considera darle una estrella al repositorio!