1050 lines
29 KiB
Markdown
1050 lines
29 KiB
Markdown
# VAULTMESH-MCP-SERVERS.md
|
|
**Exposing the Civilization Ledger to Claude**
|
|
|
|
> *Every tool is a doorway. Every doorway has a guardian.*
|
|
|
|
MCP (Model Context Protocol) servers expose VaultMesh engines to Claude, enabling AI-assisted operations while maintaining constitutional governance.
|
|
|
|
---
|
|
|
|
## 1. MCP Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ CLAUDE │
|
|
│ │
|
|
│ "What's our compliance status for Annex IV?" │
|
|
│ "Start a drill for IoT security" │
|
|
│ "Show me the mesh topology" │
|
|
└───────────────────────────┬─────────────────────────────────┘
|
|
│
|
|
│ MCP Protocol
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ MCP GATEWAY │
|
|
│ │
|
|
│ • Authentication (capability verification) │
|
|
│ • Rate limiting │
|
|
│ • Audit logging (all tool calls receipted) │
|
|
│ • Constitutional compliance checking │
|
|
└───────────────────────────┬─────────────────────────────────┘
|
|
│
|
|
┌───────────────┼───────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌───────────┐ ┌───────────┐ ┌───────────┐
|
|
│ Oracle │ │ Drills │ │ Mesh │
|
|
│ Server │ │ Server │ │ Server │
|
|
└───────────┘ └───────────┘ └───────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────────────────────────────────┐
|
|
│ VAULTMESH ENGINES │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Core MCP Server
|
|
|
|
### 2.1 Server Definition
|
|
|
|
```python
|
|
# vaultmesh_mcp/server.py
|
|
|
|
from mcp.server import Server
|
|
from mcp.types import Tool, TextContent
|
|
from typing import Any
|
|
import json
|
|
|
|
from .engines import (
|
|
oracle_engine,
|
|
drills_engine,
|
|
mesh_engine,
|
|
treasury_engine,
|
|
identity_engine,
|
|
guardian_engine,
|
|
psi_engine,
|
|
governance_engine,
|
|
)
|
|
from .auth import verify_capability, get_caller_identity
|
|
from .receipts import emit_tool_call_receipt
|
|
|
|
server = Server("vaultmesh")
|
|
|
|
# ============================================================================
|
|
# Oracle Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def oracle_answer(
|
|
question: str,
|
|
frameworks: list[str] = None,
|
|
context_docs: list[str] = None,
|
|
) -> str:
|
|
"""
|
|
Ask the VaultMesh Compliance Oracle a question about regulatory compliance.
|
|
|
|
Args:
|
|
question: The compliance question to answer
|
|
frameworks: Optional list of frameworks to focus on (e.g., ["AI_Act", "GDPR"])
|
|
context_docs: Optional list of document IDs to use as context
|
|
|
|
Returns:
|
|
Structured compliance answer with citations and confidence indicators
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "oracle_query")
|
|
|
|
result = await oracle_engine.answer(
|
|
question=question,
|
|
frameworks=frameworks or [],
|
|
context_docs=context_docs or [],
|
|
)
|
|
|
|
await emit_tool_call_receipt(
|
|
tool="oracle_answer",
|
|
caller=caller,
|
|
params={"question": question, "frameworks": frameworks},
|
|
result_hash=result.answer_hash,
|
|
)
|
|
|
|
return json.dumps(result.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def oracle_corpus_search(
|
|
query: str,
|
|
limit: int = 10,
|
|
) -> str:
|
|
"""
|
|
Search the compliance corpus for relevant documents.
|
|
|
|
Args:
|
|
query: Search query
|
|
limit: Maximum number of results
|
|
|
|
Returns:
|
|
List of matching documents with relevance scores
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "oracle_query")
|
|
|
|
results = await oracle_engine.search_corpus(query, limit)
|
|
|
|
return json.dumps([r.to_dict() for r in results], indent=2)
|
|
|
|
# ============================================================================
|
|
# Drills Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def drills_create(
|
|
prompt: str,
|
|
skills: list[str] = None,
|
|
severity: str = "medium",
|
|
) -> str:
|
|
"""
|
|
Create a new security drill contract from a scenario description.
|
|
|
|
Args:
|
|
prompt: Natural language description of the security scenario
|
|
skills: Optional list of specific skills to include
|
|
severity: Drill severity (low, medium, high, critical)
|
|
|
|
Returns:
|
|
Generated drill contract with stages and objectives
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "drills_create")
|
|
|
|
contract = await drills_engine.create_contract(
|
|
prompt=prompt,
|
|
skills=skills,
|
|
severity=severity,
|
|
)
|
|
|
|
await emit_tool_call_receipt(
|
|
tool="drills_create",
|
|
caller=caller,
|
|
params={"prompt": prompt, "severity": severity},
|
|
result_hash=contract.contract_hash,
|
|
)
|
|
|
|
return json.dumps(contract.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def drills_status(
|
|
drill_id: str = None,
|
|
) -> str:
|
|
"""
|
|
Get status of active drills or a specific drill.
|
|
|
|
Args:
|
|
drill_id: Optional specific drill ID to check
|
|
|
|
Returns:
|
|
Drill status information
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "drills_view")
|
|
|
|
if drill_id:
|
|
status = await drills_engine.get_drill_status(drill_id)
|
|
else:
|
|
status = await drills_engine.get_active_drills()
|
|
|
|
return json.dumps(status, indent=2)
|
|
|
|
@server.tool()
|
|
async def drills_complete_stage(
|
|
drill_id: str,
|
|
stage_id: str,
|
|
outputs: list[str] = None,
|
|
findings: str = None,
|
|
) -> str:
|
|
"""
|
|
Mark a drill stage as complete with outputs.
|
|
|
|
Args:
|
|
drill_id: The drill ID
|
|
stage_id: The stage to complete
|
|
outputs: List of output artifact paths
|
|
findings: Summary of findings from this stage
|
|
|
|
Returns:
|
|
Updated drill state
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "drills_execute")
|
|
|
|
state = await drills_engine.complete_stage(
|
|
drill_id=drill_id,
|
|
stage_id=stage_id,
|
|
outputs=outputs or [],
|
|
findings=findings,
|
|
)
|
|
|
|
await emit_tool_call_receipt(
|
|
tool="drills_complete_stage",
|
|
caller=caller,
|
|
params={"drill_id": drill_id, "stage_id": stage_id},
|
|
result_hash=state.state_hash,
|
|
)
|
|
|
|
return json.dumps(state.to_dict(), indent=2)
|
|
|
|
# ============================================================================
|
|
# Mesh Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def mesh_topology() -> str:
|
|
"""
|
|
Get current mesh topology including nodes, routes, and health.
|
|
|
|
Returns:
|
|
Current topology snapshot
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "mesh_view")
|
|
|
|
topology = await mesh_engine.get_topology()
|
|
|
|
return json.dumps(topology.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def mesh_node_status(
|
|
node_id: str,
|
|
) -> str:
|
|
"""
|
|
Get detailed status of a specific node.
|
|
|
|
Args:
|
|
node_id: Node identifier (e.g., "brick-01")
|
|
|
|
Returns:
|
|
Node status including health, capabilities, and recent events
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "mesh_view")
|
|
|
|
status = await mesh_engine.get_node_status(f"did:vm:node:{node_id}")
|
|
|
|
return json.dumps(status.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def mesh_capability_check(
|
|
node_id: str,
|
|
capability: str,
|
|
) -> str:
|
|
"""
|
|
Check if a node has a specific capability.
|
|
|
|
Args:
|
|
node_id: Node identifier
|
|
capability: Capability to check (anchor, storage, compute, oracle, admin)
|
|
|
|
Returns:
|
|
Capability status and details
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "mesh_view")
|
|
|
|
result = await mesh_engine.check_capability(
|
|
f"did:vm:node:{node_id}",
|
|
capability,
|
|
)
|
|
|
|
return json.dumps(result, indent=2)
|
|
|
|
# ============================================================================
|
|
# Treasury Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def treasury_balance(
|
|
account_id: str = None,
|
|
) -> str:
|
|
"""
|
|
Get treasury balance for an account or all accounts.
|
|
|
|
Args:
|
|
account_id: Optional specific account ID
|
|
|
|
Returns:
|
|
Balance information
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "treasury_view")
|
|
|
|
if account_id:
|
|
balance = await treasury_engine.get_balance(account_id)
|
|
else:
|
|
balance = await treasury_engine.get_all_balances()
|
|
|
|
return json.dumps(balance, indent=2)
|
|
|
|
@server.tool()
|
|
async def treasury_record_entry(
|
|
entry_type: str,
|
|
account: str,
|
|
amount: float,
|
|
currency: str,
|
|
memo: str,
|
|
tags: list[str] = None,
|
|
) -> str:
|
|
"""
|
|
Record a treasury entry (credit or debit).
|
|
|
|
Args:
|
|
entry_type: "credit" or "debit"
|
|
account: Account ID
|
|
amount: Amount
|
|
currency: Currency code (EUR, USD, etc.)
|
|
memo: Transaction memo
|
|
tags: Optional tags
|
|
|
|
Returns:
|
|
Entry receipt
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "treasury_write")
|
|
|
|
receipt = await treasury_engine.record_entry(
|
|
entry_type=entry_type,
|
|
account=account,
|
|
amount=amount,
|
|
currency=currency,
|
|
memo=memo,
|
|
tags=tags or [],
|
|
)
|
|
|
|
await emit_tool_call_receipt(
|
|
tool="treasury_record_entry",
|
|
caller=caller,
|
|
params={"entry_type": entry_type, "account": account, "amount": amount},
|
|
result_hash=receipt.root_hash,
|
|
)
|
|
|
|
return json.dumps(receipt.to_dict(), indent=2)
|
|
|
|
# ============================================================================
|
|
# Guardian Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def guardian_anchor_status() -> str:
|
|
"""
|
|
Get current Guardian anchor status including last anchor time and health.
|
|
|
|
Returns:
|
|
Anchor status information
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "guardian_view")
|
|
|
|
status = await guardian_engine.get_anchor_status()
|
|
|
|
return json.dumps(status.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def guardian_anchor_now(
|
|
scrolls: list[str] = None,
|
|
) -> str:
|
|
"""
|
|
Trigger an immediate anchor cycle.
|
|
|
|
Args:
|
|
scrolls: Optional list of specific scrolls to anchor (default: all)
|
|
|
|
Returns:
|
|
Anchor result
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "anchor")
|
|
|
|
result = await guardian_engine.anchor_now(scrolls)
|
|
|
|
await emit_tool_call_receipt(
|
|
tool="guardian_anchor_now",
|
|
caller=caller,
|
|
params={"scrolls": scrolls},
|
|
result_hash=result.anchor_hash,
|
|
)
|
|
|
|
return json.dumps(result.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def guardian_verify_receipt(
|
|
receipt_hash: str,
|
|
scroll: str,
|
|
) -> str:
|
|
"""
|
|
Verify a specific receipt against the anchor chain.
|
|
|
|
Args:
|
|
receipt_hash: Hash of the receipt to verify
|
|
scroll: Scroll containing the receipt
|
|
|
|
Returns:
|
|
Verification result with proof path
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "guardian_view")
|
|
|
|
result = await guardian_engine.verify_receipt(receipt_hash, scroll)
|
|
|
|
return json.dumps(result.to_dict(), indent=2)
|
|
|
|
# ============================================================================
|
|
# Identity Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def identity_resolve_did(
|
|
did: str,
|
|
) -> str:
|
|
"""
|
|
Resolve a DID to its document.
|
|
|
|
Args:
|
|
did: DID to resolve (e.g., "did:vm:node:brick-01")
|
|
|
|
Returns:
|
|
DID document
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "identity_view")
|
|
|
|
doc = await identity_engine.resolve_did(did)
|
|
|
|
return json.dumps(doc.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def identity_verify_credential(
|
|
credential_id: str,
|
|
) -> str:
|
|
"""
|
|
Verify a verifiable credential.
|
|
|
|
Args:
|
|
credential_id: Credential ID to verify
|
|
|
|
Returns:
|
|
Verification result
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "identity_view")
|
|
|
|
result = await identity_engine.verify_credential(credential_id)
|
|
|
|
return json.dumps(result, indent=2)
|
|
|
|
@server.tool()
|
|
async def identity_whoami() -> str:
|
|
"""
|
|
Get the current caller's identity and capabilities.
|
|
|
|
Returns:
|
|
Current identity context
|
|
"""
|
|
caller = await get_caller_identity()
|
|
|
|
identity = await identity_engine.get_identity_context(caller)
|
|
|
|
return json.dumps(identity.to_dict(), indent=2)
|
|
|
|
# ============================================================================
|
|
# Psi-Field Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def psi_phase_status() -> str:
|
|
"""
|
|
Get current alchemical phase status and Magnum Opus progress.
|
|
|
|
Returns:
|
|
Current phase and recent transitions
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "psi_view")
|
|
|
|
status = await psi_engine.get_phase_status()
|
|
|
|
return json.dumps(status.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def psi_transmute(
|
|
input_reference: str,
|
|
input_type: str,
|
|
title: str,
|
|
) -> str:
|
|
"""
|
|
Initiate a transmutation process to transform a negative event into capability.
|
|
|
|
Args:
|
|
input_reference: Reference to the input event (e.g., "INC-2025-12-001")
|
|
input_type: Type of input (incident, vulnerability, drill)
|
|
title: Title for the transmutation
|
|
|
|
Returns:
|
|
Initiated transmutation contract
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "psi_transmute")
|
|
|
|
contract = await psi_engine.initiate_transmutation(
|
|
input_reference=input_reference,
|
|
input_type=input_type,
|
|
title=title,
|
|
)
|
|
|
|
await emit_tool_call_receipt(
|
|
tool="psi_transmute",
|
|
caller=caller,
|
|
params={"input_reference": input_reference, "input_type": input_type},
|
|
result_hash=contract.transmutation_hash,
|
|
)
|
|
|
|
return json.dumps(contract.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def psi_opus_status() -> str:
|
|
"""
|
|
Get full Magnum Opus status including phases, transmutations, and resonances.
|
|
|
|
Returns:
|
|
Complete opus status
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "psi_view")
|
|
|
|
opus = await psi_engine.get_opus_status()
|
|
|
|
return json.dumps(opus.to_dict(), indent=2)
|
|
|
|
# ============================================================================
|
|
# Governance Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def governance_constitution_summary() -> str:
|
|
"""
|
|
Get a summary of the current constitution including version and key articles.
|
|
|
|
Returns:
|
|
Constitution summary
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "governance_view")
|
|
|
|
summary = await governance_engine.get_constitution_summary()
|
|
|
|
return json.dumps(summary.to_dict(), indent=2)
|
|
|
|
@server.tool()
|
|
async def governance_active_proposals() -> str:
|
|
"""
|
|
Get list of active governance proposals.
|
|
|
|
Returns:
|
|
Active proposals in deliberation or voting
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "governance_view")
|
|
|
|
proposals = await governance_engine.get_active_proposals()
|
|
|
|
return json.dumps([p.to_dict() for p in proposals], indent=2)
|
|
|
|
@server.tool()
|
|
async def governance_check_compliance(
|
|
action: str,
|
|
actor: str,
|
|
target: str = None,
|
|
) -> str:
|
|
"""
|
|
Check if an action would comply with the constitution.
|
|
|
|
Args:
|
|
action: Action to check (e.g., "modify_receipt", "revoke_capability")
|
|
actor: DID of the actor
|
|
target: Optional target of the action
|
|
|
|
Returns:
|
|
Compliance check result with relevant articles
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "governance_view")
|
|
|
|
result = await governance_engine.check_compliance(action, actor, target)
|
|
|
|
return json.dumps(result.to_dict(), indent=2)
|
|
|
|
# ============================================================================
|
|
# Cross-Engine Query Tools
|
|
# ============================================================================
|
|
|
|
@server.tool()
|
|
async def receipts_search(
|
|
scroll: str = None,
|
|
receipt_type: str = None,
|
|
from_date: str = None,
|
|
to_date: str = None,
|
|
tags: list[str] = None,
|
|
limit: int = 50,
|
|
) -> str:
|
|
"""
|
|
Search receipts across scrolls with filters.
|
|
|
|
Args:
|
|
scroll: Specific scroll to search (default: all)
|
|
receipt_type: Filter by receipt type
|
|
from_date: Start date (ISO format)
|
|
to_date: End date (ISO format)
|
|
tags: Filter by tags
|
|
limit: Maximum results
|
|
|
|
Returns:
|
|
Matching receipts
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "receipts_view")
|
|
|
|
from .receipts import search_receipts
|
|
|
|
results = await search_receipts(
|
|
scroll=scroll,
|
|
receipt_type=receipt_type,
|
|
from_date=from_date,
|
|
to_date=to_date,
|
|
tags=tags,
|
|
limit=limit,
|
|
)
|
|
|
|
return json.dumps([r.to_dict() for r in results], indent=2)
|
|
|
|
@server.tool()
|
|
async def system_health() -> str:
|
|
"""
|
|
Get comprehensive system health across all engines.
|
|
|
|
Returns:
|
|
Health status for all engines and nodes
|
|
"""
|
|
caller = await get_caller_identity()
|
|
await verify_capability(caller, "system_view")
|
|
|
|
from datetime import datetime
|
|
from .receipts import get_total_receipt_count
|
|
|
|
health = {
|
|
"timestamp": datetime.utcnow().isoformat() + "Z",
|
|
"mesh": (await mesh_engine.get_health()).to_dict(),
|
|
"guardian": (await guardian_engine.get_health()).to_dict(),
|
|
"oracle": (await oracle_engine.get_health()).to_dict(),
|
|
"psi_phase": (await psi_engine.get_phase_status()).current_phase,
|
|
"receipts_total": await get_total_receipt_count(),
|
|
"last_anchor_age_seconds": await guardian_engine.get_last_anchor_age(),
|
|
}
|
|
|
|
return json.dumps(health, indent=2)
|
|
|
|
# ============================================================================
|
|
# Server Entry Point
|
|
# ============================================================================
|
|
|
|
def main():
|
|
"""Run the VaultMesh MCP server."""
|
|
import asyncio
|
|
from mcp.server.stdio import stdio_server
|
|
|
|
async def run():
|
|
async with stdio_server() as (read_stream, write_stream):
|
|
await server.run(
|
|
read_stream,
|
|
write_stream,
|
|
server.create_initialization_options(),
|
|
)
|
|
|
|
asyncio.run(run())
|
|
|
|
if __name__ == "__main__":
|
|
main()
|
|
```
|
|
|
|
### 2.2 Tool Call Receipt
|
|
|
|
Every MCP tool call is receipted:
|
|
|
|
```json
|
|
{
|
|
"type": "mcp_tool_call",
|
|
"call_id": "mcp-call-2025-12-06-001",
|
|
"timestamp": "2025-12-06T14:30:00Z",
|
|
"caller": "did:vm:agent:claude-session-abc123",
|
|
"tool": "oracle_answer",
|
|
"params_hash": "blake3:params...",
|
|
"result_hash": "blake3:result...",
|
|
"duration_ms": 1250,
|
|
"capability_used": "oracle_query",
|
|
"session_id": "session-xyz789",
|
|
"tags": ["mcp", "oracle", "tool-call"],
|
|
"root_hash": "blake3:aaa111..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. MCP Gateway
|
|
|
|
### 3.1 Authentication Flow
|
|
|
|
```python
|
|
# vaultmesh_mcp/auth.py
|
|
|
|
from typing import Optional
|
|
from .identity import identity_engine
|
|
|
|
async def get_caller_identity() -> str:
|
|
"""Get the DID of the current MCP caller."""
|
|
# In production, this comes from the MCP session context
|
|
# For Claude Desktop, it's derived from the session token
|
|
session = get_current_session()
|
|
|
|
if session.authenticated_did:
|
|
return session.authenticated_did
|
|
|
|
# Anonymous callers get a session-scoped agent DID
|
|
return f"did:vm:agent:mcp-session-{session.id}"
|
|
|
|
async def verify_capability(caller: str, capability: str) -> bool:
|
|
"""Verify the caller has the required capability."""
|
|
# Check capability token
|
|
has_cap = await identity_engine.check_capability(caller, capability)
|
|
|
|
if not has_cap:
|
|
raise PermissionError(
|
|
f"Caller {caller} lacks capability: {capability}"
|
|
)
|
|
|
|
# Log capability exercise
|
|
await identity_engine.log_capability_exercise(
|
|
caller=caller,
|
|
capability=capability,
|
|
action="mcp_tool_call",
|
|
)
|
|
|
|
return True
|
|
```
|
|
|
|
### 3.2 Rate Limiting
|
|
|
|
```python
|
|
# vaultmesh_mcp/ratelimit.py
|
|
|
|
from collections import defaultdict
|
|
from datetime import datetime, timedelta
|
|
|
|
class RateLimiter:
|
|
def __init__(self):
|
|
self.calls = defaultdict(list)
|
|
self.limits = {
|
|
"oracle_answer": (10, timedelta(minutes=1)), # 10/min
|
|
"guardian_anchor_now": (5, timedelta(hours=1)), # 5/hour
|
|
"treasury_record_entry": (100, timedelta(hours=1)), # 100/hour
|
|
"default": (60, timedelta(minutes=1)), # 60/min
|
|
}
|
|
|
|
async def check(self, caller: str, tool: str) -> bool:
|
|
key = f"{caller}:{tool}"
|
|
now = datetime.utcnow()
|
|
|
|
limit, window = self.limits.get(tool, self.limits["default"])
|
|
|
|
# Clean old entries
|
|
self.calls[key] = [
|
|
t for t in self.calls[key]
|
|
if now - t < window
|
|
]
|
|
|
|
if len(self.calls[key]) >= limit:
|
|
raise RateLimitExceeded(
|
|
f"Rate limit exceeded for {tool}: {limit} per {window}"
|
|
)
|
|
|
|
self.calls[key].append(now)
|
|
return True
|
|
```
|
|
|
|
### 3.3 Constitutional Compliance
|
|
|
|
```python
|
|
# vaultmesh_mcp/compliance.py
|
|
|
|
async def check_constitutional_compliance(
|
|
tool: str,
|
|
caller: str,
|
|
params: dict,
|
|
) -> bool:
|
|
"""Check if a tool call complies with the constitution."""
|
|
|
|
# Check against axioms
|
|
if tool in AXIOM_VIOLATING_TOOLS:
|
|
raise ConstitutionalViolation(
|
|
f"Tool {tool} would violate constitutional axioms"
|
|
)
|
|
|
|
# Check for emergency restrictions
|
|
emergency = await governance_engine.get_active_emergency()
|
|
if emergency and tool in emergency.restricted_tools:
|
|
raise EmergencyRestriction(
|
|
f"Tool {tool} is restricted during current emergency"
|
|
)
|
|
|
|
# Check for specific parameter violations
|
|
violations = await governance_engine.check_params_compliance(tool, params)
|
|
if violations:
|
|
raise ConstitutionalViolation(
|
|
f"Parameters violate constitution: {violations}"
|
|
)
|
|
|
|
return True
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Claude Desktop Configuration
|
|
|
|
### 4.1 config.json
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"vaultmesh": {
|
|
"command": "python",
|
|
"args": ["-m", "vaultmesh_mcp.server"],
|
|
"env": {
|
|
"VAULTMESH_CONFIG": "/path/to/vaultmesh/config.toml",
|
|
"VAULTMESH_IDENTITY": "did:vm:agent:claude-desktop"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.2 Capability Configuration
|
|
|
|
```toml
|
|
# vaultmesh/config.toml
|
|
|
|
[mcp.capabilities]
|
|
# Default capabilities for Claude Desktop sessions
|
|
default_capabilities = [
|
|
"oracle_query",
|
|
"drills_view",
|
|
"mesh_view",
|
|
"treasury_view",
|
|
"guardian_view",
|
|
"identity_view",
|
|
"psi_view",
|
|
"governance_view",
|
|
"receipts_view",
|
|
"system_view",
|
|
]
|
|
|
|
# Elevated capabilities require explicit grant
|
|
elevated_capabilities = [
|
|
"drills_create",
|
|
"drills_execute",
|
|
"treasury_write",
|
|
"anchor",
|
|
"psi_transmute",
|
|
]
|
|
|
|
[mcp.rate_limits]
|
|
oracle_answer = { limit = 10, window_minutes = 1 }
|
|
guardian_anchor_now = { limit = 5, window_hours = 1 }
|
|
treasury_record_entry = { limit = 100, window_hours = 1 }
|
|
default = { limit = 60, window_minutes = 1 }
|
|
|
|
[mcp.audit]
|
|
receipt_all_calls = true
|
|
log_params = true
|
|
log_results = false # Results may contain sensitive data
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Tool Categories
|
|
|
|
### 5.1 Read-Only Tools (Default Access)
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `oracle_answer` | Ask compliance questions |
|
|
| `oracle_corpus_search` | Search compliance corpus |
|
|
| `drills_status` | View drill status |
|
|
| `mesh_topology` | View mesh topology |
|
|
| `mesh_node_status` | View node status |
|
|
| `mesh_capability_check` | Check node capabilities |
|
|
| `treasury_balance` | View balances |
|
|
| `guardian_anchor_status` | View anchor status |
|
|
| `guardian_verify_receipt` | Verify receipts |
|
|
| `identity_resolve_did` | Resolve DIDs |
|
|
| `identity_verify_credential` | Verify credentials |
|
|
| `identity_whoami` | View own identity |
|
|
| `psi_phase_status` | View phase status |
|
|
| `psi_opus_status` | View opus status |
|
|
| `governance_constitution_summary` | View constitution |
|
|
| `governance_active_proposals` | View proposals |
|
|
| `governance_check_compliance` | Check compliance |
|
|
| `receipts_search` | Search receipts |
|
|
| `system_health` | View system health |
|
|
|
|
### 5.2 Write Tools (Elevated Access)
|
|
|
|
| Tool | Capability Required |
|
|
|------|---------------------|
|
|
| `drills_create` | `drills_create` |
|
|
| `drills_complete_stage` | `drills_execute` |
|
|
| `treasury_record_entry` | `treasury_write` |
|
|
| `guardian_anchor_now` | `anchor` |
|
|
| `psi_transmute` | `psi_transmute` |
|
|
|
|
---
|
|
|
|
## 6. Example Interactions
|
|
|
|
### 6.1 Compliance Query
|
|
|
|
```
|
|
Human: What's our current compliance status for the AI Act Annex IV?
|
|
|
|
Claude: [Calls oracle_answer with question="What is our compliance status for AI Act Annex IV?", frameworks=["AI_Act"]]
|
|
|
|
Based on the Oracle's assessment:
|
|
|
|
**Compliance Status: Partial (73%)**
|
|
|
|
Key findings:
|
|
- Technical documentation requirements (§4.2): ✅ Compliant
|
|
- Risk management system (§4.3): ⚠️ Needs update for latest guidance
|
|
- Data governance (§4.5): ✅ Compliant
|
|
- Human oversight measures (§4.7): ⚠️ Documentation incomplete
|
|
|
|
The Oracle flagged that our risk management documentation needs updating to reflect the December 2024 EU guidance. I can help draft those updates if you'd like.
|
|
```
|
|
|
|
### 6.2 Security Drill
|
|
|
|
```
|
|
Human: Start a drill for detecting lateral movement in our Kubernetes cluster
|
|
|
|
Claude: [Calls drills_create with prompt="Detect and respond to lateral movement within Kubernetes cluster", skills=["kubernetes-security", "detection-defense-ir"]]
|
|
|
|
I've created a new security drill:
|
|
|
|
**Drill ID:** drill-1764691432
|
|
**Scenario:** Lateral Movement Detection in Kubernetes
|
|
|
|
**Stages:**
|
|
1. **Initial Access Simulation** (kubernetes-security)
|
|
- Simulate compromised pod gaining shell access
|
|
- Establish baseline network patterns
|
|
|
|
2. **Lateral Movement Attempt** (kubernetes-security)
|
|
- Attempt service account token theft
|
|
- Test pod-to-pod communication abuse
|
|
- Probe for secrets and configmaps
|
|
|
|
3. **Detection Validation** (detection-defense-ir)
|
|
- Verify Falco alerts triggered
|
|
- Check network policy enforcement
|
|
- Validate audit log capture
|
|
|
|
4. **Response Execution** (detection-defense-ir)
|
|
- Execute containment playbook
|
|
- Document response timeline
|
|
|
|
Ready to begin Stage 1?
|
|
```
|
|
|
|
### 6.3 System Health Check
|
|
|
|
```
|
|
Human: How's the system looking?
|
|
|
|
Claude: [Calls system_health]
|
|
|
|
**VaultMesh Health Summary**
|
|
|
|
🟢 **Overall Status: Healthy**
|
|
|
|
**Mesh:**
|
|
- Nodes: 5 active, 0 degraded
|
|
- Routes: 12 healthy
|
|
- Last topology change: 3 days ago
|
|
|
|
**Guardian:**
|
|
- Last anchor: 47 minutes ago
|
|
- Anchor backend: Ethereum (block 12345678)
|
|
- Receipts since last anchor: 23
|
|
|
|
**Oracle:**
|
|
- Corpus documents: 147
|
|
- Last query: 12 minutes ago
|
|
- Average response time: 1.2s
|
|
|
|
**Psi-Field:**
|
|
- Current phase: ALBEDO 🜄
|
|
- Time in phase: 4 days
|
|
- Recent transmutations: 2
|
|
|
|
**Receipts:**
|
|
- Total: 1,847 across all scrolls
|
|
- Today: 34 new receipts
|
|
|
|
Everything looks good. The Guardian is anchoring on schedule, and no anomalies detected.
|
|
```
|