@pcircle/evidencemcp-server 0.1.0 → 0.2.0

package/README.md

@@ -2,62 +2,31 @@
 
 [![npm version](https://img.shields.io/npm/v/@pcircle/evidencemcp-server)](https://www.npmjs.com/package/@pcircle/evidencemcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-19%20passing-brightgreen)](tests/)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](package.json)
 
-Model Context Protocol (MCP) server for EvidenceMCP - automatically captures and encrypts LLM conversations as legal evidence.
+Model Context Protocol (MCP) server that automatically captures and encrypts LLM conversations as legal evidence.
 
 ## Why EvidenceMCP?
 
-### For Developers & Content Creators
-- **Prove IP Ownership** - Timestamped evidence of LLM-assisted work for copyright protection
-- **Zero Effort** - Automatic capture via MCP protocol, no manual logging required
-- **Legally Valid** - Git timestamps + encryption provide tamper-proof evidence
-- **Privacy First** - All data encrypted locally, never leaves your machine
-
-### For Researchers & Academics
-- **Research Integrity** - Document AI-assisted research with provable timestamps
-- **Audit Trail** - Complete conversation history for methodology transparency
-- **Compliance Ready** - Meet institutional requirements for AI usage disclosure
-
-### For Teams & Organizations
-- **Risk Mitigation** - Legal protection against IP disputes over AI-generated content
-- **Quality Assurance** - Review and audit LLM interactions for compliance
-- **Knowledge Management** - Searchable archive of all LLM conversations
-
-## Features
-
-- 🔐 **End-to-End Encryption** - XChaCha20-Poly1305 authenticated encryption
-- 📝 **Automatic Capture** - Intercepts LLM conversations via MCP protocol
-- 🕒 **Git Timestamps** - Provable timestamps from Git commits
-- 📦 **Evidence Export** - ZIP archives with SHA-256 checksums
-- 🔍 **Evidence Management** - List, retrieve, and decrypt stored evidence
+- **Prove IP Ownership** - Timestamped evidence of LLM-assisted work
+- **Zero Effort** - Automatic capture via MCP protocol
+- **Privacy First** - End-to-end encrypted, locally stored
+- **Legally Valid** - Git timestamps + SHA-256 checksums
 
 ## Installation
 
 ```bash
-pnpm add @pcircle/evidencemcp-server
+npm install -g @pcircle/evidencemcp-server
 ```
 
 ## Quick Start
 
-### 1. Set Environment Variables
-
+1. **Set environment variables:**
 ```bash
 export EVIDENCEMCP_DB_PATH="./evidence.db"
 export EVIDENCEMCP_PASSWORD="your-secure-password"
 ```
 
-### 2. Run MCP Server
-
-```bash
-npx evidencemcp-mcp
-```
-
-### 3. Configure Claude Desktop
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
+2. **Configure Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
@@ -73,278 +42,39 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-## MCP Tools
+3. **Restart Claude Desktop** - Evidence collection starts automatically
 
-### capture-evidence
+## Features
 
-Capture and encrypt an LLM conversation.
+- 🔐 XChaCha20-Poly1305 encryption
+- 🕒 Git commit timestamps
+- 📦 Tamper-proof ZIP exports
+- 🔍 Search and retrieve evidence
 
-**Input:**
-- `conversationId` (string) - Unique conversation identifier
-- `llmProvider` (string) - LLM provider name (e.g., "Claude Sonnet 4.5")
-- `content` (string) - Conversation content
-- `messageCount` (number) - Number of messages
-- `tags` (string, optional) - Comma-separated tags
+## MCP Tools
 
-**Output:**
-```json
-{
-  "id": "uuid-v4",
-  "timestamp": "2024-01-24T00:00:00Z",
-  "gitCommitHash": "abc123...",
-  "success": true
-}
-```
+### capture-evidence
+Captures and encrypts an LLM conversation.
 
 ### list-evidences
-
-List all captured evidence with pagination.
-
-**Input:**
-- `limit` (number, optional) - Maximum results
-- `offset` (number, optional) - Pagination offset
-
-**Output:**
-```json
-{
-  "evidences": [
-    {
-      "id": "uuid",
-      "timestamp": "2024-01-24T00:00:00Z",
-      "conversationId": "conv-001",
-      "llmProvider": "Claude Sonnet 4.5",
-      "messageCount": 10,
-      "tags": "legal,contract"
-    }
-  ],
-  "total": 1
-}
-```
+Lists all captured evidence with pagination.
 
 ### get-evidence
-
-Retrieve and decrypt specific evidence.
-
-**Input:**
-- `id` (string) - Evidence ID
-
-**Output:**
-```json
-{
-  "id": "uuid",
-  "timestamp": "2024-01-24T00:00:00Z",
-  "conversationId": "conv-001",
-  "llmProvider": "Claude Sonnet 4.5",
-  "content": "User: ...\nAssistant: ...",
-  "messageCount": 10,
-  "gitInfo": {
-    "commitHash": "abc123",
-    "timestamp": "2024-01-24T00:00:00Z"
-  },
-  "tags": "legal"
-}
-```
+Retrieves and decrypts specific evidence by ID.
 
 ### export-evidences
-
-Export evidences to encrypted ZIP archive.
-
-**Input:**
-- `evidenceIds` (string[], optional) - Specific IDs (empty = all)
-- `includeGitInfo` (boolean, optional) - Include Git timestamps
-
-**Output:**
-```json
-{
-  "filename": "evidence-export-2024-01-24.zip",
-  "checksum": "sha256-hash",
-  "evidenceCount": 5,
-  "success": true
-}
-```
-
-## MCP Resources
-
-### evidence://{id}
-
-Access decrypted evidence content via URI.
-
-**Example:**
-```
-evidence://550e8400-e29b-41d4-a716-446655440000
-```
-
-Returns plain text content of the evidence.
-
-## Programmatic Usage
-
-```typescript
-import { EvidenceMCPServer } from '@pcircle/evidencemcp-server';
-
-const server = new EvidenceMCPServer({
-  dbPath: './evidence.db',
-  password: 'your-password'
-});
-
-await server.start();
-```
+Exports evidence to encrypted ZIP archive.
 
 ## Security
 
-- **Encryption**: XChaCha20-Poly1305 (256-bit keys)
-- **Key Derivation**: Argon2id (OWASP recommended params)
-- **Content Integrity**: SHA-256 hashing
-- **Local Storage**: SQLite with encrypted BLOB fields
-
-⚠️ **Important**: Store your `EVIDENCEMCP_PASSWORD` securely (e.g., macOS Keychain). Loss of password means permanent data loss.
-
-## Architecture
-
-```
-┌─────────────────┐
-│  LLM Client     │ (Claude Desktop, ChatGPT, etc.)
-│  (MCP Client)   │
-└────────┬────────┘
-         │ MCP Protocol (stdio)
-         ▼
-┌─────────────────┐
-│ EvidenceMCP MCP  │
-│     Server      │
-├─────────────────┤
-│ Tools:          │
-│ - capture       │
-│ - list          │
-│ - export        │
-│ - get           │
-├─────────────────┤
-│ Resources:      │
-│ - evidence://   │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐     ┌──────────────┐
-│ @evidencemcp/    │────▶│ XChaCha20    │
-│   crypto        │     │ -Poly1305    │
-└─────────────────┘     └──────────────┘
-         │
-         ▼
-┌─────────────────┐     ┌──────────────┐
-│ @evidencemcp/    │────▶│ SQLite       │
-│   storage       │     │ (encrypted)  │
-└─────────────────┘     └──────────────┘
-```
-
-## Troubleshooting
-
-### "EVIDENCEMCP_PASSWORD environment variable required"
-
-**Problem**: Server fails to start with this error message.
-
-**Solution**:
-1. Ensure `EVIDENCEMCP_PASSWORD` is set in your environment
-2. For Claude Desktop, verify the `env` section in `claude_desktop_config.json`:
-   ```json
-   {
-     "mcpServers": {
-       "evidencemcp": {
-         "env": {
-           "EVIDENCEMCP_PASSWORD": "your-secure-password"
-         }
-       }
-     }
-   }
-   ```
-3. For command line: `export EVIDENCEMCP_PASSWORD="your-password"`
-4. Never commit passwords to version control
-
-### "Database locked" or "SQLITE_BUSY"
-
-**Problem**: Multiple processes trying to access the same database file.
-
-**Solution**:
-1. Ensure only one EvidenceMCP instance is running
-2. Check for orphaned processes: `ps aux | grep evidencemcp-mcp`
-3. Use unique database paths for different instances:
-   ```json
-   {
-     "evidencemcp-dev": {
-       "env": {
-         "EVIDENCEMCP_DB_PATH": "/Users/you/evidencemcp-dev.db"
-       }
-     },
-     "evidencemcp-prod": {
-       "env": {
-         "EVIDENCEMCP_DB_PATH": "/Users/you/evidencemcp-prod.db"
-       }
-     }
-   }
-   ```
-
-### "Git not found" or "Git command failed"
-
-**Problem**: Git timestamp capture fails.
-
-**Solution**:
-1. Install Git if not present: `brew install git` (macOS) or `apt-get install git` (Linux)
-2. Verify Git is in PATH: `which git`
-3. Git timestamps are optional - evidence capture will succeed without them
-4. Check `.git` directory exists if running in a repository
-
-### "Permission denied" on database file
-
-**Problem**: Cannot read/write database file.
-
-**Solution**:
-1. Check file permissions: `ls -l /path/to/evidence.db`
-2. Ensure the directory exists and is writable
-3. Verify the user running Claude Desktop has write access
-4. On macOS, grant Full Disk Access if needed (System Settings → Privacy & Security)
-
-### "Failed to decrypt evidence" or "Wrong password"
-
-**Problem**: Cannot decrypt previously stored evidence.
-
-**Solution**:
-1. Verify you're using the same password that was used to encrypt
-2. Passwords are case-sensitive
-3. Check for trailing spaces or special characters in password
-4. If password is lost, evidence cannot be recovered (by design)
-
-### "Export failed" or "ZIP creation error"
-
-**Problem**: Evidence export fails.
-
-**Solution**:
-1. Ensure sufficient disk space
-2. Check write permissions in current directory
-3. Verify evidence IDs exist: use `list-evidences` first
-4. Try exporting single evidence item to isolate the issue
-
-### High memory usage
-
-**Problem**: Server consuming excessive memory.
-
-**Solution**:
-1. Evidence files are loaded into memory during encryption/decryption
-2. For large conversations (>10MB), use pagination with `list-evidences`
-3. Export in smaller batches instead of all at once
-4. Restart Claude Desktop to free memory
-
-### TypeScript errors in development
-
-**Problem**: TypeScript compilation errors.
-
-**Solution**:
-1. Ensure you're using TypeScript 5.9+: `pnpm add -D typescript@^5.9.3`
-2. Clean build artifacts: `pnpm clean && pnpm build`
-3. Check Node.js version: `node --version` (requires 22+)
-4. Verify dependencies: `pnpm install`
-
-## License
+- **Encryption**: XChaCha20-Poly1305 (256-bit)
+- **Key Derivation**: Argon2id (OWASP recommended)
+- **Storage**: Local SQLite with encrypted BLOBs
 
-MIT - See LICENSE file
+⚠️ **Store your password securely** - Loss means permanent data loss.
 
 ## Support
 
-- Issues: https://github.com/evidencemcp/evidencemcp/issues
-- Docs: https://evidencemcp.dev
+- [Documentation](https://github.com/PCIRCLE-AI/evidencemcp-server#readme)
+- [Issues](https://github.com/PCIRCLE-AI/evidencemcp-server/issues)
+- [License](https://github.com/PCIRCLE-AI/evidencemcp-server/blob/main/LICENSE)

package/dist/index.d.ts

@@ -1,9 +1,7 @@
 #!/usr/bin/env node
 import type { ServerConfig } from './types.js';
 /**
- * EvidenceMCP Server
- *
- * Captures LLM conversations and stores them as encrypted evidence
+ * EvidenceMCP Server - Captures LLM conversations as encrypted evidence
  * with Git timestamps and export capabilities.
  */
 export declare class EvidenceMCPServer {
@@ -12,21 +10,9 @@ export declare class EvidenceMCPServer {
     private db;
     private derivedKey;
     constructor(config: ServerConfig);
-    /**
-     * Derive encryption key from password (lazy initialization)
-     */
     private getDerivedKey;
-    /**
-     * Register MCP tools for evidence management
-     */
     private registerTools;
-    /**
-     * Register MCP resources for evidence access
-     */
     private registerResources;
-    /**
-     * Start the MCP server with stdio transport
-     */
     start(): Promise<void>;
 }
 export { EvidenceMCPTestHelpers } from './test-helpers.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAOA,OAAO,KAAK,EAAE,YAAY,EAAyB,MAAM,YAAY,CAAC;AAGtE;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,EAAE,CAAmB;IAC7B,OAAO,CAAC,UAAU,CAA2B;gBAEjC,MAAM,EAAE,YAAY;IAsBhC;;OAEG;YACW,aAAa;IAQ3B;;OAEG;IACH,OAAO,CAAC,aAAa;IA0QrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA0CzB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B;AA4BD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAQA,OAAO,KAAK,EAAE,YAAY,EAAyB,MAAM,YAAY,CAAC;AAMtE;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,EAAE,CAAmB;IAC7B,OAAO,CAAC,UAAU,CAA2B;gBAEjC,MAAM,EAAE,YAAY;YAkBlB,aAAa;IAQ3B,OAAO,CAAC,aAAa;IAmNrB,OAAO,CAAC,iBAAiB;IA6BnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B;AAwBD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}