vm-mcp/README.md

VaultMesh Cognitive Integration

Claude as the 7th Organ of VaultMesh - A cryptographically-bound AI co-processor.

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

# 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:

{
  "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

# 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

# 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 for details.

---

🜄 Solve et Coagula

VaultMesh Technologies - Earth's Civilization Ledger