de en es ja ko ru zh

ShadowShield MCP

Name: ShadowShield MCP
Author: Mahesh8214

by Mahesh8214

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

🛡️ ShadowShield MCP

在浪费的 LLM token 进入你的上下文窗口之前，先将其削减。

一个本地优先的模型上下文协议（MCP）服务器，为使用 Claude Desktop、Cursor 或 Claude Code 的开发者减少 LLM token 用量。

npm version npm downloads License: MIT Node

npx shadowshield-mcp install

无需账户。无需托管后端。无需改变工作流程。

📖 目录

Related MCP server: Refract

🤔 为什么选择 ShadowShield？

现代 AI 代理不仅消耗你输入内容产生的 token——它们还会在后台、在每次工具调用期间，悄无声息地烧掉上下文。

在长时间的代理会话中，它们通常会：

🔁 重新读取已经看过的文件
🔁 执行完全相同的工具调用两次
📦 接收充满噪音的超大 API 响应
🗂️ 将臃肿的提示词和输出带入上下文窗口
🧹 在空值、无用元数据和重复信息上浪费 token

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

这里没有任何东西是坏的——但你的上下文窗口会更快被填满，请求会变得更大，而你为根本不需要的 token 付了钱。

ShadowShield MCP 透明地驻留在你的 AI 客户端和其他 MCP 工具（GitHub、文件系统、网络搜索等）之间，拦截、去重、压缩并优化上下文流量——无需对你的正常工作流程做任何更改。

⚡ 核心特性

🧠 智能去重缓存

为每次 MCP 工具调用计算确定性指纹。当同一工具在滚动会话窗口内以相同参数再次被调用时，ShadowShield 会直接提供缓存的响应，而不是重新执行该操作。

First request                          Repeated request

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

避免重复执行工具
削减重复上下文
降低不必要的 token 用量
缓存命中时改善响应延迟

✂️ 智能输出压缩器

一个基于规则的修剪器，在工具响应进入模型上下文之前对其进行清理。

剔除 null 和空属性
截断过大的文本字段
移除冗余元数据
应用白名单键过滤
减少不必要的冗长结构化响应

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

把有用的信息交给模型——而不是结构噪音。

🔧 代码与提示词优化器

自动重写过大的提示词或文件，以最小化其 token 占用——并由本地嵌入余弦相似度验证（all-MiniLM-L6-v2）提供支持，帮助确保在采纳任何更改之前语义含义得到保留。

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

安全原则：

原始文件绝不会被静默覆盖
优化版本可以单独写出以供审查
低置信度的转换会被自动拒绝
优化只聚焦于冗余——而不是重写你代码的意图

📊 单文件本地节省仪表盘

一个轻量级的静态 dashboard.html——无需账户、无需后端、无需分析服务——展示：

💰 节省的 token 总数
🔁 去重节省
✂️ 压缩节省
🔧 优化节省
📈 每日节省趋势
🕒 最近的优化事件

~/.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

安装器将：

定位你受支持的 MCP 客户端配置
将 ShadowShield 注册为 MCP 服务器
保留所有现有 MCP 服务器条目
创建本地 ~/.shadowshield/ 数据目录
配置所需的运行时路径

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 数据库
❌ 单独的分析后端
❌ 仪表盘身份验证
❌ 将你的节省历史上传到任何地方

你的缓存、日志、token 核算、嵌入验证和仪表盘数据完全保留在你的机器上。

配置的优化功能所使用的任何外部模型交互，都取决于你自己的模型/提供商设置。

🧰 技术栈

组件	技术
语言	TypeScript
运行时	Node.js
MCP	`@modelcontextprotocol/sdk`
缓存	SQLite
日志	JSONL
Token 计数	`tiktoken`
语义验证	`all-MiniLM-L6-v2`
相似度度量	余弦相似度
仪表盘	HTML + Chart.js
分发	npm

📁 仓库结构

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 遵循四项核心原则：

#	原则	描述
1	减少浪费，而非削减能力	优化只有在结果上下文对模型仍然有用时才有意义。
2	保持隐形	你不应该为了节省 token 而改变使用 AI 工具的方式。
3	优先本地基础设施	缓存、日志、度量、验证和可视化——全部本地化，不依赖托管服务。
4	不过度修改	优化是保守且有目标的，绝不是重写无关代码的借口。

🗺️ 路线图

用于内联优化建议的 VS Code 扩展
按项目的 token 节省分析
更多 MCP 客户端集成
改进的特定工具压缩策略
可配置的优化阈值
每周本地节省摘要
更好的节省归因与报告

🤝 贡献

欢迎贡献！🎉

如果你发现了 bug、有优化想法，或者想改进对另一个 MCP 客户端或工具的支持：

先查看现有的 issues
打开一个新 issue，描述问题或想法
对于重大的架构变更，请在提交 PR 之前先打开一个 issue，以便讨论方案

🔐 安全

如果你发现了安全漏洞，请不要在公开 issue 中发布漏洞利用细节。

请通过仓库配置的安全渠道私下报告。

📄 许可证

以 MIT 许可证发布。完整详情请参阅 LICENSE。