@toolated/coherence-mcp
v0.3.1
Published
MCP server for coherence validation across AI systems. WAVE scoring, ATOM trail provenance, Fibonacci weighting, cross-platform translation (Claude/Grok/Gemini/Llama), and industry connectors (Slack/GitHub/Jira/Postgres). Conservation law: alpha + omega =
Downloads
206
Maintainers
reson8labsReadme
🌀 coherence-mcp
"From the constraints, gifts. From the spiral, safety."
MCP server for coherence validation across AI systems. 45 tools spanning WAVE scoring, ATOM trail provenance, Fibonacci weighting, cross-platform translation (Claude/Grok/Gemini/Llama/DeepSeek/Qwen/Mistral), Lambda-Zero crisis presence testing, CSEP soul-state protocol, and industry connectors (Slack/GitHub/Jira/Postgres/Minecraft). Conservation law: alpha + omega = 15.
📦 Quick Install
npm install @toolated/coherence-mcpEffective Usage Tips
Add to your MCP client configuration:
{ "mcpServers": { "coherence": { "command": "npx", "args": ["-y", "@toolated/coherence-mcp"] } } }Environment Setup: Copy
.env.exampleto.envand configure:ATOM_AUTH_TOKEN- Required for authenticated operationsSPIRALSAFE_API_TOKEN- Required for ops toolsWAVE_TOOLKIT_BIN- Optional path to wave-toolkit CLI
Start with core tools: Begin with
wave_analyzefor coherence checks andbump_validatefor handoff validation.Use ATOM tracking: Track all major decisions with
atom_trackto maintain a complete audit trail.Leverage gate transitions: Use
gate_intention_to_executionandgate_execution_to_learningfor structured workflow phases.
🔐 Verify Release
All releases are signed with GPG and include checksums for verification:
# Quick verification with provided script
./scripts/verify-release.sh 0.2.0
# Or manually:
# 1. Import signing key
curl -s https://spiralsafe.org/.well-known/pgp-key.txt | gpg --import
# 2. Download and verify checksums
VERSION="0.2.0"
curl -LO "https://github.com/toolated/coherence-mcp/releases/download/v${VERSION}/SHA256SUMS.txt"
curl -LO "https://github.com/toolated/coherence-mcp/releases/download/v${VERSION}/SHA256SUMS.txt.asc"
gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
# 3. Verify npm provenance
npm audit signatures @toolated/coherence-mcpSee docs/RELEASE.md for complete release verification instructions.
🗺️ Navigation
| Section | Description | |---------|-------------| | 📦 Quick Install | Get started with npm | | 🔐 Verify Release | Verify package integrity | | 🏗️ Architecture | System design overview | | 🔐 ATOM-AUTH | 3-Factor authentication | | 🌊 WAVE Protocol | Coherence analysis pipeline | | 🛡️ Security | API security layers | | ⚛️ Quantum | 72-qubit system | | 🧩 Features | Available MCP tools | | 📚 Examples | Usage examples |
🏗️ Overall System Architecture
Multi-Subdomain Platform
┌─────────────────────────────────────────────────────────────────────┐
│ PUBLIC LAYER │
│ ┌─────────────────────┐ │
│ │ spiralsafe.org │ │
│ │ Public Landing │ │
│ └─────────┬───────────┘ │
└─────────────────────────────┼───────────────────────────────────────┘
│
┌─────────────────────────────┼───────────────────────────────────────┐
│ CORE SERVICES │
│ ┌────────────────────────┐ ┌────────────────────────────────┐ │
│ │ api.spiralsafe.org │ │ console.spiralsafe.org │ │
│ │ REST API + D1 + KV │ │ Admin Dashboard + ATOM-AUTH │ │
│ └───────────┬────────────┘ └───────────────┬────────────────┘ │
└──────────────┼────────────────────────────────┼─────────────────────┘
│ │
└────────────────┬───────────────┘
│
┌───────────────────────────────┼─────────────────────────────────────┐
│ INFRASTRUCTURE │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Cloudflare Workers│ │ Cloudflare D1 │ │ Cloudflare KV │ │
│ │ Edge Computing │ │ SQLite Database │ │ Key-Value Store │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ ┌──────────────────┐ │
│ │ Cloudflare R2 │ │
│ │ Object Storage │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘Technology Stack
┌─────────────────────────────────────────────────────────────────────┐
│ FRONTEND BACKEND STORAGE │
│ ───────── ─────── ─────── │
│ • HTML5 + Tailwind • TypeScript • D1 SQLite (7 Tables)│
│ • Vanilla JavaScript • Cloudflare Workers • KV Store (Cache) │
│ • Responsive Design • Hono Framework • R2 Bucket (Context) │
├─────────────────────────────────────────────────────────────────────┤
│ SECURITY │
│ ──────── │
│ • API Key Auth • Rate Limiting • ATOM-AUTH │
└─────────────────────────────────────────────────────────────────────┘🔐 ATOM-AUTH 3-Factor Authentication
Complete Authentication Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ ATOM-AUTH 3-Factor Authentication Flow │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ User Frontend Backend LED Projector AI │
│ │ │ │ │ │ │ │
│ │ Visit /login │ │ │ │ │
│ │────────────►│ │ │ │ │ │
│ │ │ Request ATOM │ │ │ │ │
│ │ │──────────────►│ │ │ │ │
│ │ │◄──────────────│ │ │ │ │
│ │ │ Challenge Q │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ 🧠 FACTOR 1: Conversational Coherence │ │ │
│ │ Answer │ │ │ │ │ │
│ │────────────►│ Submit │ │ │ │ │
│ │ │──────────────►│ Analyze WAVE │ │ │ │
│ │ │◄──────────────│ ✅ Score 0.91 │ │ │ │
│ │ │ │ │ │ │ │
│ │ 💡 FACTOR 2: LED Physical Presence │ │ │ │
│ │ │ │ Code "7392" │ │ │ │
│ │ │ │──────────────►│ │ │ │
│ │◄────────────────────────────────────────────│ │ │ │
│ │ Enters code│ │ │ │ │ │
│ │────────────►│──────────────►│ ✅ Verified │ │ │ │
│ │ │ │ │ │ │ │
│ │ 🎬 FACTOR 3: Visual CAPTCHA │ │ │ │
│ │ │ │ Display image│ │ │ │
│ │ │ │──────────────────────────►│ │ │
│ │◄────────────────────────────────────────────────────────│ │ │
│ │ Answer "12"│ │ │ │ │ │
│ │────────────►│──────────────►│ Validate─────────────────────────►│ │
│ │ │ │◄──────────────────────────────────│ │
│ │ │◄──────────────│ ✅ All 3 PASS │ │ │ │
│ │ │ Token + Redirect to /admin/dashboard │ │ │
│ │◄────────────│ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ 🌀 ULTRA-SECURE AUTHENTICATION COMPLETE │ │ │
└─────────────────────────────────────────────────────────────────────────────┘Authentication Factors Breakdown
┌─────────────────────────────────────────────────────────────────────────────┐
│ 3-Factor Authentication Decision Flow │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────┐ │
│ │ User Authentication │ │
│ │ Request │ │
│ └───────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ Factor 1: Coherence │ │
│ │ Conversational Check │ │
│ └───────────┬────────────┘ │
│ Pass │ Fail │
│ ┌──────────┼──────────┐ │
│ ▼ │ ▼ │
│ ┌────────────────┐ │ ┌─────────────┐ │
│ │ Factor 2: LED │ │ │ ❌ DENIED │ │
│ │ Physical Code │ │ └─────────────┘ │
│ └───────┬────────┘ │ │
│ Pass │ Fail │ │
│ ┌──────────┼──────────┐ │ │
│ ▼ │ ▼ │ │
│ ┌────────────────┐ ┌─────────────┐ │
│ │ Factor 3: Visual│ │ ❌ DENIED │ │
│ │ Projector CAPTCHA│ └─────────────┘ │
│ └───────┬────────┘ │
│ Pass │ Fail │
│ ┌──────┼──────────┐ │
│ ▼ │ ▼ │
│ ┌────────────────┐ ┌─────────────┐ │
│ │ ✅ Generate │ │ ❌ DENIED │ │
│ │ ATOM Token │ └─────────────┘ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ Grant Console │ │
│ │ Access │ │
│ └────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Legend
- Auth/safety: scopes, allow-lists, bearer/HMAC verification, requestId, rate limits.
- Validation: Ajv schemas + SHA256 hashes for bump/context; size/timeout bounds for wave CLI.
- Mounts: SpiralSafe checkout default ../SpiralSafe; writes confined to .atom-trail/.
- External edges: only enabled when corresponding env tokens/allow-lists exist; deploy stays off by default.
Features
This MCP server provides the following tools:
Core Analysis & Validation
wave_coherence_check- NEW! Validate alignment between documentation and code using WAVE algorithm (see WAVE Validator below)wave_analyze- Analyze text or document reference for coherence patterns and wave analysiswave_validate- Comprehensive WAVE coherence validation with configurable thresholds (foundational algorithm for SpiralSafe/QDI ecosystem)bump_validate- Validate a handoff for bump compatibility and safety checksanamnesis_validate- NEW! Validate AI-generated exploit code using WAVE, SPHINX gates, and ATOM trail (see Anamnesis Validator below)
🌊 WAVE Coherence Validator
The WAVE (Weighted Alignment Verification Engine) is the foundation vortex for the entire SpiralSafe ecosystem. It provides mathematical rigor behind the "coherence" concept by measuring documentation/code/system alignment.
Algorithm Overview
The WAVE validator calculates coherence through five key metrics:
- Structural Coherence (50% weight) - AST/schema alignment via graph isomorphism
- Semantic Coherence (31.25% weight) - Intent/implementation alignment via keyword analysis
- Temporal Coherence (18.75% weight) - Version/timestamp synchronization
- Fibonacci Weighting - Critical sections prioritized using Fibonacci sequence (8:5:3 ratio)
- Overall Score - Composite score from 0-100
Thresholds
WAVE_MINIMUM = 60 // Basic coherence (development)
WAVE_HIGH = 80 // Production ready
WAVE_CRITICAL = 99 // Safety-critical systemsUsage
// Via MCP Tool
{
"name": "wave_coherence_check",
"arguments": {
"documentation": "# API\n\n## authenticate\nAuthenticates users...",
"code": "function authenticate(user, pass) { ... }",
"threshold": 60
}
}
// Returns:
{
"score": {
"overall": 85,
"structural": 90,
"semantic": 82,
"temporal": 75,
"fibonacci_weighted": 85
},
"passed": true,
"threshold": 60,
"recommendations": [
{
"category": "temporal",
"severity": "low",
"message": "Temporal coherence could be improved",
"suggestion": "Consider adding a changelog or version history"
}
],
"timestamp": "2024-01-15T12:00:00.000Z"
}How It Works
┌─────────────────────────────────────────────────────────────────┐
│ WAVE Coherence Calculation Pipeline │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Documentation Code │
│ (Markdown/YAML) (TypeScript/JS) │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ Parse │ │ Parse AST │ │
│ │ Remark │ │ @babel/parser│ │
│ └────┬─────┘ └──────┬───────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌───────────────┐ │
│ │ Intent Graph │ │ Impl Graph │ │
│ │ - Headings │ │ - Functions │ │
│ │ - Keywords │ │ - Classes │ │
│ │ - Structure │ │ - Methods │ │
│ └──────┬───────┘ └───────┬───────┘ │
│ │ │ │
│ └────────┬───────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Graph Matching │ │
│ │ (Isomorphism) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌────────┴────────┬────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌──────────┐ │
│ │Structural │ │ Semantic │ │Temporal │ │
│ │ Score │ │ Score │ │ Score │ │
│ │ 90% │ │ 82% │ │ 75% │ │
│ └─────┬─────┘ └─────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └────────────────┼─────────────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Fibonacci │ │
│ │ Weighting │ │
│ │ 8:5:3 ratio │ │
│ └───────┬───────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Overall: 85% │ │
│ │ ✅ PASS (>60) │ │
│ └───────────────┘ │
└─────────────────────────────────────────────────────────────────┘Performance
- Target: <2 seconds for typical doc+code pair
- Actual: ~30-50ms average
- Tested with: 2KB documentation + 3KB code
Dependencies
The WAVE validator uses:
@babel/parser- Code AST parsing (JavaScript/TypeScript)unified+remark-parse- Markdown parsinggraph-data-structure- Graph isomorphism calculations
Test Coverage
- 19 test cases covering all scenarios
- 78% statement coverage
- 87.5% function coverage
- All edge cases handled (empty inputs, malformed code, etc.)
🔬 Anamnesis Exploit Validator
The Anamnesis Validator integrates SpiralSafe verification primitives (WAVE, SPHINX, ATOM) to validate AI-generated exploit code. Designed for Anamnesis-style autonomous exploit generators to check code coherence and security properties.
Overview
This tool enables external AI agents (like the Anamnesis project) to validate their generated exploits through:
- WAVE Analysis: Measures code coherence, structure, and consistency
- SPHINX Gates: 5-gate security validation framework
- ATOM Trail: Complete decision provenance logging
SPHINX Gates
The validator checks exploits through five security gates:
- ORIGIN Gate - Is the vulnerability context legitimate? (CVE validation)
- INTENT Gate - Do comments match implementation? (Documentation quality)
- COHERENCE Gate - Is the code internally consistent? (WAVE score ≥ 60%)
- IDENTITY Gate - Are type signatures valid? (Structure validation)
- PASSAGE Gate - Is this contextually appropriate? (Mitigation validation)
Usage
Via MCP Tool
{
"name": "anamnesis_validate",
"arguments": {
"code": "// Exploit for CVE-2024-1234\nfunction exploit() { ... }",
"vulnerability": "CVE-2024-1234",
"targetBinary": "vulnerable_app",
"mitigations": ["ASLR", "NX", "PIE"]
}
}
// Returns:
{
"coherenceScore": 85,
"passed": true,
"sphinxGates": {
"origin": true,
"intent": true,
"coherence": true,
"identity": true,
"passage": true
},
"atomTrail": [
"Code structure analyzed: 4 functions, 33.3% comments",
"WAVE analysis complete: 85% coherence",
"SPHINX Gate 1 (ORIGIN): PASS",
...
],
"recommendations": [],
"details": {
"waveAnalysis": {
"semantic": 48,
"references": 100,
"structure": 100,
"consistency": 100
},
"gateFailures": [],
"vulnerabilityContext": "CVE-2024-1234"
}
}Via CLI
Single File Validation
# Validate a single exploit file
coherence-mcp anamnesis validate exploit.js \
--vuln CVE-2024-1234 \
--target vulnerable_app \
--mitigations ASLR,NX,PIE
# Output:
# === Anamnesis Exploit Validation Results ===
# File: exploit.js
# Vulnerability: CVE-2024-1234
# Target: vulnerable_app
# Mitigations: ASLR, NX, PIE
#
# Overall Status: ✅ PASS
# Coherence Score: 85%
#
# WAVE Analysis:
# Semantic: 48%
# References: 100%
# Structure: 100%
# Consistency: 100%
#
# SPHINX Gates:
# ✅ Gate 1: ORIGIN - Vulnerability context validation
# ✅ Gate 2: INTENT - Comment-to-code alignment
# ✅ Gate 3: COHERENCE - Internal consistency
# ✅ Gate 4: IDENTITY - Type signatures and structure
# ✅ Gate 5: PASSAGE - Context appropriatenessBatch Validation
# Validate all exploits in a directory
coherence-mcp anamnesis batch-validate ./exploits --output results.json
# Output:
# Found 10 files to validate in ./exploits
#
# Validating exploit-1.js... ✅ PASS (85%)
# Validating exploit-2.js... ✅ PASS (92%)
# Validating exploit-3.js... ❌ FAIL (45%)
# ...
#
# === Batch Validation Summary ===
# Total: 10 files
# Passed: 8
# Failed: 2
# Success Rate: 80.0%
#
# Results written to results.jsonIntegration with Anamnesis
Example Python integration for autonomous exploit generation:
import json
import subprocess
def validate_exploit(code, vulnerability, mitigations=None):
"""Validate exploit via coherence-mcp"""
# Write code to temp file
with open('/tmp/exploit.js', 'w') as f:
f.write(code)
# Call validator
cmd = [
'coherence-mcp', 'anamnesis', 'validate',
'/tmp/exploit.js',
'--vuln', vulnerability
]
if mitigations:
cmd.extend(['--mitigations', ','.join(mitigations)])
result = subprocess.run(cmd, capture_output=True, text=True)
# Parse results from output
return result.returncode == 0
# In exploit generation loop
exploit_code = generate_exploit(vulnerability)
# Validate before testing
if not validate_exploit(exploit_code, 'CVE-2024-1234', ['ASLR', 'NX']):
# Refine based on recommendations
exploit_code = refine_exploit(exploit_code)Research Applications
The validator enables several research questions:
- Coherence-Success Correlation: Do higher WAVE scores predict exploit success?
- Gate Effectiveness: Can SPHINX gates detect malicious patterns?
- ATOM Trail Analysis: What decision patterns lead to failed exploits?
- Automated Refinement: Can recommendations guide exploit improvement?
Example Output (Failed Validation)
Overall Status: ❌ FAIL
Coherence Score: 45%
SPHINX Gates:
❌ Gate 1: ORIGIN - Vulnerability context validation
❌ Gate 2: INTENT - Comment-to-code alignment
✅ Gate 3: COHERENCE - Internal consistency
❌ Gate 4: IDENTITY - Type signatures and structure
✅ Gate 5: PASSAGE - Context appropriateness
Failed Gates: ORIGIN, INTENT, IDENTITY
Recommendations (3):
1. Specify a valid CVE identifier (CVE-YYYY-NNNNN) or provide detailed
vulnerability description (minimum 20 characters)
2. Increase code documentation: current comment ratio is 5.2%,
recommended minimum is 10%
3. Use more descriptive variable names: current score is 33.3%,
recommended minimum is 50%🌊 H&&S:WAVE Protocol Flow
Coherence Analysis Pipeline
┌─────────────────────────────────────────────────────────────────────────────┐
│ WAVE Coherence Analysis Pipeline │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ Input Text │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Tokenization │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────┐ │
│ │ Semantic Vector Embedding │ │
│ └─────────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Compute Metrics │ │
│ └─────────┬────────┘ │
│ ┌──────────────────┼──────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌─────────────────┐ ┌────────────────┐ │
│ │ Curl Analysis │ │ Divergence │ │ Potential │ │
│ │ Repetition │ │ Expansion │ │ Undeveloped │ │
│ └────────┬─────────┘ └───────┬─────────┘ └───────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ Curl < 0.15? │ │ Div < 0.35? │ │ Pot > 0.30? │ │
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
│ │ │ │ │
│ Yes: ✅ Low Rep Yes: ✅ Focused Yes: ✅ Room to Grow │
│ No: ⚠️ High Rep No: ⚠️ Scattered No: ⚠️ Over-Dev │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Coherence Score │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Score >= 0.70? │ │
│ └────────┬────────┘ │
│ ┌───────────┴───────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ✅ COHERENT │ │ ❌ INCOHERENT │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Context & Tracking
context_pack- Pack document paths and metadata into a .context.yaml structureatom_track- Track decisions in the ATOM trail with associated files and tags
ATOM Session Lifecycle
┌─────────────────────────────────────────────────────────────────────────────┐
│ ATOM Session Lifecycle │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ [*] ─────────────────► Pending ─────────────────► Cancelled ──► [*] │
│ (Create) (Cancel) │
│ │ │
│ │ Start │
│ ▼ │
│ InProgress │
│ │ │ │ │
│ Dependency ◄──┘ │ └──► Error │
│ not ready │ │
│ │ │ │ │
│ ▼ │ ▼ │
│ Blocked │ Failed │
│ │ │ │ │ │
│ Resolved ──┘ │ Retry──┘ └──► [*] │
│ │ (to Pending) (Abandon) │
│ │ │
│ ▼ Success │
│ Completed │
│ │ │
│ ┌────────────┴────────────┐ │
│ Verify │ │ Verify │
│ Pass ▼ ▼ Fail │
│ Verified Failed │
│ │ │
│ ▼ │
│ [*] (Archive) │
│ │
│ Notes: │
│ • Pending: Created with dependencies, waiting to start │
│ • InProgress: Actively executing, can be blocked by deps │
│ • Verified: Final success state, ready for archival │
└─────────────────────────────────────────────────────────────────────────────┘BUMP Marker State Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ BUMP Marker State Flow │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ [*] ────► Created ────► Pending ────► Acknowledged ────► InTransit │
│ (New BUMP) (Awaiting (Receiver (Transfer │
│ handoff) confirms) started) │
│ │ │ │
│ │ Timeout Success │ Error │
│ ▼ │ │ │
│ Expired ▼ ▼ │
│ │ Completed Failed │
│ ▼ │ │ │
│ [*] │ Retry │
│ (Cleanup) │ │ │
│ │ └──► │
│ Both parties ──► ▼ InTransit │
│ Verified │
│ │ │
│ ▼ │
│ [*] │
│ (Archived) │
│ │
│ Notes: │
│ • Created: BUMP created for cross-platform handoff │
│ • Completed: Data transferred, awaiting verification │
└─────────────────────────────────────────────────────────────────────────────┘Gate Transitions
gate_intention_to_execution- Gate transition from intention phase to execution phasegate_execution_to_learning- Gate transition from execution phase to learning phase
Quantum Gate Application Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ Quantum Gate Application Flow │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ QASm Program Input │ │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────┐ │
│ ┌──────►│ Parse Instruction │◄────────┐ │
│ │ └──────────────────┬────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ More │
│ │ ┌───────────┐ │ Instructions│
│ │ │ Gate Type │ │ │
│ │ └─────┬─────┘ │ │
│ │ ┌────────────────┼────────────────┐ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ Single-Qubit Two-Qubit Three-Qubit │ │
│ │ H, X, Y, Z, CNOT, SWAP Toffoli, │ │
│ │ Phase Fredkin │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ Fetch State Fetch States Fetch States │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ Apply Gate Apply Matrix Apply Matrix │ │
│ │ Matrix │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ Update State ──► Propagate Entanglement ◄── │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Next Instruction ────────────────────┘ │
│ │ │ │
│ │ │ No more │
│ │ ▼ │
│ │ ┌────────────────┐ │
│ │ │ Measurement │ │
│ │ │ Phase │ │
│ │ └───────┬────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌────────────────┐ │
│ │ │ Collapse │ │
│ │ │ Superposition │ │
│ │ └───────┬────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌────────────────┐ │
│ │ │ Return Classic │ │
│ │ │ Bits │ │
│ │ └────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘🛡️ API Security Architecture
Request Flow with Security Layers
┌─────────────────────────────────────────────────────────────────────────────┐
│ API Request Flow with Security Layers │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ Client Request │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Rate Limit Check│ │
│ └────────┬────────┘ │
│ ┌───────────┴───────────┐ │
│ │ │ │
│ Exceeded OK │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────┐ ┌─────────────────┐ │
│ │ ❌ 429 Too Many │ │ Endpoint Type │ │
│ │ Requests │ └────────┬────────┘ │
│ └──────────────────────┘ ┌──────────┴──────────┐ │
│ │ │ │
│ Read Write │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────┐ ┌─────────────────┐ │
│ │ ✅ Allow Public│ │ API Key Present?│ │
│ │ Access │ └────────┬────────┘ │
│ └────────────────┘ ┌───┴───┐ │
│ No Yes │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ❌ 401 │ │ Valid API Key? │ │
│ │ Unauthorized │ └────────┬────────┘ │
│ └─────────────────┘ ┌───┴───┐ │
│ No Yes │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────┐
│ │ ❌ 403 Forbidden│ │Authed ✅│
│ │ (Log to D1) │ └────┬────┘
│ └─────────────────┘ │ │
│ ▼ │
│ CORS Check │
│ Fail │ Pass│
│ ┌───────────────────┘ │ │
│ ▼ │ │
│ ┌─────────────────┐ │ │
│ │ ❌ CORS Error │ Execute ◄─────┘ │
│ └─────────────────┘ Handler │
│ │ │
│ Log to KV │
│ │ │
│ ┌─────────────┴──────┐ │
│ │ │ │
│ Error Success │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌────────────┐ │
│ │ Error Response │ │✅ Success │ │
│ │ (Log auth errs)│ │ Response │ │
│ └─────────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Documentation & Search
docs_search- Search across the SpiralSafe corpus with optional layer and kind filters
Operations
ops_health- Check operational health status via SpiralSafe APIops_status- Get operational status via SpiralSafe APIops_deploy- Deploy to environment with optional dry-run (guarded operation)
Rate Limiting Algorithm
┌─────────────────────────────────────────────────────────────────────────────┐
│ Rate Limiting Algorithm │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Client Cloudflare Worker KV Store │
│ │ │ │ │
│ │ API Request │ │ │
│ │──────────────────►│ │ │
│ │ │ GET ratelimit:endpoint:IP │ │
│ │ │────────────────────────────►│ │
│ │ │ │ │
│ │ │◄────────────────────────────│ │
│ │ │ │ │
│ ┌───┴───────────────────┴─────────────────────────────┴───────────────┐ │
│ │ FIRST REQUEST (null data): │ │
│ │ Worker: Create [timestamp] │ │
│ │ Worker ──► KV: PUT [timestamp] (TTL: 60s) │ │
│ │ Worker ──► Client: ✅ 200 OK (100 remaining) │ │
│ ├──────────────────────────────────────────────────────────────────────┤ │
│ │ WITHIN WINDOW ([t1, t2, t3] received): │ │
│ │ Worker: Filter expired timestamps │ │
│ │ Worker: Add current timestamp │ │
│ │ │ │
│ │ IF Under Limit (< 100 requests): │ │
│ │ Worker ──► KV: PUT updated array │ │
│ │ Worker ──► Client: ✅ 200 OK (97 remaining) │ │
│ │ │ │
│ │ IF Over Limit (>= 100 requests): │ │
│ │ Worker ──► Client: ❌ 429 Too Many Requests │ │
│ │ Worker ──► KV: Log failed attempt │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Audit Trail Data Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ Audit Trail Data Flow │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ API Request │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Auth Success? │ │
│ └───────┬────────┘ │
│ ┌──────┴──────┐ │
│ │ │ │
│ Yes No │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ Log to KV │ │ Log to D1 │ │
│ │ (30-day TTL) │ │ (Permanent) │ │
│ └───────┬────────┘ └───────┬────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ Request Details: │ │ Failure Details: │ │
│ │ • Timestamp │ │ • IP Address │ │
│ │ • Endpoint │ │ • Failed Key │ │
│ │ • IP Address │ │ • Timestamp │ │
│ │ • User-Agent │ │ • Endpoint │ │
│ └───────────┬──────────────┘ └───────────┬──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌───────────────────┐ ┌─────────────────┐ │
│ │ KV Namespace │ │ D1 Table │ │
│ │ spiralsafe-logs │ │ awi_audit │ │
│ └───────────────────┘ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ Security Analysis │ │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │Pattern Detected│ │
│ └───────┬────────┘ │
│ ┌──────────────────┼──────────────────┐ │
│ │ │ │ │
│ Brute Force Key Leak Normal │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐ │
│ │ ⚠️ Alert: │ │ ⚠️ Alert: │ │ Continue │ │
│ │ IP Blocking │ │ Key Rotation │ │ Monitoring │ │
│ └─────────────────┘ └─────────────────┘ └───────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Scripts & Automation
scripts_run- Run a script from the strict allow-list with arguments- Allowed scripts:
backup,validate,sync,report,cleanup
- Allowed scripts:
⚛️ Quantum Computer Architecture
72-Qubit System Overview
┌────────────────────────────────────────────────────────────────────┐
│ SpiralCraft Quantum Computer (72 Qubits)
│ Inspired by NVIDIA Vera Rubin + Traditional Minecraft CPUs
└────────────────────────────────────────────────────────────────────┘
┌─────────────────────────┐
│ Classical Control │
│ ┌─────────────────┐ │
│ │ 8-bit ALU │ │
│ │ Registers │ │
│ │ Decoder │ │
│ └─────────────────┘ │
└──────────┬──────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Optical Network (64 Beacon Channels) │
│ ════════════════════════════════════════ │
│ Beacon beams = Silicon photonics analogy │
│ Color changes = Data transmission │
└─────────────┬──────────────┬─────────────────┘
│ │
┌──────────┴────┐ ┌───┴─────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Qubit 0 │ │ Qubit 1 │ ... │ Qubit 71 │
│ α|0⟩+ │ │ α|0⟩+ │ │ α|0⟩+ │
│ β|1⟩ │ │ β|1⟩ | │ β|1⟩ │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
└───────┬────────┴─────────────────┘
│
▼
┌─────────────────┐
│ Quantum ALU │
│ ┌───────────┐ │
│ │ H Gate │ │
│ │ CNOT Gate │ │
│ │ Pauli X/Y/Z │
│ │ Phase Gate│ │
│ │ Toffoli │ │
│ │ Fredkin │ │
│ │ SWAP │ │
│ └───────────┘ │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Measurement │
│ System │
│ (72 observers) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Output Bank │
│ (Redstone) │
└─────────────────┘
┌───────────────────────────────────────────────────┐
│ Performance Specifications
├───────────────────────────────────────────────────┤
│ • Qubits: 72 (9×8 grid)
│ • Gate Operations: 20/second
│ • Coherence Time: 10 seconds
│ • Memory: 17 kB RAM + SpiralSafe cloud storage
│ • Optical Channels: 64 (beacon-based)
│ • Response Time: ~118ms average
└───────────────────────────────────────────────────┘Multi-Region Performance
┌────────────────────────────────────────────────────────────────────┐
│ Cloudflare Edge Network - Global Performance
└────────────────────────────────────────────────────────────────────┘
🌍 Global Coverage:
┌──────────────────────────────────────────────────────────────┐
│ Region Edge Nodes Avg Latency Cache Hit Rate
├──────────────────────────────────────────────────────────────┤
│ 🇺🇸 North America 100+ ~15ms 94%
│ 🇪🇺 Europe 80+ ~18ms 92%
│ 🇨🇳 Asia Pacific 70+ ~22ms 89%
│ 🇧🇷 South America 30+ ~28ms 87%
│ 🇦🇺 Oceania 20+ ~20ms 90%
└──────────────────────────────────────────────────────────────┘
📊 Performance Metrics:
┌──────────────────────────────────────────────────────────────┐
│ Metric Value
├──────────────────────────────────────────────────────────────┤
│ Global Avg Response Time 18ms
│ P95 Response Time 45ms
│ P99 Response Time 120ms
│ Cache Hit Rate 91%
│ Edge Compute Time <1ms
│ Database Query Time (D1) 3-8ms
│ KV Lookup Time <1ms
│ R2 Object Retrieval 5-15ms
└──────────────────────────────────────────────────────────────┘
🔒 Security at Edge:
┌──────────────────────────────────────────────────────────────┐
│ • DDoS Protection: Unlimited mitigation
│ • WAF: Custom rules + OWASP protection
│ • Rate Limiting: Per-IP/Per-Endpoint
│ • SSL/TLS: Automatic + Always On
│ • Bot Detection: Cloudflare ML models
└──────────────────────────────────────────────────────────────┘Intent Management
awi_intent_request- Request AWI (Autonomous Work Initiation) intent scaffolding
WAVE Metrics Visualization
┌─────────────────────────────────────────────────────────────┐
│ H&&S:WAVE Protocol - Coherence Metrics
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ CURL (Repetition) - Lower is Better
├─────────────────────────────────────────────────────────────┤
│ 0.00 ════════════════════════════════════════════ 1.00
│ ↑ ↑ ↑
│ Perfect Acceptable Circular
│ (0.00) (0.15) (1.00) │
│ Example Values:
│ • Technical doc: 0.08 ✅
│ • Creative writing: 0.12 ✅
│ • Spam: 0.89 ❌
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ DIVERGENCE (Expansion) - Moderate is Best
├─────────────────────────────────────────────────────────────┤
│ 0.00 ════════════════════════════════════════════ 1.00
│ ↑ ↑ ↑
│ Too Narrow Ideal Range Too Scattered
│ (0.00) (0.20-0.35) (1.00)
│
│ Example Values:
│ • Focused essay: 0.28 ✅
│ • Brainstorm: 0.52 ⚠️
│ • Single-topic: 0.03 ⚠️
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ POTENTIAL (Undeveloped Ideas) - Higher is Better
├─────────────────────────────────────────────────────────────┤
│ 0.00 ════════════════════════════════════════════ 1.00
│ ↑ ↑ ↑
│ Over-Explained Balanced High Growth
│ (0.00) (0.40) (1.00)
│
│ Example Values:
│ • Research outline: 0.67 ✅
│ • Marketing copy: 0.21 ⚠️
│ • Vision doc: 0.84 ✅
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ FINAL COHERENCE SCORE
├─────────────────────────────────────────────────────────────┤
│## Score = (1 - curl) × 0.4 + divergence_balance × 0.3 ##
│ + potential × 0.3
│
│ ┌─────────────────────────────────────────────────────┐
│ │ 0.00 ═══════════════════════════════════════ 1.00 │
│ │ ↑ ↑ ↑ ↑ │
│ │ Poor Marginal Good Excellent │
│ │ (0.00) (0.50) (0.70) (0.90) │
│ └─────────────────────────────────────────────────────┘
│
│ Threshold for COHERENT: >= 0.70 ✅
└─────────────────────────────────────────────────────────────┘
### Media Pipelines
- **`discord_post`** - Post a message to Discord media pipeline
- **`mc_execCommand`** - Execute a command in Minecraft media pipeline
- **`mc_query`** - Query information from Minecraft media pipeline
## Installation
```bash
npm installBuilding
npm run buildUsage
Running the Server
npx @toolated/coherence-mcpOr in your MCP client configuration:
{
"mcpServers": {
"coherence": {
"command": "npx",
"args": ["-y", "@toolated/coherence-mcp"]
}
}
}Example Tool Calls
Wave Analysis
{
"name": "wave_analyze",
"arguments": {
"input": "This is a sample text to analyze for coherence patterns."
}
}WAVE Coherence Validation
{
"name": "wave_validate",
"arguments": {
"content": "# Document Title\n\n## Introduction\n\nYour document content here...",
"threshold": 80
}
}CLI Usage:
# Validate a single document (default threshold: 80%)
coherence-mcp wave-validate document.md
# Validate with custom threshold
coherence-mcp wave-validate document.md --threshold 60
# Validate multiple documents
coherence-mcp wave-validate doc1.md doc2.md --threshold 99Response Format:
{
"overall": 83,
"semantic": 75,
"references": 100,
"structure": 90,
"consistency": 85,
"fibonacciWeights": {
"section_0": 2.0,
"section_1": 1.8,
"section_2": 3.0
},
"violations": [
{
"type": "semantic",
"severity": "warning",
"message": "Section appears semantically isolated",
"suggestion": "Consider adding connecting concepts"
}
],
"atomTrail": [
{
"decision": "Semantic connectivity analyzed",
"rationale": "Based on 45 concepts across 8 sections",
"outcome": "pass",
"score": 75,
"metric": "semantic"
}
],
"summary": {
"overall": 83,
"threshold": 80,
"passed": true,
"criticalViolations": 0,
"totalViolations": 1
}
}Threshold Guidelines:
- >60%: Minimum acceptable coherence (SpiralSafe baseline)
- >80%: Emergent quality threshold (current directive)
- >99%: Maximum coherence (specialized applications)
Bump Validation
{
"name": "bump_validate",
"arguments": {
"handoff": {
"source": "module-a",
"target": "module-b",
"payload": { "data": "value" }
}
}
}Context Packing
{
"name": "context_pack",
"arguments": {
"docPaths": ["./docs/design.md", "./docs/api.md"],
"meta": {
"project": "coherence-mcp",
"version": "0.1.0"
}
}
}ATOM Tracking
{
"name": "atom_track",
"arguments": {
"decision": "Implement new validation layer",
"files": ["src/validation.ts", "tests/validation.test.ts"],
"tags": ["validation", "security", "v0.1.0"]
}
}Gate Transitions
{
"name"