de en es ja ko ru zh

ShadowShield MCP

Name: ShadowShield MCP
Author: Mahesh8214

by Mahesh8214

Overview Schema Related Servers Score Discussions

TypeScript

Local

🛡️ ShadowShield MCP

無駄なLLMトークンを、コンテキストウィンドウに到達する前に削減します。

Claude Desktop、Cursor、Claude Codeを使用する開発者向けに、LLMトークン使用量を削減するローカルファーストのModel Context Protocol (MCP)サーバーです。

npm version npm downloads License: MIT Node

npx shadowshield-mcp install

アカウント不要。ホスト型バックエンド不要。ワークフローの変更も不要。

📖 目次

Related MCP server: Refract

🤔 ShadowShieldが必要な理由

現代のAIエージェントは、あなたが入力した内容だけでトークンを消費するわけではありません。ツール呼び出しのたびに、バックグラウンドで静かにコンテキストを消費し続けます。

長時間のエージェントセッション中、エージェントは日常的に以下を行います：

🔁 既に確認したファイルを再読込する
🔁 まったく同じツール呼び出しを2回実行する
📦 ノイズだらけの過剰なAPIレスポンスを受け取る
🗂️ 肥大化したプロンプトと出力をコンテキストウィンドウに持ち込む
🧹 null値、不要なメタデータ、重複情報にトークンを浪費する

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、ファイルシステム、Web検索など）の間に透過的に配置され、コンテキストトラフィックをインターセプト、重複排除、圧縮、最適化します。通常のワークフローを変更する必要はありません。

⚡ 主な機能

🧠 スマート重複排除キャッシュ

すべてのMCPツール呼び出しに対して決定的なフィンガープリントを計算します。ローリングセッションウィンドウ内で同じツールが同一の引数で再度呼び出された場合、ShadowShieldは操作を再実行せずにキャッシュされたレスポンスを提供します。

First request                          Repeated request

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

ツールの繰り返し実行を回避
重複コンテキストを削減
不要なトークン使用量を削減
キャッシュヒット時のレスポンスレイテンシを改善

✂️ インテリジェント出力圧縮

ツールのレスポンスがモデルのコンテキストに入る前にクリーンアップする、ルールベースのトリマーです。

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

構造的なノイズではなく、有用な情報をモデルに送信します。

🔧 コード＆プロンプト最適化

過大なプロンプトやファイルを自動的に書き換え、トークンフットプリントを最小化します。変更を受け入れる前に意味が保持されていることを確認するため、ローカル埋め込みコサイン類似度検証（all-MiniLM-L6-v2）でバックアップされています。

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

安全原則：

元のファイルが黙って上書きされることはありません
最適化バージョンはレビュー用に別途書き出すことができます
信頼度の低い変換は自動的に拒否されます
最適化は冗長性に焦点を当てたものであり、コードの意図を書き換えるものではありません

📊 単一ファイルのローカル節約ダッシュボード

軽量な静的dashboard.html — アカウント不要、バックエンド不要、アナリティクスサービス不要 — で以下を表示します：

💰 節約されたトークン総数
🔁 重複排除による節約
✂️ 圧縮による節約
🔧 最適化による節約
📈 日別の節約トレンド
🕒 最近の最適化イベント

~/.shadowshield/dashboard.html

🧰 ゼロ設定インストーラー

1つのコマンドで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データベース
❌ 別のアナリティクスバックエンド
❌ ダッシュボード認証
❌ 節約履歴をどこかにアップロードすること

キャッシュ、ログ、トークン会計、埋め込み検証、ダッシュボードデータはすべて、完全にあなたのマシン上に留まります。

設定された最適化機能で使用される外部モデルとのやり取りは、お客様自身のモデル/プロバイダー設定に依存します。

🧰 技術スタック

コンポーネント	技術
言語	TypeScript
ランタイム	Node.js
MCP	`@modelcontextprotocol/sdk`
キャッシュ	SQLite
ロギング	JSONL
トークンカウント	`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は4つの核となる原則に従います：

#	原則	説明
1	無駄を減らし、能力は削らない	最適化は、結果として得られるコンテキストがモデルにとって有用であり続ける場合にのみ意味を持ちます。
2	見えない存在であること	トークンを節約するために、AIツールの使い方を変える必要があってはなりません。
3	ローカルインフラを優先	キャッシュ、ログ、測定、検証、可視化 — すべてローカルで、ホスト型サービスは不要です。
4	必要以上に変更しない	最適化は保守的かつ的を絞ったものであり、無関係なコードを書き換える口実ではありません。

🗺️ ロードマップ

VS Code拡張機能によるインライン最適化提案
プロジェクト別のトークン節約分析
追加のMCPクライアント統合
ツール固有の圧縮戦略の改善
設定可能な最適化しきい値
週次のローカル節約サマリー
節約の帰属とレポートの改善

🤝 コントリビューション

コントリビューションを歓迎します！🎉

バグを見つけた場合、最適化のアイデアがある場合、または別のMCPクライアントやツールのサポートを改善したい場合は：

まず既存のissuesを確認してください
問題やアイデアを説明する新しいissueを開いてください
重要なアーキテクチャ変更の場合は、PRを提出する前にissueを開き、アプローチについて議論できるようにしてください

🔐 セキュリティ

セキュリティの脆弱性を発見した場合は、公開issueにエクスプロイトの詳細を公開しないでください。

代わりに、リポジトリで設定されているセキュリティチャネルを通じて非公開で報告してください。

📄 ライセンス

MITライセンスの下で公開されています。詳細はLICENSEを参照してください。