Korean University Disclosure Indicators (대학알리미)

academyinfo-mcp

English | 한국어

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。与本地形式使用相同的随附快照和相同的八个工具。

这是一个按现状提供的个人部署：它可能随时停止提供，且不受任何可用性保证的保障（参见支持）。对于需要复现的工作，建议使用本地形式并固定版本 — [email protected]。

关于粘贴对象格式的更多信息，包括不应放入其中的传输字段，请参阅 examples/。

试试看

可以向助手提出类似这样的问题：

“请比较全南大学和釜山大学的就业率和竞争率。”

服务不会猜测有歧义的名称。“全南大学”匹配两个校区，因此第一次调用 explore_universities 会返回 status: "ambiguous" 及候选结果，而不是表格：

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

选择一个校区后再次提问（助手通常会自行进行后续提问）：

“请比较全南大学本校和釜山大学。”

第二次调用会返回 status: "ok"，并附上每所院校的数值、来源、年份和单位 — 例如（随附的 2025 年快照）：

大学	就业率	新生竞争率
全南大学本校	57.6%	7.4:1
釜山大学	57.5%	9:1

这种两步流程是预期行为，并非失败：遇到有歧义的名称时，服务会返回候选校区，而不会自行猜测；比较结果也绝不会进行排名、评分或选出赢家 — 数值会连同来源信息如实呈现，由你自行判断。

证据范围内的状态

在此检出版本中已实现：

• 一个以文件为先、离线、只读的 stdio 服务，由随附的 15118998 衍生数据库提供支持；
• 恰好注册了八个 MCP 工具（七个旧版工具加上 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 包中），并为全部八个工具添加了 readOnlyHint/openWorldHint 注解；同时提供打包的 stdio 入口点。

已发布：[email protected] 已在公共 npm 注册表（latest）上线，发布工作由人工在隔离的终端流程中完成（docs/manual-publish-runbook.md）。初始版本 0.1.0 已通过匿名 npx -y [email protected] 安装进行了冒烟验证，该安装会解析到确切的注册表 tarball 并列出全部八个工具；后续版本（0.1.1、0.1.2、0.2.0、0.3.0、0.3.1、0.4.0）均遵循同一运行手册。

尚未执行（对于首次个人发布而言，这是有意且适度的安排）：

• 在三个官方 Node 22 环境（macOS/arm64、Windows/x64、Ubuntu glibc/x64）中完成正式的无需编译 npx 验证——目前只进行了单机冒烟测试。另有一次性手动运行（2026-07-24，在 CI 之外）在安装了 Node 22 的 Ubuntu 24.04 glibc/x64 上匿名安装了 [email protected]，通过预编译二进制文件解析了 better-sqlite3，无需编译，并验证了初始化、全部八个工具，以及一次 explore_universities 调用的 stdout 仅包含 JSON-RPC 内容；这是记录在案的观察结果，并非正式环境验证，macOS/arm64 和 Windows/x64 仍未验证；
• 绑定收据的 candidate→client→promotion 证据链，以及实际客户端（Claude Desktop）的收据；
• 获批的官方无人值守下载链接，或已完成的年度刷新。

此包仅将 [email protected] 作为后端。它可在维护者的 Node 22 macOS/arm64 环境中通过预编译二进制文件安装，在上述一次性手动运行的 Ubuntu 24.04 glibc/x64 环境中也可如此安装；但完整的三个环境预编译专用矩阵尚未经过独立验证。此包恰好包含一个后端。

要求

请使用 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 服务。它不提供交互式 shell。MCP 协议输出写入 stdout；诊断信息必须保留在 stderr。

无需 API 密钥环境变量。ACADEMYINFO_DB_PATH 可用于选择其他兼容的本地数据库；否则将使用捆绑的种子数据。运行时工具不会写入数据库，也不会联系外部服务。 此开发检出版本定义了 npm run doctor、npm run refresh:acquire-validate 和 npm run refresh:verify-artifact。只有 doctor 的编译程序包含在打包后的 npm 工件中，它用于本地程序包／数据／运行时诊断；不能证明公开安装、后端选择、刷新验收或发布批准。编译后的刷新程序、其 TypeScript 构建源文件和所需的开发依赖都不包含在程序包中，因此两个刷新命令都是仅限检出版本使用的受保护工作流内部命令，并非受支持的已安装程序包命令。直接在本地调用绝不能作为权威的采集、写入或发布凭证。

远程端点（Streamable HTTP，仅限检出版本）

npm 程序包仍仅支持 stdio。检出版本（或从中构建的容器映像）还提供无状态的 Streamable HTTP 入口，供 claude.ai 自定义连接器等远程 MCP 客户端使用：

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

• POST /mcp 每次调用接受一个 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 行为不变。

远程部署提供相同的捆绑时点快照，并遵循相同的署名和免责声明界限：它不是实时数据源，也不保证数据为最新；运营方仍与 Ministry of Education、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 的行为完全相同。

精确的八个工具范围

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

前七项契约保持向后兼容。为兼容客户端，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–10 个不重复、已去除首尾空白且长度为 1–120 个 Unicode 码点的查询字符串，并接受可选的 indicators 数组，其中最多包含五个不重复且受支持的非空指标 ID。输入无效时，会在评估任何查询流程之前失败。

有效的 explore_universities 请求会根据一个本地只读快照进行解析。处理结果要么完整返回，要么全部不返回。找不到大学或匹配不明确时，不会返回部分指标、比较结果或说明。对于不明确的匹配，会按仓库顺序最多返回 20 个候选项，且绝不会擅自选定其中一个。该工具不会按指标值排序，也不会代替用户做出选择。

每个成功返回的数值或说明都会保留来源和许可证信息、年份或基准年份、单位、来源列、派生／捆绑状态以及警告。缺失的来源值会明确标示，而不会被推断。

指标与数据边界

目录包含来自捆绑数据集 15118998 的恰好 17 个指标：

指标	标签	快照年份	单位
competition_rate	新生竞争率	2025	:1
fill_rate	新生录取率	2025	%
employment_rate	就业率	2025	%
scholarship_per_student	学生人均年度奖学金	2025	원
avg_tuition	平均学费	2026	천원
admission_quota	招生名额	2025	명
graduates_count	毕业生人数	2025	명
fulltime_faculty_count	专任教师人数（本科＋研究生院）	2025	명
enrolled_students	在校生	2025	명
international_students	外国留学生人数	2025	명
students_per_fulltime_faculty	专任教师人均学生数（按学生定员计算）（本科＋研究生院）	2025	명
fulltime_faculty_ratio_quota	专任教师配备率（按学生定员计算）（本科＋研究生院）	2025	%
fulltime_faculty_ratio_enrolled	专任教师配备率（按在校生计算）（本科＋研究生院）	2025	%
fulltime_faculty_lecture_ratio	专任教师授课比例	2025	%
education_expense_per_student	学生人均教育经费（本科＋研究生院）	2025	천원
dormitory_capacity_rate	宿舍容纳率（本科＋研究生院）	2025	%
books_per_student	学生人均图书资料数（本科＋研究生院）	2025	권

这些日期描述的是当前捆绑的时间点快照，不代表实时数据流，也不保证是最新数据。该目录是 JSON 数据，经过封闭静态架构验证，并根据数据许可证打包；它不是生成的可执行源代码。数据库、清单和目录会分别进行交叉核对。

比率、比例或人均指标中的精确 0 不会作为数值返回。它会以 zero_not_aggregatable 的原因出现在 missing_metrics 中，并保留来源文本，因为无法区分此类单元格究竟是真实值还是占位符，否则就会在无人察觉的情况下被纳入平均值。人数为零时会返回并附注，因为某个机构确实可能没有相关人员。证据和待解决问题见 docs/zero-values.md。

数据集 15139279 不会被捆绑、启用、抽样、规范化，也不会用于默认的就业结果。实时 OpenAPI 访问、网页抓取和细粒度就业行为不在此版本的范围内。

刷新安全摘要

刷新审批基于语义，而非冻结的校验和或固定的列数。数据获取为只读操作，并与固定路径的仓库写入器分离。刷新必须保留已索引的原始单元格，并证明：

• 官方来源、工作簿和许可证的身份；
• 唯一的身份映射，以及十七个逻辑指标各自唯一的映射；
• 固定且已验证的单位，以及非递减的整数年份；
• 精确的行覆盖：每个来源行恰好映射一次，并分类为十七个数值或缺失项；
• 仅当文本经去除首尾空白后为空，或为 ASCII - 时才视为缺失值；
• 精确的非负十进制解析和往返安全性，不进行舍入。

下载后的 SHA-256 仅作为完整性、变更和审计证据。只要所有语义不变量均满足，即使校验和、机构集合、数值、允许的缺失情况、无关列发生变化，或工作簿有有效的 24/26 列，也可以通过。校验和与之前相同并不能验证来源。请参阅 docs/refresh-release-runbook.md。

自动数据获取目前会停在 DOWNLOAD_LINK_MISSING：已审核的规范页面可以访问，且其许可证已验证，但页面没有提供可匿名获取的下载链接，而政策禁止猜测端点或抓取替代内容。因此，刷新需手动执行——请参阅 docs/manual-refresh.md。

新鲜度和发布行为

刷新事件具有不可变的首次发现时间和七天（604800000 毫秒）的截止期限；元数据、ETag 或重复失败所产生的偏移不会重置该期限。无效的官方时间戳不会被视为可信时间。

• 只有在验证来源、许可证和工作簿，并取得管理员证明的无变化验证回执后，重新获取的相同字节才可关闭事件。
• 不同字节会进入变更生命周期，只有在匹配的发布数据摘要提升为 latest 后才会关闭。
• 验证或发布失败时，继续提供最后已知良好的数据和公开版本。
• 回滚会重新开启原始变更事件的计时；修正后的发布使用新的 SemVer。

候选版本发布并不代表流程完成。必须将公开矩阵证据与实际的 Claude Desktop/macOS 证据整合到受保护的回执中，才能进行管理员批准的提升。 候选版本发布、提升和回滚都会通过 academyinfo-mcp-registry-mutation 并发组串行执行 npm 注册表变更，并设置 cancel-in-progress: false。提升后，必须保留上传的变更后 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／操作系统／架构（以及 Ubuntu 上的 glibc）；已启用的 Python／node-gyp／编译器陷阱和经演示验证的金丝雀；经过脱敏的详细安装日志；初始化；准确的 8 个工具列表和 explore_universities 架构；捆绑数据查询；无密钥时的行为；以及仅通过 stdout 输出 JSON-RPC。经单独批准的后端替换，必须同时更改验证器和此封闭依赖集合。如果任何流程编译了原生代码、解析到其他直接依赖版本、访问了本地软件包，或缺少必需证据，则禁止晋级。

管理员前提条件

发布候选版本之前，管理员必须确认 npm 软件包的身份／历史记录和所有权，选择未使用过的 SemVer 版本，确认双重身份验证／可信发布及来源证明已就绪，准确配置以下受保护环境，并设置所需审批和制品保留：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。管理员必须解决单后端门槛，并在各自独立的权限边界批准不可变候选版本、客户端证明、晋级以及任何回滚收据。每次受保护的验证器调用都会绑定已配置的授权身份和经过审核的验证器字节；收据提供的身份和调用方选择的历史代码均不具备授权资格。没有任何仓库文档会指定版本或授予这些批准。

支持

本项目按原样发布，不提供支持。我们不会监控问题、疑问和功能请求，通常也不会回复；对于可用性、数据时效性或响应时间，不提供服务级别承诺。这是由一人尽力维护的个人开源项目，并非由任何机构运营。

欢迎根据以下许可证使用本项目；如果需要修改，也欢迎 Fork。 请勿将其用于以下场景：若问题无人回复或缺陷未修复，将造成重要影响。

许可证和隐私边界

• 代码采用 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 维护。