stat-guy/code-execution

Advanced MCP Code Execution Server

The most comprehensive code execution environment for AI assistants, providing advanced workspace management, file operations, and development environments far beyond any built-in tools.

🚀 Why Choose This Server?

Superior to Any Native Code Tools

• ✅ Complete workspace isolation: Multiple independent development environments
• ✅ Advanced file operations: Syntax validation, automatic backups, diff generation
• ✅ Multi-language environments: Python, Node.js, Go with package management
• ✅ Session persistence: Maintain state across complex development workflows
• ✅ Professional tooling: Everything needed for real development projects

Perfect Synergy with Our Bash Server

⚡ OPTIMAL PERFORMANCE: Load both bash + code-execution servers together!

• Bash Server: Handles system commands, process management, background jobs
• Code Execution Server: Manages workspaces, file operations, development environments
• Combined Power: Complete development ecosystem with specialized optimization for each domain

Perfect For

• Claude Code: Complete development environment with advanced capabilities
• Cursor Agent CLI: Professional-grade code execution with workspace management
• Custom AI assistants: Full MCP protocol support with enterprise features

Key Advantages

• 4 unified tools providing complete development environment
• Zero workspace contamination between different projects
• Advanced syntax validation for 20+ programming languages
• Multi-environment support with automatic dependency management
• Production-ready reliability with comprehensive error handling

⚡ Quick Setup

For Experts (30 seconds)

git clone https://github.com/stat-guy/code-execution.git
cd code-execution
npm install

Configure in Claude Desktop (~/.config/claude_desktop_config.json):

{
  "mcpServers": {
    "code-execution": {
      "command": "node",
      "args": ["path/to/code-execution/index.js"]
    }
  }
}

For Claude Code Users (10 seconds)

git clone https://github.com/stat-guy/code-execution.git
cd code-execution && npm install
claude mcp add code-execution node /ABSOLUTE/PATH/TO/code-execution/index.js

Replace /ABSOLUTE/PATH/TO/ with your actual folder path!

Recommended: Dual Server Setup (Best Performance)

# Install both servers for optimal performance
git clone https://github.com/stat-guy/bash.git
git clone https://github.com/stat-guy/code-execution.git

# Setup bash server
cd bash && npm install && pip3 install mcp pydantic
claude mcp add bash node /ABSOLUTE/PATH/TO/bash/mcp-bash-wrapper.js

# Setup code execution server  
cd ../code-execution && npm install
claude mcp add code-execution node /ABSOLUTE/PATH/TO/code-execution/index.js

For Beginners (Step-by-step)

1. Prerequisites

• Node.js 16+: Download from nodejs.org
• Git: Download from git-scm.com

2. Download & Install

# Clone the repository
git clone https://github.com/stat-guy/code-execution.git
cd code-execution

# Install dependencies  
npm install

3. Test Installation

# Test the server starts correctly
npm test

You should see: 🎉 All tests passed! Server is ready for production use.

4. Configure Claude Desktop

macOS: Edit ~/.config/claude_desktop_config.json Windows: Edit %APPDATA%\claude_desktop_config.json

{
  "mcpServers": {
    "code-execution": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/code-execution/index.js"]
    }
  }
}

⚠️ Important: Use the absolute path to index.js

5. Restart Claude Desktop

Completely quit and restart Claude Desktop to load the new server.

🔧 Server Configuration

The server automatically manages sessions with these defaults:

• Session timeout: 1 hour of inactivity
• Cleanup interval: Every 5 minutes
• File size limit: 10MB per file
• Workspace isolation: Complete separation between sessions

📖 Usage Examples

Basic File Operations

// Create and edit files with syntax validation
file_editor({
  operation: "create",
  path: "app.py", 
  file_text: "print('Hello, World!')",
  session_id: "python-project"
})

// Advanced string replacement with diff
file_editor({
  operation: "str_replace",
  path: "app.py",
  old_str: "print('Hello, World!')",
  new_str: "print('Hello, Code Execution!')"
})

Workspace Management

// Create isolated project workspace
workspace_manager({
  operation: "create_project",
  project_name: "web_app",
  template: "nodejs",
  session_id: "web-dev"
})

// Upload files to workspace
workspace_manager({
  operation: "upload_file", 
  file_path: "data/dataset.csv",
  content: "name,age,city\nJohn,30,NYC",
  session_id: "data-analysis"
})

Development Environments

// Create Python environment with packages
environment_controller({
  operation: "create_env",
  env_name: "ml_project", 
  env_type: "python",
  packages: ["pandas", "numpy", "scikit-learn"],
  session_id: "ml-session"
})

// Activate environment for development
environment_controller({
  operation: "activate_env",
  env_name: "ml_project",
  session_id: "ml-session" 
})

Command Execution

// Execute commands in isolated sessions
bash_execution({
  command: "python train_model.py",
  session_id: "ml-session",
  timeout: 300000
})

// Background processes
bash_execution({
  command: "npm run dev",
  background: true,
  session_id: "web-dev"
})

🛠 Available Tools

🎯 Why Use Both Servers Together?

Specialized Optimization

• Bash Server: Optimized for system commands, process management, shell operations
• Code Execution Server: Optimized for file operations, workspace management, development environments

Performance Benefits

• Reduced overhead: Each server handles what it does best
• Better resource management: Specialized memory and process handling
• Faster response times: Optimized tool routing and caching
• Enhanced reliability: Isolated failure domains

Complete Development Environment

// Typical workflow using both servers:

// 1. Bash server: System setup
bash.execute_command("git clone https://github.com/user/project.git")

// 2. Code execution: Project workspace
code_execution.workspace_manager({operation: "create_project", template: "python"})

// 3. Code execution: Environment setup  
code_execution.environment_controller({operation: "create_env", packages: ["fastapi"]})

// 4. Code execution: File operations
code_execution.file_editor({operation: "create", path: "main.py", content: "..."})

// 5. Bash server: Testing and deployment
bash.execute_command("pytest tests/", background: true)

🔍 Troubleshooting

Common Issues

Server not starting:

# Check Node.js version
node --version  # Should be 16+

# Verify dependencies
npm list @modelcontextprotocol/sdk

Claude not finding server:

• Verify absolute paths in configuration
• Restart Claude Desktop completely
• Check Claude Desktop logs for error messages

Permission errors:

# Ensure read permissions
chmod +r index.js

# Check workspace permissions
ls -la ~/.code-execution/

Memory issues with large files:

• Files over 10MB are streamed automatically
• Use file chunking for very large datasets
• Monitor session cleanup (automatic every 5 minutes)

Getting Help

• Issues: GitHub Issues
• Documentation: See CLAUDE.md for AI-specific instructions
• Examples: Check docs/examples/ for real-world usage patterns

📊 Performance & Reliability

• File operations: 0.05-0.2s for typical files
• Environment creation: 2-10s depending on packages
• Session isolation: 100% guaranteed separation
• Error handling: Comprehensive validation and recovery
• Memory management: Automatic cleanup and optimization

🔒 Security Features

• Workspace isolation: Complete separation between sessions
• Path validation: Prevents directory traversal attacks
• Input sanitization: Comprehensive validation of all inputs
• Resource limits: Configurable timeouts and size limits
• Audit logging: Complete operation history tracking

🎯 Real-World Examples

Data Science Pipeline

// Complete data analysis workflow
workspace_manager({operation: "create_project", template: "python"})
environment_controller({operation: "create_env", packages: ["pandas", "matplotlib"]})
workspace_manager({operation: "upload_file", file_path: "data.csv", content: "..."})
file_editor({operation: "create", path: "analyze.py", file_text: "import pandas as pd..."})
bash_execution({command: "python analyze.py"})

Web Development

// Full-stack development setup
workspace_manager({operation: "create_project", template: "nodejs"})
environment_controller({operation: "create_env", packages: ["express", "react"]})
file_editor({operation: "create", path: "server.js", file_text: "const express = require..."})
bash_execution({command: "npm run dev", background: true})

📄 License

MIT License - see file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Ready to supercharge your development workflow?

⭐ Star this repo and experience the most advanced code execution environment for AI assistants!

💡 Pro Tip: Install both bash and code-execution servers for the ultimate development experience.