⭐ GitHub

🚀 Quick Start

Get started with ProofScan in 5 minutes

Prerequisites

Before you begin, make sure you have:

  • ProofScan installed (Installation Guide)
  • An MCP server to scan (or use one of the examples below)
  • Basic familiarity with command-line tools

Basic Workflow

ProofScan follows a simple workflow:

Step 1: Initialize Configuration

Create your ProofScan configuration file:

pfscan config init

Output:

✓ Configuration initialized
  Config path: ~/.config/proofscan/config.json

Step 2: Add a Connector

Register an MCP server (connector):

pfscan connectors add \
  --id time-server \
  --stdio "npx -y @modelcontextprotocol/server-everything"

Output:

✓ Connector added: time-server

Step 3: Start Scanning

Begin monitoring the connector:

pfscan scan start --id time-server

Output:

✓ Scan started
  Session: f2442c9b
  Connector: time-server
  
Waiting for events... (Press Ctrl+C to stop)

Step 4: View Events

In another terminal, watch the captured events in real-time:

pfscan view --follow

Or view events from a specific session:

pfscan view --session f2442c9b

Step 5: Generate Reports

Create a summary report:

pfscan summary --session f2442c9b

Or generate a complete proof record:

pfscan popl generate --session f2442c9b

Common Usage Patterns

Real-Time Monitoring

Watch events as they happen:

# Start scanning in background
pfscan scan start --id myserver &

# Follow events in real-time
pfscan view --follow --fulltime

Error Tracking

Monitor only errors:

pfscan view --follow --errors

Session Analysis

Analyze a completed session:

# View hierarchical structure
pfscan tree --session 

# Generate summary
pfscan summary --session 

# Export as proof
pfscan popl generate --session

Multiple Connectors

Monitor multiple MCP servers:

# Add multiple connectors
pfscan connectors add --id server1 --stdio "..."
pfscan connectors add --id server2 --stdio "..."

# Start both
pfscan scan start --id server1 &
pfscan scan start --id server2 &

# View all events
pfscan view --follow

Example Scenarios

Scenario 1: Testing an MCP Server

You're developing an MCP server and want to see all JSON-RPC traffic:

# Add your server
pfscan connectors add --id myserver --stdio "node dist/index.js"

# Start scanning with full details
pfscan scan start --id myserver

# In another terminal, watch events with full timestamps
pfscan view --follow --fulltime --json

Scenario 2: Debugging Connection Issues

Your MCP client isn't connecting properly:

# Start scanning
pfscan scan start --id problematic-server

# Monitor only errors
pfscan view --follow --errors

# Check connection status
pfscan status --id problematic-server

Scenario 3: Audit Trail Generation

You need a verifiable record of all communications:

# Scan with proof generation enabled
pfscan scan start --id production-server

# After session completes, generate proof
pfscan popl generate --session  --output audit.json

# Verify the proof
pfscan popl verify --file audit.json

Tips & Tricks

💡 Useful Tips
  • Background Scanning: Add & to run scans in background: pfscan scan start --id myserver &
  • Filter by Time: Use --since to view recent events: pfscan view --since 1h
  • JSON Output: Add --json for machine-readable output
  • Save Sessions: Session data is automatically saved for later analysis
  • List Sessions: Run pfscan sessions ls to see all recorded sessions

Next Steps

Now that you know the basics: