旦挞 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)

특정 강의의 전체 평가를 봅니다, 「교수 + 학기」별로 그룹화.

반환 내용 포함:

• 4차원 평점: 종합 / 내용 / 업무량 / 평가(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의 키체인 경로는 작성했지만 실제 테스트는 되지 않았습니다.

연락

문제, 제안 또는 버그 피드백: likangxian1007@gmail.com 또는 Issues에 제출하세요.

라이선스

GPL-3.0 — 자세한 내용은 LICENSE 참조.

이 프로젝트의 WebVPN 암호화 방식과 UIS 로그인 프로세스는 DanXi-Dev/DanXi(GPL-3.0)에서 파생되었습니다. GPL 전염성 조항에 따라 이 프로젝트는 동일한 라이선스로 배포되어야 합니다.

면책 조항

이 도구는 본인이 접근 권한이 있는 교내 리소스에만 접근하는 데 사용되며, 수동으로 웹페이지에 로그인하여 볼 수 있는 내용과 동일합니다.

复旦大学 네트워크 사용 규정과 树洞 커뮤니티 규약을 준수하세요. 사용자는 자신의 행동에 책임을 집니다.