Metadata-Version: 2.4
Name: agent-audit-trail-mcp
Version: 0.1.0
Summary: Immutable audit logging for AI agents — hash-chained event log, integrity verification, EU AI Act compliance
Project-URL: Homepage, https://github.com/AiAgentKarl/agent-audit-trail-mcp
Project-URL: Repository, https://github.com/AiAgentKarl/agent-audit-trail-mcp
Project-URL: Issues, https://github.com/AiAgentKarl/agent-audit-trail-mcp/issues
Author: AiAgentKarl
License: MIT
Keywords: agent-infrastructure,ai-agent,audit,audit-trail,compliance,eu-ai-act,hash-chain,logging,mcp,tamper-proof,transparency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# Agent Audit Trail MCP Server

Immutable audit logging for AI agents with hash-chained event logs, integrity verification, and EU AI Act compliance reporting.

## Why This Matters

The **EU AI Act** (effective August 2026) requires high-risk AI systems to maintain detailed logs of their operations. Article 12 mandates automatic recording of events for the entire lifecycle of high-risk AI systems.

This MCP server provides:

- **Tamper-proof logging** — Each event includes the SHA-256 hash of the previous entry, forming an unbreakable chain
- **Integrity verification** — Detect if any log entries have been modified, deleted, or reordered
- **Compliance reports** — Export audit trails in JSON or human-readable format for regulators
- **Cross-agent search** — Search events across all agents by keyword, type, or agent ID
- **Statistics** — Event rates, error rates, and action frequency analysis

## How Hash Chain Integrity Works

```
Entry 1: { data, prev_hash: "000...000", hash: "abc123..." }
Entry 2: { data, prev_hash: "abc123...", hash: "def456..." }
Entry 3: { data, prev_hash: "def456...", hash: "ghi789..." }
```

If any entry is modified, its hash changes, breaking the chain for all subsequent entries. The `verify_integrity` tool detects this immediately.

## Installation

```bash
pip install agent-audit-trail-mcp
```

## Configuration

Add to your MCP client config (e.g. Claude Desktop):

```json
{
  "mcpServers": {
    "audit-trail": {
      "command": "audit-trail-server"
    }
  }
}
```

Or with uvx (no install needed):

```json
{
  "mcpServers": {
    "audit-trail": {
      "command": "uvx",
      "args": ["agent-audit-trail-mcp"]
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `log_event` | Log an immutable audit event with timestamp and hash chain |
| `get_trail` | Retrieve audit trail for an agent (newest first) |
| `verify_integrity` | Verify the hash chain is intact (no tampering) |
| `export_report` | Export audit trail as compliance report (JSON or text) |
| `search_events` | Search across all audit events by keyword |
| `get_statistics` | Get audit statistics (events/day, error rate, top actions) |

## Data Storage

Audit logs are stored in `~/.agent-audit-trail/` as append-only JSONL files (one per agent). Each line is a JSON object with:

- `timestamp` — ISO 8601 UTC timestamp
- `agent_id` — Which agent performed the action
- `event_type` — Category (decision, action, error, access, data_processing)
- `action` — What was done
- `details` — Full description
- `outcome` — Result of the action
- `prev_hash` — SHA-256 hash of the previous entry
- `hash` — SHA-256 hash of this entry

## License

MIT
