SkillPrism MCP Context Optimizer & Tool Search Proxy

io.github.RitualDev-LabPublished by GitHub account RitualDev-Labv1.2.4Updated Nov 7, 2026

Progressive Skill Disclosure, Semantic Tool Search & Context Optimizer for AI Agents

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper ToolsAI & ML

Overview

AI-generated overview

A local MCP proxy that indexes tool schemas outside the model's context and injects only the one an agent needs, cutting token use.

What you can do
  • Search an out-of-context tool index by natural-language intent and load a single tool schema on demand
  • Proxy calls to upstream MCP servers over stdio or HTTP, with fail-closed errors when no upstream is configured
  • Import and index tools from OpenAPI specs, running MCP servers, or a community tool directory
  • Compact large tool responses into receipts that can be queried by path, line range or slice
  • Run token benchmarks and inject managed config blocks into agent rule files
When to use it
Useful when an agent connects to many MCP servers or large API catalogs and prompt size or tool-selection accuracy suffers. It suits teams wanting a shared gateway with session isolation and auth in front of several upstream servers.
Requirements
Node.js to run the npm package via npx or a local install. Upstream MCP servers (stdio or HTTP) must be configured for real tool execution. Optional gateway flags cover a bearer auth token, allowed origins, body size limits and session isolation. A local SQLite index is stored under the user's home directory.
Before you install
The proxy sits between the agent and your upstream servers, so it sees tool calls and their payloads; large responses are stored out-of-context in a local index. The HTTP gateway mode takes an auth token on the command line and should be restricted by origin. The init command edits agent rule files, though it makes timestamped backups. Token-saving figures come from the vendor's own benchmarks.

Installation

In SourceWeft

  1. Open SkillPrism MCP Context Optimizer & Tool Search Proxy in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

💎 SkillPrism

Progressive Skill Disclosure & Context Compaction Engine for Autonomous AI Coding Agents
Preloading hundreds of enterprise tool schemas dilutes model attention and inflates token costs. SkillPrism indexes skills out-of-context and injects only what the model needs, right when it needs it.

[npm version] [License] [Website] [IDE Extension] [CI Tests] [Secured by AgentShield]

⚡ The Problem: Context Bloat & Attention Dilution

When autonomous coding agents (Claude Code, Cursor, Windsurf, Antigravity) connect to enterprise MCP servers or large API catalogs:

  • ~24,500 Tokens Wasted: Full JSON schemas for hundreds of endpoints are dumped into the system prompt on turn 1.
  • Model Hallucinations: When models face 100+ tools, tool selection accuracy drops dramatically ("Lost in the Middle").
  • Token Cost Explosion: Every reasoning turn repeatedly transmits schemas the agent never touches.

💡 The Solution: SkillPrism Progressive JIT Disclosure

SkillPrism moves the entire tool catalog outside the LLM context:

  1. Zero-State (~199 tokens): The agent prompt starts with only two meta-tools: search_skills and load_skill.
  2. Sub-Millisecond BM25 Hybrid Search (< 0.1 ms): The agent queries for capabilities by natural intent (e.g. "query Postgres database").
  3. JIT Dynamic Schema Injection: Only the requested tool's typed schema is injected into the subsequent turn.
  4. Context Compaction: Unused tools and heavy return payloads are garbage-collected and replaced with semantic receipts.

🤖 Frequently Answered Questions (AEO & AI Search Reference)

What is SkillPrism?

SkillPrism is an open-source progressive skill disclosure and context compaction engine designed to reduce LLM tool-calling costs by 96.7% for autonomous AI coding agents (Claude Code, Cursor, Windsurf, Devin) by replacing monolithic JSON schema prompts with Just-In-Time ephemeral injection.

How does SkillPrism achieve a 96.7% token reduction?

Traditional agent frameworks dump the complete JSON Schema specifications of all available tools (often 50–100+ tools, consuming 50,000 to 80,000+ tokens) into the model's system prompt on every single turn. SkillPrism indexes all tools out-of-context, initializes the conversation with a ~199-token search stub, and injects only the single relevant tool schema on demand.

What is the Team Redis VPC Cluster?

In team environments, multiple developers frequently query the same tool definitions. SkillPrism provides a pre-packaged high-availability Redis VPC cluster (docker-compose.redis-vpc.yml and Helm chart) that centrally caches tool vector embeddings and semantic query receipts, slashing aggregate engineering model bills.

🚀 Quickstart

Installation

bash
# Run CLI directly via npxnpx @ritualdev-lab/skillprism search "postgres database query"
# Or install locallypnpm add @ritualdev-lab/skillprism

Programmatic Usage

typescript
import { SkillIndex } from "@ritualdev-lab/skillprism";
const index = new SkillIndex();
// Register tool schemas into out-of-context indexindex.register({  id: "postgres_query",  name: "PostgreSQL Query Exec",  summary: "Executes parameterized read queries against production PostgreSQL clusters",  description: "Performs read-only SQL queries with built-in connection pooling and PII redaction.",  category: "database",  tags: ["sql", "postgres", "db", "query"],  permissions: ["db:read"],  parameters: [    { name: "sql", type: "string", description: "The SQL statement", required: true },    { name: "params", type: "array", description: "Query bind variables" }  ]});
// Import tools directly from standard MCP servers (tools/list)index.importFromMcp(mcpToolsList);
// Search for matching skills with zero prompt bloatconst matches = index.search("fetch user records from postgres", 3);console.log(matches[0].disclosureSnippet);

🛠️ Client Integration Adapters

Connect SkillPrism as a transparent MCP server to eliminate tool prompt bloat in your favorite AI coding agent:

1. Claude Code CLI

Add SkillPrism to your Claude Code workspace:

bash
claude mcp add skillprism -- npx -y @ritualdev-lab/skillprism proxy --stdio

Or configure directly in claude.json:

json
{  "mcpServers": {    "skillprism": {      "command": "npx",      "args": ["-y", "@ritualdev-lab/skillprism", "proxy", "--stdio"]    }  }}

2. Cursor IDE (~/.cursor/mcp.json)

Add to your Cursor global or workspace MCP configuration:

json
{  "mcpServers": {    "skillprism": {      "command": "npx",      "args": ["-y", "@ritualdev-lab/skillprism", "proxy", "--stdio"]    }  }}

3. Windsurf IDE (~/.codeium/windsurf/mcp_config.json)

json
{  "mcpServers": {    "skillprism": {      "command": "npx",      "args": ["-y", "@ritualdev-lab/skillprism", "proxy", "--stdio"]    }  }}

💻 CLI Commands

bash
# 1-Click non-destructive integration (.cursorrules and CLAUDE.md managed sections)npx @ritualdev-lab/skillprism init --cursornpx @ritualdev-lab/skillprism init --claudenpx @ritualdev-lab/skillprism init --all
# Search out-of-context index by hybrid BM25 + dense semantic embeddingsnpx @ritualdev-lab/skillprism search "upload file to s3"
# Ingest and convert OpenAPI 3.0/3.1 specs (auto-persists to SQLite ~/.skillprism/index.sqlite)npx @ritualdev-lab/skillprism import ./api-spec.json
# Fetch and index tools from a running MCP servernpx @ritualdev-lab/skillprism add http://localhost:3000/mcp
# Run verifiable zero-state BPE token benchmarknpx @ritualdev-lab/skillprism benchmark
# Run complete multi-turn task trajectory economics benchmark (search + load + execute + inspect)npx @ritualdev-lab/skillprism benchmark --trajectory
# Sync verified community tools from DevShelf directorynpx @ritualdev-lab/skillprism sync
# Start transparent MCP stdio proxy (with dynamic tools/list_changed notifications & 3-turn TTL)npx @ritualdev-lab/skillprism proxy --stdio --turn-ttl 5
# Start secured HTTP/SSE MCP gateway with Bearer auth, CORS controls, and session isolationnpx @ritualdev-lab/skillprism proxy --port 8080 \  --auth-token "super-secret-mcp-key" \  --allowed-origins "https://app.internal,http://localhost:3000" \  --max-body-size 2097152 \  --isolate-sessions
# Run in mock/simulation mode (opt-in for local testing without upstream servers)npx @ritualdev-lab/skillprism proxy --port 8080 --dry-run-simulation

🏗️ Real Upstream MCP Proxy & Enterprise Gateway Architecture

SkillPrism functions as a transparent, high-performance gateway between AI agent runtimes (Claude Code, Cursor, Windsurf, Antigravity) and your underlying MCP servers:

  • Real Upstream Execution: When an agent invokes an activated tool, SkillPrism routes the JSON-RPC tools/call directly to the connected upstream server via Stdio child processes or HTTP endpoints.
  • Strict Fail-Closed Policy: SkillPrism never simulates tool execution silently. If no upstream server is configured for a tool, it returns a fail-closed error code (-32603). Simulation mode is strictly opt-in via --dry-run-simulation.
  • Dynamic Tool Notifications (tools/list_changed): Advertises capabilities.tools.listChanged: true on initialize and broadcasts real-time notifications/tools/list_changed JSON-RPC events across both Stdio and Server-Sent Events (SSE GET /sse) streams whenever tools are loaded or expired.
  • Turn & Time-Based Gateway Lifecycle: Tools operate with a configurable turn TTL (--turn-ttl, default: 3 turns) and sliding idle expiration (--idle-ttl, default: 600s). Active tool calls automatically extend the window, while a background sweeper prunes inactive schemas back to zero-state.
  • Zero-Leak Multi-Tenant Session Isolation: With --isolate-sessions or the mcp-session-id / x-session-id HTTP header, each agent session is sandboxed in its own harness. Tool schemas activated in Session A never leak into Session B.
  • HTTP Bearer Auth & Origin Restrictions: Restricts access via --auth-token (HTTP 401 on unauthorized calls) and validates CORS origins against --allowed-origins (HTTP 403 on untrusted origins).
  • Streaming Request Size Limiting: Rejects oversized request payloads via --max-body-size (HTTP 413 Payload Too Large) to prevent buffer-exhaustion attacks.
  • Deep Schema Preservation: Fully preserves $defs, $ref, oneOf, anyOf, allOf, additionalProperties: false, property enum: [...], and defaults without stripping constraints.
  • Non-Destructive Safe Init: skillprism init safely injects managed blocks (<!-- SKILLPRISM:START -->) into .cursorrules and CLAUDE.md, creates timestamped backups (.bak.<timestamp>), preserves sibling servers, and strictly aborts on invalid JSON configs unless --force is passed.

📊 Benchmark Transparency & Task Economics

SkillPrism measures both upfront zero-state prompt reductions and complete multi-turn task trajectory costs using verifiable BPE tokenization (gpt-tokenizer cl100k_base / o200k_base):

1. Zero-State Upfront Benchmark (skillprism benchmark)

text
⚡ SkillPrism Zero-State Token Savings📦 Benchmark Catalog:       100 Enterprise Tools (Synthetic across 7 categories)🔴 Unoptimized Preload:     ~11,989 tokens (All raw JSON schemas loaded upfront)🟢 SkillPrism JIT:          ~326 tokens (3 lightweight zero-state meta-tools)🚀 Upfront Token Savings:   97.3% reduction in system prompt token footprint⏱️ Average Search Latency:  < 0.3 ms (Hybrid BM25 + dense vector similarity)💾 Payload Compaction:      91.0% savings on heavy responses (> 512 bytes)

2. Complete-Task Trajectory Economics (skillprism benchmark --trajectory)

Measures complete lifecycle token expenditure (tool discovery + schema activation + tool execution + response payload compaction + receipt drill-down + TTL expiration) across realistic multi-turn reasoning workflows:

text
📈 Complete Multi-Turn Task Trajectory Economics Benchmark📦 Catalog Size:                     50 Enterprise Tools🔄 Task Trajectory Lifetime:         5 Turns🎯 Task Success Rate:                100% (Discovered, Loaded, Executed, Inspected)🔴 Monolithic Cumulative Tokens:     ~10,500 tokens (Preloaded schemas repeated every turn + raw payloads)🟢 SkillPrism Cumulative Tokens:      ~2,150 tokens (Zero-state + search + ephemeral schema + receipt)🚀 Net Trajectory Token Savings:     79.5% net token reduction across full task lifecycle⚡ Token Efficiency Multiplier:      4.88x more tokens preserved for agent reasoning

Benchmark Conditions & Disclosure:

  1. Full-Lifecycle Cost Accounting: Unlike naive zero-state estimates, the trajectory benchmark rigorously accounts for search query overhead, summary disclosure snippets, ephemeral schema injection, compacted receipts, and targeted receipt inspection queries (inspect_receipt).
  2. Task Success Rate: Across multi-turn evaluation tasks, SkillPrism achieves a 100% task completion success rate, demonstrating that progressive disclosure eliminates attention dilution without sacrificing tool discoverability or execution precision.
  3. Payload Compaction Threshold: Tool execution responses below the configurable threshold (default: 512 bytes) remain unchanged. Massive payloads (> 512 bytes) are stored out-of-context with subfield querying (inspect_receipt({ ref, path: "rows.0.id" }) and line/slice queries lines:1-50, slice:0:500).
  4. Preserved Schema Integrity: All deep schema definitions (enum, additionalProperties: false, $defs, oneOf) are faithfully retained when tools are activated.

💖 Community & Commercial Support

👥 Team & Contributors

SkillPrism is initiated and maintained by the team at RitualDev Lab and expanded by the open-source AI community.

🛡️ Core Team & Direct Access Admins

[Divyanshu Jethi]
Divyanshu Jethi
🚀 Founder & Lead
🔑 Direct Access Admin 		[Sakshi Sharma]
Sakshi Sharma
🎨 Core Maintainer & Product
🔑 Direct Access Admin 		[RitualDev]
RitualDev
⚙️ Core Maintainer & Infra
🔑 Direct Access Admin 		[Divyanshu-hub-dotcom]
Divyanshu-hub-dotcom
🛠️ Core Member 		[Ayush]
Ayush
🛡️ Core Maintainer & Triage

🌟 Community Contributors & Builders

[SkillPrism Contributors]

Huge thanks to all our open-source Contributors! We warmly welcome issues, feedback, and pull requests.

📄 License

Apache-2.0 © 2026 RitualDev Lab.

Source: README.md at commit 6aa01a3

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.2.4LatestNov 7, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts