@loosechain/delta-engine-mcp

MCP Server for Loosechain Delta Engine - AI-Native Bundle Processing

Overview

The Delta Engine MCP server exposes Loosechain's Delta Engine functionality to AI assistants through the Model Context Protocol (MCP). This enables AI assistants like Claude Desktop to process bundles, validate data structures, and verify receipts without any adapter code.

What is MCP?

Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data sources. Think of it as a universal "plugin system" for AI assistants.

Why Use This Server?

• AI-Native Integration: Use Delta Engine directly from Claude Desktop or any MCP-compatible client
• Zero Adapter Code: No need to write custom integrations—just configure and go
• Type-Safe Operations: Full TypeScript type safety with comprehensive validation
• Production Ready: Battle-tested validation, error handling, and logging

Features

🔧 Three MCP Tools

| Tool | Description | |------|-------------| | delta_run_engine | Execute Delta Engine on bundles to verify data consensus across sources | | delta_validate_bundle | Validate bundle structure without executing (fast pre-flight check) | | delta_verify_receipt | Verify receipt integrity by recomputing hashes |

📦 Four MCP Resources

| Resource URI | Description | |--------------|-------------| | mcp://delta-engine/schema/bundle | JSON schema for DeltaBundle structure | | mcp://delta-engine/schema/receipt | JSON schema for DeltaReceipt structure | | mcp://delta-engine/receipts/{uvrn} | Retrieve receipts by UVRN (storage not yet implemented) | | mcp://delta-engine/bundles/{id} | Retrieve bundles by ID (storage not yet implemented) |

💡 Three MCP Prompts

| Prompt | Description | |--------|-------------| | verify_data | Template for data verification queries | | create_bundle | Guided bundle creation with placeholder data | | analyze_receipt | Receipt analysis and explanation template |

Installation

Global Installation (Recommended for CLI use)

npm install -g @loosechain/delta-engine-mcp

Local Project Installation

npm install @loosechain/delta-engine-mcp

Requirements

• Node.js >= 18.0.0
• npm >= 9.0.0

Quick Start

Claude Desktop Configuration

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "delta-engine": {
      "command": "npx",
      "args": ["-y", "@loosechain/delta-engine-mcp"]
    }
  }
}

With environment variables:

{
  "mcpServers": {
    "delta-engine": {
      "command": "npx",
      "args": ["-y", "@loosechain/delta-engine-mcp"],
      "env": {
        "LOG_LEVEL": "info",
        "MAX_BUNDLE_SIZE": "10485760"
      }
    }
  }
}

Restart Claude Desktop, and the Delta Engine tools will be available!

Running Standalone

# Global installation
delta-engine-mcp

# Using npx
npx @loosechain/delta-engine-mcp

# Local installation
node node_modules/@loosechain/delta-engine-mcp/dist/index.js

Tools Reference

delta_run_engine

Execute the Delta Engine on a bundle to verify data consensus.

Input:

{
  "bundle": {
    "bundleId": "test-bundle-001",
    "claim": "Product X has 10,000 sales",
    "dataSpecs": [
      {
        "id": "source-1",
        "label": "Internal CRM",
        "sourceKind": "report",
        "originDocIds": ["crm-2024-01"],
        "metrics": [
          { "key": "sales_count", "value": 10000 }
        ]
      },
      {
        "id": "source-2",
        "label": "Analytics Platform",
        "sourceKind": "metric",
        "originDocIds": ["analytics-dashboard"],
        "metrics": [
          { "key": "sales_count", "value": 9950 }
        ]
      }
    ],
    "thresholdPct": 0.05
  }
}

Output:

{
  "receipt": {
    "bundleId": "test-bundle-001",
    "deltaFinal": 50,
    "outcome": "consensus",
    "rounds": [...],
    "hash": "sha256:abc123...",
    "ts": "2026-01-15T12:00:00Z"
  },
  "success": true
}

Error Scenarios:

• VALIDATION_ERROR: Bundle structure invalid or thresholdPct out of range
• EXECUTION_ERROR: Engine execution failed (check bundle data)

delta_validate_bundle

Validate bundle structure without executing the engine.

Input:

{
  "bundle": {
    "bundleId": "test-bundle-001",
    "claim": "...",
    "dataSpecs": [...],
    "thresholdPct": 0.05
  }
}

Output (Success):

{
  "valid": true,
  "details": "Bundle \"test-bundle-001\" is valid with 2 data specs"
}

Output (Failure):

{
  "valid": false,
  "error": "thresholdPct must be > 0 and <= 1",
  "details": "thresholdPct must be > 0 and <= 1"
}

delta_verify_receipt

Verify receipt integrity by recomputing its hash.

Input:

{
  "receipt": {
    "bundleId": "test-bundle-001",
    "deltaFinal": 50,
    "sources": ["source-1", "source-2"],
    "rounds": [...],
    "outcome": "consensus",
    "hash": "sha256:abc123...",
    "ts": "2026-01-15T12:00:00Z"
  }
}

Output (Valid):

{
  "verified": true,
  "recomputedHash": "sha256:abc123...",
  "details": "Receipt for bundle \"test-bundle-001\" is valid. Hash verified: sha256:abc123..."
}

Output (Invalid):

{
  "verified": false,
  "error": "Hash mismatch",
  "details": "Expected sha256:abc123..., got sha256:def456..."
}

Resources Reference

Schema Resources

Get Bundle Schema:

URI: mcp://delta-engine/schema/bundle
Returns: JSON Schema for DeltaBundle

Get Receipt Schema:

URI: mcp://delta-engine/schema/receipt
Returns: JSON Schema for DeltaReceipt

Data Resources (Not Yet Implemented)

[!NOTE] Receipt and bundle retrieval resources are declared but not functional in Phase A.3 (storage layer not implemented).

Get Receipt by UVRN:

URI: mcp://delta-engine/receipts/{uvrn}
Status: Planned for future phase

Get Bundle by ID:

URI: mcp://delta-engine/bundles/{id}
Status: Planned for future phase

Prompts Reference

verify_data

Template for data verification queries.

Usage in Claude:

Use the verify_data prompt to help me verify this claim: "..."

create_bundle

Guided bundle creation with examples.

Usage in Claude:

Use the create_bundle prompt to help me create a bundle for verifying revenue data

analyze_receipt

Receipt analysis and explanation.

Usage in Claude:

Use the analyze_receipt prompt to explain this receipt: {...}

Configuration

See ENVIRONMENT.md for detailed configuration options.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | LOG_LEVEL | info | Logging verbosity (debug, info, warn, error) | | MAX_BUNDLE_SIZE | 10485760 | Maximum bundle size in bytes (10 MB) | | VERBOSE_ERRORS | false | Include stack traces in error responses | | STORAGE_PATH | (none) | Optional storage path (not yet implemented) |

Example:

LOG_LEVEL=debug MAX_BUNDLE_SIZE=20971520 npx @loosechain/delta-engine-mcp

Troubleshooting

Server doesn't appear in Claude Desktop

1. Check your claude_desktop_config.json syntax (must be valid JSON)
2. Verify the file path is correct for your OS
3. Restart Claude Desktop completely
4. Check Claude Desktop logs for errors

macOS Logs:

tail -f ~/Library/Logs/Claude/mcp*.log

Tool execution fails

Check bundle validation first:

{
  "tool": "delta_validate_bundle",
  "arguments": {
    "bundle": { ...your bundle... }
  }
}

Common issues:

• thresholdPct must be > 0 and <= 1
• Need at least 2 data specs
• Each metric must have key and value

Performance issues

Reduce bundle size:

• Limit number of data specs
• Reduce metrics per data spec
• Set lower MAX_BUNDLE_SIZE

Enable debug logging:

LOG_LEVEL=debug npx @loosechain/delta-engine-mcp

Type errors in TypeScript projects

Ensure you're importing types correctly:

import type { DeltaBundle, DeltaReceipt } from '@loosechain/delta-engine-mcp';

Development

Building from Source

git clone https://github.com/your-repo/lc_delta-core.git
cd lc_delta-core/packages/delta-engine-mcp
npm install
npm run build

Running Tests

npm test

Local Development with Claude Desktop

{
  "mcpServers": {
    "delta-engine-dev": {
      "command": "node",
      "args": ["/absolute/path/to/packages/delta-engine-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "debug",
        "VERBOSE_ERRORS": "true"
      }
    }
  }
}

Architecture

For detailed architecture information, see MCP_INTEGRATION.md.

graph LR
    A[Claude Desktop] -->|MCP Protocol| B[Delta Engine MCP Server]
    B -->|Executes| C[Delta Engine Core]
    C -->|Returns| D[DeltaReceipt]
    D -->|via MCP| A

Related Documentation

• MCP Integration Guide - Detailed integration patterns
• ENVIRONMENT.md - Configuration reference
• CLAUDE_DESKTOP_SETUP.md - Setup guide
• Phase A.3 Task List - Implementation details

License

MIT

Related Projects

• Loosechain Delta Engine Core - Core engine functionality
• MCP Protocol Specification - Official MCP docs

Loosechain - Receipts are truth. Interfaces are untrusted. Verification comes first.