🏗️ Architecture

System Overview

ProofScan is designed as a transparent proxy that sits between MCP clients and servers, capturing all JSON-RPC communications. The architecture follows a modular design with clear separation of concerns.

Main Components

1. Connector Manager

Manages MCP server connections and lifecycle:

• Registration: Store connector configurations (stdio, SSE, WebSocket)
• Spawning: Launch MCP server processes
• Connection: Establish and maintain communication channels
• Health Monitoring: Track connector status and availability

2. Proxy Layer

The transparent proxy that intercepts and forwards JSON-RPC messages:

• Message Interception: Capture all JSON-RPC traffic
• Bidirectional Forwarding: Pass messages between client and server
• Protocol Support: Handle stdio, SSE, and WebSocket transports
• Error Handling: Gracefully handle connection failures

3. Event Storage

Persistent storage for captured JSON-RPC events:

• Session Management: Group events by scanning session
• Hierarchical Storage: Organize by connector → session → RPC
• Timestamping: Record precise timing information
• Indexing: Enable fast querying and filtering

4. Query Engine

Retrieve and analyze stored events:

• Filtering: By session, connector, time range, event type
• Aggregation: Generate summaries and statistics
• Real-time: Stream events as they're captured
• Export: Output in various formats (JSON, POPL)

5. POPL Generator

Create Proof-of-Protocol records:

• Evidence Collection: Gather all relevant events
• Cryptographic Signing: Add signatures for verification
• Format Compliance: Follow POPL standard
• Verification: Validate proof integrity

Data Flow

Understanding how data flows through ProofScan:

User → Config Manager → Connector Registry
     ↓
Configuration File
     ↓
Connector Definitions

User Command → Scanner
     ↓
Connector Manager → Spawn Process
     ↓
Proxy Layer → Establish Connection
     ↓
Event Storage → Create Session

MCP Client ←→ Proxy Layer ←→ MCP Server
              ↓
        Event Storage
              ↓
     Session Database

User Query → Query Engine
     ↓
Event Storage → Retrieve Events
     ↓
Formatter → Output Results

Storage Structure

ProofScan uses a hierarchical storage model:

Directory Layout

~/.config/proofscan/
├── config.json              # Main configuration
├── connectors/              # Connector definitions
│   ├── connector1.json
│   └── connector2.json
└── sessions/                # Captured sessions
    ├── session1/
    │   ├── metadata.json    # Session info
    │   └── events.jsonl     # Event stream
    └── session2/
        ├── metadata.json
        └── events.jsonl

Event Format

Each captured event includes:

{
  "timestamp": "2024-02-17T10:30:45.123Z",
  "session_id": "f2442c9b",
  "connector_id": "myserver",
  "direction": "request|response|notification",
  "message": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    ...
  },
  "metadata": {
    "latency_ms": 45,
    "size_bytes": 256
  }
}

Proxy Modes

ProofScan supports different proxy modes for various use cases:

Inline Mode (Default)

ProofScan spawns and manages the MCP server process:

Client → ProofScan → MCP Server (spawned)

• Full control over server lifecycle
• Automatic process management
• Best for development and testing

Transparent Proxy Mode

ProofScan connects to an existing MCP server:

Client → ProofScan → MCP Server (external)

• Works with existing deployments
• No process management needed
• Best for production monitoring

Recording Mode

ProofScan only records, doesn't forward:

MCP Traffic → ProofScan (recording only)

• Passive monitoring
• No latency impact
• Best for audit trails

Performance Characteristics

Latency Impact

• Typical overhead: 1-5ms per message
• Async storage: Events written without blocking
• Memory efficient: Streaming storage for large sessions

Scalability

• Concurrent connectors: Supports multiple simultaneous scans
• Large sessions: Handles thousands of events efficiently
• Long-running: Designed for continuous monitoring

Resource Usage

• CPU: Minimal (< 5% for typical workloads)
• Memory: ~50MB base + ~1KB per captured event
• Disk: ~500 bytes per JSON-RPC message

Extensibility Points

Custom Transports

Add support for new MCP transport protocols:

• Implement transport interface
• Register with connector manager
• Example: HTTP, gRPC, custom protocols

Event Processors

Add custom processing for captured events:

• Real-time analysis
• Custom filtering
• Integration with external systems

Export Formats

Support additional output formats:

• Custom JSON schemas
• CSV, XML, Protobuf
• Integration with analysis tools

Security Considerations

Best Practices

• Secure your ~/.config/proofscan/ directory
• Be aware that ProofScan captures all traffic (including sensitive data)
• Use appropriate file permissions
• Regularly archive and rotate old sessions

Next Steps

• → MCP Protocol - Learn about the Model Context Protocol
• → Workflows - Common usage patterns
• → Command Reference - Detailed command documentation