<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.**

[![npm version](https://img.shields.io/npm/v/shadowshield-mcp.svg)](https://www.npmjs.com/package/shadowshield-mcp)
[![npm downloads](https://img.shields.io/npm/dm/shadowshield-mcp.svg)](https://www.npmjs.com/package/shadowshield-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)

```bash
npx shadowshield-mcp install
```

No accounts. No hosted backend. No workflow changes.

</div>

---

## 📖 Table of Contents

- [Why ShadowShield?](#-why-shadowshield)
- [Key Features](#-key-features)
- [Quick Start](#-quick-start)
- [How It Works](#️-how-it-works)
- [Local-First by Design](#-local-first-by-design)
- [Technology Stack](#-technology-stack)
- [Repository Structure](#-repository-structure)
- [Development](#️-development)
- [Design Principles](#-design-principles)
- [Roadmap](#️-roadmap)
- [Contributing](#-contributing)
- [Security](#-security)
- [License](#-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

```text
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.

```text
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

```json
// 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.

```text
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

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

```bash
npx shadowshield-mcp install
```

Or build from source:

```bash
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:

```text
shadowshield_dedup_cache
shadowshield_compress_output
shadowshield_optimize
```

### 3. Just Use Your AI — As Normal

There's no separate ShadowShield workflow to learn.

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

### 4. Check Your Savings

Open the dashboard in any browser:

```text
~/.shadowshield/dashboard.html
```

---

## 🏗️ How It Works

```text
┌──────────────────────────┐
│     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.**

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

```text
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:

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

Build the project:

```bash
npm run build
```

Run the installer locally:

```bash
node bin/install.js
```

Sanity-check the package before publishing:

```bash
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](../../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`](LICENSE) for full details.

---

<div align="center">

### 🛡️ ShadowShield MCP

**Less redundant context. Fewer wasted tokens. Same workflow.**

```bash
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>