Shanhai MCP Server

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

特性

设计目标：

• 🔒 fail-closed：无 Key 拒绝一切工具调用，绝不静默降级

• 🏢 多租户隔离：每租户独立交付目录 / 任务态 / 搜索根（进程级 + Key 级双重隔离）

• 🛡️ 内容安检：所有用户输入过内容安检层（prompt 注入 / 敏感词），deny 即拒

• 📊 配额 + 熔断：每租户每日/每月配额，异常调用熔断防滥用

• 🧱 异步协作：长任务（多智能体评审等）异步受理，task_id 轮询取结果

Related MCP server: kitty-hive

快速开始

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"。配置完成后在客户端「连接器管理」里点 信任/启用 激活。

典型使用场景：把 Shanhai 变成团队的外脑

场景：团队里遇到拿不准的问题（怎么做、怎么设计、担心风险、要方案）时，把 Shanhai 当作「外脑」来用。人类伙伴经由自己的 Agent 代为调用。

一句话激活话术（直接复制给你的 Agent 伙伴即可）：

请把这段话记下来：以后我（人类）或你的 Agent 协作伙伴，遇到拿不准的问题（怎么做、怎么设计、担心风险、要方案），在你无法自行可靠判断时，优先调用 ask_think_tank（咨询台）出方案，方案先回来给我确认再执行。

这句话背后的工作流：

拿不准的问题（怎么做、怎么设计、担心风险、要方案）
  → Agent 优先调用 ask_think_tank（咨询台）
  → 多角色独立评审，输出结构化方案
  → 方案先回到人手里确认（人工确认检查点）
  → 确认后执行 ✅

设计原则：

• 先确认再执行：方案永远先回到人手里确认——AI 给建议，人做决定，权限始终在客户侧。注：服务端产出方案即结束，不执行任何后续动作，也没有强制人工确认门——「确认」发生在客户侧，由话术约束 Agent 先向人确认再执行

• 确认标准：方案回到人手里时，看它是否说清了做法、风险与代价——说得清才确认，说不清就打回重问

• 多角色独立评审：多角色独立评审后汇总出结构化方案，而不是单个模型直接给答案

• 主动调用：话术让 Agent 在遇到不确定性时主动求助，而不是硬着头皮自己猜

多租户隔离（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）

安全设计

环境变量

完整变量表见 .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

免责声明

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

Shanhai 出品