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 에이전트는 사용자가 입력한 내용에서만 토큰을 소비하지 않습니다 — 모든 도구 호출 중에 백그라운드에서 조용히 컨텍스트를 소모합니다.

긴 에이전트 세션 동안 다음과 같은 일이 일상적으로 발생합니다:

🔁 이미 본 파일을 다시 읽기
🔁 정확히 동일한 도구 호출을 두 번 실행하기
📦 노이즈로 가득 찬 과도하게 큰 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, 파일시스템, 웹 검색 등) 사이에 투명하게 위치하여 컨텍스트 트래픽을 가로채고, 중복을 제거하며, 압축하고, 최적화합니다 — 평소 워크플로우를 전혀 변경할 필요 없이 말입니다.

⚡ 주요 기능

🧠 스마트 중복 제거 캐시

모든 MCP 도구 호출에 대해 결정적(deterministic) 지문을 계산합니다. 동일한 도구가 동일한 인수로 롤링 세션 창 내에서 다시 호출되면, 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

🧰 제로 구성 설치 프로그램

한 번의 명령으로 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는 네 가지 핵심 원칙을 따릅니다:

#	원칙	설명
1	낭비를 줄이되, 기능은 유지	최적화는 결과 컨텍스트가 모델에게 여전히 유용할 때만 의미가 있습니다.
2	투명하게 유지	토큰을 절약하기 위해 AI 도구 사용 방식을 바꿀 필요가 없어야 합니다.
3	로컬 인프라 우선	캐싱, 로그, 측정, 검증, 시각화 — 모두 로컬에서, 호스팅 서비스 없이.
4	필요 이상으로 수정하지 않기	최적화는 보수적이고 목표 지향적이며, 관련 없는 코드를 재작성하는 구실이 되어서는 안 됩니다.

🗺️ 로드맵

인라인 최적화 제안을 위한 VS Code 확장 프로그램
프로젝트별 토큰 절감 분석
추가 MCP 클라이언트 통합
도구별 개선된 압축 전략
구성 가능한 최적화 임계값
주간 로컬 절감 요약
더 나은 절감 귀속 및 보고

🤝 기여

기여는 언제나 환영합니다! 🎉

버그를 발견했거나, 최적화 아이디어가 있거나, 다른 MCP 클라이언트나 도구에 대한 지원을 개선하고 싶다면:

먼저 기존 이슈를 확인하세요
문제나 아이디어를 설명하는 새 이슈를 여세요
중요한 아키텍처 변경의 경우, PR을 제출하기 전에 이슈를 열어 접근 방식을 논의하세요

🔐 보안

보안 취약점을 발견한 경우, 공개 이슈에 익스플로잇 세부 정보를 게시하지 마세요.

대신 저장소에 구성된 보안 채널을 통해 비공개로 신고해 주세요.

📄 라이선스

MIT 라이선스로 배포됩니다. 전체 내용은 LICENSE를 참조하세요.