🛡️ ShadowShield MCP

Сократите впустую потраченные токены LLM, прежде чем они попадут в ваше контекстное окно.

Локальный сервер Model Context Protocol (MCP), который снижает расход токенов LLM для разработчиков, использующих Claude Desktop, Cursor или Claude Code.

npx shadowshield-mcp install

Никаких аккаунтов. Никакого облачного бэкенда. Никаких изменений в рабочем процессе.

📖 Содержание

• Зачем нужен ShadowShield?

• Ключевые возможности

• Быстрый старт

• Как это работает

• Локальность как принцип

• Технологический стек

• Структура репозитория

• Разработка

• Принципы проектирования

• Дорожная карта

• Участие в разработке

• Безопасность

• Лицензия

Related MCP server: Refract

🤔 Зачем нужен ShadowShield?

Современные AI-агенты потребляют токены не только из того, что вы печатаете, — они молча сжигают контекст в фоновом режиме при каждом вызове инструмента.

Во время длительных агентных сессий они регулярно:

• 🔁 Перечитывают файлы, которые уже видели

• 🔁 Выполняют один и тот же вызов инструмента дважды

• 📦 Получают раздутые ответы API, полные шума

• 🗂️ Проносят разросшиеся промпты и результаты через контекстное окно

• 🧹 Тратят токены на нулевые значения, мёртвые метаданные и дублирующуюся информацию

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

Ничего здесь не сломано — но ваше контекстное окно заполняется быстрее, запросы становятся больше, и вы платите за токены, которые вам никогда не были нужны.

ShadowShield MCP прозрачно располагается между вашим AI-клиентом и другими MCP-инструментами (GitHub, файловая система, веб-поиск и другие), перехватывая, дедуплицируя, сжимая и оптимизируя контекстный трафик — без каких-либо изменений в вашем обычном рабочем процессе.

⚡ Ключевые возможности

🧠 Умный кэш дедупликации

Вычисляет детерминированные отпечатки для каждого вызова MCP-инструмента. Когда тот же инструмент вызывается снова с идентичными аргументами в пределах скользящего окна сессии, ShadowShield возвращает кэшированный ответ вместо повторного выполнения операции.

First request                          Repeated request

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

• Исключает повторное выполнение инструментов

• Устраняет дублирующийся контекст

• Снижает ненужный расход токенов

• Улучшает задержку ответа при попадании в кэш

✂️ Интеллектуальный компрессор вывода

Правило-ориентированный оптимизатор, который очищает ответы инструментов до того, как они попадут в контекст модели.

• Удаляет нулевые и пустые свойства

• Обрезает чрезмерно длинные текстовые поля

• Убирает избыточные метаданные

• Применяет фильтрацию по белому списку ключей

• Сокращает излишне многословные структурированные ответы

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

Отправляйте модели полезную информацию, а не структурный шум.

🔧 Оптимизатор кода и промптов

Автоматически переписывает чрезмерно большие промпты или файлы, чтобы минимизировать их токенный след, — с проверкой локальной косинусной близостью эмбеддингов (all-MiniLM-L6-v2), которая помогает убедиться, что смысл сохранён до принятия любого изменения.

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

Принципы безопасности:

• Исходные файлы никогда не перезаписываются молча

• Оптимизированные версии могут записываться отдельно для проверки

• Преобразования с низкой уверенностью отклоняются автоматически

• Оптимизация сосредоточена на избыточности, а не на переписывании смысла вашего кода

📊 Локальная панель экономии в одном файле

Лёгкий статический dashboard.html — без аккаунта, без бэкенда, без сервисов аналитики — показывающий:

• 💰 Всего сэкономлено токенов

• 🔁 Экономия от дедупликации

• ✂️ Экономия от сжатия

• 🔧 Экономия от оптимизации

• 📈 Дневные тренды экономии

• 🕒 Последние события оптимизации

~/.shadowshield/dashboard.html

🧰 Установщик без настройки

Одна команда находит конфигурацию вашего MCP-клиента, регистрирует ShadowShield и сохраняет все существующие записи серверов — ручное редактирование JSON не требуется.

🚀 Быстрый старт

Требования

• Node.js (v18+)

• npm

• Поддерживаемый MCP-совместимый клиент (Claude Desktop, Cursor, Claude Code)

1. Установка

npx shadowshield-mcp install

Или сборка из исходников:

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

Установщик:

1. Найдёт конфигурацию вашего поддерживаемого MCP-клиента

2. Зарегистрирует ShadowShield как MCP-сервер

3. Сохранит все существующие записи MCP-серверов

4. Создаст локальный каталог данных ~/.shadowshield/

5. Настроит необходимые пути выполнения

2. Перезапустите ваш AI-клиент

Перезапустите Claude Desktop, Cursor или ваше окружение Claude Code. ShadowShield подключится автоматически и предоставит:

shadowshield_dedup_cache
shadowshield_compress_output
shadowshield_optimize

3. Просто пользуйтесь своим AI — как обычно

Отдельного рабочего процесса ShadowShield учить не нужно.

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

4. Проверьте свою экономию

Откройте панель в любом браузере:

~/.shadowshield/dashboard.html

🏗️ Как это работает

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

Каждое событие оптимизации измеряется и записывается локально, так что вы всегда точно знаете, откуда берётся ваша экономия.

🔒 Локальность как принцип

Ваш контекст разработки должен оставаться под вашим контролем.

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

ShadowShield не требует:

• ❌ Аккаунта ShadowShield

• ❌ Облачной базы данных ShadowShield

• ❌ Отдельного бэкенда аналитики

• ❌ Аутентификации на панели

• ❌ Загрузки вашей истории экономии куда-либо

Ваш кэш, журналы, учёт токенов, проверка эмбеддингов и данные панели остаются полностью на вашей машине.

Любое внешнее взаимодействие с моделью, используемое настроенной функциональностью оптимизации, зависит от вашей собственной настройки модели/провайдера.

🧰 Технологический стек

📁 Структура репозитория

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

🛠️ Разработка

Клонируйте репозиторий и установите зависимости:

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

Соберите проект:

npm run build

Запустите установщик локально:

node bin/install.js

Проверьте пакет перед публикацией:

npm pack --dry-run

🎯 Принципы проектирования

ShadowShield следует четырём основным принципам:

🗺️ Дорожная карта

• Расширение VS Code для встроенных предложений по оптимизации

• Аналитика экономии токенов по проектам

• Дополнительные интеграции MCP-клиентов

• Улучшенные стратегии сжатия для конкретных инструментов

• Настраиваемые пороги оптимизации

• Еженедельные локальные сводки экономии

• Улучшенная атрибуция и отчётность по экономии

🤝 Участие в разработке

Вклад приветствуется! 🎉

Если вы нашли ошибку, у вас есть идея по оптимизации или вы хотите улучшить поддержку другого MCP-клиента или инструмента:

1. Сначала проверьте существующие issues

2. Откройте новый issue с описанием проблемы или идеи

3. Для значительных архитектурных изменений откройте issue до отправки PR, чтобы подход можно было обсудить

🔐 Безопасность

Если вы обнаружили уязвимость в безопасности, пожалуйста, не публикуйте детали эксплуатации в публичном issue.

Сообщите о ней приватно через настроенный канал безопасности репозитория.

📄 Лицензия

Выпущено под лицензией MIT. Полные условия см. в LICENSE.

🛡️ ShadowShield MCP

Меньше избыточного контекста. Меньше потраченных впустую токенов. Тот же рабочий процесс.

npx shadowshield-mcp install

Создан для разработчиков, которые хотят, чтобы их AI-инструменты использовали контекст эффективнее.

⭐ Если ShadowShield экономит ваши токены, поставьте звёздочку репозиторию!