🚀 MCP Workspace Server
🚀 只需一個 MCP，就能實現你的完整 Agent 能力！本項目是一個超越文件系統的 AI 開發環境，可讓 AI 像 Claude Code 一樣進行完整的 Web 開發、數據處理和代碼執行。無需集成多個 MCP 工具，一個 MCP 服務器即可提供文件操作、代碼執行、Web 部署、數據處理、圖像生成等完整的 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}} 或固定用戶IDX-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"
]
}
}
}
✨ 主要特性
🔐 多租戶會話隔離
每個用戶/會話擁有獨立的虛擬工作空間，完全隔離，互不干擾。
工作目錄命名規則：
| 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.comuser789_chat012.proxy.your-domain.com
優勢：
- ✅ 無需手動配置域名和端口
- ✅ 自動隔離，互不干擾
- ✅ 支持 HTTPS，生產就緒
- ✅ 單端口服務，簡化部署
📦 安裝指南
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
💻 使用示例
🚀 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"
}
Tool: fs_read
Arguments: {
"path": ["/file1.txt", "/file2.json", "/data.xlsx"]
}
Tool: fs_search
Arguments: {
"search_type": "content",
"pattern": "function\\s+\\w+\\(",
"context_lines": 2
}
Tool: fs_replace
Arguments: {
"path": "/config.py",
"diff": "------- SEARCH\nDEBUG = True\n========\nDEBUG = False\n+++++++ REPLACE"
}
Tool: exec
Arguments: {
"code": "print('Hello, World!')"
}
Tool: exec
Arguments: {
"file": "/script.py",
"args": ["--verbose", "input.txt"]
}
Tool: fs_read
Arguments: {
"path": "/data.xlsx",
"sheet": "Sheet1",
"range": "A1:D100"
}
Tool: fs_write
Arguments: {
"path": "/output.xlsx",
"content": [
["Name", "Age", "City"],
["Alice", 30, "Beijing"],
["Bob", 25, "Shanghai"]
]
}
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[結束]"
}
Tool: generate_image
Arguments: {
"html_code": "<html><body><h1>數據可視化</h1>...</body></html>"
}
📚 詳細文檔
與 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 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 |
| 配置複雜，需要逐個集成 |
開箱即用，一鍵配置 |
| 功能分散，難以統一管理 |
功能集中，統一管理 |
| 安全策略不統一 |
統一安全策略 |
| 維護成本高 |
維護簡單 |
🎁 開箱即用的能力
配置完成後，你的 AI Agent 立即擁有：
- 📝 文件操作：創建、讀取、編輯、搜索文件
- 💻 代碼執行：運行 Python/Node.js 腳本，實時調試
- 🌐 Web 開發：創建前端應用並一鍵部署到生產環境
- 📊 數據處理：讀取、編輯 Excel，生成報告
- 🎨 圖像生成：創建流程圖、數據可視化圖表
- 🔍 智能搜索：文件內容搜索、知識庫檢索（如啟用）
一個 MCP Server = 完整的 Agent 能力棧 🚀
架構設計
┌─────────────────────────────────────────────────────────────┐
│ 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
🔑 認證配置
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。
🔧 技術細節
為什麼選擇我們？
🎯 一個 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 服務
📄 許可證
Apache License 2.0
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
