na-openapi-mcp

na-openapi-mcp

📈 使用量 — 最近 14 天查看 1 次（唯一用户 1）· 克隆 157 次（唯一用户 97）· 发布资产累计下载 94

_{2026-10-27 自动更新 · 完整历史记录见 docs/usage.csv。GitHub 流量统计仅提供 14 天的数据窗口，因此本仓库每天记录并累积数据。}

国会图书馆（National Assembly Library of Korea）资料检索 OpenAPI，可供 Claude 等 MCP 客户端直接使用的服务 + CLI。可搜索和采集图书、学位论文、国内外文章、国会会议记录、议案信息等 21 种数据库，并导出为 xlsx/csv/json/sqlite。

姊妹项目：nl-openapi-mcp（国立中央图书馆图书·灰色文献）· kci-openapi-mcp（学术论文·引用指数）· scienceON-mcp（KISTI 文献）

---

本工具特别关注的问题

① 对不支持的检索项，返回整个目录，而不是报错

这是此 API 最大的陷阱。综合检索在无法识别检索项名称时，不会拒绝请求，而是直接忽略整个检索词。

저자,오욱환      →  total=76          ← 정상
저자명,오욱환    →  total=13,097,591  ← 전체 DB. 오류도 경고도 없다

作者名 在高级检索中是有效名称，因此很容易误以为它不是拼写错误而使用。 照此检索会把 1,300 万条记录误认为是“搜索结果”。 → 本服务会通过白名单在调用前拒绝请求，并告知正确名称。

检索项	搜索 오욱환 的结果
全部 · 基本检索 · 资料名 · 作者 · 关键词	105 · 88 · 4 · 76 · 7
作者名 · ISBN · 发行年份 · 拼写错误	各 13,097,591（整个数据库）

② 防止静默截断

我们会始终通过元数据告知收到的结果是否完整，还是遭到了截断。

信号	含义	解决办法
truncated	在 max_records 处停止	提高上限即可解决
cap_hit	total > 可提取上限 — API 不会再返回更多结果	必须拆分检索式
early_stop_note	因无新增记录而提前结束	可能是响应重复或服务器异常
stopped_early_note	因预算耗尽，某些检索词甚至未能查询	提高 max_records
zero_yield_warning	检索项被接受，但始终返回 0 条	使用其他检索项
option_ignored_warning	年份筛选器被忽略（综合检索）	同时指定 dbname
ignored_search_warning	返回了整个目录的规模	检查检索项
toc_enrich_truncated_note	仅补充了部分目录候选项	提高 toc_max
toc_enrich_incomplete_note	有些目录查询失败	提高上限无济于事 — 请检查控制编号
toc_enrich_aborted_note	因配额或密钥问题而中止补充	提高上限反而会恶化 — 请查看 na_status

可提取上限为 pageno 最大 99 × page_size（实测）。默认值（1000）对应 99,000 条； 降低 page_size 也会相应降低上限 — 本服务会将这一点纳入报告。

③ 通过实测确认官方文档与实际情况不符之处

如果只依据文档（.hwp/.docx）开发，以下这些地方会悄无声息地出错。

项目	官方文档	✅ 实际情况
记录标签	<record>	<recode> — 按文档处理会导致未能提取任何记录，但 total 正常
<item> 子项顺序	value → name	name → value
控制编号字段名	controlno	제어번호
displaylines 上限	100	1000
认证密钥	（未提及）	必须将 Encoding 值直接拼接到 URL 中
高亮标记	（未提及）	在匹配字段中插入 <font color="red">

完整对照表和依据见 docs/NA_API_GUIDE.md。

---

安装

1) Claude Code / Claude Desktop（uvx — 推荐）

{
  "mcpServers": {
    "na": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rubatoyd/na-openapi-mcp", "na-mcp"],
      "env": { "NA_API_KEY": "발급받은_인증키" }
    }
  }
}

2) Claude Desktop .mcpb 一键安装

从发布页面下载并运行。 提供轻量版（na-openapi-mcp.mcpb，通过 uvx 运行）以及无需 Python 和 uv 的独立完整版本 （win-x64 · macos-arm64 · linux-x64）。

3) 本地开发

git clone https://github.com/rubatoyd/na-openapi-mcp
cd na-openapi-mcp
uv sync --all-groups
uv run pytest -q
uv run na status

4) 其他 MCP 客户端

默认使用 stdio 传输。需要 HTTP 时，请运行 na-mcp --transport streamable-http --host 127.0.0.1 --port 9126 （也支持环境变量 NA_MCP_TRANSPORT·NA_MCP_HOST·NA_MCP_PORT）。

---

认证密钥

在公共数据门户 data.go.kr 申请使用国会图书馆_资料检索服务 （数据集 15098174），即可获取认证密钥。开发账号的流量限额为每天 10,000 次。

要使用 na_detail·na_toc，还需同时申请详细信息查询服务（15098175）—— 认证密钥以账号为单位，因此同一个密钥即可使用。

NA_API_KEY=발급받은_키          # Decoding(원문) 권장
NA_API_KEY_ENCODED=            # Encoding 값만 있으면 이쪽에
NA_OS_TRUST=1                  # 교육망·사내망 SSL 인터셉션 대응(기본 1)

🔑 data.go.kr 会提供两种认证密钥：Encoding / Decoding。此 API 必须将 Encoding 值直接拼接到 URL 中（实测），如果通过库的 params= 传入，%2B 会被二次编码为 %252B，导致认证悄无声息地失败。无论输入哪种密钥，代码都会自动转换，无需担心。

---

MCP 工具

工具	用途
na_status	检查是否持有认证密钥 + 实际往返 1 次
na_search	搜索资料，同时返回截断信号
na_collect	合并搜索词进行并集收集 → xlsx/csv/json/sqlite。使用 toc_max 补充目录正文（默认关闭）
na_detail	查询 1 条控制编号的详细信息
na_toc	查询 1 条控制编号的目录
na_fields	搜索字段、dbname 有效值 + 实测依据（普查）

搜索词格式

格式为 搜索字段,关键词。用 | 连接即组成 AND 条件。

전체,교육불평등
전체,교육|자료명,불평등          ← AND

API 没有 OR（并集）语法，因此由 na_collect(terms=[…]) 实现。

统一搜索字段（7 种）：基本搜索 全部 资料名 作者 出版者 关键词 索书号

指定 dbname 后会切换为详细搜索，搜索字段词汇因 DB 而异 （学位论文 = 论文名·指导教授，国内文章 = 文章名，学术期刊·报纸 = 合并为一个字段的 收录刊名/报纸名）。 准确列表请通过 na_fields 查看。

---

CLI

na status
na fields                          # 검색항목·dbname 유효값 (--json 으로 census 전체)
na search "전체,교육불평등" --max-records 20
na search "저자명,양연동" --dbname 학위논문
na collect --terms "전체,교육불평등" "전체,교육격차" --max-records 2000

# 목차 본문까지 붙이기 — 건당 1회를 더 씁니다(기본 꺼져 있음). 본문은 json·sqlite 에만.
na collect --search "자료명,교육불평등" --dbname 일반도서 --toc-max 300 --formats json xlsx
na detail MONO12026000012887
na toc    MONO12026000012887

# 연도 범위는 상세검색의 option 으로만 걸립니다(통합검색에서는 무시됨)
na search "자료명,교육" --dbname 일반도서 --option "발행년도,2000|발행년도,2010"

---

响应字段

记录没有固定架构。它由 <item><name>·<value> 键值对组成，字段名称集合 因资料类型而异——仅标题字段就有 资料名（图书）/ 论文名（学位论文）/ 文章名（文章）/ 收录刊名/报纸名（学术期刊·报纸）/ 期刊名（电子期刊）/ 议题（会议记录）/ 议案名（议案信息）/ 翻译法令名 / 表图名 等不同名称。

已知名称会规范化为通用列，原始数据则原样保存在 raw 中。

需要注意的值（均为实测）：

• 说明文字可能出现在值的位置——E-BOOK 的 DDC 中，99.95% 的值为 仅可通过电子形式阅览。 规范化字段留空，名称保留在 placeholder_fields 中（原文保存在 raw 中）。
• 年份可能不是 4 位数字——201u（MARC 不确定年份）、空值、0。
• 即使 초록유무=Y，也无法获取摘要正文。 只有国会议案信息（제안이유 및 주요내용）和国会会议记录（내용）含有叙述性文本。
• 所有记录均无目录的资料类型：E-BOOK · 学术期刊、杂志 · 报纸 · 国外文章 · 视频资料。

启用目录补充（toc_max）时

目录未附带的原因有 5 种，每种原因对应的处理方法都不同。如果把它们混作同一种空值，就会错误地得出“此资料没有目录”的结论，因此 toc_status 列会逐行区分原因。

toc_status	含义	处理方法
ok	已获取正文	—
skipped	目录标记不是 Y，或没有控制编号——不调用	—（不消耗配额）
empty	响应正常，但没有正文 → 标记不准确	—
sentinel	正文重复出现 无目录信息	—
failed	查询失败	使用 na_toc 重新查询单条记录
not_attempted	因预算耗尽或中断而未调用	提高 toc_max

has_toc='Y' 但 toc_status='empty' 的记录是最重要的信号，因此这两列会并排显示。 正文（toc_text）仅包含在 json·sqlite 中——正文可能长达数千字，会超出 xlsx 单元格上限（32,767），也会使 csv 文件变得臃肿。

---

验证状态

• 209 项回归测试。 不仅固定解析器和收集器，也固定测量工具本身（tests/test_probe_instrumentation.py）——白名单来自探测器的输出，如果探测器悄然出错，该错误就会原样成为代码。CI 不仅运行测试，还会检查客户端能否实际启动——确认新依赖解析后存在 mcp.server.fastmcp、执行实际 stdio 握手、公开 6 种工具、无密钥时 CLI 能否启动，以及机密文件未被跟踪。
• 所有 API 事实均通过实际在线往返确认（未从文档或姊妹项目照搬）。 13 种资料类型的字段普查样本约 21,000 条。复现方式：scripts/probe_*.py。
• 详细依据和验证等级（✅ 实测 / 📄 文档依据 / ❓ 未验证）见 docs/NA_API_GUIDE.md。

---

许可证

MIT