Ssumcp

ssuMCP

한국어 · English

这是一个 Spring Boot 后端，通过 52 个 MCP 工具和 REST API 提供崇实大学的公开与个人数据。 它在同一服务边界内处理学校系统集成、按用户区分的认证状态、按操作划分的同意协议、故障隔离和运行可观测性。

Web 演示 · 文档索引

在平台中的职责

服务	职责	仓库
ssuAI	用户界面、same-origin BFF、SSE 聊天 UX	ghdtjdwn/ssuAI
ssuAgent	LangGraph 路由、对话状态、HITL 编排	ghdtjdwn/ssuAgent
ssuMCP	校园领域逻辑、MCP/REST 协议、认证与状态变更	当前仓库
ssu-ai-service	隔离的嵌入请求网关	ghdtjdwn/ssu-ai-service

ssuMCP 负责原子化的领域工具和学校系统集成。自然语言意图解析和多个工具的组合由 ssuAgent 负责，界面和浏览器会话边界则由 ssuAI 负责。

架构

REST Controller 和 MCP @Tool adapter 调用同一个 Service 层。外部学校系统隔离在 *Connector 接口之后。默认 profile 使用确定性的 mock 支持离线开发；production profile 会验证所有 connector 是否为 real/rusaint/llm，并在配置为 mock 或缺少配置时拒绝启动。详细的运行时、数据和部署边界见架构文档。

核心请求流程

ssuAI REST/BFF 또는 MCP client
  → REST Controller / MCP Tool adapter
  → shared Service layer
  → PostgreSQL · Redis/Redisson · Kafka
  → u-SAINT · LMS · 도서관 · 학교 웹사이트 connector

• 公开查询无需认证即可使用；个人查询仅关联到 OAuth subject 或所有权已确认的 MCP 会话。
• 座位预约、暂离、归还和 LMS 导出拆分为 prepare_* → confirm_action，不会在用户批准前执行。wait_for_library_seat 调用本身即表示同意自动预约；cancel_library_wait 则是立即执行明确取消等待操作的例外。
• 预约 intent 以 PostgreSQL 行锁和 claim lease 作为一致性依据，并将按座位划分的 Redisson lock 作为减少重复 upstream write 的辅助层。
• 座位归还与变更的 claim 和结束结果独立于 provider fence 提交。如果进程在 upstream write 期间终止，系统会重新查询当前预约，并收敛为成功、安全重试、恢复原座位或部分失败。
• 运行状态 fan-out 使用 Kafka；缓存、共享 rate limit 和领导者选举使用 Redis，并针对各条路径明确规定故障时采用 fail-open 或 fail-closed 策略。

工程依据

问题	实现与验证依据
MCP 工具与静态 server card 之间的协议漂移	52-tool inventory/schema parity test · live tool audit
用户间会话混淆和未经批准的写入	authoritative session resolution · scoped confirm contract
外部 API 延迟、429 和并发预约	failure scenarios · reservation concurrency integration test
upstream write 后进程中断	持久化操作阶段 + 当前预约对账 — ADR 0099
搜索依据追踪与嵌入故障	词法 + 嵌入 RRF、来源元数据、词法回退 — ADR 0020
未经验证的镜像自动部署	在 test/JaCoCo gate 之后发布多架构镜像 — CI workflow · GitOps runbook
复现并预防运行故障	故障排查要点 · 负载实验

主要技术栈包括 Java 21、Kotlin 2.4、Spring Boot 4.1、Spring AI、PostgreSQL、Redis/Redisson、Kafka、Resilience4j、Testcontainers、Helm、ArgoCD、Prometheus、Tempo 和 Loki。

연결하기

원격 MCP를 지원하는 클라이언트에는 다음 endpoint를 등록한다.

{
  "mcpServers": {
    "ssuMCP": {
      "url": "https://ssumcp.duckdns.org/mcp"
    }
  }
}

Claude Desktop, Cursor와 클라이언트별 인증 흐름은 MCP 도구·인증 문서에 정리했다. Java 21 이상이 설치된 환경에서는 공개 런처로 self-host할 수 있다.

npx ssumcp

실제 MCP 클라이언트 연동 화면

개인 값과 활성 좌석 식별자는 공개용 이미지에서 비식별화했다. 화면은 한 번의 실제 연동 결과이며, 외부 학교 시스템의 모든 시점 가용성을 보장하지 않는다.

인증된 졸업요건 조회	승인 후 도서관 좌석 예약

LMS 자료 내보내기 준비	단기 링크로 ZIP 다운로드

로컬 실행과 검증

기본 profile은 mock connector를 사용하므로 실제 학교 계정이나 외부 네트워크가 필요하지 않다.

git clone https://github.com/ghdtjdwn/ssuMCP.git
cd ssuMCP
./gradlew bootRun

검증 명령은 다음과 같다. Docker가 있으면 Testcontainers 기반 PostgreSQL·Redis 통합 테스트도 실행된다. 로컬에서 container test가 skip된 경우 통과로 간주하지 않으며, Docker가 있는 GitHub Actions가 권위 게이트다.

./gradlew test
./gradlew test jacocoTestReport jacocoTestCoverageVerification
./gradlew build

실제 connector와 운영 설정은 .env.example, 배포 runbook을 참고한다. 운영 Actuator는 public ingress와 분리된 내부 management port에서만 제공한다. 실제 자격증명은 저장소에 커밋하지 않는다.

문서

• 문서 지도
• MCP 도구와 인증 계약
• 보안·세션·write consistency
• ADR 목록
• 운영 장애 하이라이트

범위와 제약

• 숭실대학교 공식 서비스가 아니며, 학교 웹페이지나 비공개 API 변경에 따라 connector가 일시적으로 동작하지 않을 수 있다.
• 개인 도구는 유효한 학교 계정과 해당 provider 인증이 필요하다.
• 공개 데모와 Grafana는 프로젝트 운영 환경이며 상용 SLA를 제공하지 않는다.

라이선스

MIT