@turwin/mcp-server

Verified AI code generation via Model Context Protocol - Connect Claude Desktop and other AI assistants to Turwin's mathematical verification engine.

What is This?

Turwin MCP Server exposes Turwin's verification capabilities as tools for AI assistants through the Model Context Protocol. Get mathematically verified code generation with ε-robustness guarantees, martingale convergence proofs, and cryptographic certificates.

Key Features

• 🔬 Mathematical Verification - ε-robustness, martingale convergence, falsification loop
• 🎯 Real-Time Certification - Connects to Firebase Cloud Functions for production verification
• 🛡️ Cryptographic Proof - SHA-256 proof hashes with blockchain timestamps
• 🔄 Automatic Fallback - Mock kernel for testing without credentials
• 📦 Zero Config - Works out of the box, optionally connects to real API

Quick Start

Installation

npm install -g @turwin/mcp-server

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "turwin": {
      "command": "npx",
      "args": ["-y", "@turwin/mcp-server"]
    }
  }
}

Restart Claude Desktop. You'll now have 3 Turwin verification tools available!

Available Tools

1. turwin_execute_protocol

Execute and verify an AI protocol with mathematical guarantees.

Input:

{
  "protocol": "Build a secure authentication system with OAuth2",
  "goal": "Ensure security and reliability"
}

Output: Execution ID, verification status, certificate, artifacts

2. turwin_verify_code

Verify code against specified constraints.

Input:

{
  "code": "function authenticate(user) { ... }",
  "constraints": [
    "No SQL injection vulnerabilities",
    "Proper error handling",
    "Type-safe inputs"
  ]
}

Output: Per-constraint verification results with proofs

3. turwin_get_certificate

Retrieve a previously generated certificate.

Input:

{
  "executionId": "cert_abc123..."
}

Output: Full certificate with proof artifacts

Production Setup (Real API)

Configuration

Create .env file or set environment variables:

FIREBASE_FUNCTIONS_URL=https://us-central1-your-project.cloudfunctions.net
FIREBASE_API_KEY=your_firebase_api_key

Update Claude Desktop config:

{
  "mcpServers": {
    "turwin": {
      "command": "node",
      "args": ["/path/to/node_modules/@turwin/mcp-server/dist/index.js"],
      "env": {
        "FIREBASE_FUNCTIONS_URL": "https://us-central1-your-project.cloudfunctions.net",
        "FIREBASE_API_KEY": "your_api_key_here"
      }
    }
  }
}

See FIREBASE_INTEGRATION.md for complete setup guide.

How It Works

Architecture

AI Assistant (Claude Desktop)
    ↓ Model Context Protocol
Turwin MCP Server
    ↓ HTTP + Firebase Auth
Firebase Cloud Functions
    ├── /certify → TurwinVerificationEngine
    ├── /getCertificationStatus
    └── /vaosApi/verify

Verification Process

1. Protocol Submission → MCP tool called from AI assistant
2. Certification Request → HTTP POST to /certify with protocol content
3. Mathematical Verification → Turwin engine runs ε-robustness, martingale convergence, falsification loop
4. Certificate Generation → Cryptographic proof hash (SHA-256)
5. Result Return → Certificate with verification status, confidence scores, warnings, recommendations

Development

Local Testing

git clone https://github.com/your-org/turwin-mcp-server.git
cd turwin-mcp-server
npm install
npm run build
npm start

Mock Mode (No Firebase)

Without .env credentials, the server runs in mock mode:

• ✅ All tools functional
• ✅ Valid certificate structures
• ⚠️ Mock verification (not real proofs)

Perfect for testing and development!

Configuration Options

Certification Levels

| Level | ε-threshold | Confidence | Use Case | |-------|-------------|------------|----------| | basic | 0.1 | 0.8 | Prototyping, low-risk | | standard | 0.01 | 0.95 | Production systems | | critical | 0.001 | 0.999 | Financial, healthcare | | ultra-critical | 0.0001 | 0.9999 | Safety-critical systems |

Documentation

• 📘 Firebase Integration Guide - Production API setup
• 🔧 Kernel Integration - Technical details
• 🌐 Turwin Whitepaper - Mathematical foundations
• 🔗 Model Context Protocol - MCP specification

License

MIT © Turwin