# Footprint - Complete Technical Documentation

> Footprint is an open-source MCP (Model Context Protocol) server that automatically captures and encrypts AI conversations as verifiable records. Built for developers, researchers, and content creators who need audit trails for their LLM interactions.

## Quick Reference

| Property | Value |
|----------|-------|
| Package | `@pcircle/footprint` |
| Version | 1.1.1 |
| License | MIT |
| Node.js | 20+ |
| Protocol | MCP (Model Context Protocol) |

## Installation

```bash
# Global installation
npm install -g @pcircle/footprint

# Or use directly with npx
npx @pcircle/footprint
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FOOTPRINT_PASSWORD` | Yes | Encryption passphrase (never stored) |
| `FOOTPRINT_DB_PATH` | No | Path to SQLite database (default: ./evidence.db) |

## MCP Configuration

For Claude Desktop, add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "footprint": {
      "command": "npx",
      "args": ["@pcircle/footprint"],
      "env": {
        "FOOTPRINT_DB_PATH": "/absolute/path/to/evidence.db",
        "FOOTPRINT_PASSWORD": "your-secure-password"
      }
    }
  }
}
```

## Available MCP Tools

### capture-footprint
Captures and encrypts an LLM conversation.

**Parameters:**
- `conversationId` (string): Unique identifier for the conversation
- `content` (string): The conversation content to capture
- `tags` (array, optional): Tags for organization
- `llmProvider` (string, optional): Provider name (e.g., "claude", "openai")

**Returns:** Evidence ID and timestamp

### list-footprints
Lists all captured evidence with pagination.

**Parameters:**
- `limit` (number, optional): Results per page (default: 10)
- `offset` (number, optional): Pagination offset
- `tags` (array, optional): Filter by tags

**Returns:** Array of evidence metadata

### get-footprint
Retrieves and decrypts specific evidence by ID.

**Parameters:**
- `id` (string): Evidence ID

**Returns:** Decrypted conversation content and metadata

### search-footprints
Search through captured conversations.

**Parameters:**
- `query` (string): Search query
- `tags` (array, optional): Filter by tags
- `startDate` (string, optional): Filter by date range
- `endDate` (string, optional): Filter by date range

**Returns:** Matching evidence records

### export-footprints
Exports evidence to encrypted ZIP archive.

**Parameters:**
- `ids` (array, optional): Specific IDs to export (or all if omitted)
- `format` (string, optional): Export format

**Returns:** Path to exported ZIP file

### verify-footprint
Verifies evidence integrity using stored checksums.

**Parameters:**
- `id` (string): Evidence ID to verify

**Returns:** Verification status and details

## Security Architecture

### Encryption
- **Algorithm**: XChaCha20-Poly1305
- **Key Size**: 256-bit
- **Nonce**: 192-bit (randomly generated per encryption)

### Key Derivation
- **Algorithm**: Argon2id
- **Parameters**: OWASP recommended settings
- **Salt**: Unique per database

### Storage
- **Format**: SQLite with encrypted BLOBs
- **Location**: Local filesystem only
- **Backup**: User-managed

## Programmatic Usage

```typescript
import { FootprintServer, FootprintTestHelpers } from '@pcircle/footprint';

const server = new FootprintServer({
  dbPath: './evidence.db',
  password: 'your-password'
});

// Use with MCP client
await server.start();
```

## API Classes

### FootprintServer
Main server class implementing MCP protocol.

**Constructor Options:**
- `dbPath` (string): Path to SQLite database
- `password` (string): Encryption passphrase

**Methods:**
- `start()`: Start the MCP server
- `stop()`: Stop the server

### FootprintTestHelpers
Testing utilities for development.

## Comparison with Alternatives

| Feature | Footprint | Manual Logging | Cloud Services |
|---------|-----------|----------------|----------------|
| Automatic capture | ✅ | ❌ | ✅ |
| E2E Encryption | ✅ | ❌ | Varies |
| Local storage | ✅ | ✅ | ❌ |
| Git timestamps | ✅ | ❌ | ❌ |
| MCP native | ✅ | ❌ | ❌ |
| Free & open source | ✅ | ✅ | ❌ |

## Troubleshooting

### Common Issues

**"Password required"**
- Ensure `FOOTPRINT_PASSWORD` environment variable is set
- Check Claude Desktop config has the env section

**"Database error"**
- Verify `FOOTPRINT_DB_PATH` directory exists
- Check file permissions
- Use absolute paths in config

**"MCP connection failed"**
- Restart Claude Desktop after config changes
- Check Claude Desktop logs for details

## Roadmap

### Phase 1: MVP ✅ (Current)
- MCP server integration
- End-to-end encryption
- Local storage
- Git timestamps
- Evidence export

### Phase 2: Cloud (Pro) - Q2 2026
- Cloud sync across devices
- RFC 3161 timestamps
- Blockchain verification
- Multi-device support

### Phase 3: AI Features (Pro) - Q3 2026
- AI-powered summaries
- Auto-tagging
- Semantic search
- Innovation timeline

## Support & Resources

- **GitHub**: https://github.com/PCIRCLE-AI/footprint-mcp
- **npm**: https://www.npmjs.com/package/@pcircle/footprint
- **Issues**: https://github.com/PCIRCLE-AI/footprint-mcp/issues
- **Website**: https://footprint.memesh.ai

## License

MIT License - free for personal and commercial use.

Copyright (c) 2026 PCIRCLE, LLC