CEDARScript MCP Server

AI-Assisted Code Transformations via Model Context Protocol

Overview

CEDARScript MCP Server exposes the powerful CEDARScript Editor through the Model Context Protocol (MCP), enabling AI agents like Claude to perform intelligent, semantic-aware code transformations.

Key Features

• 🔒 Secure by Default: Path validation, sandboxing, read-only mode
• 🎯 Dry-Run Mode: Preview changes before applying
• 🌲 Tree-Sitter Powered: Language-aware code analysis
• 📡 STDIO Transport: Simple subprocess integration (no HTTP overhead)
• 🛠️ Production-Ready: Comprehensive logging, error handling, testing

Quick Start

Installation

pip install cedarscript-mcp-server

Usage with Claude Desktop

1. Open Claude Desktop configuration (usually ~/.config/Claude/claude_desktop_config.json)

2. Add CEDARScript MCP server:

{
  "mcpServers": {
    "cedarscript": {
      "command": "python",
      "args": [
        "-m",
        "cedarscript_mcp.server",
        "--root",
        "/path/to/your/project"
      ]
    }
  }
}

1. Restart Claude Desktop

2. Ask Claude to use CEDARScript:

   • "Parse this CEDARScript command: UPDATE myfile.py SET imports.append('import os')"
   • "Apply this transformation (preview first): UPDATE calculator.py SET function:calculate REPLACE 'x + 1' WITH 'x + 2'"

Command-Line Usage

# Start server (STDIO mode)
python -m cedarscript_mcp.server --root /path/to/project

# With custom options
python -m cedarscript_mcp.server \
  --root /path/to/project \
  --read-only \
  --log-level DEBUG \
  --max-file-size 10485760

Architecture

CEDARScript MCP Server is a thin adapter layer that:

1. Accepts JSON-RPC requests over STDIO
2. Validates paths and security constraints
3. Delegates to CEDARScript Editor for execution
4. Returns structured results or error messages

┌─────────────────────────────────┐
│   Claude Desktop / VS Code      │
│        (MCP Client)             │
└────────────┬────────────────────┘
             │ JSON-RPC over STDIO
┌────────────▼────────────────────┐
│  CEDARScript MCP Server         │
│  • Security (path validation)   │
│  • Tools (parse, apply, list)   │
│  • Adapters (protocol mapping)  │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│   CEDARScript Editor (core)     │
│  • AST parsing                  │
│  • Tree-sitter analysis         │
│  • File transformations         │
└─────────────────────────────────┘

Available Tools

parse_cedarscript

Parse and validate CEDARScript commands without execution.

Parameters:

• content (string): CEDARScript commands

Returns: Parsed AST commands

Example:

{
  "content": "UPDATE myfile.py SET imports.append('import os')"
}

apply_cedarscript

Apply CEDARScript transformations to code files.

Parameters:

• commands (string): CEDARScript commands
• root (string): Project root directory path
• dry_run (boolean, default: true): Preview changes without writing

Returns: Results, diffs (if dry_run), affected files

Example:

{
  "commands": "UPDATE calculator.py SET function:add REPLACE 'x + y' WITH 'x + y + 1'",
  "root": "/path/to/project",
  "dry_run": true
}

list_capabilities

List server capabilities and supported features.

Returns: Server version, features, security settings

Configuration

Environment Variables

• CEDARSCRIPT_ROOT: Default project root (default: current directory)
• CEDARSCRIPT_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
• CEDARSCRIPT_LOG_FORMAT: Log format (text, json)
• CEDARSCRIPT_READ_ONLY: Force read-only mode (true/false)
• CEDARSCRIPT_MAX_FILE_SIZE: Max file size in bytes (default: 10485760)

CLI Arguments

python -m cedarscript_mcp.server \
  --root /path/to/project \         # Project root directory
  --read-only \                     # Enable read-only mode
  --log-level DEBUG \               # Logging level
  --max-file-size 10485760          # Max file size (bytes)

Security

Path Validation

• All file paths are validated against the specified root directory
• Path traversal attacks (../../../etc/passwd) are blocked
• Symlinks are resolved and validated

Denylist Patterns

Files matching these patterns are automatically rejected:

• .git/**, node_modules/**, __pycache__/**
• .env, *.env, .env.*
• credentials.json, *.key, *.pem

Read-Only Mode

When enabled, all write operations are rejected (parsing/analysis only).

File Size Limits

Configurable maximum file size (default: 10MB) to prevent resource exhaustion.

Development

Setup

# Clone repository
git clone https://github.com/CEDARScript/cedarscript-mcp-server.git
cd cedarscript-mcp-server

# Install development dependencies
make install

# Run tests
make test

# Run with coverage
make test-cov

# Format and lint
make check

Makefile Targets

make help              # Show all available targets
make install           # Install with dev dependencies
make test              # Run full test suite
make test-fast         # Run tests (skip integration)
make check             # Format, lint, security checks
make run               # Launch server (demo mode)
make build             # Build distribution packages

See planning/MAKEFILE_DESIGN.md for complete target documentation.

Testing

# Run all tests
make test

# With coverage report
make test-cov

# Watch mode (auto-rerun on changes)
make test-watch

# Test against multiple cedarscript-editor versions
make test-matrix

Documentation

• ARCHITECTURE.md: System design, protocol mapping, security model
• IMPLEMENTATION.md: Step-by-step implementation guide
• MAKEFILE_DESIGN.md: Makefile targets and automation
• Examples: Claude Desktop, VS Code, quickstart guides

Examples

Claude Desktop Configuration

See examples/claude_desktop.json for drop-in configuration.

VS Code MCP Client

See examples/vscode_mcp.json for VS Code setup.

Programmatic Usage

from cedarscript_mcp import PathValidator, apply_cedarscript_tool

# Create validator
validator = PathValidator(Path("/path/to/project"))

# Apply transformation (dry-run)
result = apply_cedarscript_tool(
    commands="UPDATE myfile.py SET imports.append('import os')",
    root="/path/to/project",
    dry_run=True,
    validator=validator
)

print(result)

Troubleshooting

Server Not Starting

Issue: ModuleNotFoundError: No module named 'mcp'

Solution: Install MCP SDK: pip install mcp>=1.0.0

Path Validation Errors

Issue: SecurityError: Path escape attempt

Solution: Ensure file paths are within the specified root directory.

Read-Only Mode Blocking Writes

Issue: SecurityError: Write operation rejected

Solution: Remove --read-only flag or set CEDARSCRIPT_READ_ONLY=false.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run make check test before committing
4. Submit a pull request

License

Apache License 2.0 - see LICENSE for details.

Related Projects

• CEDARScript Editor - Core transformation library
• CEDARScript AST Parser - Language parser
• Model Context Protocol - MCP specification

Support

• Issues: GitHub Issues
• Documentation: GitHub README
• Email: cedarscript@orgecc.com

Made with ❤️ by the CEDARScript Team