<div align="center">

🛡️ ShadowShield MCP

Cut wasted LLM tokens before they ever reach your context window.

A local-first Model Context Protocol (MCP) server that reduces LLM token usage for developers using Claude Desktop, Cursor, or Claude Code.

npx shadowshield-mcp install

No accounts. No hosted backend. No workflow changes.

</div>

---

📖 Table of Contents

• Why ShadowShield?
• Key Features
• Quick Start
• How It Works
• Local-First by Design
• Technology Stack
• Repository Structure
• Development
• Design Principles
• Roadmap
• Contributing
• Security
• License

---

🤔 Why ShadowShield?

Modern AI agents don't just consume tokens from what you type — they burn through context silently, in the background, during every tool call.

During long agentic sessions, they routinely:

• 🔁 Re-read files they've already seen
• 🔁 Execute the exact same tool call twice
• 📦 Receive oversized API responses full of noise
• 🗂️ Carry bloated prompts and outputs through the context window
• 🧹 Waste tokens on null values, dead metadata, and duplicate information

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

Nothing here is broken — but your context window fills up faster, requests get bigger, and you pay for tokens you never needed.

ShadowShield MCP sits transparently between your AI client and other MCP tools (GitHub, filesystem, web search, and more), intercepting, deduplicating, compressing, and optimizing context traffic — without requiring any change to your normal workflow.

---

⚡ Key Features

🧠 Smart Dedup Cache

Computes deterministic fingerprints for every MCP tool call. When the same tool is invoked again with identical arguments inside a rolling session window, ShadowShield serves the cached response instead of re-running the operation.

First request                          Repeated request

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

• Avoids repeated tool execution
• Cuts duplicate context
• Lowers unnecessary token usage
• Improves response latency on cache hits

✂️ Intelligent Output Compressor

A rule-based trimmer that cleans up tool responses before they ever enter the model's context.

• Strips null and empty properties
• Truncates oversized text fields
• Removes redundant metadata
• Applies whitelisted key filtering
• Reduces unnecessarily verbose structured responses

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

Send useful information to the model — not structural noise.

🔧 Code & Prompt Optimizer

Automatically rewrites oversized prompts or files to minimize their token footprint — backed by local embedding cosine similarity validation (all-MiniLM-L6-v2) to help ensure semantic meaning is preserved before any change is accepted.

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

Safety principles:

• Original files are never silently overwritten
• Optimized versions can be written separately for review
• Low-confidence transformations are rejected automatically
• Optimization stays focused on redundancy — not rewriting your code's intent

📊 Single-File Local Savings Dashboard

A lightweight, static dashboard.html — no account, no backend, no analytics service — showing:

• 💰 Total tokens saved
• 🔁 Deduplication savings
• ✂️ Compression savings
• 🔧 Optimization savings
• 📈 Daily savings trends
• 🕒 Recent optimization events

~/.shadowshield/dashboard.html

🧰 Zero-Config Installer

One command locates your MCP client config, registers ShadowShield, and preserves every existing server entry — no manual JSON editing required.

---

🚀 Quick Start

Requirements

• Node.js (v18+)
• npm
• A supported MCP-compatible client (Claude Desktop, Cursor, Claude Code)

1. Install

npx shadowshield-mcp install

Or build from source:

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

The installer will:

1. Locate your supported MCP client configuration
2. Register ShadowShield as an MCP server
3. Preserve all existing MCP server entries
4. Create the local ~/.shadowshield/ data directory
5. Configure the required runtime paths

2. Restart Your AI Client

Restart Claude Desktop, Cursor, or your Claude Code environment. ShadowShield connects automatically and exposes:

shadowshield_dedup_cache
shadowshield_compress_output
shadowshield_optimize

3. Just Use Your AI — As Normal

There's no separate ShadowShield workflow to learn.

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

4. Check Your Savings

Open the dashboard in any browser:

~/.shadowshield/dashboard.html

---

🏗️ How It Works

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

Every optimization event is measured and logged locally, so you always know exactly where your savings come from.

---

🔒 Local-First by Design

Your development context should remain under your control.

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

ShadowShield does not require:

• ❌ A ShadowShield account
• ❌ A hosted ShadowShield database
• ❌ A separate analytics backend
• ❌ Dashboard authentication
• ❌ Uploading your savings history anywhere

Your cache, logs, token accounting, embedding verification, and dashboard data stay entirely on your machine.

Any external model interaction used by configured optimization functionality depends on your own model/provider setup.

---

🧰 Technology Stack

Component	Technology
Language	TypeScript
Runtime	Node.js
MCP	@modelcontextprotocol/sdk
Cache	SQLite
Logging	JSONL
Token counting	tiktoken
Semantic verification	all-MiniLM-L6-v2
Similarity metric	Cosine similarity
Dashboard	HTML + Chart.js
Distribution	npm

---

📁 Repository Structure

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

---

🛠️ Development

Clone the repository and install dependencies:

git clone <your-repository-url>
cd shadowshield-mcp
npm install

Build the project:

npm run build

Run the installer locally:

node bin/install.js

Sanity-check the package before publishing:

npm pack --dry-run

---

🎯 Design Principles

ShadowShield follows four core principles:

#	Principle	Description
1	Reduce waste, not capability	Optimization only matters if the resulting context stays useful to the model.
2	Stay invisible	You shouldn't have to change how you work with your AI tools to save tokens.
3	Prefer local infrastructure	Caching, logs, measurement, verification, and visualization — all local, no hosted services.
4	Don't modify more than necessary	Optimization is conservative and targeted, never an excuse to rewrite unrelated code.

---

🗺️ Roadmap

• [ ] VS Code extension for inline optimization suggestions
• [ ] Per-project token savings analytics
• [ ] Additional MCP client integrations
• [ ] Improved tool-specific compression strategies
• [ ] Configurable optimization thresholds
• [ ] Weekly local savings summaries
• [ ] Better savings attribution and reporting

---

🤝 Contributing

Contributions are welcome! 🎉

If you've found a bug, have an optimization idea, or want to improve support for another MCP client or tool:

1. Check existing issues first
2. Open a new issue describing the problem or idea
3. For significant architectural changes, open an issue before submitting a PR so the approach can be discussed

---

🔐 Security

If you discover a security vulnerability, please do not publish exploit details in a public issue.

Report it privately through the repository's configured security channel instead.

---

📄 License

Released under the MIT License. See LICENSE for full details.

---

<div align="center">

🛡️ ShadowShield MCP

Less redundant context. Fewer wasted tokens. Same workflow.

npx shadowshield-mcp install

Built for developers who want their AI tooling to use context more efficiently.

⭐ If ShadowShield saves you tokens, consider starring the repo!

</div>