# Shanhai MCP Server

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 特性

| 工具 | 能力 |
|:--|:--|
| `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. 安装

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

### 2. 配置

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

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

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

```bash
python3 server.py
```

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

```bash
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"`）：

```json
{
  "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`）

## 安全设计

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

## 环境变量

完整变量表见 [.env.example](.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 出品*