MCP Workspace Server

A secure, sandboxed Model Context Protocol (MCP) server that gives LLMs like Claude, ChatGPT, and local models (via Ollama) controlled file system access to build and manage projects.

🌟 Features

• 🔒 Secure Sandboxing: All file operations strictly confined to a designated workspace directory

• 📁 Complete File Operations: Read, write, list, delete files and directories

• 🔧 Command Execution: Run allowed build and test commands (npm, git, etc.)

• 🛡️ Path Traversal Protection: Comprehensive security against directory escape attempts

• 🔄 Atomic Operations: Safe file writes that prevent partial updates

• 📝 Patch Support: Apply targeted file modifications without rewriting entire files

• 🚫 Read-Only Mode: Optional mode to prevent any write operations

• 📊 Structured Logging: Configurable logging for debugging and monitoring

• ✅ Fully Tested: 109 passing tests including property-based tests

📋 Table of Contents

• Installation

• Quick Start

• Configuration Guide

• Usage with Different AI Clients

• 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/YOUR_USERNAME/mcp-workspace-server.git cd mcp-workspace-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/mcp-workspace-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'"

For Cline (VS Code) Users

1. Install Cline extension from VS Code marketplace

2. Open VS Code Settings (Ctrl+, or Cmd+,)

3. Search for "Cline" and find "MCP Servers" section

4. Add this configuration (or edit settings.json):

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

5. Reload VS Code and start using Cline!

⚙️ 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\\mcp-workspace-server\\dist\\index.js"

• macOS/Linux: "/home/username/path/to/mcp-workspace-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:

🤖 Usage with Different AI Clients

Claude Desktop

• Best for: General use, easiest setup

• Supports: Claude models only

• Config location: See Quick Start

Cline (VS Code Extension)

• Best for: Coding workflows, integrated development

• Supports: Claude, OpenAI, Ollama, and more

• Config location: VS Code Settings → Cline → MCP Servers

Open WebUI

• Best for: Web-based interface with Ollama

• Supports: Ollama models

• Setup: Configure in Open WebUI settings under MCP/Tools section

Custom Integration

You can integrate this server with any MCP-compatible client. The server communicates via stdio using the MCP protocol.

🛠️ Available Tools

The server exposes these tools to AI clients:

list_files

List files and directories in the workspace.

Parameters:

• path (optional): Relative path to list

• recursive (optional): Include nested directories

Example:

read_file

Read the contents of a file.

Parameters:

• path (required): Relative path to the file

Example:

write_file

Create or overwrite a file.

Parameters:

• path (required): Relative path for the file

• content (required): File content

• createDirectories (optional): Create parent directories

Example:

delete_file

Delete a file or empty directory.

Parameters:

• path (required): Relative path to delete

Example:

create_folder

Create a directory and its parents.

Parameters:

• path (required): Relative path for the directory

Example:

apply_patch

Apply a patch to modify an existing file.

Parameters:

• path (required): Relative path to the file

• patch (required): Patch in custom format

Patch Format:

Example:

run_command

Execute an allowed command.

Parameters:

• command (required): Command name (must be in allowed list)

• args (optional): Command arguments

• cwd (optional): Working directory

• timeoutMs (optional): Timeout override

Example:

🔒 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

• Discussions: GitHub Discussions

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