@weave_protocol/inspector

🔍 @weave_protocol/inspector

Real-Time MCP Security Proxy for AI Agents

Part of the Weave Protocol security suite.

✨ What It Does

Inspector sits between AI agents and MCP servers, providing:

┌─────────────────────────────────────────────────────────────┐
│  AI Agent (Claude Code, Cursor, etc.)                       │
└─────────────────┬───────────────────────────────────────────┘
                  │ Tool calls
                  ▼
┌─────────────────────────────────────────────────────────────┐
│  🔍 Weave Inspector                                         │
│                                                             │
│  • Intercept every tool call                                │
│  • Scan arguments for secrets, PII, injection               │
│  • Detect drift from declared intent                        │
│  • Check server reputation                                  │
│  • Gate risky operations for approval                       │
│  • Log everything with blockchain anchoring                 │
│                                                             │
└─────────────────┬───────────────────────────────────────────┘
                  │ Approved calls only
                  ▼
┌─────────────────────────────────────────────────────────────┐
│  Target MCP Servers (filesystem, github, slack, etc.)       │
└─────────────────────────────────────────────────────────────┘

"Said X, Doing Y" Detection: Catches when an AI agent says it will "read a file" but actually tries to "delete the database."

📦 Installation

npm install @weave_protocol/inspector

🚀 Quick Start

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "inspector": {
      "command": "npx",
      "args": ["-y", "@weave_protocol/inspector"]
    }
  }
}

Basic Usage

import { Interceptor, ReputationManager } from '@weave_protocol/inspector';

// Create components
const interceptor = new Interceptor({
  mode: 'active',           // 'passive' | 'active' | 'strict'
  scanEnabled: true,
  driftDetectionEnabled: true,
  reputationEnabled: true,
  minReputationScore: 30,
});

const reputationManager = new ReputationManager();

// Wire them together
interceptor.setReputationChecker(async (serverId) => {
  return reputationManager.getScore(serverId);
});

// Create a session
const session = interceptor.createSession('my-agent');

// Declare intent (enables drift detection)
interceptor.declareIntent(session.id, 'Read and summarize the README file');

// Intercept a tool call
const call = await interceptor.intercept(
  session.id,
  'filesystem',
  'read_file',
  { path: '/README.md' }
);

if (call.status === 'approved') {
  // Execute the actual call
  // ...
  interceptor.recordResult(call.id, result);
} else if (call.status === 'pending') {
  console.log('Manual approval required:', call.decisionReason);
} else {
  console.log('Blocked:', call.decisionReason);
}

🛠️ MCP Tools

Session Management

Tool	Purpose
inspector_create_session	Start inspection session
inspector_declare_intent	Declare what you plan to do
inspector_end_session	End session and get summary

Live Feed & History

Tool	Purpose
inspector_get_live_feed	Real-time stream of intercepted calls
inspector_get_call_history	Query historical call data
inspector_diff_intent	"Said X, doing Y" analysis

Manual Approval

Tool	Purpose
inspector_get_pending	List calls waiting for approval
inspector_approve_call	Manually approve a pending call
inspector_block_call	Manually block a pending call

Reputation

Tool	Purpose
inspector_check_reputation	Get server trust score
inspector_report_suspicious	Report bad behavior
inspector_get_server_stats	Detailed server analytics
inspector_list_servers	List all known servers

Configuration

Tool	Purpose
inspector_set_policy	Configure inspection rules
inspector_get_config	View current settings
inspector_get_stats	Overall statistics

🔒 Inspection Modes

Mode	Behavior
passive	Log everything, block nothing
active	Block critical issues, require approval for high-risk
strict	Block all high-risk operations automatically

// Set mode via tool
inspector_set_policy({ mode: 'strict' })

// Or programmatically
interceptor.setConfig({ mode: 'strict' });

📊 Reputation Scoring

Servers are scored 0-100 based on:

Factor	Weight	Description
Trust	30%	Verification status, age, known good
Security	40%	Blocked calls, scan results
Community	15%	User reports, confirmed issues
Reliability	15%	Success rate, response time

Pre-loaded Trusted Servers

anthropic/filesystem     - 95
anthropic/github         - 95
anthropic/slack          - 90
modelcontextprotocol/*   - 85-90

Automatic Detection

• Malicious name patterns (hack, exploit, etc.) → Start at 10
• Typosquatting detection → Flag for review
• Unknown servers → Start at 50

🎯 Drift Detection

Compares declared intent against actual tool calls:

// Declare intent
inspector_declare_intent({
  session_id: 'abc123',
  intent: 'Read and summarize the README file'
});

// Later, if the agent tries to:
// - Delete files → DRIFT DETECTED (scope expansion)
// - Access payment data → DRIFT DETECTED (data access)
// - Execute code → DRIFT DETECTED (capability escalation)

Drift severity:

• Low: Minor deviation, auto-approved
• Medium: Requires review in active mode
• High: Blocked in strict mode, requires approval in active
• Critical: Always blocked

🔌 Integration with Mund & Domere

Inspector integrates with other Weave Protocol packages:

import { Interceptor } from '@weave_protocol/inspector';
import { scan } from '@weave_protocol/mund';
import { ComplianceManager } from '@weave_protocol/domere';

const interceptor = new Interceptor();
const compliance = new ComplianceManager(['soc2']);

// Use Mund for scanning
interceptor.setScanner(async (content) => {
  const result = await scan(content);
  return {
    safe: result.safe,
    issues: result.issues,
    scannedAt: new Date(),
    scanDurationMs: 0,
  };
});

// Use Domere for blockchain anchoring
interceptor.setBlockchainAnchor(async (data) => {
  const checkpoint = await compliance.createCheckpoint({
    action: 'tool_call',
    resource: 'mcp',
    actor: 'inspector',
    metadata: data,
  });
  return checkpoint.id;
});

📈 Example: Security Dashboard

// Get live feed for dashboard
const feed = await inspector_get_live_feed({ limit: 50 });

// Show pending approvals
const pending = await inspector_get_pending();

// Check overall health
const stats = await inspector_get_stats();

console.log(`
📊 Inspector Dashboard
─────────────────────
Total Calls:    ${stats.interceptor.totalCalls}
Approved:       ${stats.interceptor.approvedCalls}
Blocked:        ${stats.interceptor.blockedCalls}
Pending:        ${stats.interceptor.pendingCalls}
Active Sessions: ${stats.interceptor.activeSessions}

🏢 Server Health
─────────────────────
Total Servers:  ${stats.reputation.total_servers}
Verified:       ${stats.reputation.verified_servers}
Malicious:      ${stats.reputation.malicious_servers}
Low Rep:        ${stats.reputation.low_reputation_servers}
`);

🤖 AI Agent Skill

This package includes a SKILL.md for Claude AI integration.

Skill name: security-inspection

Triggers: inspect, intercept, drift, reputation, approve, block, live feed

📄 License

Apache 2.0 - See LICENSE

🔗 Links

• GitHub: https://github.com/Tyox-all/Weave_Protocol
• npm: https://www.npmjs.com/package/@weave_protocol/inspector
• Main README: Weave Protocol