🏆 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)

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:

2. Workspace Root Directory (Required)

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)

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):

Logging Level

Control how much logging you see:

Command Timeout

Set maximum time for commands (in milliseconds):

📋 Complete Configuration Examples

Example 1: Web Development Project

Example 2: Python Data Science Project

Example 3: Read-Only Code Review

Example 4: Multiple Workspaces

You can configure multiple MCP servers for different projects:

🛠️ 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

System Administration

Data & Content Processing

Cloud & DevOps

🔒 Security

Sandboxing

All file operations are strictly sandboxed to the MCP_WORKSPACE_ROOT directory:

✅ Allowed:

❌ Blocked:

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:

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 LICENSE 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!