https://docs.rs/hedl-mcp

hedl-mcp

Model Context Protocol server for HEDL—complete AI/LLM integration with 11 tools, caching, rate limiting, and streaming support.

AI/LLM systems need seamless access to HEDL files: reading documents, validating schemas, converting formats, querying entities, optimizing token usage. hedl-mcp provides a production-grade MCP server that bridges AI systems with the HEDL ecosystem through 11 specialized tools (including batch operations), high-performance caching (2-5x speedup), rate limiting (DoS protection), and streaming support for large files.

This is the official Model Context Protocol server for HEDL. Connect any MCP-compatible AI system (Claude Desktop, custom agents, LLM applications) to HEDL with comprehensive tools for validation, conversion, optimization, and querying.

What's Implemented

Complete MCP server with production-ready infrastructure:

1. 11 MCP Tools: Read, query, validate, optimize, stats, format, write, convert (to/from), stream, batch
2. JSON-RPC 2.0 Protocol: Full MCP specification compliance (protocol version 2024-11-05)
3. High-Performance Caching: LRU cache with 2-5x speedup on repeated operations
4. Rate Limiting: Token bucket algorithm with 200 burst capacity, 100 req/s sustained
5. Streaming Support: Memory-efficient pagination for large documents
6. Security Features: Path traversal protection, input size limits (10 MB), safe file operations
7. Parallel Processing: Configurable thread pool for directory scanning
8. Resource Protocol: List and read HEDL files as MCP resources
9. Stdio Transport: Both sync and async modes for flexible integration
10. Comprehensive Testing: All tools with valid/invalid inputs, edge cases, caching, rate limiting

Installation

# From source
cargo install hedl-mcp

# Or build locally
cd crates/hedl-mcp
cargo build --release

Binary location: target/release/hedl-mcp

Quick Start

Standalone Server

# Start server with stdio transport
hedl-mcp --stdio

# Server listens on stdin/stdout for JSON-RPC 2.0 messages

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

{
  "mcpServers": {
    "hedl": {
      "command": "/path/to/hedl-mcp",
      "args": ["--stdio"],
      "env": {
        "HEDL_ROOT": "/path/to/hedl/documents"
      }
    }
  }
}

Environment Variables:

• HEDL_ROOT - Root directory for scoped file operations (default: current directory)

Custom MCP Client Integration

use hedl_mcp::{McpServer, McpServerConfig};
use std::path::PathBuf;

let config = McpServerConfig {
    root_path: PathBuf::from("/data/hedl"),
    name: "hedl-server".to_string(),
    version: "1.0.0".to_string(),
    rate_limit_burst: 200,         // Burst capacity
    rate_limit_per_second: 100,    // Sustained rate
    cache_size: 1000,              // LRU cache entries
};

let server = McpServer::new(config);
server.run_stdio().await?;  // Async mode
// or
server.run_stdio_sync()?;   // Sync mode

MCP Tools (11 Total)

1. hedl_read - Read and Parse HEDL Files

Read HEDL files from directory or specific file with optional JSON representation:

{
  "tool": "hedl_read",
  "arguments": {
    "path": "data/users.hedl"
  }
}

Arguments:

• path (string, required) - File or directory path (scoped to root_path)
• recursive (boolean, optional) - Recursively scan directories (default: true)
• include_json (boolean, optional) - Include JSON representation in output (default: false)
• num_threads (number, optional) - Thread count for parallel processing (default: CPU core count)

Output:

{
  "files_read": 1,
  "documents": [
    {
      "path": "data/users.hedl",
      "version": "1.0",
      "schemas": ["User", "Post"],
      "entity_count": 125,
      "json": { ... }  // Optional JSON representation
    }
  ]
}

Parallel Processing: Automatically uses parallel processing for directory operations with configurable thread pool. Single-file operations do not use parallelism.

2. hedl_query - Query Entity Registry

Query parsed entities by type and ID with graph-aware nested children support:

{
  "tool": "hedl_query",
  "arguments": {
    "hedl": "%VERSION: 1.0\n---\nusers: @User[id, name]\n  | alice, Alice Smith",
    "type_name": "User",
    "id": "alice"
  }
}

Arguments:

• hedl (string, required) - HEDL document content to query
• type_name (string, optional) - Filter by entity type name
• id (string, optional) - Filter by entity ID
• include_children (boolean, optional) - Include nested children in results (default: true)

Output:

{
  "matches": [
    {
      "type": "User",
      "id": "alice",
      "fields": ["alice", "Alice Smith"],
      "line": 3,
      "children": [
        {
          "type": "Post",
          "id": "post1",
          "fields": ["post1", "My First Post"],
          "line": 4
        }
      ]
    }
  ],
  "count": 1
}

Features:

• Filter by type_name only: returns all entities of that type
• Filter by id only: returns entities with matching ID across all types
• Recursive children traversal via %NEST relationships
• Set include_children: false to exclude nested entity information

3. hedl_validate - Validate HEDL Documents

Validate syntax, schema, and references with detailed diagnostics:

{
  "tool": "hedl_validate",
  "arguments": {
    "hedl": "%VERSION: 1.0\n---\nusers: @User[id, name]\n  | alice, Alice",
    "strict": true,
    "lint": true
  }
}

Arguments:

• hedl (string, required) - HEDL document content to validate
• strict (boolean, optional) - Treat lint warnings as errors (default: true)
• lint (boolean, optional) - Include linting diagnostics (default: true)

Output (valid document):

{
  "valid": true,
  "version": "1.0",
  "schemas": 1,
  "entities": 1,
  "diagnostics": []
}

Output (invalid document):

{
  "valid": false,
  "errors": [
    {
      "line": 3,
      "severity": "error",
      "message": "Parse error: unexpected end of line, expected ']'",
      "rule": null
    }
  ],
  "warnings": [
    {
      "line": 2,
      "severity": "warning",
      "message": "Matrix list 'users' missing count hint",
      "rule": "add-count-hints"
    }
  ]
}

Validation Levels:

• Syntax: Parse errors (missing brackets, invalid tokens)
• Schema: Type mismatches, field count errors
• References: Unresolved entity references
• Lint: Best practices (unused aliases, missing count hints)

4. hedl_optimize - JSON → HEDL Optimization

Convert JSON to optimized HEDL format with token savings statistics:

{
  "tool": "hedl_optimize",
  "arguments": {
    "json": "{\"users\": [{\"id\": \"alice\", \"name\": \"Alice\"}]}",
    "ditto": true
  }
}

Arguments:

• json (string, required) - JSON content to convert
• ditto (boolean, optional) - Enable ditto optimization for repeated values (default: true)
• compact (boolean, optional) - Minimize whitespace in output (default: false)

Output:

{
  "hedl": "users: @User[id, name]\n  | alice, Alice",
  "json_tokens": 150,
  "hedl_tokens": 90,
  "savings": 60,
  "savings_percent": 40.0,
  "optimization": "40% token reduction"
}

Reported Capability: 40-60% token savings for typical JSON documents

5. hedl_stats - Token Usage Statistics

Compare HEDL vs JSON token counts with detailed breakdown:

{
  "tool": "hedl_stats",
  "arguments": {
    "hedl": "users: @User[id, name]\n  | alice, Alice\n  | bob, Bob",
    "tokenizer": "simple"
  }
}

Arguments:

• hedl (string, required) - HEDL document content to analyze
• tokenizer (string, optional) - Tokenizer to use: "simple" or "cl100k" (default: "simple")

Output:

{
  "hedl": {
    "bytes": 58,
    "tokens": 15
  },
  "json_compact": {
    "bytes": 95,
    "tokens": 24,
    "increase_percent": 60.0
  },
  "json_pretty": {
    "bytes": 142,
    "tokens": 36,
    "increase_percent": 140.0
  },
  "savings": {
    "vs_compact": 9,
    "vs_pretty": 21,
    "efficiency": "37.5% fewer tokens vs JSON compact"
  }
}

Tokenizers:

• simple: ~4 chars/token heuristic (fast, approximate)
• cl100k: OpenAI tiktoken cl100k_base (accurate for GPT models)

6. hedl_format - Format to Canonical Form

Canonicalize HEDL with optional ditto optimization:

{
  "tool": "hedl_format",
  "arguments": {
    "hedl": "users:@User[id,name]\n|alice,Alice",
    "ditto": true
  }
}

Arguments:

• hedl (string, required) - HEDL document content to format
• ditto (boolean, optional) - Enable ditto optimization for repeated values (default: true)

Output:

{
  "formatted": "users: @User[id, name]\n  | alice, Alice",
  "canonical": true
}

Canonicalization:

• Normalizes whitespace (2-space indentation)
• Adds spaces after colons and commas
• Alphabetically sorts header directives
• Optionally compresses repeated values with ditto (^)

7. hedl_write - Write HEDL Content to File

Write HEDL content with optional validation and formatting:

{
  "tool": "hedl_write",
  "arguments": {
    "path": "output/data.hedl",
    "content": "users: @User[id, name]\n  | alice, Alice",
    "validate": true,
    "format": true,
    "backup": true
  }
}

Arguments:

• path (string, required) - Output file path (scoped to root_path)
• content (string, required) - HEDL content to write
• validate (boolean, optional) - Validate before writing (default: true)
• format (boolean, optional) - Canonicalize before writing (default: false)
• backup (boolean, optional) - Create .hedl.bak backup (default: true)

Output:

{
  "written": true,
  "path": "output/data.hedl",
  "bytes": 58,
  "backup_created": "output/data.hedl.bak"
}

Safety Features:

• Path traversal protection (canonicalize + prefix checking)
• Optional validation prevents writing invalid HEDL
• Backup creation preserves existing files

8. hedl_convert_to - Convert HEDL to Other Formats

Export HEDL to JSON, YAML, XML, CSV, Parquet (base64), Cypher (Neo4j), or TOON:

{
  "tool": "hedl_convert_to",
  "arguments": {
    "hedl": "users: @User[id, name]\n  | alice, Alice",
    "format": "json",
    "options": {
      "pretty": true
    }
  }
}

Arguments:

• hedl (string, required) - HEDL document content to convert
• format (string, required) - Target format: "json", "yaml", "xml", "csv", "parquet", "cypher", "toon"
• options (object, optional) - Format-specific options:
  • For JSON/YAML/XML: pretty (bool) - Pretty-print output (default: true)
  • For XML: include_metadata (bool) - Include metadata (default: true), root_element (string)
  • For CSV: include_headers (bool) - Include CSV headers (default: true)
  • For Cypher: include_constraints (bool) - Add constraints (default: false)

Output:

{
  "format": "json",
  "content": "{\n  \"users\": [\n    {\"id\": \"alice\", \"name\": \"Alice\"}\n  ]\n}"
}

Parquet Output: Base64-encoded parquet_base64 field with byte count Cypher Output: Neo4j CREATE/MERGE statements with optional constraints

9. hedl_convert_from - Convert Other Formats to HEDL

Import JSON, YAML, XML, CSV, Parquet, or TOON into HEDL:

{
  "tool": "hedl_convert_from",
  "arguments": {
    "content": "{\"users\": [{\"id\": \"alice\", \"name\": \"Alice\"}]}",
    "format": "json",
    "options": {
      "canonicalize": true
    }
  }
}

Arguments:

• content (string, required) - Source content to convert (base64 for parquet)
• format (string, required) - Source format: "json", "yaml", "xml", "csv", "parquet", "toon"
• options (object, optional) - Format-specific options:
  • General: canonicalize (bool) - Canonicalize output (default: false)
  • CSV: schema (array of strings) - Column names (required for headerless CSV)

Output:

{
  "hedl": "users: @User[id, name]\n  | alice, Alice",
  "canonical": true
}

CSV Conversion: Requires schema option for headerless CSV; auto-detects types for values Parquet Input: Provide base64-encoded content in content field

10. hedl_stream - Stream Parse Large Documents

Memory-efficient parsing with pagination and type filtering:

{
  "tool": "hedl_stream",
  "arguments": {
    "hedl": "users: @User[id, name]\n  | alice, Alice\n  | bob, Bob",
    "type_filter": "User",
    "offset": 0,
    "limit": 100
  }
}

Arguments:

• hedl (string, required) - HEDL document content to stream parse
• type_filter (string, optional) - Filter entities by type
• offset (number, optional) - Skip first N entities (default: 0)
• limit (number, optional) - Maximum entities to return (default: 100)

Output:

{
  "entities": [
    {
      "type": "User",
      "id": "alice",
      "fields": ["alice", "Alice"],
      "line": 2
    }
  ],
  "count": 1,
  "total": 2,
  "has_more": true,
  "next_offset": 100
}

Performance: Streaming architecture processes documents efficiently with configurable pagination.

11. batch - Execute Multiple Operations

Execute multiple operations in a single request with dependency resolution and parallel execution:

{
  "tool": "batch",
  "arguments": {
    "operations": [
      {
        "id": "validate1",
        "tool": "hedl_validate",
        "arguments": {
          "hedl": "%VERSION: 1.0\n---\nusers: @User[id, name]\n  | alice, Alice"
        }
      },
      {
        "id": "format1",
        "tool": "hedl_format",
        "arguments": {
          "hedl": "users:@User[id,name]\n|alice,Alice"
        },
        "depends_on": ["validate1"]
      }
    ],
    "mode": "continue_on_error",
    "parallel": true,
    "transaction": false,
    "timeout": 30
  }
}

Arguments:

• operations (array, required) - List of operations to execute:
  • id (string, required) - Unique operation identifier
  • tool (string, required) - Tool name to execute
  • arguments (object, required) - Tool-specific arguments
  • depends_on (array, optional) - Operation IDs this depends on
• mode (string, optional) - Execution mode: "continue_on_error" or "stop_on_error" (default: "continue_on_error")
• parallel (boolean, optional) - Enable parallel execution for independent operations (default: true)
• transaction (boolean, optional) - All-or-nothing transaction semantics (default: false)
• timeout (number, optional) - Maximum execution time in seconds (1-3600)

Output:

{
  "results": [
    {
      "id": "validate1",
      "status": "success",
      "result": {
        "valid": true,
        "version": "1.0"
      }
    },
    {
      "id": "format1",
      "status": "success",
      "result": {
        "formatted": "users: @User[id, name]\n  | alice, Alice"
      }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0,
    "duration_ms": 45
  }
}

Features:

• Dependency Resolution: Automatically orders operations based on depends_on declarations
• Parallel Execution: Independent operations run concurrently (when parallel: true)
• Error Handling: Continue on errors or stop at first failure
• Transaction Semantics: All-or-nothing execution with rollback on failure
• Timeout Protection: Maximum execution time prevents runaway operations

High-Performance Caching

LRU cache for immutable operations provides 2-5x speedup on repeated requests:

Cached Operations

• hedl_validate - Validation results for identical content
• hedl_query - Entity lookups for unchanged files
• hedl_stats - Token statistics for same content

Cache Key: Operation name + SHA256 hash of inputs

Configuration:

McpServerConfig {
    cache_size: 1000,  // Max entries (default)
    ...
}

Cache Statistics:

{
  "cache": {
    "hits": 1523,
    "misses": 478,
    "evictions": 23,
    "hit_rate": 76.1
  }
}

Impact: Validation of frequently-accessed documents drops from 50ms to <1ms.

Rate Limiting: DoS Protection

Token bucket algorithm prevents request flooding:

Configuration:

McpServerConfig {
    rate_limit_burst: 200,         // Burst capacity
    rate_limit_per_second: 100,    // Sustained rate
    ...
}

Behavior:

• Burst: Allow up to 200 requests instantly
• Sustained: Refill 100 tokens/second
• Exceeded: Returns error with retry-after time

Error Response:

{
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded. Try again in 0.5s"
  }
}

Use Case: Prevents aggressive clients from overwhelming server with thousands of requests.

Security Features

Path Traversal Protection

All file operations are scoped to configured root_path:

// Canonicalize path and check prefix
let canonical = std::fs::canonicalize(&path)?;
if !canonical.starts_with(&self.config.root_path) {
    return Err(PathTraversalError);
}

Blocked Attempts:

/etc/passwd              → Error: Path traversal detected
../../../secrets.hedl    → Error: Path traversal detected
/data/hedl/users.hedl    → OK (within root_path)

Input Size Validation

Maximum Input: 10 MB per request

if content.len() > 10_000_000 {
    return Err("Input size exceeds 10 MB limit");
}

Purpose: Prevents memory exhaustion from malicious large inputs.

Safe File Operations

• All writes create parent directories if needed
• Backup files preserve original content (.hedl.bak)
• Validation prevents writing malformed HEDL

Resource Protocol Support

List and read HEDL files as MCP resources:

resources/list

{
  "method": "resources/list"
}

Response:

{
  "resources": [
    {
      "uri": "file:///data/hedl/users.hedl",
      "name": "users.hedl",
      "mimeType": "application/x-hedl"
    },
    {
      "uri": "file:///data/hedl/config.hedl",
      "name": "config.hedl",
      "mimeType": "application/x-hedl"
    }
  ]
}

resources/read

{
  "method": "resources/read",
  "params": {
    "uri": "file:///data/hedl/users.hedl"
  }
}

Response:

{
  "contents": [
    {
      "uri": "file:///data/hedl/users.hedl",
      "mimeType": "application/x-hedl",
      "text": "users: @User[id, name]\n  | alice, Alice"
    }
  ]
}

MCP Protocol Implementation

Supported Methods

Lifecycle:

• initialize - Protocol handshake with capability negotiation
• initialized - Client confirmation notification
• shutdown - Graceful server termination

Tools:

• tools/list - List all 11 available tools with schemas
• tools/call - Execute specific tool with arguments

Resources:

• resources/list - List HEDL files in root_path
• resources/read - Read HEDL file content

Health:

• ping - Health check endpoint (always returns pong)

Server Capabilities

{
  "capabilities": {
    "tools": {
      "listChanged": false
    },
    "resources": {
      "subscribe": false,
      "listChanged": false
    }
  },
  "protocolVersion": "2024-11-05",
  "serverInfo": {
    "name": "hedl-mcp",
    "version": "1.0.0"
  }
}

Error Handling

Comprehensive error types with MCP error codes:

Error Codes:

• -32700: Parse error (invalid JSON-RPC)
• -32600: Invalid request (malformed method/params)
• -32601: Method not found
• -32000: Server error (HEDL-specific errors)

HEDL-Specific Errors:

{
  "code": -32000,
  "message": "Parse error at line 5: unexpected token",
  "data": {
    "line": 5,
    "column": 12
  }
}

Tool Errors: Returned as successful responses with is_error: true:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Path traversal detected"
    }
  ],
  "isError": true
}

Use Cases

AI-Powered HEDL Editing: LLMs read HEDL files, suggest edits, validate changes, write back canonical HEDL—all through MCP tools.

Automated Optimization: AI agents convert JSON to HEDL, analyze token savings, optimize with ditto, validate output, deploy optimized configs.

Interactive Query Assistant: Chat with HEDL data—ask "Show me all users created in 2024", agent uses hedl_query to fetch entities, formats response.

Multi-Format Pipeline: Agent reads CSV exports, converts to HEDL via hedl_convert_from, validates schemas, exports to Neo4j Cypher, tracks token efficiency.

Bulk Document Processing: AI orchestrates parallel HEDL validation across directories, aggregates lint issues, generates summary reports.

LLM Context Optimization: Analyze HEDL vs JSON token usage with hedl_stats, optimize prompts with hedl_optimize, validate context window limits.

What This Crate Doesn't Do

Direct File Watching: No file system watching—client must explicitly call tools to check for changes. Use inotify/fsevents in client if needed.

Multi-Document Transactions: Each tool call is independent—no transactional updates across multiple files. Implement transactions in client layer if required.

Schema Evolution: No automatic schema migration—manual handling of %STRUCT changes required. Use hedl-lint for schema consistency validation.

Distributed Coordination: Single-server design—no distributed consensus or multi-server coordination. Deploy multiple instances behind load balancer if needed.

Performance Characteristics

Tool Execution: ~50-200 MB/s parsing throughput depending on complexity

Caching: 2-5x speedup for repeated validation/query operations

Streaming: O(1) memory per entity regardless of file size

Rate Limiting: <0.1ms overhead per request (~1% impact)

Parallel Processing: Linear speedup up to CPU core count for directory scanning

Detailed performance benchmarks are available in the HEDL repository benchmark suite.

Testing Coverage

Comprehensive test suite covering:

• All 11 Tools: Valid/invalid inputs, edge cases, error conditions
• Batch Operations: Dependency resolution, parallel execution, error handling
• Caching: Hits, misses, LRU eviction, statistics
• Rate Limiting: Burst capacity, sustained rate, token refill, overflow
• Security: Path traversal detection, input size validation
• Parallel Processing: Custom threads, recursive scanning, error collection
• Format Conversions: Round-trip fidelity for all supported formats

Dependencies

• hedl-core 1.0 - HEDL parsing and data model
• hedl-c14n 1.0 - Canonicalization
• hedl-lint 1.0 - Best practices linting
• hedl-json, hedl-yaml, hedl-xml, hedl-csv, hedl-parquet, hedl-neo4j 1.0 - Format conversion
• serde 1.0, serde_json 1.0 - JSON serialization
• tokio 1.0 - Async runtime
• dashmap 6.1 - Concurrent HashMap for caching
• rayon 1.10 - Parallel processing
• thiserror 1.0 - Error type definitions

License

Apache-2.0