MCP Workspace Server

English | 中文

🚀 只需一个 MCP，就能实现你的完整 Agent 能力！

超越文件系统的 AI 开发环境 - 让 AI 像 Claude Code 一样进行完整的 Web 开发、数据处理和代码执行

💡 核心价值：无需集成多个 MCP 工具，一个 MCP 服务器即可提供文件操作、代码执行、Web 部署、数据处理、图像生成等完整的 Agent 能力。开箱即用，一站式解决方案。

一个功能强大的 MCP (Model Context Protocol) 服务器，不仅提供安全的文件系统操作，更是一个完整的 AI 开发工作空间。支持代码执行、Web 应用一键部署、泛域名访问、Excel 处理、图像生成等企业级能力。

✨ 为什么选择我们？

🎯 一个 MCP，完整 Agent 能力

传统方案：需要集成多个 MCP 工具才能实现完整功能

❌ 文件操作 → 需要一个 MCP
❌ 代码执行 → 需要另一个 MCP
❌ Web 部署 → 需要第三个 MCP
❌ 数据处理 → 需要第四个 MCP
❌ 图像生成 → 需要第五个 MCP
结果：配置复杂、维护困难、功能分散

我们的方案：只需一个 MCP，所有能力开箱即用

✅ 文件操作 + 代码执行 + Web 部署 + 数据处理 + 图像生成
✅ 统一配置：一次配置，全部启用
✅ 统一管理：一个服务，集中管理
✅ 统一安全：一套安全策略，全面保护

我们提供的是完整的 AI 开发工作空间，能力远超传统文件系统服务器：

🚀 Web 开发能力：AI 可以创建完整的 Web 应用（HTML/CSS/JS），并一键部署到生产环境
🌐 泛域名部署：支持 *.your-domain.com 泛域名，每个会话自动获得独立子域名访问
💻 代码执行：内置 Python 3.12 和 Node.js 20 沙盒环境，支持代码实时执行和调试
📊 数据处理：完整的 Excel/CSV 处理能力，支持模板、公式、格式化
🎨 图像生成：支持 Mermaid 流程图、数据图表、HTML 渲染等多种图像生成方式
🔍 智能搜索：文件内容搜索、知识库检索、网页抓取等高级能力
🔐 企业级安全：多租户隔离、路径安全防护、资源限制、沙盒执行

🎁 All-in-One 优势

传统方案	我们的方案
需要 5+ 个 MCP 工具	只需 1 个 MCP
配置复杂，需要逐个集成	开箱即用，一键配置
功能分散，难以统一管理	功能集中，统一管理
安全策略不统一	统一安全策略
维护成本高	维护简单

一句话总结：一个 MCP 服务器 = 完整的 Agent 能力栈 🚀

💡 典型使用场景

场景 1：AI 驱动的 Web 开发

AI 创建完整的前端应用 → 一键部署 → 获得独立域名访问
例如：https://user123_chat456.your-domain.com

场景 2：数据分析与可视化

读取 Excel → 数据处理 → 生成图表 → 创建报告 → 部署展示页面

场景 3：代码开发与测试

编写 Python 脚本 → 执行测试 → 修复 Bug → 部署 API 服务

✨ 核心特性

🔐 多租户会话隔离

每个用户/会话拥有独立的虚拟工作空间，完全隔离，互不干扰。

工作目录命名规则：

X-User-ID	X-Chat-ID	工作目录
`user123`	`chat456`	`user_data/user123_chat456/`
`user123`	(空)	`user_data/user123/`
(空)	`chat456`	`user_data/chat456/`
(空)	(空)	使用默认全局模式

通过 HTTP 请求头传递身份标识：

X-User-ID: 用户唯一标识（可选）
X-Chat-ID: 会话唯一标识（可选）

🛡️ 虚拟路径系统

LLM 视角完全虚拟化：AI 模型看到的是一个干净的虚拟文件系统，以 / 为根目录。

LLM 看到的路径          实际物理路径
─────────────────────────────────────────────────────────
/                    → /server/user_data/user123_chat456/
/todo.txt            → /server/user_data/user123_chat456/todo.txt
/docs/readme.md      → /server/user_data/user123_chat456/docs/readme.md

优势：

✅ 不暴露服务器真实目录结构
✅ AI 平台无法获知物理路径信息
✅ 简化 AI 的文件操作指令
✅ 提升安全性和隐私保护

🔒 路径安全防护

内置多层安全机制，防止路径遍历攻击：

攻击尝试                              结果
─────────────────────────────────────────────────
/../../../etc/passwd                 ❌ 被阻止
../../../etc/passwd                  ❌ 被阻止  
/foo/../../../etc/passwd             ❌ 被阻止
/foo/bar/../../..                    ❌ 被阻止

安全机制：

路径解析：使用 Path.resolve() 解析所有 .. 和符号链接
边界检查：验证解析后的路径是否在允许范围内
双重保护：即使路径被解析，仍必须在 allowed_dirs 内

📡 SSE 传输协议

支持 Server-Sent Events (SSE) 传输，适配各类 AI 平台：

客户端                                服务器
   │                                    │
   │──── GET /sse ──────────────────────▶│  建立 SSE 连接
   │◀─── SSE: endpoint=/messages?sid=xxx │  返回消息端点
   │                                    │
   │──── POST /messages?session_id=xxx ─▶│  发送工具调用
   │◀─── SSE: message (响应) ───────────│  接收结果

🌐 一键部署与泛域名支持

一键部署 Web 应用：

AI 创建的前端项目可通过 preview_frontend 工具一键部署
自动生成可访问的 URL，支持 HTTPS
支持自定义入口文件和目录结构

泛域名部署（生产环境）：

{
  "preview": {
    "wildcard_domain": "*.proxy.your-domain.com",
    "use_tls": true
  }
}

配置后，每个会话自动获得独立子域名：

user123_chat456.proxy.your-domain.com
user789_chat012.proxy.your-domain.com

优势：

✅ 无需手动配置域名和端口
✅ 自动隔离，互不干扰
✅ 支持 HTTPS，生产就绪
✅ 单端口服务，简化部署

📦 完整功能列表

💻 Web 开发与部署

工具	功能	亮点
`fs_write`	创建 Web 文件（HTML/CSS/JS）	自动识别格式，支持完整前端项目
`preview_frontend`	一键部署静态前端	支持泛域名，自动生成独立子域名
`exec`	执行 Python/Node.js 代码	沙盒环境，支持实时调试
`generate_image`	生成图表和流程图	Mermaid、数据可视化、HTML 渲染

📁 文件系统操作

工具	功能
`fs_read`	读取文件（支持批量、Excel、行范围）
`fs_write`	创建/覆盖文件（自动识别格式）
`fs_ops`	文件系统操作（list/mkdir/move/info/delete）
`fs_replace`	基于 SEARCH/REPLACE 精确编辑文件
`fs_search`	搜索文件（glob=按文件名，content=按内容正则）

📊 Excel 数据处理

工具	功能
`fs_read`	读取 Excel 文件（支持 sheet、range 参数）
`fs_write`	创建/覆盖 Excel 文件（自动识别格式）
`excel_edit`	编辑 Excel（批量更新单元格、格式化）
`list_excel_templates`	列出可用 Excel 模板
`create_excel_from_template`	从模板创建 Excel 文件

🔍 高级能力（可选）

工具	功能	配置项
`kb_search`	企业知识库 glob 搜索	`kb.enabled=true`
`kb_read`	读取知识库文件（返回 Markdown）	`kb.enabled=true`
`crawl_url`	抓取网页并返回 Markdown	`web_crawl.enabled=true`
`web_search`	联网搜索	`web_search.enabled=true`

🔌 与 AI 平台集成

🎯 为什么选择我们作为你的 MCP Server？

我们是强大的 All-in-One MCP Server，只需一次配置，即可为你的 AI 平台提供完整的 Agent 能力：

✅ 文件操作：读写、搜索、编辑文件
✅ 代码执行：Python/Node.js 沙盒环境
✅ Web 部署：一键部署前端应用，支持泛域名
✅ 数据处理：Excel/CSV 完整处理能力
✅ 图像生成：Mermaid 流程图、数据图表
✅ 智能搜索：知识库检索、网页抓取（可选）

无需集成多个 MCP 工具，一个 MCP Server 即可满足所有需求！

🚀 支持的 AI 平台

我们与主流 AI 平台完美集成，配置简单，开箱即用：

Dify

进入 Dify 工作流配置
- 添加 MCP Tool 节点
- 选择 SSE 传输协议

配置 MCP Server 连接

SSE 地址: http://your-server:8000/sse

设置请求头（多租户隔离）

X-User-ID: {{user_id}}
X-Chat-ID: {{conversation_id}}

完成！ 现在你的 Dify Agent 拥有完整的文件操作、代码执行、Web 部署等能力。

FastGPT

进入 FastGPT 知识库/应用配置
- 添加 外部工具 → MCP
- 传输方式选择 SSE

配置连接信息

MCP Server URL: http://your-server:8000/sse

配置用户标识（可选，用于多租户隔离）

自定义 Header:
X-User-ID: {{userId}}
X-Chat-ID: {{chatId}}

启用工具：所有工具自动可用，无需逐个配置！

Cherry Studio

进入 Cherry Studio 设置
- 打开 MCP Servers 配置
- 添加新的 MCP Server

配置连接

{
  "name": "MCP Workspace Server",
  "transport": "sse",
  "url": "http://your-server:8000/sse"
}

设置会话标识（多租户支持）
- Cherry Studio 会自动传递用户和会话信息
- 每个会话获得独立的工作空间

💡 集成优势

传统方案	使用我们的 All-in-One MCP
需要配置 5+ 个不同的 MCP 工具	只需配置 1 个 MCP Server
每个工具需要单独连接和认证	一次配置，全部启用
工具之间功能分散，难以统一管理	功能集中，统一管理
不同工具的安全策略不一致	统一安全策略，全面保护
维护多个服务的成本高	维护简单，一个服务搞定

🎁 开箱即用的能力

配置完成后，你的 AI Agent 立即拥有：

📝 文件操作：创建、读取、编辑、搜索文件
💻 代码执行：运行 Python/Node.js 脚本，实时调试
🌐 Web 开发：创建前端应用并一键部署到生产环境
📊 数据处理：读取、编辑 Excel，生成报告
🎨 图像生成：创建流程图、数据可视化图表
🔍 智能搜索：文件内容搜索、知识库检索（如启用）

一个 MCP Server = 完整的 Agent 能力栈 🚀

🚀 快速开始

Docker 部署（推荐）

# 克隆项目
git clone <repository-url>
cd mcp-filesystem

# 首次部署：构建镜像并启动
docker-compose up -d --build

> 如果无法使用docker镜像源，可以先执行 export DOCKER_BUILDKIT=0

# 更新代码后重启生效
git pull && docker-compose restart

# 查看日志
docker-compose logs -f

# 仅当依赖变化时需要重新构建
docker-compose up -d --build

💡 镜像包含运行环境，代码通过 volume 挂载，更新代码只需 git pull && docker-compose restart

⚠️ 重要说明：本项目运行环境高度依赖 Docker 基础镜像，包含完整的 Python 3.12、Node.js 20 运行环境以及所有系统依赖（如 Tesseract OCR、图像处理库等）。强烈建议使用 Docker 方式部署，不推荐本地 Python 直接运行。如需本地开发，请确保已安装所有系统依赖。

快速配置参考

📖 详细集成说明：请查看上方的 🔌 与 AI 平台集成章节，包含 Dify、FastGPT、Cherry Studio 的完整配置步骤。

快速连接信息：

SSE 地址: http://your-server:8000/sse
请求头（多租户隔离）:
- X-User-ID: {{userId}} 或固定用户ID
- X-Chat-ID: {{chatId}} 或固定会话ID

Claude Desktop（STDIO 模式）：

编辑配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-workspace": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-filesystem",
        "run",
        "run_server.py",
        "/path/to/allowed/dir1",
        "/path/to/allowed/dir2"
      ]
    }
  }
}

🏗️ 架构设计

┌─────────────────────────────────────────────────────────────┐
│          AI 平台 (Dify / FastGPT / Cherry Studio)           │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ SSE + HTTP POST
                              │ Headers: X-User-ID, X-Chat-ID
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              MCP Workspace Server (All-in-One)               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              会话管理 & 身份识别                       │    │
│  │         (user_id + chat_id → workspace_name)        │    │
│  └─────────────────────────────────────────────────────┘    │
│                              │                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              虚拟路径转换层                           │    │
│  │         /todo.txt → /user_data/xxx/todo.txt         │    │
│  └─────────────────────────────────────────────────────┘    │
│                              │                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              路径安全验证                             │    │
│  │         PathValidator + 路径遍历防护                  │    │
│  └─────────────────────────────────────────────────────┘    │
│                              │                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              文件操作执行                             │    │
│  │         FileOperations / AdvancedFileOperations      │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      物理文件系统                            │
│  user_data/                                                 │
│  ├── user1_chat1/                                           │
│  │   ├── todo.txt                                           │
│  │   └── docs/                                              │
│  ├── user1_chat2/                                           │
│  └── user2_chat1/                                           │
└─────────────────────────────────────────────────────────────┘

🔧 管理员 API

提供 HTTP 接口用于监控、调试和运维。

🔑 认证配置

Admin API 需要 Bearer Token 认证。首先配置 config.json：

# 复制示例配置文件
cp config.example.json config.json

# 编辑配置，设置你的管理员密钥
vim config.json

{
  "admin_token": "your-secret-admin-token-here"
}

所有 Admin API 请求必须携带 Authorization 头：

curl -H "Authorization: Bearer your-secret-admin-token-here" \
     http://localhost:8000/admin/stats

⚠️ 安全提示：config.json 已添加到 .gitignore，请勿将其提交到版本库。

获取服务器统计信息

GET /admin/stats
Authorization: Bearer <admin_token>

响应示例：

{
  "success": true,
  "user_data_dir": "/path/to/user_data",
  "total_workspaces": 15,
  "unique_users": 8,
  "total_size_bytes": 1048576,
  "total_size_human": "1.00 MB",
  "active_sessions": 3
}

列出所有工作空间

GET /admin/workspaces
GET /admin/workspaces?user_id=user123
Authorization: Bearer <admin_token>

获取工作空间详情

GET /admin/workspace/{workspace_id}
GET /admin/workspace/{workspace_id}/tree?max_depth=5
Authorization: Bearer <admin_token>

删除工作空间

DELETE /admin/workspace/{workspace_id}?confirm=yes
Authorization: Bearer <admin_token>

⚠️ 警告：此操作不可逆！必须添加 ?confirm=yes 参数才能执行删除。

👤 用户工作空间 API

为用户提供无需管理员 Token 的工作空间目录树查询。

GET /api/workspace/tree?user_id={user_id}&chat_id={chat_id}&max_depth=5

不需要 Authorization 头
仅返回对应 user_id + chat_id 组合的工作空间
每个目录层级按最近修改时间排序，仅保留前 20 个文件/文件夹，其余直接过滤以节省带宽

🧩 Excel 配置

config.json/config.example.json 新增 excel 段落，用于设置最大文件大小、默认读取行数、支持格式与公式检测开关。
模板：excel.templates_file 默认指向 excel_templates/templates.json，模板源文件放在 excel_templates/，对外只暴露 title/desc，create_excel_from_template 会自动避开重名。首次使用时，请从 templates_example.json 复制创建 templates.json，并根据实际情况配置模板路径。
环境变量覆盖：MCP_EXCEL_MAX_ROWS、MCP_EXCEL_MAX_SIZE_MB。
详细参数与示例见 docs/EXCEL_TOOLS.md。

⚙️ 启动配置

config.json 中新增 mcp 段落，可配置 transport（默认 sse）、host（默认 0.0.0.0）、port（默认 18089）。
CLI 参数 --transport/--host/--port 优先级高于配置文件。
Web 管理界面：config.json 新增 admin_web 段落（enabled 默认 false，password 默认 123456）。开启后访问 http://<host>:<port>/admin，输入密码可查看 user_data 下文件树并预览文本/Markdown/CSV。

📖 使用示例

🚀 Web 开发完整流程

步骤 1：创建前端项目

Tool: fs_write
Arguments: {
  "path": "/index.html",
  "content": "<!DOCTYPE html>..."
}

步骤 2：一键部署

Tool: preview_frontend
Arguments: {
  "entry_file": "index.html"
}

返回结果：

{
  "success": true,
  "url": "https://user123_chat456.proxy.your-domain.com/index.html",
  "subdomain": "user123_chat456"
}

步骤 3：访问部署的应用

自动获得独立子域名
支持 HTTPS（如配置）
无需手动配置端口和域名

💻 代码执行与调试

读取文件（支持行范围）

Tool: fs_read
Arguments: {
  "path": "/file.txt",
  "line_range": "100:150"  # 读取第100-150行
}

批量读取文件

Tool: fs_read
Arguments: {
  "path": ["/file1.txt", "/file2.json", "/data.xlsx"]
}

搜索文件

Tool: fs_search
Arguments: {
  "search_type": "content",  # glob=按文件名, content=按内容
  "pattern": "function\\s+\\w+\\(",
  "context_lines": 2  # 返回匹配行前后2行上下文
}

精确编辑文件

Tool: fs_replace
Arguments: {
  "path": "/config.py",
  "diff": "------- SEARCH\nDEBUG = True\n========\nDEBUG = False\n+++++++ REPLACE"
}

执行 Python 代码

Tool: exec
Arguments: {
  "code": "print('Hello, World!')"
}

执行 Python 文件

Tool: exec
Arguments: {
  "file": "/script.py",
  "args": ["--verbose", "input.txt"]
}

读取 Excel 文件

Tool: fs_read
Arguments: {
  "path": "/data.xlsx",
  "sheet": "Sheet1",      # 可选，指定工作表
  "range": "A1:D100"      # 可选，指定读取范围
}

创建 Excel 文件

Tool: fs_write
Arguments: {
  "path": "/output.xlsx",
  "content": [
    ["Name", "Age", "City"],
    ["Alice", 30, "Beijing"],
    ["Bob", 25, "Shanghai"]
  ]
}

编辑 Excel 文件

Tool: excel_edit
Arguments: {
  "path": "/data.xlsx",
  "edit_type": "cells",
  "sheet": "Sheet1",
  "updates": [
    {"cell": "A1", "value": "Updated Value"}
  ]
}

🎨 生成图表和流程图

Tool: generate_image
Arguments: {
  "mermaid_code": "flowchart TD\nA[开始] --> B[处理] --> C[结束]"
}

或使用 HTML 渲染复杂图表：

Tool: generate_image
Arguments: {
  "html_code": "<html><body><h1>数据可视化</h1>...</body></html>"
}

🔐 安全最佳实践

生产环境部署
- 使用反向代理（Nginx）处理 HTTPS
- 限制访问 IP 或使用 API 密钥认证
- 设置合理的请求频率限制
数据隔离
- 确保 X-User-ID 和 X-Chat-ID 由可信来源生成
- 定期清理过期的会话工作目录

Admin API 保护

location /admin/ {
    allow 10.0.0.0/8;
    deny all;
    proxy_pass http://localhost:8000;
}

⚙️ 环境变量

变量名	说明	默认值
`MCP_WORKSPACES_DIR`	用户工作空间根目录	`项目目录/user_data`
`MCP_ALLOWED_DIRS`	允许访问的目录列表（全局模式）	当前工作目录
`FASTMCP_PORT`	服务器端口	`8000`

📄 许可证

Apache License 2.0

🤝 贡献

欢迎提交 Issue 和 Pull Request！

MCP Workspace Serverрабочее пространство