旦挞 MCP · DanTa MCP

English | 中文

让 AI 自动检索复旦树洞和旦克课程评价的 MCP 服务器。校外可用。

树洞是复旦学生的匿名社区——生活、情感、就业、心理、转专业、二手交易，什么都聊。 这个工具让 AI 帮你把这些真实经验搜出来、读完、汇总，而不是自己一页页翻。

你：帮我查一下高等微积分Ⅰ这门课怎么样

AI：（自动调用 search_courses → get_course_reviews）
    找到「高等微积分Ⅰ」(MATH20021)，相辉学堂，5 学分，3 条评价。
    教师严金海 + 王嬴（习题课）
    综合评分 ★★★★★ / ★★★★☆
    - 给分：两位评价者最终都拿了 A，但都提到"课下要花很多时间"
    - 严老师：PPT 有用、往年卷会分享、题型固定不偏；但上课爱扯题外话
    - 王嬴老师：口碑极好，答疑响应快，改作业细致
    - 难度：期中偏难，秋季学期后考试强度有下降

目录

• 能干什么

• 快速开始

• 工具说明

• 工作原理

• 安全设计

• 排障

• 已知限制

• 许可证

Related MCP server: juejin-mcp-server

能干什么

配好之后直接用自然语言问，AI 会自动调工具：

数据来源：复旦树洞（实时匿名讨论，23000+ 话题标签）+ 旦克课程评价库（结构化评分 + 学生长评）。

快速开始

前置要求

• Python 3.10+

• 一个复旦 UIS 账号（学号 + 密码）

• 一个旦挞/树洞账号（邮箱 + 密码，在 旦挞 App 里注册）

• 一个支持 MCP 的客户端（Hermes / Claude Desktop / Cline 等）

1. 安装

git clone <你的仓库地址> danta-mcp
cd danta-mcp

# Windows
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

# macOS / Linux
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

2. 配置凭据

# Windows
.venv\Scripts\python setup_credentials.py

# macOS / Linux
.venv/bin/python setup_credentials.py

会依次问你两组账号（密码输入时不回显）：

— 复旦 UIS 统一身份认证（学号 + 密码）
  用户名: 20307130001
  密码（不回显）:
  ✅ 已保存

— 旦挞/树洞账号（邮箱 + 密码）
  用户名: 20307130001@m.fudan.edu.cn
  密码（不回显）:
  ✅ 已保存

存储位置：

• Windows → 凭据管理器（DPAPI 加密，绑定你的 Windows 账户）

• macOS/Linux → 系统钥匙串（需 pip install keyring）

• 任何平台 → 也可用环境变量 DANTA_UIS_USER / DANTA_UIS_PASS / DANTA_HOLE_USER / DANTA_HOLE_PASS

验证：

.venv/Scripts/python setup_credentials.py --check

3. 自检

.venv/Scripts/python -E verify_mcp.py

应看到：

✅ handshake OK — 10 tools registered:
   • search_courses
   ...
✅ 连接正常
  WebVPN: 已建立会话
  用户 ID: 51359
✅ all checks passed

4. 接入 MCP 客户端

在客户端配置里加（注意 -E 参数不能少，见排障）：

{
  "mcpServers": {
    "danta": {
      "command": "/绝对路径/danta-mcp/.venv/Scripts/python.exe",
      "args": ["-E", "/绝对路径/danta-mcp/run_server.py"],
      "cwd": "/绝对路径/danta-mcp"
    }
  }
}

Hermes 用户写在 config.yaml 的 mcp_servers: 下（YAML 格式，字段同上）。

重启客户端即可。

工具说明

树洞检索（通用，什么话题都能搜）

search_holes(keyword, limit=15, accurate=False, within_days=0)

全站搜索树洞内容。这是最常用的工具。

search_holes("食堂")                      # 模糊搜索
search_holes("转专业", accurate=True)      # 精确匹配，关键词必须完整出现
search_holes("实习", within_days=14)       # 只看最近两周

• accurate=True — 精确匹配，适合专有名词、课程代码、人名

• within_days=N — 只看最近 N 天，适合找时效性内容（实习招聘、最新政策）

get_hole(hole_id, limit=40)

读某个树洞的全部楼层。

树洞的价值常在回复里 —— 楼主提问，楼里的人给经验。搜到感兴趣的洞一定要读全文。

browse_by_tag(tag, limit=15)

按话题标签浏览最新树洞。比关键词搜索更适合"逛"某个话题。

常用标签：提问 求助 生活 学习 恋爱 情感 吐槽 emo 交友 选课 转专业 保研 期末考试 出分 二手交易 找搭子 军训 家教

list_hot_tags(limit=40, keyword="")

列出最热门的话题标签（按热度排序），可过滤。

list_hot_tags()                  # 看树洞上大家都在聊什么
list_hot_tags(keyword="实习")     # 找所有和实习相关的标签

树洞共有 23000+ 标签，热度前几名：提问(18万) 求助氵(9.5万) 生活(7.4万) 学习(6万) 恋爱(3.7万) 吐槽(2.3万) emo(1.8万)。

browse_division(division_id, limit=15) / list_divisions()

按板块浏览：

课程评价（旦克）

search_courses(keyword, limit=10)

搜课程。keyword 可以是课程名、课程代码、关键词。

search_courses("微积分")
→ [1136] 微积分（上）(MATH120012) 基础医学院 | 评价数: 0
  [8911] 高等微积分Ⅰ (MATH20021) 相辉学堂 | 评价数: 3

先看评价数，为 0 的课没有参考价值。

get_course_reviews(course_group_id, max_reviews=12)

看某门课的完整评价，按「教师 + 学期」分组。

返回内容包含：

• 四维评分：综合 / 内容 / 工作量 / 考核（1-5 星）

• remark 推荐指数、点赞数

• 评价正文（通常含给分情况、考试难度、作业量、助教情况）

树洞

search_holes(keyword, limit=15)

全站搜索树洞内容。适合找老师风评、选课经验、真实吐槽。

get_hole(hole_id, limit=40)

读某个树洞的全部楼层。

list_divisions() / browse_division(division_id, limit=15)

板块浏览。板块 ID：

排障

build_citation_report(title, queries, summary_markdown="", per_query=6)

把检索结果生成一份带完整出处的 HTML 引证报告，保存到桌面，浏览器打开即可。

每条引用保留：洞号（可点击溯源）、楼层、匿名昵称、时间、点赞数、原文照登。 适合需要人工核对结论的场景 —— 你可以逐条检查 AI 有没有过度解读。

build_citation_report(
  title="复旦留学生宿舍 · 快递地址怎么填",
  queries="北区驿站::北区 菜鸟驿站|顺丰京东::顺丰 京东 本部|hole:692300::地址怎么写",
  summary_markdown="<p>结论写在这里</p>"
)

queries 用 | 分隔多个来源分组，每组格式 小节标题::关键词； 也支持 hole:洞号 直接引用整个树洞的所有楼层。

报告特性：响应式布局、自动适配深色模式、内容全部 HTML 转义（防注入）。

check_connection()

检查 WebVPN 会话、token、账号状态。出问题时先跑这个。

工作原理

为什么需要这一层

复旦树洞的 API 全部部署在校内：

forum.fduhole.com → 10.107.13.152   ← 校内私有地址
auth.fduhole.com  → 10.107.13.152
danke.fduhole.com → 10.107.13.152

校外物理上无法直连。本项目复刻了旦挞官方客户端的 WebVPN 方案。

完整链路

1. 读取凭据（系统钥匙串 / 环境变量）
        ↓
2. UIS 登录 id.fudan.edu.cn
   getJsPublicKey → RSA-PKCS1 加密密码 → authExecute → loginToken
        ↓
3. authnEngine → CAS ticket (ST-xxxxx)
        ↓
4. 兑换 ticket → 拿到 WebVPN 会话 cookie
        ↓
5. API 域名 AES-CFB 加密改写
   https://auth.fduhole.com/api/login
   → https://webvpn.fudan.edu.cn/https/7772647670...c38/api/login
        ↓
6. 树洞账号换 JWT → 之后所有请求带 Bearer

第 5 步的加密：AES-CFB，key = iv = wrdvpnisthebest!，主机名按字符数（非字节数）补齐到 16 的倍数，输出 iv_hex + 密文hex[:2n]。

自检小技巧：auth.fduhole.com 加密结果恒为 77726476706e69737468656265737421f1e2559469366c45760785a9d6562c38， 前 32 位正是 wrdvpnisthebest! 的 hex。对不上说明实现有问题。

缓存

会话和 token 缓存在 ~/.danta-mcp/：

• cookies.json — WebVPN 会话，6 小时后视为过期

• token.json — 树洞 JWT，20 天

正常使用不会反复登录。

校内直连

报到后连校园网 / eduroam，直连即可通，WebVPN 这层自动变成透明兜底，代码不用改。

安全设计

密码不落盘明文

存在系统级凭据库，代码只读不写副本。仓库里也没有任何凭据（见 .gitignore）。

UIS 登录单次尝试，失败即停

这是最重要的一条设计。

复旦 UIS 对连续登录失败会触发验证码，一旦触发，必须手动打开浏览器登录一次才能解除。所以：

# authExecute 明确 tries=1，绝不重试
r = self._req("POST", ".../authExecute", tries=1, json={...})

检测到 message 含「验证码」时立即抛错并提示手动登录，不会自动重试轰炸。

网络层重试（tries=3）只作用于 WebVPN 的不稳定连接，不作用于登录尝试。

缓存文件权限

~/.danta-mcp/ 下的文件权限设为 600（仅所有者可读写）。

只读

本项目只提供读取工具，不提供发帖、回复、投票等写操作。AI 不会替你在树洞发言。

排障

No module named 'mcp.server.fastmcp'

MCP SDK 2.x 把 FastMCP 改名为 MCPServer。server.py 已做双版本兼容，如果仍报错，说明 venv 被外部 PYTHONPATH 污染了 → 见下条。

工具在客户端里不出现 / 服务器启动即退出

九成是 PYTHONPATH 污染。 某些 MCP 宿主会把自己的 site-packages 注入子进程环境，盖掉本项目 venv 里的包。

解法：配置里必须用 -E（启动时忽略环境变量）：

"args": ["-E", "/path/to/run_server.py"]

⚠️ 在代码里改 sys.path 是无效的 —— sys.path 在解释器启动时就由 PYTHONPATH 定型了。

❌ UIS 触发了验证码

用浏览器打开 https://id.fudan.edu.cn 手动登录一次即可解除。

不要反复重试，会加重锁定。

login returned non-JSON

WebVPN 会话过期，被弹回登录页。代码会自动重建会话重试一次。如果仍失败：

rm -rf ~/.danta-mcp   # 清缓存重新登录

IDP did not return a login context

WebVPN 不稳（它的根路径 / 经常超时）。稍等重试即可。

改了 UIS 密码之后

.venv/Scripts/python setup_credentials.py

重新录入即可。

已知限制

• 依赖复旦认证系统的当前实现。学校升级认证流程后可能失效，需跟进 DanXi 上游 的改动。

• 不支持双因素认证（2FA）。如果你的账号开了增强认证，会抛 EnhancedAuthenticationRequiredException。

• WebVPN 本身不稳定，超时是常态，代码已加重试但无法完全消除。

• 课评数据取决于有没有人写。冷门课可能一条评价都没有。

• 仅在 Windows 上完整测试过；macOS/Linux 的钥匙串路径写了但未实测。

联系

问题、建议或 bug 反馈：likangxian1007@gmail.com 或在 Issues 提出。

许可证

GPL-3.0 — 详见 LICENSE。

本项目的 WebVPN 加密方案与 UIS 登录流程衍生自 DanXi-Dev/DanXi（GPL-3.0）。依据 GPL 传染性条款，本项目必须以相同许可证发布。

免责声明

本工具仅用于访问你本人有权访问的校内资源，等价于你手动登录网页所能看到的内容。

请遵守复旦大学网络使用规定和树洞社区公约。使用者对自己的行为负责。