Shanhai MCP Server

一个开箱即用的多租户 MCP Server：让 WorkBuddy / Claude / 任意 MCP 客户端通过 SSE 或 stdio 接入你的服务能力——知识检索、任务投递、交付物管理、多智能体咨询。

---

特性

工具	能力
list_capabilities	平台能力、权限边界与信任背书声明
search_study	知识库 / 学习模块检索（RAG 语义 + 关键词兜底）
dispatch_task	提交协作任务（内容安检 → 投递到后端场景编排引擎）
get_task_status	查询任务状态（异步任务轮询）
submit_result	提交任务执行结果（同样过内容安检）
list_deliverables	列出本租户交付目录文件（顶层 + 白名单子目录）
get_deliverable	拉取交付文件内容（水印 + 每日限读防扩散）
ask_think_tank	咨询台：复杂问题 → 多角色独立评审 → 结构化方案

设计目标：

• 🔒 fail-closed：无 Key 拒绝一切工具调用，绝不静默降级
• 🏢 多租户隔离：每租户独立交付目录 / 任务态 / 搜索根（进程级 + Key 级双重隔离）
• 🛡️ 内容安检：所有用户输入过内容安检层（prompt 注入 / 敏感词），deny 即拒
• 📊 配额 + 熔断：每租户每日/每月配额，异常调用熔断防滥用
• 🧱 异步协作：长任务（多智能体评审等）异步受理，task_id 轮询取结果

---

快速开始

1. 安装

git clone <your-repo-url> && cd shanhai-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2. 配置

复制环境变量模板并填写：

cp .env.example .env
# 编辑 .env：SHANHAI_API_KEY 必填（fail-closed 主 Key）

3. 运行（stdio 模式，本地连接器）

python3 server.py

4. 运行（SSE 模式，远程服务）

cp start-sse-public.example.sh start-sse-public.sh
# 按注释配置多租户环境变量
./start-sse-public.sh

SSE 端点：https://your-domain.com/mcp-public/sse

5. 客户端接入（WorkBuddy / 任意 MCP 客户端）

远程 SSE 服务正确写法（"type": "sse"，不是 "type": "http" / "transport": "sse"）：

{
  "mcpServers": {
    "shanhai-city": {
      "type": "sse",
      "url": "https://your-domain.com/mcp-public/sse",
      "headers": {
        "Authorization": "Bearer your-mcp-key-here"
      }
    }
  }
}

💡 本地 stdio 连接器用 "type": "stdio"。配置完成后在客户端「连接器管理」里点 信任/启用 激活。

---

多租户隔离（SSE 客户模式）

SHANHAI_TASK_DIR        # 任务态目录（与内部物理隔离，缺省拒绝启动）
SHANHAI_CUSTOMER_DIR    # 默认租户交付目录
SHANHAI_CUSTOMER_DIR_MAP  # 按 Key 映射交付目录（key1:dir1,key2:dir2）
SHANHAI_DELIVERABLE_SUBDIRS  # 交付子目录白名单（"知识卡片,咨询方案"）
SHANHAI_WISDOM_ROOT     # 租户搜索根（脱敏学习模块）

• 每租户独立 Key → 独立交付目录，交叉访问被拦（forbidden / file_not_found）
• 文件名白名单正则 + resolve() 防路径穿越
• 客户模式不返回服务器内部路径（result_path 恒为空，交付物走 get_deliverable）

安全设计

层	机制
认证	Bearer Key 白名单（SHANHAI_MCP_KEYS）+ fail-closed
隔离	进程级（内部/客户双实例）+ 目录锁死 + 搜索根隔离
安检	内容安检层（注入检测 / 敏感词），deny 即拒
防滥用	交付物每日限读 + 咨询台月配额 + 熔断（1h 超阈值冷静）
审计	工具调用统计落盘（SHANHAI_USAGE_LOG_DIR）

环境变量

完整变量表见 .env.example（所有密钥/路径均为占位符）。

项目结构

shanhai-mcp-server/
├── server.py                 # MCP Server 主体（FastMCP，8 工具）
├── start-sse-public.example.sh  # SSE 客户实例启动模板
├── mcp.json.example          # 客户端接入配置模板
├── .env.example              # 环境变量模板
├── requirements.txt
├── LICENSE                   # MIT
└── README.md

免责声明

本项目由山海城邦出品，以 MIT 协议开源，仅供学习与参考。实际部署请结合自身业务环境调整：务必替换所有密钥、配置独立域名与 TLS、按需裁剪工具权限。作者不对因使用本软件造成的任何直接或间接损失承担责任。

---

Shanhai · 山海城邦出品