旦挞 MCP · DanTa MCP

English | Chinese

An MCP server that lets AI automatically search 复旦树洞 and 旦克课程评价. Usable off campus.

Tree Hole is an anonymous community for Fudan students — daily life, relationships, jobs, mental health, changing majors, second-hand trading, they talk about everything. This tool lets AI find, read through, and summarize these real experiences for you, instead of flipping through pages yourself.

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

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

Table of Contents

• What It Can Do

• Quick Start

• Tool Reference

• How It Works

• Security Design

• Troubleshooting

• Known Limitations

• License

Related MCP server: cc98-mcp

What It Can Do

Once configured, just ask in natural language and the AI will call the tools automatically:

Data sources: 复旦树洞 (real-time anonymous discussions, 23,000+ topic tags) + 旦克课程评价库 (structured ratings + long-form student reviews).

Quick Start

Prerequisites

• Python 3.10+

• A Fudan UIS account (student number + password)

• A 旦挞/树洞 account (email + password, register in the 旦挞 App)

• An MCP-capable client (Hermes / Claude Desktop / Cline, etc.)

1. Install

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. Configure credentials

# Windows
.venv\Scripts\python setup_credentials.py

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

1. Run the configuration — you will be asked for two accounts in sequence (password input is not echoed):

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

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

Storage locations:

• Windows → Credential Manager (DPAPI-encrypted, bound to your Windows account)

• macOS/Linux → System keychain (install pip install keyring)

• Any platform → Or use environment variables DANTA_UIS_USER / DANTA_UIS_PASS / DANTA_HOLE_USER / DANTA_HOLE_PASS

Verify:

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

3. Self-check

.venv/Scripts/python -E verify_mcp.py

You should see:

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

4. Connect to MCP client

Add this to your client configuration (note: the - E flag is required, see [Troubleshooting]).

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

For Hermes, put it under mcp_servers: in config.yaml (YAML format, same fields as above).

Restart the client and you are done.

Tool Reference

Tree hole (general purpose, search any topic)

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

Search hole contents across the entire site. This is the most commonly used tool.

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

• accurate=True — exact match, good for proper nouns, course codes, and names

• within_days=N — only look at the last N days, good for time-sensitive content (interns, policy updates)

getHole(hole_id, limit=40)

Read all floors of a hole.

The value of a hole is often in its replies — the original poster asks, and the people underneath give their experience. If you find an interesting hole, read the full thread.

browse_by_tag(tag, limit=15)

Browse the latest holes by tag. Better for "browsing" a topic than keyword search.

Common tags: 提问 求助 生活 学习 爱情 情感 吐槽 emo 交友 选课 转专业 保研 期末 出分 二手交易 找搭子 军训 家教

list_hot_tags(limit=40, keyword="")

List the hottest tags (sorted by popularity), with running filter.

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

The hole has 23,000+ tags; top by popularity: 提问(18万) 求助(9.5万) 生活(7.4万) 学习(6万) 恋爱(3.7万) 吐槽(2.3万) 吐槽(2万) emo(1.8万).

browse_divisions(div_id, limit=15) / list_divisions()

Browse by division:

Divisions:

Course Reviews (旦克课程评价)

search_nononsuite? — extract

Search courses by name, code, or keyword. keyword can be a course name.

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

Check the review count first — a course with 0 reviews has no reference value.

get_course_reviews(course_group_id, max_reviews=12)

View the full set of reviews for a course, grouped by "professor + semester".

Returns:

• Four-dimension scores: Overall / Content / Workload / Assessement (1–5 stars)

• remark — recommended index, like count

• Review text (usually gives grade distribution, exam difficulty, homework load, TA situation)

Tree Hole

search_holes(keyword, limit=15)

Full game — search all hole content. Good for teacher reputation, course-selection experience, real complaints.

get_hole(hole_id, limit=40)

Read all floors of a hole.

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

Divisions by div. Division IDs:

Troubleshooting

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

Generate an HTML citation report with complete item, save to Desktop, open in browser.

Each reference keeps: hole number (clickable, original), floor, anonymous nickname, timestamp, like count, exact copied.

Great for scenarios that require human review of conclusions — you can check each entry to verify the AI isn't over-interpreting.

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

Use | to separate source or lower groups in queries. Each group is 小adj::keyword; You can also use hole:<hole_id> to directly cite all floors of a whole hole.

Report features: responsive layout, dark-mode support, HTML-escaped all content (prevents injection).

check_connection()

Check WebUNT session, token, and account status. Run this first if something goes wrong.

How It Works

What's it take this layer?

The 复旦树洞 API is immediately deployed:

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

Off-campus physically cannot connect. This project re-implements the WebVPN method like [旦挞 official client](https://github.com/DanXi- 述/DanXi)?

Full chain

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

For step 5: AES-based key = iv = wrdvpnisthebest!, hostname padded to a multiple of 16 character (not bytes); output iv_hex + ciphertext_hex[:2n].

Tip: auth.fduhole.com encrypted result always 7772647670... (left 32 hex are wrdproduct...); if not, the implementation is broken.

Caching

Caches are stored in ~/.device-mcp/:

• cookies.json — WebVPN session, expired after 6 hours old

• token.json — Tree Hole JWT, 20 days

Normal use will not login repeatedly.

On-Campus direct connect

After registering and connecting to campus network / eduroam, direct connection works, WebVPN becomes transparently fallback; no code change needed.

Security Design

Passwords never stored as plaintext

They live in the system's credential store; the code only reads, never writes a copy. The repository also contains no credentials (see .gitignore).

UIS login is single-attempt, stops on failure

This is the most important design decision.

UIS (Fudan University's authentication system) triggers a captcha after several consecutive failed login attempts; once triggered, you must separately open a browser and log in once to unlock. So:

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

When message contains "验证码" — immedi atch, terminating with a prompt to manually login, no auto-retries.

Network-layer retries (tries=3) only apply to the unreliable WebVPN channel, never to login attempts.

Cache permissions

Files under ~/.danta-mcp/ are chmod to 600 (only user can read/write).

Read-only

This project only provides read-only operations — no posting, no replies, novotings. AI will not speak for you in the Hole.

故障排除

`No module named 'p.server.fastmcp'

MCP requirement: MCP SDK 2.x renamed FastMCP → MCPServer. server.py already handles both. If it still complains, platform PYTHONPATH is polluting → see below.

Tools don't appear in the client / server exits at startup

九成 into "PYTHONPATH" pollution. Some MCP executors inject their own site-packages into the child env, competing with the project's venv.

Solution: configure with - E (ignore env variables on start):

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

⚠️ Editing sys.path in the code doesn't help — sys.path oonce set by PYTHONPATH at interpreter starting.

❌ 验证码

Click the browser open https://id.fudan.edu and log in manually once to clear.

Do not keep retrying — it will aggravate.

login has a login context?

WebVPN expired, hello when back to login page. Code automatically reconstructs the session once. If still failing:

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

Wait 5 minutes and retry.

IDP did not return a login context

WebVPN is fland, its / roads often timeout. Wait and retry.

UIS password changed

Need to re-enroll:

.venv/Scripts/python setup_credentials.py

Simply securely re-insert credentials (prompting once).

Known Limitations

• Depends on the current implementation of the university authentication system. If campus upgrades, it may need to be revised; watch [Dan Xi upstream](https github's Devs) for this.

• No 2- FA support. If your account has two-factor enabled, it will throw EnhancedLack.

• WebVPN is not a reliable infrastructure — timeout is the norm; the code retries but can't eliminate it.

• Course reviews depend on contributors — unpopular courses may have zero reviews.

• Only fully tested on Windows; macOS/Linux keychain flow is written but not validated.

Contact

Questions, suggestions, or bug reports: or via Issues.

License

GPL-3.0 — see LICENSE.

This project draws the VPN cipher and the UIS flow from DanXi-Dev/DanXi (GPL-3.0 ). Due to the license, this project is released under the same license, can not be republicized — see LICENSE for details.

Disclaimant

This tool is intended only to access your own Fudan resources, equivalent to what you would manually see by using the Web portal.

Please follow the Campus Networking Policy and the Tree Hole Community Rules. Use it at your own.