Korean University Disclosure Indicators (대학알리미)

academyinfo-mcp

英語 | 한국어

academyinfo-mcp は、韓国の大学情報公開指標を事実に基づいて照会し、並べて比較するための、独立した読み取り専用 MCP サーバーです。バンドルされたローカルスナップショットを使用するため、API キーや実行時のネットワーク接続は不要です。

このプロジェクトは、教育部、KCUE、KEDI、data.go.kr、academyinfo.go.kr、またはいかなる大学とも提携、承認、認可、後援、保守の関係にありません。

クイックスタート

academyinfo-mcp は、インストール、API キー、ログインなしで動作します。韓国の大学情報公開指標（대학알리미、KOGL Type 1）のバンドル済みスナップショットを読み込み、AI アシスタントからの事実に基づく照会や並べての比較に回答します。

Claude Desktop

claude_desktop_config.json（macOS の場合：~/Library/Application Support/Claude/）に追加してから、Claude Desktop を再起動してください。

{
  "mcpServers": {
    "academyinfo": {
      "command": "npx",
      "args": ["-y", "academyinfo-mcp"]
    }
  }
}

Cursor

同じ形式の command／args を ~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）に追加し、MCP サーバーのリストを再読み込みしてください。

任意の MCP stdio クライアント

npx -y academyinfo-mcp

サーバーは stdio 経由で MCP を使用します（stdout には JSON-RPC、stderr には診断情報が出力されます）。

ホスト型エンドポイント（インストール不要）

ローカルプロセスを実行できないクライアント向けです。URL フィールドでコネクターを登録するクライアント（claude.ai のカスタムコネクターなど）では、アドレスを指定するだけです。

https://academyinfo-mcp-433006350023.asia-northeast3.run.app/mcp

貼り付ける mcpServers オブジェクトを受け取るクライアントでは、次のエントリーを指定します。

{
  "mcpServers": {
    "academyinfo": {
      "description": "대학알리미 공시데이터 — 488개 대학·캠퍼스 17개 지표 비교",
      "url": "https://academyinfo-mcp-433006350023.asia-northeast3.run.app/mcp"
    }
  }
}

認証情報は不要なので、headers も必要ありません。ローカル版と同じバンドル済みスナップショットと同じ 8 つのツールを使用します。

これは個人によるデプロイであり、現状のまま提供されます。予告なく利用できなくなる可能性があり、可用性は保証されません（サポートをご覧ください）。再現性が必要な作業では、ローカル版を使用し、バージョンを固定してください — [email protected]。

貼り付け形式の詳細と、含めてはいけないトランスポートフィールドについては、examples/をご覧ください。

試してみる

アシスタントに次のように尋ねてみてください。

"전남대와 부산대의 취업률과 경쟁률을 비교해줘."

サーバーは曖昧な名前を推測で判断しません。「전남대학교」は 2 つのキャンパスに一致するため、最初の explore_universities 呼び出しでは表ではなく、候補とともに status: "ambiguous" が返されます。

전남대학교 → 2 candidates
    전남대학교 / 본교       (국립, 광주)
    전남대학교 / 제2캠퍼스  (국립, 전남)

キャンパスを選んでもう一度尋ねてください（アシスタントが自動的にこの追加質問をすることもよくあります）。

"전남대학교 본교와 부산대학교로 비교해줘."

2 回目の呼び出しでは status: "ok" とともに、各機関の値と出典、年度、単位が返されます。たとえば、バンドル済みの 2025 年スナップショットでは次のようになります。

大学	就職率	新入生競争率
전남대학교 本校	57.6%	7.4:1
부산대학교	57.5%	9:1

この 2 段階の流れは意図した動作であり、失敗ではありません。曖昧な名前に対しては推測する代わりに候補のキャンパスを返し、比較では順位付け、スコア付け、勝者の選定を行いません。数値は出典情報とともにそのまま提示されるため、判断は利用者に委ねられます。

証拠の範囲に限定したステータス

このチェックアウトで実装済み：

• 同梱の 15118998 派生データベースを使用する、ファイル優先、オフライン、読み取り専用の stdio サーバー；
• 正確に8つの MCP ツールを登録（従来の7つのツールに explore_universities を追加）；
• data/seed/indicators.json にある、スキーマ検証済みで KOGL の帰属表示が付いたデータのみの指標カタログ；
• Node エンジン >=22 <23 と、直接依存する本番用依存関係を @modelcontextprotocol/[email protected]、[email protected]、[email protected]、[email protected] に限定；
• 推測せず候補を返す曖昧さへの対応、およびスコア、順位、勝者、推奨を示さない事実に基づく比較；
• チェックアウト専用のステートレスな Streamable HTTP エントリーポイント（dist/src/http.js、POST のみ、npm パッケージには含めない）と、パッケージに含まれる stdio エントリーポイント。8つすべてのツールに readOnlyHint／openWorldHint の注釈を付与。

公開状況：[email protected] は公開 npm レジストリで公開済み（latest）です。隔離されたターミナルでの手動公開手順（docs/manual-publish-runbook.md）に従い、手動で公開しました。最初の 0.1.0 リリースでは、匿名の npx -y [email protected] インストールをスモークテストし、レジストリの正確な tarball が解決され、8つすべてのツールが一覧表示されることを確認しました。その後のリリース（0.1.1、0.1.2、0.2.0、0.3.0、0.3.1、0.4.0）も同じ手順に従っています。

未実施（初の単独リリースとして意図的かつ相応の判断によるもの）：

• 公式 Node 22 の3つの環境（macOS/arm64、Windows/x64、Ubuntu glibc/x64）すべてでの、コンパイルなしの正式な npx 検証。実施したのは単一マシンでのスモークテストのみです。これとは別に、CI 外で一度だけ手動実行（2026-07-24）し、Node 22 をインストールした Ubuntu 24.04 glibc/x64 上で [email protected] を匿名でインストールしました。コンパイルせずに better-sqlite3 が事前ビルド済みバイナリから解決されること、初期化、8つすべてのツール、JSON-RPC のみを標準出力する explore_universities 呼び出しを確認しました。これは記録された観測結果であり、正式な環境別検証の証明ではありません。macOS/arm64 と Windows/x64 は未検証です；
• レシートに紐付いた候補→クライアント→昇格の証拠チェーン、および実際のクライアント（Claude Desktop）のレシート；
• 承認済みの自動ダウンロード公式リンク、または完了済みの年次更新。

このパッケージに含まれるバックエンドは [email protected] のみです。メンテナーの Node 22 macOS/arm64 環境、および上記の一度限りの手動実行を行った Ubuntu 24.04 glibc/x64 環境では、事前ビルド済みバイナリからインストールされます。3環境すべてで事前ビルド済みバイナリのみを使用するマトリックスは、独立した検証を完了していません。含まれるバックエンドは正確に1つです。

要件

Node >=22 <23 を使用してください。Node 24 以降はサポート対象ではなく、サポートを主張していません。公開サポートマトリックスは、以下の Node 22 環境に限定されています。

• macOS/arm64；
• Windows/x64；
• Ubuntu glibc/x64。

これらの環境は、公開インストールの証拠を収集するまでは対象環境です。ローカルでの成功は、公開サポートの証拠にはなりません。

ローカルチェックアウトでの利用

実装されたローカルでの動作は、チェックアウトから実行できます。

npm install
npm run build
node dist/src/index.js

最後のコマンドは、MCP stdio サーバーを起動します。対話型シェルは提供しません。MCP プロトコルの出力は stdout に書き込まれ、診断情報は stderr に出力されます。

API キーの環境変数は必要ありません。ACADEMYINFO_DB_PATH を指定すると、互換性のある別のローカルデータベースを選択できます。指定しない場合は、同梱のシードデータが使用されます。実行時のツールはデータベースに書き込まず、外部サービスにも接続しません。 この開発用チェックアウトでは、npm run doctor、npm run refresh:acquire-validate、npm run refresh:verify-artifact が定義されています。コンパイル済みプログラムがパッケージ化された npm アーティファクトに含まれるのは doctor のみです。これはローカルのパッケージ／データ／ランタイム診断であり、一般公開されたインストール、バックエンドの選択、更新の受け入れ、リリースの承認を証明するものではありません。コンパイル済みの更新プログラム、その TypeScript ビルドソース、および必要な開発依存関係はパッケージから除外されるため、どちらの更新コマンドもチェックアウト専用の保護されたワークフロー内部機能であり、インストール済みパッケージでサポートされるコマンドではありません。ローカルで直接実行しても、権威ある取得、書き込み、またはリリースの証明記録にはなりません。

リモートエンドポイント（Streamable HTTP、チェックアウト専用）

npm パッケージは引き続き stdio のみをサポートします。チェックアウト（またはそこからビルドされたコンテナイメージ）では、claude.ai のカスタムコネクターなどのリモート MCP クライアント向けに、ステートレスな Streamable HTTP エントリーポイントも提供されます。

npm run build
PORT=8080 ALLOWED_HOSTS=<public-host> npm run start:http

• POST /mcp は、1 回の呼び出しにつき 1 件の JSON-RPC MCP リクエストを受け付け、JSON レスポンスを返します。各リクエストで新しいサーバーインスタンスが実行されるため、GET（SSE ストリーム）と DELETE（セッション）は提供されません。
• GET /healthz と GET /health は、デプロイのヘルスチェックに対して 200 ok を返します（Cloud Run の run.app ドメインでは Google のフロントエンドが文字列どおりの /healthz パスを消費するため、外部のプローブでは /health を使用する必要があります）。
• ALLOWED_HOSTS（カンマ区切り）を設定すると、DNS リバインディング保護が有効になります。信頼できるプロキシの背後にある場合に限り、未設定のままにしてください。
• dist/src/http.js は npm パッケージから除外されるため、インストール済みの npx academyinfo-mcp の動作に変更はありません。

リモートデプロイでは、同じ帰属表示と免責の範囲に基づき、同じ特定時点のスナップショットが提供されます。これはライブフィードではなく、最新データを保証するものでもありません。また、運営者は教育部、KCUE、KEDI、data.go.kr、academyinfo.go.kr、またはいずれの大学とも関係ありません。

バージョンの固定

クイックスタートでは、バージョンを指定しない academyinfo-mcp を使用します。これは現在の latest（現在は 0.4.0）に解決されます。特定のバージョンに固定するには、args で [email protected] を使用します。Cursor と Codex は、Claude Desktop の例と同じ command／args の形式を使用します。これらは設定例として記載されており、MCP stdio では同じように動作します。

正確に8つのツールを対象とします

1. list_sources
2. list_indicators
3. search_university
4. get_university_metrics
5. compare_universities
6. explain_indicator
7. validate_source_coverage
8. explore_universities

最初の7つのコントラクトは、引き続き後方互換性を保ちます。クライアントとの互換性のため、tools/list は、次の厳密にこのとおりの寛容な Draft-07 外部入力スキーマで explore_universities を登録します。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "university_queries": {},
    "indicators": {}
  },
  "additionalProperties": {}
}

登録されるスキーマには意図的に required キーワードがなく、両方のプロパティスキーマと additionalProperties は空のスキーマです。これは検出の境界にすぎず、ハンドラーでは別途、厳格な内部検証を適用します。ハンドラーは university_queries を必須とし、トップレベルの不明なフィールドを拒否します。また、1～120 Unicode コードポイントの、トリミング済みで重複のないクエリー文字列を1～10件受け付け、任意の indicators 配列には、対応している空でないインジケーター ID を重複なく最大5件まで受け付けます。無効な入力は、ジャーニーの評価前に失敗します。

有効な explore_universities リクエストは、1つのローカルな読み取り専用スナップショットに対して解決されます。処理は全件成功か全件失敗かのいずれかです。大学が見つからない場合や曖昧な場合、指標、比較、説明の一部だけが返されることはありません。曖昧な一致では、リポジトリ順で最大20件の候補が返され、いずれかが選択されることはありません。このツールは指標値で順位付けしたり、ユーザーの選択を代行したりしません。

成功したすべての値または説明には、出典とライセンス情報、年または基準年、単位、出典列、派生値／バンドル済みの区別、および警告が保持されます。出典の値が欠落している場合は、推測せず、明示的に欠落として扱います。

指標とデータの境界

カタログには、バンドルされたデータセット 15118998 からの指標がちょうど17件含まれています。

指標	ラベル	スナップショットの年	単位
competition_rate	신입생 경쟁률	2025	:1
fill_rate	신입생 충원율	2025	%
employment_rate	취업률	2025	%
scholarship_per_student	학생 1인당 연간 장학금	2025	원
avg_tuition	평균 등록금	2026	천원
admission_quota	입학정원	2025	명
graduates_count	졸업생수	2025	명
fulltime_faculty_count	전임교원수(학부+대학원)	2025	명
enrolled_students	재학생	2025	명
international_students	외국인 학생 수	2025	명
students_per_fulltime_faculty	전임교원 1인당 학생 수(학생정원기준)(학부+대학원)	2025	명
fulltime_faculty_ratio_quota	전임교원 확보율(학생정원기준)(학부+대학원)	2025	%
fulltime_faculty_ratio_enrolled	전임 교원 확보율(재학생 기준)(학부+대학원)	2025	%
fulltime_faculty_lecture_ratio	전임교원 강의 담당 비율	2025	%
education_expense_per_student	학생 1인당 교육비(학부+대학원)	2025	천원
dormitory_capacity_rate	기숙사 수용율(학부+대학원)	2025	%
books_per_student	학생 1인당 도서 자료 수(학부+대학원)	2025	권

これらの日付は、現在バンドルされている時点スナップショットを示すものであり、ライブフィードや最新データを保証するものではありません。カタログは JSON データであり、閉じた静的スキーマで検証され、データライセンスのもとでパッケージ化されています。実行可能なソースコードから生成されるものではありません。データベース、マニフェスト、カタログは、それぞれ独立して相互検証されます。

率、比率、学生1人当たりの指標で値が厳密に 0 の場合、値として提供されません。代わりに、出典のテキストを保持したまま、zero_not_aggregatable として missing_metrics に含められます。このようなセルはプレースホルダーと区別できず、そのままでは平均値に気づかれずに含まれてしまうためです。在籍人数のゼロは、実際に該当者がいない機関もあり得るため、注記付きで提供されます。根拠と未解決の問いについては、docs/zero-values.md を参照してください。

データセット 15139279 はバンドルされておらず、有効化、サンプリング、正規化もされていません。また、デフォルトの就職結果にも使用されません。ライブ OpenAPI アクセス、スクレイピング、詳細な就職関連の挙動は、このリリースの対象外です。

更新の安全性に関する概要

更新の承認は意味的な検証に基づくものであり、固定されたチェックサムや列数に基づくものではありません。取得処理は読み取り専用で、固定パスへのリポジトリ書き込み処理とは分離されています。更新では、インデックス化された生データのセルを保持し、以下を証明する必要があります。

• 公式のソース、ワークブック、ライセンスの識別情報
• 一意な識別情報のマッピングと、17 個の論理指標それぞれに対する一意なマッピング
• 検証済みの固定単位と、減少しない整数の年
• 行の完全な網羅性：すべてのソース行を一度ずつマッピングし、17 個の数値または欠損の分類を行うこと
• 欠損値として認められるのは、前後の空白を除去した空文字列または ASCII の - のみ
• 丸めを行わず、非負の小数を正確に解析し、往復変換の安全性を確保すること

ダウンロード後の SHA-256 は、整合性、変更、監査の証拠としてのみ使用します。すべての意味的不変条件を満たせば、チェックサム、機関の集合、値、許容される欠損値、無関係な列が変更されていても、有効な 24 列または 26 列のワークブックであっても更新を承認できます。以前のチェックサムとの一致は、ソースの真正性を証明するものではありません。docs/refresh-release-runbook.md を参照してください。

自動取得は現在 DOWNLOAD_LINK_MISSING で停止します。確認済みの正規ページにはアクセスでき、ライセンスも検証できますが、匿名で取得可能なダウンロードリンクは公開されていません。また、ポリシーにより、エンドポイントの推測や代替手段としてのスクレイピングは禁止されています。そのため、更新は手動で実施します。詳しくは docs/manual-refresh.md を参照してください。

鮮度とリリースの動作

更新インシデントの初回検知時刻は変更できず、期限は 7 日間（604800000 ms）です。メタデータ、ETag、または失敗の繰り返しによる変化で期限がリセットされることはありません。無効な公式タイムスタンプは、信頼できる時刻として扱われません。

• 再取得したバイト列が同一でも、オリジン、ライセンス、ワークブックの検証が完了し、管理者が変更なしを証明するレシートを承認した後でなければ、インシデントをクローズできません。
• バイト列が異なる場合は変更ライフサイクルに入り、一致するリリースデータダイジェストが latest に昇格した場合にのみクローズします。
• 検証またはリリースに失敗した場合も、最後に正常と確認されたデータと公開バージョンを引き続き提供します。
• ロールバックすると、元の変更イベントの期限計測が再開されます。修正リリースには新しい SemVer を使用します。

候補版の公開は完了を意味しません。管理者が承認した昇格を行う前に、公開マトリックスの証拠と、実際の Claude Desktop/macOS での証拠を保護されたレシートにまとめる必要があります。ロールバックでは、以前の latest を復元し、不適切なバージョンを非推奨にし、証拠を保持します。また、該当する場合はインシデントを再開します。 候補版の公開、昇格、ロールバックでは、いずれも cancel-in-progress: false を指定した academyinfo-mcp-registry-mutation 同時実行グループを通じて、npm レジストリへの変更処理を直列化します。昇格後は、アップロードされた変更処理後の promotion.v1.json を保持し、ロールバックを実行可能にする前に、保護された不変のデフォルトブランチ上の証拠コミット evidence/releases/<version>/promotion.v1.json にバイト単位で同一の内容を保存する必要があります。ロールバック後も、アップロードされた変更処理後の rollback.v1.json を同様に保持し、evidence/releases/<bad_version>/rollback.v1.json にバイト単位で同一の内容を保存する必要があります。

公開インストールの証明境界

ローカルインストールやローカル tarball は、公開受け入れの要件を満たしません。各公式レーンでは、チェックアウトの外部にある新しいホーム、キャッシュ、作業ディレクトリ、設定を使用し、明示的な公開レジストリを指定し、到達可能なローカルアーティファクトが存在しない状態で、正確に次を使用する必要があります。

npx -y academyinfo-mcp@<version>

証明には、インストールされたアプリケーションと、完全な本番用直接依存関係セット（現在の単一バックエンドパッケージでは @modelcontextprotocol/[email protected]、[email protected]、[email protected]、[email protected]）、各レジストリの整合性情報、候補タグと来歴／署名の証拠、Node／OS／アーキテクチャ（Ubuntu では glibc も含む）、有効な Python／node-gyp／コンパイラーのトラップと、実証済みのカナリア、詳細なサニタイズ済みインストールログ、初期化、正確な 8 つのツール一覧と explore_universities のスキーマ、バンドルデータへのクエリ、キーなしでの動作、JSON-RPC のみを出力することを記録する必要があります。バックエンドを別のものに置き換える場合は、別途承認が必要であり、検証ツールとこの閉じた依存関係セットを同時に変更する必要があります。いずれかのレーンでネイティブコードがコンパイルされる、別の直接依存バージョンが解決される、ローカルパッケージに到達する、または必要な証拠が欠ける場合、昇格は禁止されます。

管理者の前提条件

候補の公開前に、管理者は npm パッケージの識別情報／履歴と所有権を確立し、未使用の SemVer を選択して、2FA／信頼された公開と来歴の準備状況を確認し、必須の承認とアーティファクトの保持を設定した保護環境 refresh-pr-writer、npm-candidate、public-candidate-proof、claude-desktop-client-proof、npm-promotion、npm-rollback のみを構成する必要があります。また、保護された ACADEMYINFO_RELEASE_ADMINISTRATOR をレシートの権限主体として正確に定義し、レビュー済みの現行検証ポリシーに基づいて ACADEMYINFO_PUBLIC_INSTALL_VERIFIER_SHA256 と ACADEMYINFO_RELEASE_RECEIPT_VERIFIER_SHA256 を定義する必要があります。管理者は単一バックエンドのゲートを解決し、別個の権限境界において、不変の候補、クライアント証明、昇格、および必要に応じてロールバックの各レシートを承認する必要があります。保護された検証ツールの呼び出しでは、設定済みの権限主体とレビュー済みの検証ツールのバイト列を常にバインドします。レシートに記載された識別情報も、呼び出し側が選択した過去のコードも、権限の根拠にはなりません。リポジトリ内の文書がバージョンを選定したり、これらの承認を付与したりすることはありません。

サポート

このプロジェクトは現状のまま公開されており、サポートはありません。Issue、質問、機能リクエストは監視されておらず、通常は返信されません。また、可用性、データの鮮度、応答時間に関するサービスレベルはありません。これは、1 人が可能な範囲で保守する個人のオープンソースプロジェクトであり、いかなる機関によっても運営されていません。

以下のライセンスのもとで自由にご利用ください。変更が必要な場合は、フォークしていただけます。 質問への回答がないことや、欠陥にパッチが適用されないことが問題となる用途では、このプロジェクトに依存しないでください。

ライセンスとプライバシーの境界

• コードは MIT ライセンスです（LICENSE）。
• バンドルされている 15118998 データは、KOGL Type 1 の帰属表示要件に基づく正規化された派生物です（DATA_LICENSE.md、NOTICE.md、data/seed/LICENSE.15118998.md）。コードとデータのライセンスは別々です。
• リリースアーティファクト、レシート、ログ、エラー、サンプル、MCP の応答に、認証情報、サービスキー、署名付きクエリ文字列、ローカルユーザー名、マシン識別子、非公開のファイルシステムパスを含めてはなりません。
• 元のワークブックと署名付きダウンロード URL は、パッケージの内容物ではありません。

規範となる適用範囲とゲートは、リポジトリ内の PROJECT_CHARTER.md、NON_GOALS.md、RELEASE_CHECKLIST.md で管理されています。