init: vaultmesh mcp server

2025-12-26 23:23:08 +00:00
commit e4871c2a29
35 changed files with 6511 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,194 @@
+# VaultMesh Cognitive Integration
+
+**Claude as the 7th Organ of VaultMesh** - A cryptographically-bound AI co-processor.
+
+[![Governance CI](https://img.shields.io/badge/CI-Passing-success)](/.github/workflows/governance.yml)
+[![Constitution](https://img.shields.io/badge/Constitution-v1.0.0-blue)](/docs/MCP-CONSTITUTION.md)
+[![Python](https://img.shields.io/badge/Python-3.10+-blue)](https://python.org)
+[![License](https://img.shields.io/badge/License-MIT-green)](/LICENSE)
+
+## Overview
+
+This package provides a Model Context Protocol (MCP) server that enables Claude to operate as the cognitive layer of VaultMesh - with full cryptographic accountability, profile-based authority, and constitutional governance.
+
+### Features
+
+- **19 MCP Tools** across 4 domains (Guardian, Treasury, Cognitive, Auth)
+- **5 Capability Profiles** (Observer → Operator → Guardian → Phoenix → Sovereign)
+- **Cryptographic Receipts** for every mutation via BLAKE3
+- **Constitutional Governance** with immutable rules and amendment protocol
+- **Escalation Engine** with proof-backed authority transitions
+- **Ed25519 Authentication** with challenge-response
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/vaultmesh/cognitive-integration.git
+cd cognitive-integration
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # or `venv\Scripts\activate` on Windows
+
+# Install
+pip install -e ".[dev]"
+
+# Verify constitution
+make verify-constitution
+
+# Run tests (48 governance tests)
+make test
+
+# Run Golden Drill
+make drill
+```
+
+## Structure
+
+```
+vaultmesh-cognitive-integration/
+├── governance/
+│   └── constitution.lock       # Pinned constitution hash
+├── packages/vaultmesh_mcp/
+│   ├── server.py               # MCP server (19 tools)
+│   └── tools/
+│       ├── auth.py             # Ed25519 auth + 5 profiles
+│       ├── cognitive.py        # 8 cognitive tools
+│       ├── escalation.py       # Proof-backed escalation
+│       ├── key_binding.py      # Key-profile bindings
+│       ├── guardian.py         # Merkle anchoring
+│       ├── treasury.py         # Budget management
+│       └── file.py             # File operations
+├── tests/governance/           # 48 governance tests
+├── docs/
+│   ├── MCP-CONSTITUTION.md     # Immutable governance law
+│   ├── MCP-AUTHORITY-MATRIX.md # Tool × Profile matrix
+│   └── DRILL.md                # Controlled failure runbook
+├── keys/                       # Guardian + Sovereign keys
+├── realms/cognitive/memory/    # CRDT memory realm
+└── .github/workflows/
+    └── governance.yml          # CI pipeline
+```
+
+## Profiles
+
+| Profile | Symbol | Trust | Key Binding |
+|---------|--------|-------|-------------|
+| OBSERVER | 👁 | Minimal | Ephemeral |
+| OPERATOR | ⚙ | Moderate | Session |
+| GUARDIAN | 🛡 | High | Device-bound |
+| PHOENIX | 🔥 | Maximum | Time-locked |
+| SOVEREIGN | 👑 | Absolute | Hardware |
+
+## Claude Desktop Integration
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "vaultmesh": {
+      "command": "python",
+      "args": ["-m", "vaultmesh_mcp.server"],
+      "env": {
+        "VAULTMESH_ROOT": "/path/to/vaultmesh-cognitive-integration"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Guardian Tools (Merkle Anchoring)
+- `guardian_anchor_now` - Anchor scrolls to Merkle root
+- `guardian_verify_receipt` - Verify receipt in scroll
+- `guardian_status` - Get status of all scrolls
+
+### Treasury Tools (Budget Management)
+- `treasury_create_budget` - Create budget (SOVEREIGN only)
+- `treasury_balance` - Check balance
+- `treasury_debit` - Spend from budget
+- `treasury_credit` - Add to budget
+
+### Cognitive Tools (AI Reasoning)
+- `cognitive_context` - Read mesh context
+- `cognitive_decide` - Submit attested decision
+- `cognitive_invoke_tem` - Invoke threat transmutation
+- `cognitive_memory_get` - Query CRDT memory
+- `cognitive_memory_set` - Store reasoning artifacts
+- `cognitive_attest` - Create cryptographic attestation
+- `cognitive_audit_trail` - Query decision history
+- `cognitive_oracle_chain` - Execute compliance oracle
+
+### Auth Tools (Authentication)
+- `auth_challenge` - Generate Ed25519 challenge
+- `auth_verify` - Verify signature, issue token
+- `auth_check_permission` - Check tool permission
+- `auth_create_dev_session` - Create dev session
+- `auth_revoke` - Revoke session
+- `auth_list_sessions` - List active sessions
+
+## Testing
+
+```bash
+# Run all governance tests
+make test
+
+# Run constitution verification
+make verify-constitution
+
+# Run Golden Drill (threat → escalate → Tem → de-escalate)
+make drill
+
+# Run specific test
+pytest tests/governance/test_auth_fail_closed.py -v
+```
+
+## Constitution
+
+Version 1.0.0 - Ratified December 18, 2025
+
+```
+Hash: blake3:c33ab6c0610ce4001018ba5dda940e12a421a08f2a1662f142e565092ce84788
+```
+
+**Statement:** *"This constitution constrains me as much as it constrains the system."*
+
+### Immutable Rules
+
+1. SOVEREIGN profile requires human verification
+2. No AI may grant itself SOVEREIGN authority  
+3. Every mutation emits a receipt
+4. Authority collapses downward, never upward
+5. This immutability clause itself
+
+## Development
+
+```bash
+# Install with dev dependencies
+make dev
+
+# Run linter
+make lint
+
+# Format code
+make format
+
+# Build package
+make build
+
+# Clean artifacts
+make clean
+```
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+---
+
+🜄 **Solve et Coagula**
+
+*VaultMesh Technologies - Earth's Civilization Ledger*