proofscan 0.1.0 → 0.2.0

package/README.md

@@ -8,33 +8,36 @@ proofscan provides visibility into MCP (Model Context Protocol) server communica
 
 - Connects to MCP servers via stdio transport
 - Captures all JSON-RPC messages (requests, responses, notifications)
-- Stores events in JSONL format for later analysis
+- Stores events in SQLite for efficient querying and analysis
 - Supports importing server configurations from mcp.so / Claude Desktop format
+- Manages session history with retention policies and archival
 
 ## Installation
 
 ```bash
-npm install
-npm run build
-npm link  # Makes 'proofscan' available globally
+npm install -g proofscan
 ```
 
-Or run directly:
+Or run without installing:
 
 ```bash
-node dist/cli.js --help
+npx proofscan --help
 ```
 
+## CLI Commands
+
+The CLI is available as both `pfscan` (short) and `proofscan` (full).
+
 ## Quickstart
 
 ### 1. Initialize Configuration
 
 ```bash
 # Create config in OS-standard location
-proofscan config init
+pfscan config init
 
 # Check where config is stored
-proofscan config path
+pfscan config path
 ```
 
 ### 2. Import MCP Server from mcp.so / Claude Desktop
@@ -43,31 +46,38 @@ Copy the `mcpServers` JSON from mcp.so or Claude Desktop settings and import via
 
 ```bash
 # Full mcpServers format
-echo '{ "mcpServers": { "time": { "command": "uvx", "args": ["mcp-server-time"] } } }' | proofscan connectors import --from mcpServers --stdin
+echo '{ "mcpServers": { "time": { "command": "uvx", "args": ["mcp-server-time"] } } }' | pfscan connectors import --from mcpServers --stdin
 
 # Or just the server definition (requires --name)
-echo '{ "command": "uvx", "args": ["mcp-server-time"] }' | proofscan connectors import --from mcpServers --stdin --name time
+echo '{ "command": "uvx", "args": ["mcp-server-time"] }' | pfscan connectors import --from mcpServers --stdin --name time
 
 # Import from file
-proofscan connectors import --from mcpServers --file ./servers.json
+pfscan connectors import --from mcpServers --file ./servers.json
 ```
 
 ### 3. List Connectors
 
 ```bash
-proofscan connectors list
+pfscan connectors list
 ```
 
 ### 4. Scan a Connector
 
 ```bash
-proofscan scan start --id time
+pfscan scan start --id time
 ```
 
-### 5. View Events
+### 5. View Sessions and Events
 
 ```bash
-proofscan monitor tail --id time --last 20
+# List all sessions
+pfscan sessions list
+
+# Show session details
+pfscan sessions show --id <session_id>
+
+# View recent events
+pfscan monitor tail --id time --last 20
 ```
 
 ## Commands
@@ -83,37 +93,53 @@ proofscan monitor tail --id time --last 20
 ### Config
 
 ```bash
-proofscan config path                    # Show config file path
-proofscan config init [--force]          # Initialize config
-proofscan config show                    # Show config (secrets masked)
-proofscan config validate                # Validate config
+pfscan config path                    # Show config file path
+pfscan config init [--force]          # Initialize config
+pfscan config show                    # Show config (secrets masked)
+pfscan config validate                # Validate config
 ```
 
 ### Connectors
 
 ```bash
-proofscan connectors list                        # List all connectors
-proofscan connectors show --id <id>              # Show connector details
-proofscan connectors add --id <id> --stdio "cmd" # Add stdio connector
-proofscan connectors enable --id <id>            # Enable connector
-proofscan connectors disable --id <id>           # Disable connector
-proofscan connectors remove --id <id>            # Remove connector
+pfscan connectors list                        # List all connectors
+pfscan connectors show --id <id>              # Show connector details
+pfscan connectors add --id <id> --stdio "cmd" # Add stdio connector
+pfscan connectors enable --id <id>            # Enable connector
+pfscan connectors disable --id <id>           # Disable connector
+pfscan connectors remove --id <id>            # Remove connector
 
 # Import from mcpServers format
-proofscan connectors import --from mcpServers --stdin
-proofscan connectors import --from mcpServers --file <path> [--name <id>]
+pfscan connectors import --from mcpServers --stdin
+pfscan connectors import --from mcpServers --file <path> [--name <id>]
 ```
 
 ### Scan
 
 ```bash
-proofscan scan start --id <id> [--timeout <sec>]
+pfscan scan start --id <id> [--timeout <sec>]
 ```
 
 ### Monitor
 
 ```bash
-proofscan monitor tail --id <id> [--last <N>]
+pfscan monitor tail --id <id> [--last <N>]
+```
+
+### Sessions (Phase 2)
+
+```bash
+pfscan sessions list [--connector <id>] [--limit <N>]   # List sessions
+pfscan sessions show --id <session_id>                   # Show session details
+pfscan sessions prune [--before <date>] [--keep-last <N>] [--yes]  # Prune old sessions
+```
+
+### Archive (Phase 2)
+
+```bash
+pfscan archive status                           # Show database status
+pfscan archive plan                             # Show what would be archived
+pfscan archive run [--yes] [--vacuum]           # Execute archive based on retention
 ```
 
 ## Config File Format
@@ -137,63 +163,99 @@ Config is stored in the OS-standard location:
         "args": ["mcp-server-time", "--local-timezone=America/New_York"]
       }
     }
-  ]
+  ],
+  "retention": {
+    "keep_last_sessions": 50,
+    "raw_days": 7,
+    "max_db_mb": 500
+  }
 }
 ```
 
-## Event Storage
+### Retention Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `keep_last_sessions` | 50 | Keep last N sessions per connector |
+| `raw_days` | 7 | Clear raw JSON after N days |
+| `max_db_mb` | 500 | Target database size limit |
 
-Events are stored in JSONL format:
+## Data Storage (Phase 2)
+
+proofscan uses a 2-file SQLite structure:
 
 ```
-~/.config/proofscan/events/<connector_id>/<YYYYMMDD>.jsonl
+~/.config/proofscan/
+├── config.json
+├── events.db     # Sessions, events, RPC calls (can be pruned)
+└── proofs.db     # Immutable proof records (never pruned)
 ```
 
-Each event contains:
+### events.db Schema
 
-```json
-{
-  "event_id": "uuid",
-  "ts": "2024-01-15T10:30:00.000Z",
-  "connector_id": "time",
-  "direction": "client_to_server",
-  "kind": "request",
-  "method": "tools/list",
-  "rpc_id": 1,
-  "ok": true,
-  "raw": "{...}"
-}
-```
+- **sessions**: Scan session records with connector, timestamps, exit status
+- **events**: Individual JSON-RPC messages with direction, kind, timestamps
+- **rpc_calls**: Request/response pairs with timing and success status
+
+### proofs.db Schema
+
+- **proofs**: Immutable proof records with hashes, references, and artifact URIs
+
+Sessions linked to proofs are automatically protected from pruning.
 
 ## Example Session
 
 ```bash
 # Initialize
-$ proofscan config init
+$ pfscan config init
 ✓ Config created at: /home/user/.config/proofscan/config.json
 
 # Import a server
 $ echo '{"mcpServers":{"time":{"command":"uvx","args":["mcp-server-time"]}}}' \
-  | proofscan connectors import --from mcpServers --stdin
+  | pfscan connectors import --from mcpServers --stdin
 ✓ Imported 1 connector(s): time
 
 # List connectors
-$ proofscan connectors list
+$ pfscan connectors list
 ID    Enabled  Type   Command/URL
 -----------------------------------
 time  yes      stdio  uvx mcp-server-time
 
 # Scan the server
-$ proofscan scan start --id time
+$ pfscan scan start --id time
 Scanning connector: time...
 ✓ Scan successful!
   Connector: time
-  Tools found: 1
-  Tool names: get_current_time
+  Session: dcaa519e-e14b-41ea-ac7c-7f2066cc8020
+  Tools found: 2
+  Tool names: get_current_time, convert_time
   Events recorded: 8
 
+# List sessions
+$ pfscan sessions list
+Session ID   Connector  Started              Duration  Status  Events  Protected
+--------------------------------------------------------------------------------
+dcaa519e...  time       2025/01/15 10:30:00  450ms     normal  8       no
+
+# Show session details
+$ pfscan sessions show --id dcaa519e-e14b-41ea-ac7c-7f2066cc8020
+Session: dcaa519e-e14b-41ea-ac7c-7f2066cc8020
+Connector: time
+Started: 2025/01/15 10:30:00
+Ended: 2025/01/15 10:30:00
+Duration: 450ms
+Status: normal
+Protected: no
+Events: 8
+RPC Calls: 2
+Proofs: 0
+
+RPC Calls:
+  ✓ initialize (id: 1)
+  ✓ tools/list (id: 2)
+
 # View events
-$ proofscan monitor tail --id time --last 5
+$ pfscan monitor tail --id time --last 5
 Recent events for 'time' (last 5):
 
 Time     Dir Status Kind         Summary
@@ -205,12 +267,88 @@ Time     Dir Status Kind         Summary
 10:30:01 ←   response
 ```
 
+## Archive Example (Phase 2)
+
+```bash
+# Check current database status
+$ pfscan archive status
+Database Status
+===============
+
+events.db size: 80.0 KB
+proofs.db size: 24.0 KB
+
+Total sessions: 6
+Protected sessions: 0
+Total proofs: 0
+raw_json storage: 4.8 KB
+
+# View archive plan (based on retention settings)
+$ pfscan archive plan
+Archive Plan
+============
+
+Retention Settings:
+  keep_last_sessions: 3
+  raw_days: 7
+  max_db_mb: 500
+
+Current Status:
+  events.db size: 80.0 KB
+  proofs.db size: 24.0 KB
+
+Planned Actions:
+
+  Sessions to delete: 3
+Session ID   Connector  Events  Reason
+--------------------------------------------------------------
+c3f3ee9a...  time       8       Exceeds keep_last_sessions (3)
+050212d2...  time       8       Exceeds keep_last_sessions (3)
+dcaa519e...  time       8       Exceeds keep_last_sessions (3)
+
+  raw_json to clear: 0 events
+  Estimated savings: ~0.0 MB
+
+Run "pfscan archive run" to execute (or "pfscan archive run --yes" to confirm).
+
+# Dry run (shows what would happen)
+$ pfscan archive run
+Archive Run (DRY RUN)
+=====================
+
+Sessions to delete: 3
+raw_json to clear: 0 events
+Estimated savings: ~0.0 MB
+
+Run with --yes to actually execute.
+
+# Execute archive with vacuum
+$ pfscan archive run --yes --vacuum
+Archive Run Complete
+====================
+
+Sessions deleted: 3
+raw_json cleared: 0 events
+Database vacuumed
+
+Final events.db size: 72.0 KB
+✓ Archive complete
+
+# Verify sessions after archive
+$ pfscan sessions list
+Session ID   Connector  Started              Duration  Status  Events  Protected
+--------------------------------------------------------------------------------
+f2442c9b...  time       2025/01/15 11:01:58  454ms     normal  8       no
+f641b379...  time       2025/01/15 11:01:58  467ms     normal  8       no
+3cf5a66e...  time       2025/01/15 11:01:57  449ms     normal  8       no
+```
+
 ## JSON Output
 
 Add `--json` for machine-readable output:
 
 ```bash
-$ proofscan connectors list --json
+$ pfscan connectors list --json
 [
   {
     "ID": "time",
@@ -220,14 +358,25 @@ $ proofscan connectors list --json
   }
 ]
 
-$ proofscan scan start --id time --json
+$ pfscan scan start --id time --json
 {
   "success": true,
   "connector_id": "time",
-  "tools_count": 1,
-  "tools": ["get_current_time"],
+  "session_id": "dcaa519e-e14b-41ea-ac7c-7f2066cc8020",
+  "tools_count": 2,
+  "tools": ["get_current_time", "convert_time"],
   "event_count": 8
 }
+
+$ pfscan archive status --json
+{
+  "events_db_size": 81920,
+  "proofs_db_size": 24576,
+  "total_sessions": 6,
+  "protected_sessions": 0,
+  "total_proofs": 0,
+  "raw_json_size": 4896
+}
 ```
 
 ## Supported mcpServers Input Formats
@@ -266,14 +415,15 @@ proofscan accepts several JSON formats for import:
 Failures are always recorded as events. Even if a scan fails, you can inspect what happened:
 
 ```bash
-$ proofscan scan start --id broken-server
+$ pfscan scan start --id broken-server
 Scanning connector: broken-server...
 ✗ Scan failed!
   Connector: broken-server
+  Session: abc123...
   Error: Initialize failed: Request timeout for method: initialize
   Events recorded: 3
 
-$ proofscan monitor tail --id broken-server --last 5
+$ pfscan monitor tail --id broken-server --last 5
 Time     Dir Status Kind         Summary
 ----------------------------------------------------------------------
 10:35:01 →   transport    [connect_attempt]

package/dist/cli.js

@@ -6,7 +6,7 @@
 import { Command } from 'commander';
 import { resolveConfigPath } from './utils/config-path.js';
 import { setOutputOptions } from './utils/output.js';
-import { createConfigCommand, createConnectorsCommand, createScanCommand, createMonitorCommand, } from './commands/index.js';
+import { createConfigCommand, createConnectorsCommand, createScanCommand, createMonitorCommand, createSessionsCommand, createArchiveCommand, } from './commands/index.js';
 const program = new Command();
 // Global state for config path
 let globalConfigPath;
@@ -14,9 +14,9 @@ function getConfigPath() {
     return resolveConfigPath({ configPath: globalConfigPath });
 }
 program
-    .name('proofscan')
+    .name('pfscan')
     .description('MCP Server scanner - eliminate black boxes by capturing JSON-RPC from connection to tools/list')
-    .version('0.1.0')
+    .version('0.2.0')
     .option('-c, --config <path>', 'Path to config file')
     .option('--json', 'Output in JSON format')
     .option('-v, --verbose', 'Verbose output')
@@ -33,6 +33,8 @@ program.addCommand(createConfigCommand(getConfigPath));
 program.addCommand(createConnectorsCommand(getConfigPath));
 program.addCommand(createScanCommand(getConfigPath));
 program.addCommand(createMonitorCommand(getConfigPath));
+program.addCommand(createSessionsCommand(getConfigPath));
+program.addCommand(createArchiveCommand(getConfigPath));
 // Parse and run
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,+BAA+B;AAC/B,IAAI,gBAAoC,CAAC;AAEzC,SAAS,aAAa;IACpB,OAAO,iBAAiB,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,OAAO;KACJ,IAAI,CAAC,WAAW,CAAC;KACjB,WAAW,CAAC,gGAAgG,CAAC;KAC7G,OAAO,CAAC,OAAO,CAAC;KAChB,MAAM,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;KACpD,MAAM,CAAC,QAAQ,EAAE,uBAAuB,CAAC;KACzC,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC;KACzC,IAAI,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,EAAE;IACjC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;IAChC,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC/B,gBAAgB,CAAC;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,kBAAkB;AAClB,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC,CAAC;AACvD,OAAO,CAAC,UAAU,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC,CAAC;AAC3D,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC;AACrD,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC,aAAa,CAAC,CAAC,CAAC;AAExD,gBAAgB;AAChB,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,+BAA+B;AAC/B,IAAI,gBAAoC,CAAC;AAEzC,SAAS,aAAa;IACpB,OAAO,iBAAiB,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,OAAO;KACJ,IAAI,CAAC,QAAQ,CAAC;KACd,WAAW,CAAC,gGAAgG,CAAC;KAC7G,OAAO,CAAC,OAAO,CAAC;KAChB,MAAM,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;KACpD,MAAM,CAAC,QAAQ,EAAE,uBAAuB,CAAC;KACzC,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC;KACzC,IAAI,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,EAAE;IACjC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;IAChC,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC/B,gBAAgB,CAAC;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,kBAAkB;AAClB,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC,CAAC;AACvD,OAAO,CAAC,UAAU,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC,CAAC;AAC3D,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC;AACrD,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC,aAAa,CAAC,CAAC,CAAC;AACxD,OAAO,CAAC,UAAU,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC,CAAC;AACzD,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC,aAAa,CAAC,CAAC,CAAC;AAExD,gBAAgB;AAChB,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/commands/archive.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Archive commands - plan and run cleanup based on retention settings
+ */
+import { Command } from 'commander';
+export declare function createArchiveCommand(getConfigPath: () => string): Command;
+//# sourceMappingURL=archive.d.ts.map

package/dist/commands/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/commands/archive.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4DpC,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,MAAM,GAAG,OAAO,CAwNzE"}