ShayYeffet/ultimate_mcp_server

🏆 ULTIMATE MCP Workspace Server

The Most Comprehensive MCP Server Ever Created - 36 professional tools across 15+ categories for development, DevOps, data processing, and automation. Transform Claude Desktop into the ultimate development environment!

🌟 Ultimate Features

• 🏆 36 Comprehensive Tools: The most complete MCP server available
• 🔒 Enterprise Security: Military-grade sandboxing and path validation
• 🚀 15+ Categories: File ops, Git, Docker, cloud storage, databases, and more
• 🌐 Multi-Platform: Windows, macOS, and Linux support
• ☁️ Multi-Cloud: AWS S3, Google Cloud, Azure integration
• 🐳 DevOps Ready: Docker management, package managers, CI/CD tools
• 📊 Data Processing: CSV, JSON, databases, web scraping, image processing
• 🔐 Security Suite: Encryption, hashing, secure key generation
• ⏰ Automation: Task scheduling, notifications, webhooks
• 🎨 Code Quality: Formatting, linting, analysis tools
• ✅ Production Ready: 109+ passing tests, comprehensive error handling

📋 Table of Contents

• Installation
• Quick Start
• Configuration Guide
• Available Tools
• Security
• Testing
• Troubleshooting
• Contributing
• License

🚀 Installation

Prerequisites

• Node.js v18 or higher (Download)
• npm (comes with Node.js)
• An MCP-compatible client (Claude Desktop, Cline, etc.)

Setup Steps

1. Clone the repository

   git clone https://github.com/ShayYeffet/ultimate_mcp_server.git
   cd ultimate_mcp_server
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Verify installation

   npm test
   

You should see all 109 tests passing! ✅

⚡ Quick Start

For Claude Desktop Users

1. Find your Claude config file:

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

2. Create or edit the file with this configuration:

   {
     "mcpServers": {
       "workspace": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/ultimate_mcp_server/dist/index.js"],
         "env": {
           "MCP_WORKSPACE_ROOT": "/path/to/your/project",
           "MCP_ALLOWED_COMMANDS": "npm,git,node",
           "MCP_LOG_LEVEL": "info"
         }
       }
     }
   }
   

3. Restart Claude Desktop

4. Test it! Ask Claude:

   "List all files in my workspace"
   "Create a new file called test.txt with 'Hello World'"
   

⚙️ Configuration Guide

🔧 What You MUST Change

When setting up the MCP server, you must customize these values in your config file:

1. Path to the Server (Required)

"args": ["/ABSOLUTE/PATH/TO/ultimate_mcp_server/dist/index.js"]

Replace with:

• Windows: "C:\\Users\\YourName\\path\\to\\ultimate_mcp_server\\dist\\index.js"
• macOS/Linux: "/home/username/path/to/ultimate_mcp_server/dist/index.js"

How to find it:

# In the ultimate_mcp_server directory, run:
pwd  # macOS/Linux
cd   # Windows

2. Workspace Root Directory (Required)

"MCP_WORKSPACE_ROOT": "/path/to/your/project"

This is THE MOST IMPORTANT setting! This directory is where the AI can read/write files.

Examples:

• Your web project: "C:\\Users\\YourName\\projects\\my-website"
• Your app: "/home/username/projects/my-app"
• A test folder: "C:\\Users\\YourName\\ai-workspace"

⚠️ Security Note: The AI can ONLY access files inside this directory. Choose carefully!

3. Allowed Commands (Recommended)

"MCP_ALLOWED_COMMANDS": "npm,git,node"

Customize based on your needs:

• Web development: "npm,git,node,yarn"
• Python projects: "python,pip,git"
• No commands: "" (empty string - disables command execution)
• Multiple commands: "npm,git,python,node,cargo,go"

⚠️ Security Note: Only list commands you trust the AI to run!

📝 Optional Configuration

Read-Only Mode

Prevent ALL write operations (useful for analysis only):

"MCP_READ_ONLY": "true"

Logging Level

Control how much logging you see:

"MCP_LOG_LEVEL": "debug"  // Options: debug, info, warn, error

Command Timeout

Set maximum time for commands (in milliseconds):

"MCP_COMMAND_TIMEOUT": "600000"  // 10 minutes

📋 Complete Configuration Examples

Example 1: Web Development Project

{
  "mcpServers": {
    "workspace": {
      "command": "node",
      "args": ["C:\\Users\\John\\ultimate_mcp_server\\dist\\index.js"],
      "env": {
        "MCP_WORKSPACE_ROOT": "C:\\Users\\John\\projects\\my-react-app",
        "MCP_ALLOWED_COMMANDS": "npm,git,node,yarn",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Example 2: Python Data Science Project

{
  "mcpServers": {
    "workspace": {
      "command": "node",
      "args": ["/home/jane/ultimate_mcp_server/dist/index.js"],
      "env": {
        "MCP_WORKSPACE_ROOT": "/home/jane/projects/data-analysis",
        "MCP_ALLOWED_COMMANDS": "python,pip,git,jupyter",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Example 3: Read-Only Code Review

{
  "mcpServers": {
    "workspace": {
      "command": "node",
      "args": ["/Users/alex/ultimate_mcp_server/dist/index.js"],
      "env": {
        "MCP_WORKSPACE_ROOT": "/Users/alex/code-to-review",
        "MCP_ALLOWED_COMMANDS": "",
        "MCP_READ_ONLY": "true",
        "MCP_LOG_LEVEL": "warn"
      }
    }
  }
}

Example 4: Multiple Workspaces

You can configure multiple MCP servers for different projects:

{
  "mcpServers": {
    "project-a": {
      "command": "node",
      "args": ["C:\\ultimate_mcp_server\\dist\\index.js"],
      "env": {
        "MCP_WORKSPACE_ROOT": "C:\\projects\\project-a",
        "MCP_ALLOWED_COMMANDS": "npm,git"
      }
    },
    "project-b": {
      "command": "node",
      "args": ["C:\\ultimate_mcp_server\\dist\\index.js"],
      "env": {
        "MCP_WORKSPACE_ROOT": "C:\\projects\\project-b",
        "MCP_ALLOWED_COMMANDS": "python,pip"
      }
    }
  }
}

🛠️ Ultimate Tool Arsenal - 36 Tools

📁 Core File Operations (7 Tools)

• list_files - List directory contents with filtering and sorting
• read_file - Read file contents with encoding support
• write_file - Create or update files atomically
• delete_file - Delete files or directories safely
• create_folder - Create directories with parent creation
• apply_patch - Apply unified diff patches to files
• run_command - Execute shell commands securely

🔍 Advanced File Operations (5 Tools)

• search_files - Grep-like text search across files with patterns
• find_files - Find files by name, pattern, size, date, extension
• copy_file - Copy files and directories recursively
• move_file - Move or rename files and folders
• get_file_info - Detailed file metadata, checksums, permissions

📦 Archive & Compression (2 Tools)

• compress_files - Create ZIP/TAR/GZ archives with compression
• extract_archive - Extract compressed archives safely

🌐 Network Operations (1 Tool)

• http_request - Full HTTP client with all methods, headers, timeouts

🔧 Git Operations (4 Tools)

• git_status - Repository status, changes, branch information
• git_diff - Show differences between commits, branches, files
• git_log - View commit history with filters and formatting
• git_branch - Branch management, creation, deletion, listing

💻 System Operations (3 Tools)

• system_info - CPU, memory, disk, network, OS information
• list_processes - Show running processes with resource usage
• kill_process - Terminate processes by PID or name

🗄️ Database Operations (1 Tool)

• database_query - Execute SQL queries on SQLite databases

🖼️ Image Processing (1 Tool)

• image_process - Resize, crop, rotate, convert image formats

📄 PDF Manipulation (1 Tool)

• pdf_manipulate - Extract text, get info, merge, split PDFs

🔐 Encryption & Security (1 Tool)

• encrypt_decrypt - AES-256 encryption, hashing (SHA-256/512, MD5), key generation

⏰ Task Scheduling (1 Tool)

• schedule_task - Schedule commands with cron/Windows Task Scheduler

📢 Notifications (1 Tool)

• send_notification - System notifications, webhooks, email alerts

📝 Text Processing (1 Tool)

• text_process - Analyze, transform, extract patterns, compare, generate text

📊 Data Processing (2 Tools)

• csv_process - Read, write, transform, analyze, filter, merge, split CSV files
• json_process - Parse, validate, transform, merge, extract, minify, prettify JSON

🕷️ Web Scraping (1 Tool)

• web_scrape - Fetch HTML, extract elements, links, images, text, metadata

🐳 Docker Management (1 Tool)

• docker_manage - Manage containers, images, networks, volumes, logs, exec

☁️ Cloud Storage (1 Tool)

• cloud_storage - Upload, download, list, delete files on AWS S3, GCP, Azure

📦 Package Management (1 Tool)

• package_manager - Install, uninstall, update packages with npm, yarn, pip, composer, gem, cargo, go

🎨 Code Formatting (1 Tool)

• code_format - Format, lint, analyze, fix code with prettier, eslint, black, etc.

💡 Example Commands

Development Workflow

"Search for all TODO comments in TypeScript files"
"Show git status and list all modified files"
"Format all JavaScript files with prettier"
"Create a ZIP archive of the src folder"
"Run npm install and build the project"

System Administration

"Show system information including CPU and memory usage"
"List all processes using more than 100MB of memory"
"Schedule a daily backup at 2 AM"
"Send a notification when the deployment completes"
"Kill the process using port 3000"

Data & Content Processing

"Query the database for all users created this month"
"Resize all images in this folder to 800x600"
"Extract text from this PDF and save to a file"
"Analyze this CSV file and show statistics"
"Scrape product data from this website"

Cloud & DevOps

"Upload build artifacts to AWS S3"
"List all running Docker containers"
"Install dependencies with npm and pip"
"Make a POST request to the API with this data"
"Encrypt sensitive files with AES-256"

🔒 Security

Sandboxing

All file operations are strictly sandboxed to the MCP_WORKSPACE_ROOT directory:

✅ Allowed:

read_file("src/index.ts")
write_file("output/data.json", content)

❌ Blocked:

read_file("../../../etc/passwd")
read_file("/etc/passwd")
write_file("C:\\Windows\\System32\\file.txt", content)

Protection Mechanisms

1. Path Resolution: All paths resolved to absolute paths and validated
2. Boundary Checking: Resolved paths must start with workspace root
3. Traversal Detection: ../ sequences that escape workspace are blocked
4. Absolute Path Blocking: Absolute paths outside workspace rejected
5. Symbolic Link Resolution: Symlinks resolved and validated
6. Command Allowlist: Only explicitly allowed commands can execute
7. Argument Safety: Command arguments passed as arrays (no shell injection)

Best Practices

• ✅ Use a dedicated workspace directory for AI operations
• ✅ Only allow commands you trust
• ✅ Use read-only mode for code review/analysis
• ✅ Regularly review what the AI is doing
• ✅ Keep the workspace separate from system directories
• ❌ Don't set workspace root to / or C:\
• ❌ Don't allow dangerous commands like rm, del, format

🧪 Testing

The project includes comprehensive test coverage:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

Test Structure

• Unit Tests: Test individual functions and modules (26 tests)
• Property-Based Tests: Use fast-check to verify properties across random inputs (83 tests)
• Integration Tests: Test full MCP protocol communication

All 109 tests validate the correctness properties defined in the design specification.

🐛 Troubleshooting

Server Won't Start

Problem: Claude/Cline shows connection errors

Solutions:

1. Verify Node.js is installed: node --version (should be 18+)
2. Check the server path in config is correct and absolute
3. Ensure the project is built: npm run build
4. Check that dist/index.js exists

Security Errors

Problem: "Path outside workspace" errors

Solutions:

1. Ensure MCP_WORKSPACE_ROOT is an absolute path
2. Use relative paths in requests (no leading /)
3. Avoid ../ to navigate outside workspace
4. Check for symbolic links pointing outside workspace

Command Not Allowed

Problem: "Command not allowed" errors

Solutions:

1. Add command to MCP_ALLOWED_COMMANDS: "npm,git,python"
2. Use only the command name, not full path
3. Ensure commands are comma-separated without spaces

Command Timeout

Problem: Commands killed before completing

Solutions:

1. Increase MCP_COMMAND_TIMEOUT (value in milliseconds)
2. For long builds: "MCP_COMMAND_TIMEOUT": "1800000" (30 min)
3. Check if command is actually hanging

File Not Found

Problem: AI can't find files that exist

Solutions:

1. Verify MCP_WORKSPACE_ROOT points to correct directory
2. Use relative paths from workspace root
3. Check file actually exists: ls or dir in workspace

JSON Parse Error (Claude Desktop)

Problem: "Could not load app settings" or "invalid JSON"

Solutions:

1. Validate JSON syntax at jsonlint.com
2. Ensure all paths use double backslashes on Windows: C:\\Users\\...
3. Check for trailing commas (not allowed in JSON)
4. Verify file encoding is UTF-8 without BOM

📚 Environment Variables Reference

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork the repository
2. Clone your fork
3. Install dependencies: npm install
4. Make your changes
5. Run tests: npm test
6. Build: npm run build
7. Submit a PR

Guidelines

• Ensure all tests pass
• Add tests for new features
• Follow TypeScript strict mode
• Update documentation as needed

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Built following the Model Context Protocol specification
• Tested with fast-check for property-based testing
• Inspired by the need for secure AI-filesystem interaction

📞 Support

• Issues: GitHub Issues

⭐ If you find this project useful, please consider giving it a star on GitHub!