🚀 Workspace MCP 🛠️

The ultimate local filesystem bridge for Claude Desktop & Claude Code! ⚡ Stop losing code to token limits — let Claude design, scaffold, build, and save full-stack software projects directly on your hard drive! 📁💻

---

🎯 Overview: Solving Claude's Token Limits 🛑

When using Claude to build multi-file projects, developers frequently run into output token limits and context window cutoffs:

1. ⚠️ Truncated File Outputs: Claude hits completion token limits mid-file, cutting off output and forcing you to repeatedly ask it to continue.
2. 🔄 Lost Progress: When a conversation gets too long or expires, un-saved code in the chat window disappears unless manually copy-pasted into your editor.
3. 🚫 No Direct Disk Access: Standard web and desktop chats cannot write files directly to your local computer.

🪄 How Workspace MCP Helps 🌟

Workspace MCP connects Claude directly to your local filesystem:

• 💾 Incremental Local Disk Saves: Every file and folder is saved immediately as Claude works. If Claude hits an output token limit on a long response, everything written up to that point remains 100% safely stored on disk.
• 🔁 Resuming Work: In a new chat prompt, simply ask Claude to read your project files and pick up right where it left off using read_file, find_text, or update_file.
• 📝 Automatic Work Logs (CLOUD.md): Maintains an architectural work log tracking what was built, key decisions, and next steps for future chat sessions.

---

🧭 Capabilities Guide: What Workspace MCP Does 🛠️

Think of workspace-mcp as providing file and project management hands 🤲 to your AI assistant. The AI handles the reasoning (what code to write and how to structure it); workspace-mcp handles applying those changes directly to disk in a clean, organized folder layout.

🎨 The 4 Main Tool Categories

Category	Description
🗂️ Project & Folder Management	Create, rename, or remove project roots and subdirectories.
📄 File Operations	Create, read, edit, move, rename, and delete individual files safely.
🔍 Search & Discovery	Find text across files (grep), search by filename patterns (glob), or list directory trees.
📊 Auto-Documentation	Automatically generate README.md, PROJECT_TREE.md, and CLOUD.md work logs.

---

🗂️ 1. Project & Folder Management

• create_project 🏗️ — Initializes a project directory with a default scaffold.
• create_directory 📁 — Creates subfolders (e.g. src/, docs/) and missing parent folders automatically.
• rename_project ✏️ — Moves or renames an entire project directory.
• delete_directory 🗑️ — Recursively deletes a folder (requires explicit confirm=true).
• delete_project 💥 — Permanently removes an entire project directory (requires confirm=true).

💡 Tip: Always start a new application with create_project to keep files scoped inside a dedicated folder!

---

📄 2. File Operations

• create_file ✨ — Creates a new file with content (fails if the file already exists to prevent accidental overwrites).
• write_file 📝 — Overwrites a file completely or creates it if missing (requires confirm=true if overwriting).
• update_file 🔧 — Performs targeted string edits (find/replace) on existing files without replacing the entire file.
• append_file ➕ — Appends text to the end of a file without touching existing content.
• read_file 📖 — Reads a file's full UTF-8 text content.
• move_file 🚚 — Relocates a file to another directory.
• rename_file 🏷️ — Renames a file within its current folder.
• delete_file ❌ — Deletes a single file (requires confirm=true).

💡 Tip: Use create_file for brand new files, update_file for inline edits, and write_file when replacing an entire file!

---

🔍 3. Search & Discovery

• find_text 🔎 — Grep-like search across text files for literal strings (e.g. finding TODO comments or function usages).
• search_files 🎯 — Glob search for files matching a pattern (e.g. **/*.py or *.ts).
• list_directory 📋 — Lists files and subdirectories with sizes and metadata.

💡 Tip: Use search_files when looking for file types or names, and find_text when searching for specific code text across your project!

---

📊 4. Auto-Documentation & Validation

• generate_readme 📘 — Creates or updates a structured README.md.
• generate_project_tree 🌴 — Saves an ASCII visual tree map to PROJECT_TREE.md.
• project_tree 👁️ — Returns an ASCII visual tree in the tool response without saving to disk.
• generate_cloud_log ☁️ — Writes CLOUD.md documenting what was built and why.
• validate_workspace 🏥 — Checks workspace health, server configuration, and limits.
• validate_path 🛡️ — Verifies if a path is safe and valid before performing file operations.

---

🔄 Typical Workflow

1. create_project        🏗️ → Initialize project directory
2. create_directory      📁 → Scaffold subfolders (src/, docs/)
3. create_file           ✨ → Write initial source files
4. update_file           🔧 → Edit and refine code incrementally
5. find_text/search_files🔎 → Locate references or check for TODOs
6. move_file/rename_file 🚚 → Organize file structure
7. generate_project_tree 🌴 → Save project tree map
8. generate_readme       📘 → Document setup and usage
9. generate_cloud_log    ☁️ → Save AI work log
10. validate_workspace   🏥 → Verify workspace state

---

🔌 Connecting to Claude Desktop 🤖

Claude Desktop manages MCP servers via its configuration file. Using uv allows Claude Desktop to run workspace-mcp automatically in the background without needing to start a server manually! ⚡

📂 Step 1: Locate claude_desktop_config.json

OS	Config Path
Windows 🪟	%APPDATA%\Claude\claude_desktop_config.json
macOS 🍎	~/Library/Application Support/Claude/claude_desktop_config.json
Linux 🐧	~/.config/Claude/claude_desktop_config.json

⚙️ Step 2: Add Configuration

Add the following to your claude_desktop_config.json. Update the paths to point to your local installation of workspace-mcp and your desired --workspace-root directory:

Windows 🪟

{
  "mcpServers": {
    "workspace-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/YourUsername/mcp/servers/workspace-mcp",
        "run",
        "workspace-mcp",
        "--workspace-root",
        "C:/Users/YourUsername/AIProjects"
      ]
    }
  }
}

macOS 🍎 / Linux 🐧

{
  "mcpServers": {
    "workspace-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/user/workspace-mcp",
        "run",
        "workspace-mcp",
        "--workspace-root",
        "/home/user/AIProjects"
      ]
    }
  }
}

💡 Note: Requires uv to be installed on your system PATH.

🔄 Step 3: Restart Claude Desktop 🔨

1. Fully close Claude Desktop (from system tray or menu bar).
2. Re-open Claude Desktop.
3. Click the hammer icon (🔨) in the chat bar to confirm that the workspace-mcp tools are active! 🎉

---

🎮 Usage & Master Prompt 👑

🌟 Comprehensive Master Prompt

Copy and paste this prompt into Claude Desktop to test all tool capabilities at once:

Using the workspace MCP, create a new project called [project-name]. Set up the following structure: create a src/ directory, add starter files inside it ([file1], [file2]), and create a top-level README.md and .gitignore.

Once the files exist, append a notes section to the README, then update [file1] with the core logic for [feature].

Search the project for any TODO or FIXME comments using find_text. Find all files matching *.[ext] using search_files.

Rename [file2] to [new-name], then move it into a new docs/ directory.

Generate the project tree, generate a proper README, and generate a CLOUD.md log summarizing what was built.

Finally, validate the workspace configuration, and list the contents of the project root to confirm everything is in place.

⚡ Resuming Work After Token Limits

If Claude hits a completion limit mid-task:

1. Open a new chat session.
2. Prompt Claude:

   "Check the files in MyProject/src, review CLOUD.md to see what was built so far, and finish implementing the main module."

3. Claude will use list_directory, read_file, and update_file to continue development seamlessly! 🚀

---

🛡️ Security Sandbox Architecture 🔒

Workspace MCP strictly isolates all operations to the configured --workspace-root:

Claude Desktop (Client 🤖)
       │
       ▼ Stdio Transport ⚡
Workspace MCP Server 🖥️
       │
       ▼
  Service Layer ⚙️ ──► PathValidator (os.path.realpath Sandbox 🛡️)
                               │
                               ▼
                     Sandboxed Workspace Root 📁

• 🛡️ Path Security: All input paths are resolved using os.path.realpath / Path.resolve(strict=False) to prevent .. path traversal sequences and symlink escapes.
• 🚫 Reserved Names: Windows reserved filenames (CON, NUL, AUX, COM1-9) are rejected to preserve cross-platform compatibility.
• 🔐 Confirmation Gating: Destructive actions (delete_file, delete_directory, file overwrites) require explicit confirmation flags (confirm=true / overwrite=true).
• 📜 Audit Logs: Operations are logged to both operations.jsonl (machine-readable) and operations.log (human-readable text).

---

🧰 Tool Reference 📦

Category	Tool	Description
Project 🏗️	create_project	Scaffolds directory structure + .gitignore, Dockerfile, README.md, CLOUD.md
	delete_project	Removes project folder (requires confirm=true)
	rename_project	Renames or relocates a project directory
Directory 📁	create_directory	Creates subdirectories (including missing parents)
	delete_directory	Deletes directory recursively (requires confirm=true)
	list_directory	Lists directory files and metadata
File 📄	create_file	Creates a new file
	read_file	Reads UTF-8 text file content
	write_file	Overwrites file content (requires confirm=true)
	append_file	Appends text to end of file
	update_file	Performs find/replace string substitution or partial update
	move_file / rename_file	Relocates or renames a file
	delete_file	Deletes a file (requires confirm=true)
Search 🔍	search_files	Glob search for matching filenames
	find_text	Grep-like search across text files
	project_tree	Generates ASCII project tree string
Docs 📘	generate_readme	Creates/updates README.md
	generate_cloud_log	Creates CLOUD.md work log
	generate_project_tree	Saves PROJECT_TREE.md to disk
Validation 🏥	validate_workspace	Returns server health and settings
	validate_path	Validates relative path safety without modifying disk

---

⚙️ Configuration Reference 🔧

Settings can be specified via command-line flags or environment variables (WORKSPACE_MCP_*):

Option	Environment Variable	Default	Description
--workspace-root	WORKSPACE_MCP_WORKSPACE_ROOT	./workspace	Base sandboxed directory for all operations
--config	WORKSPACE_MCP_CONFIG	None	Path to YAML/JSON configuration file
max_file_size_bytes	WORKSPACE_MCP_MAX_FILE_SIZE_BYTES	10485760 (10MB)	File size write limit
require_overwrite_confirmation	WORKSPACE_MCP_REQUIRE_OVERWRITE_CONFIRMATION	true	Enforces confirmation on file overwrite/delete

---

📜 License ⚖️

Distributed under the MIT License.