Ssumcp

ssuMCP

韓国語 · 英語

崇実大学の公開・個人データを52個のMCPツールとREST APIで提供するSpring Bootバックエンドです。 学校システムとの連携、ユーザーごとの認証状態、操作ごとの同意契約、障害分離と運用監視を、ひとつのサービス境界内で扱います。

ウェブデモ · ドキュメントマップ

プラットフォームにおける役割

サービス	責務	リポジトリ
ssuAI	ユーザー画面、同一オリジンの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アダプターは、同じ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の 途中で終了した場合は、現在の予約を再照会し、成功、安全な再実行、元の座席への補償、または部分的な失敗へ収束させます。
• 運用状態のファンアウトにはKafka、キャッシュ・共有rate limit・リーダー選出にはRedisを使用し、障害時の経路ごとに fail-openまたはfail-closedの方針を明示します。

エンジニアリング上の根拠

課題	実装と検証の根拠
MCPツールと静的server cardの契約のずれ	52-tool inventory/schema parity test · live tool audit
ユーザーごとのセッション混同と承認のない書き込み	権威あるセッション解決 · スコープ付きconfirm契約
外部APIの遅延・429・同時予約	障害シナリオ · 予約競合の統合テスト
upstream write後のプロセス中断	永続化されたアクションフェーズ＋現在の予約情報との照合 — ADR 0099
検索根拠の追跡と埋め込み障害	lexical＋embedding RRF、ソースメタデータ、lexical fallback — ADR 0020
検証されていないイメージの自動デプロイ	test/JaCoCo gate後にmulti-arch imageを公開 — 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