内容
# 🚀 工作空间 MCP 🛠️
> **适用于 Claude Desktop 和 Claude Code 的终极本地文件系统桥接！** ⚡ 停止因令牌限制而丢失代码 — 让 Claude 直接在您的硬盘上设计、搭建、构建和保存全栈软件项目！ 📁💻
[](https://www.python.org/)
[](LICENSE)
[](https://modelcontextprotocol.io)
---
## 🎯 概述：解决 Claude 的令牌限制 🛑
在使用 Claude 构建多文件项目时，开发人员经常遇到 **输出令牌限制** 和 **上下文窗口截断**：
1. ⚠️ **文件输出截断**：Claude 在文件中间达到完成令牌限制，截断输出，迫使您反复要求它继续。
2. 🔄 **进度丢失**：当对话太长或过期时，聊天窗口中未保存的代码消失，除非手动复制粘贴到编辑器中。
3. 🚫 **无直接磁盘访问**：标准网络和桌面聊天无法直接向本地计算机写入文件。
### 🪄 工作空间 MCP 如何帮助 🌟
工作空间 MCP 直接连接到 Claude 的本地文件系统：
- 💾 **增量本地磁盘保存**：Claude 工作时，每个文件和文件夹都会立即保存。如果 Claude 在长响应中达到输出令牌限制，直到该点为止的所有内容都将 100% 安全地存储在磁盘上。
- 🔁 **恢复工作**：在新的聊天提示中，只需要求 Claude 读取您的项目文件，并使用 `read_file`、`find_text` 或 `update_file` 继续工作。
- 📝 **自动工作日志（`CLOUD.md`）**：维护一个架构工作日志，跟踪已构建的内容、关键决策和未来聊天会话的下一步骤。
---
## 🧭 功能指南：工作空间 MCP 的功能 🛠️
将 `workspace-mcp` 视为为您的 AI 助手提供 **文件和项目管理** 的功能。AI 处理推理（编写代码和结构）；`workspace-mcp` 处理将这些更改直接应用于磁盘，以干净、有序的文件夹布局。
### 🎨 4 大工具类别
| 类别 | 描述 |
|---|---|
| 🗂️ **项目和文件夹管理** | 创建、重命名或删除项目根目录和子目录。 |
| 📄 **文件操作** | 创建、读取、编辑、移动、重命名和安全删除单个文件。 |
| 🔍 **搜索和发现** | 跨文件查找文本（`grep`）、按文件名模式搜索（`glob`）或列出目录树。 |
| 📊 **自动文档** | 自动生成 `README.md`、`PROJECT_TREE.md` 和 `CLOUD.md` 工作日志。 |
---
### 🗂️ 1. 项目和文件夹管理
- `create_project` 🏗️ — 初始化具有默认脚手架的项目目录。
- `create_directory` 📁 — 创建子文件夹（例如 `src/`、`docs/`）和缺失的父文件夹。
- `rename_project` ✏️ — 移动或重命名整个项目目录。
- `delete_directory` 🗑️ — 递归删除文件夹（需要明确的 `confirm=true`）。
- `delete_project` 💥 — 永久删除整个项目目录（需要 `confirm=true`）。
*💡 提示：* 始终使用 `create_project` 启动新应用程序，以保持文件在专用文件夹内！
---
### 📄 2. 文件操作
- `create_file` ✨ — 创建具有内容的新文件（如果文件已存在则失败，以防止意外覆盖）。
- `write_file` 📝 — 覆盖文件或创建它（如果丢失）（需要 `confirm=true` 如果覆盖）。
- `update_file` 🔧 — 对现有文件执行有针对性的字符串编辑（`find`/`replace`）而无需替换整个文件。
- `append_file` ➕ — 在不触及现有内容的情况下，将文本追加到文件末尾。
- `read_file` 📖 — 读取文件的完整 UTF-8 文本内容。
- `move_file` 🚚 — 将文件移动到另一个目录。
- `rename_file` 🏷️ — 在当前文件夹中重命名文件。
- `delete_file` ❌ — 删除单个文件（需要 `confirm=true`）。
*💡 提示：* 使用 `create_file` 创建新文件，使用 `update_file` 进行内联编辑，使用 `write_file` 替换整个文件！
---
### 🔍 3. 搜索和发现
- `find_text` 🔎 — 跨文本文件搜索字面字符串（例如查找 `TODO` 评论或函数用法）。
- `search_files` 🎯 — 搜索匹配模式的文件（例如 `**/*.py` 或 `*.ts`）。
- `list_directory` 📋 — 列出具有大小和元数据的文件和子目录。
*💡 提示：* 使用 `search_files` 查找文件类型或名称，使用 `find_text` 查找特定代码文本！
---
### 📊 4. 自动文档和验证
- `generate_readme` 📘 — 创建或更新结构化的 `README.md`。
- `generate_project_tree` 🌴 — 将 ASCII 视觉树图保存到 `PROJECT_TREE.md`。
- `project_tree` 👁️ — 在工具响应中返回 ASCII 视觉树图，而不保存到磁盘。
- `generate_cloud_log` ☁️ — 编写 `CLOUD.md` 文档，记录已构建的内容和原因。
- `validate_workspace` 🏥 — 检查工作空间健康状况、服务器配置和限制。
- `validate_path` 🛡️ — 验证路径是否安全有效，然后再进行文件操作。
---
### 🔄 典型工作流程
```text
1. create_project 🏗️ → 初始化项目目录
2. create_directory 📁 → 脚手架子文件夹（src/, docs/）
3. create_file ✨ → 编写初始源文件
4. update_file 🔧 → 编辑和改进代码
5. find_text/search_files🔎 → 查找引用或检查 TODO
6. move_file/rename_file 🚚 → 组织文件结构
7. generate_project_tree 🌴 → 保存项目树图
8. generate_readme 📘 → 文档设置和使用
9. generate_cloud_log ☁️ → 保存 AI 工作日志
10. validate_workspace 🏥 → 验证工作空间状态
```
---
## 🔌 连接到 Claude Desktop 🤖
Claude Desktop 通过其配置文件管理 MCP 服务器。使用 `uv` 允许 Claude Desktop 在后台自动运行 `workspace-mcp`，无需手动启动服务器！ ⚡
### 📂 步骤 1：定位 `claude_desktop_config.json`
| 操作系统 | 配置路径 |
| --- | --- |
| **Windows 🪟** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **macOS 🍎** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Linux 🐧** | `~/.config/Claude/claude_desktop_config.json` |
### ⚙️ 步骤 2：添加配置
将以下内容添加到您的 `claude_desktop_config.json`。更新路径以指向您的 `workspace-mcp` 本地安装和您期望的 `--workspace-root` 目录：
#### Windows 🪟
```json
{
"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 🐧
```json
{
"mcpServers": {
"workspace-mcp": {
"command": "uv",
"args": [
"--directory",
"/home/user/workspace-mcp",
"run",
"workspace-mcp",
"--workspace-root",
"/home/user/AIProjects"
]
}
}
}
```
*💡 注意：* 需要在系统 PATH 上安装 [`uv`](https://github.com/astral-sh/uv)。
### 🔄 步骤 3：重启 Claude Desktop 🔨
1. 完全关闭 Claude Desktop（从系统托盘或菜单栏）。
2. 重新打开 Claude Desktop。
3. 点击聊天栏中的锤子图标（🔨）以确认 **workspace-mcp** 工具处于活动状态！ 🎉
---
## 🎮 用例和主提示 👑
### 🌟 综合主提示
复制并粘贴此提示到 Claude Desktop 中，一次测试所有工具功能：
```text
使用工作空间 MCP，创建一个名为 [项目名称] 的新项目。设置以下结构：创建一个 src/ 目录，在其中添加启动文件（[file1]，[file2]），并创建一个顶级 README.md 和 .gitignore。
文件存在后，在 README 中追加一个注释部分，然后使用 [file1] 更新 [功能] 的核心逻辑。
使用 find_text 在项目中搜索任何 TODO 或 FIXME 评论。使用 search_files 查找匹配 *.[ext] 的所有文件。
将 [file2] 重命名为 [新名称]，然后将其移动到新的 docs/ 目录中。
生成项目树，生成适当的 README，并生成一个 CLOUD.md 日志，总结已构建的内容。
最后，验证工作空间配置，并列出项目根目录的内容以确认所有内容都已就位。
```
### ⚡ 在令牌限制后恢复工作
如果 Claude 在任务中途达到完成限制：
1. 打开新的聊天会话。
2. 提示 Claude：
> "检查 `MyProject/src` 中的文件，查看 `CLOUD.md` 以了解到目前为止已构建的内容，然后继续实现主模块。"
3. Claude 将使用 `list_directory`、`read_file` 和 `update_file` 无缝继续开发！ 🚀
---
## 🛡️ 安全沙箱架构 🔒
工作空间 MCP 严格将所有操作隔离到配置的 `--workspace-root`：
```
Claude Desktop (客户端 🤖)
│
▼ 标准输入/输出传输 ⚡
工作空间 MCP 服务器 🖥️
│
▼
服务层 ⚙️ ──► 路径验证器（os.path.realpath 沙箱 🛡️）
│
▼
沙箱工作空间根目录 📁
```
- 🛡️ **路径安全**：所有输入路径都使用 `os.path.realpath` / `Path.resolve(strict=False)` 进行解析，以防止 `..` 路径遍历序列和符号链接逃逸。
- 🚫 **保留名称**：拒绝 Windows 保留文件名（`CON`、`NUL`、`AUX`、`COM1-9`）以保持跨平台兼容性。
- 🔐 **确认门控**：破坏性操作（`delete_file`、`delete_directory`、文件覆盖）需要明确的确认标志（`confirm=true` / `overwrite=true`）。
- 📜 **审计日志**：操作记录到 `operations.jsonl`（机器可读）和 `operations.log`（人类可读文本）。
---
## 🧰 工具参考 📦
| 类别 | 工具 | 描述 |
| --- | --- | --- |
| **项目 🏗️** | `create_project` | 脚手架目录结构 + `.gitignore`、`Dockerfile`、`README.md`、`CLOUD.md` |
| | `delete_project` | 删除项目文件夹（需要 `confirm=true`） |
| | `rename_project` | 重命名或重新定位项目目录 |
| **目录 📁** | `create_directory` | 创建子目录（包括缺失的父目录） |
| | `delete_directory` | 递归删除目录（需要 `confirm=true`） |
| | `list_directory` | 列出目录文件和元数据 |
| **文件 📄** | `create_file` | 创建新文件 |
| | `read_file` | 读取 UTF-8 文本文件内容 |
| | `write_file` | 覆盖文件内容（需要 `confirm=true`） |
| | `append_file` | 在文件末尾追加文本 |
| | `update_file` | 执行 `find`/`replace` 字符串替换或部分更新 |
| | `move_file` / `rename_file` | 重新定位或重命名文件 |
| | `delete_file` | 删除文件（需要 `confirm=true`） |
| **搜索 🔍** | `search_files` | 搜索匹配文件名的文件 |
| | `find_text` | 跨文本文件搜索类似 grep |
| | `project_tree` | 生成 ASCII 项目树字符串 |
| **文档 📘** | `generate_readme` | 创建/更新 `README.md` |
| | `generate_cloud_log` | 创建 `CLOUD.md` 工作日志 |
| | `generate_project_tree` | 将 `PROJECT_TREE.md` 保存到磁盘 |
| **验证 🏥** | `validate_workspace` | 返回服务器健康状态和设置 |
| | `validate_path` | 验证相对路径安全性而不修改磁盘 |
---
## ⚙️ 配置参考 🔧
设置可以通过命令行标志或环境变量 (`WORKSPACE_MCP_*`) 指定：
| 选项 | 环境变量 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `--workspace-root` | `WORKSPACE_MCP_WORKSPACE_ROOT` | `./workspace` | 所有操作的基于沙箱的目录 |
| `--config` | `WORKSPACE_MCP_CONFIG` | `None` | YAML/JSON 配置文件路径 |
| `max_file_size_bytes` | `WORKSPACE_MCP_MAX_FILE_SIZE_BYTES` | `10485760` (10MB) | 文件大小写入限制 |
| `require_overwrite_confirmation` | `WORKSPACE_MCP_REQUIRE_OVERWRITE_CONFIRMATION` | `true` | 强制文件覆盖/删除确认 |
---
## 📜 许可证 ⚖️
在 [MIT License](LICENSE) 下分发。
