内容
# 工具列表
**KOICA 现行规定 149个 MCP搜索·查询.** 韩国国际合作团内部规定查询 + 正文直接查询 + 引用验证(标题幻觉验证) + 相互引用图表 + **规定整备雷达**，适用于MCP兼容客户端(Claude Desktop·claude.ai·Claude Code·Codex·Cursor等)。规定原文从 [ALIO(公共机构经营信息公开系统)](https://www.alio.go.kr/item/itemOrganList.do?apbaId=C0146&reportFormRootNo=21110) **自动同步**。
[](https://modelcontextprotocol.io)
[](LICENSE)
## 🚀 立即使用 — 无需安装
**这是已经部署的远程MCP服务器。** 无需 `clone`·`pip`·`build`，只需在使用的客户端注册以下URL即可：
```
https://koica-reg-mcp.fly.dev/mcp
```
| 客户端 | 注册方法 |
|---|---|
| **Claude Desktop / claude.ai (网页)** | 设置 → 连接器 → *自定义连接器添加* → "远程MCP服务器URL"中输入以上地址 |
| **Claude Code** | `claude mcp add --transport http koica-reg https://koica-reg-mcp.fly.dev/mcp` |
| **Codex** | `codex mcp add koica-reg --url https://koica-reg-mcp.fly.dev/mcp` |
注册·重启后，可以用自然语言询问规定 — 例如： *"KOICA晋升加分规定找给我"*， *"人事规定第11条给我"*。公开服务器无需认证·令牌。
> 🛠️ **如果您不需要直接修改源码，`git clone`不是必须的。** 只有在开发或贡献时才需要克隆和构建（→ 以下[快速开始](#快速开始)的本地安装，以及[AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md))。
---
> KOICA员工在工作中可能会遇到 "这个人事规定在哪一条？" 的情况，此时可以通过AI助手用自然语言询问，立即得到准确的条款和原文。
---
## 解决什么问题
- **缩短查询时间** — 149个规定每次打开Ctrl+F查询变得更加高效，通过自然语言查询即可实现条款级别的搜索
- **始终保持最新版本** — 定期从ALIO的KOICA规定列表中自动收集并更新，确保 **最新修订版** 被索引
- **引用验证** — 报告·答案中引用的"{规定名称}第N条"会自动交叉验证其是否存在（防止LLM幻觉）
- **相互引用自动追踪** — 任何条款与实施细则·相关指南的引用关系通过双向图表展示
- **考试准备辅助** — KOICA招聘·晋升考试的应试者可以通过此工具验证自己的答案和依据条款
---
## 索引范围（现行规定149个，约6,392个条款 = 正文4,202 + 附则2,190）
从ALIO的KOICA规定列表(`apbaId=C0146`)中 **自动收集全部现行规定**。规定名称搜索是主要使用轴 — **规定名称(`source`) + 正文全文搜索**。
| 规定类型 | 规定数量 | 示例 |
|---|---|---|
| 规定 | 49 | 人事·劳工·薪酬·职制规定，会计规定，国家合作事业规定，采购及合同规定… |
| 指南 | 86 | 招聘业务处理指南，工作成绩评估指南，环境·社会安全防护实施指南… |
| 实施细则 | 11 | 人事规定实施细则，职制规定实施细则，全球研修事业规定实施细则… |
| 章程·标准·细则 | 3 | 韩国国际合作团章程，ODA专家资格管理标准… |
> 规定类型从规定名称中自动推导，可以作为`category`过滤器（可选），但大多数查询可以通过规定名称·正文搜索完成。
> 外部法律（公共机构运营法·国际开发合作基本法·国家公务员法等）不属于KOICA规定，此工具不涉及。相关外部法律可使用 [`korean-law-mcp`](https://github.com/chrisryugj/korean-law-mcp) 结合使用（以下"推荐工具"）。
---
## 快速开始
> ⭐ **最简单的方法 — 远程连接器（无需安装）：** Claude Desktop·网页版(claude.ai)的 *自定义连接器添加* → **"远程MCP服务器URL"** 栏输入 `https://koica-reg-mcp.fly.dev/mcp` 即可。无需Python·克隆·构建。
>
> - 提供工具8个：`search_regulation` · `get_article` · `verify_citation` · `find_references` · `compliance_radar` · `list_attachments` · `get_attachment` · `list_sources`
> - 管理工具（`update`·`sync_from_alio`）和考试题目（`find_questions`）在公开远程版中被排除 — 如果需要全部11个工具，请使用以下本地安装。
> - 服务器在闲置时会进入睡眠模式，因此如果一段时间未使用，连接可能会有几秒的延迟（重试后立即连接）。
> - 如果需要自行托管，请参考 `server_http.py`（FastMCP streamable-http）+ `Dockerfile`·`fly.toml`（Fly.io）。
以下是 **本地安装**（全部11个工具 + 直接ALIO同步）方法：
### 1. 安装
```bash
git clone https://github.com/amnotyoung/koica-reg-mcp.git
cd koica-reg-mcp
pip install -r requirements.txt
python3 koica_search.py build
```
构建完成后，`data/index.json`中会索引约6,392个条款 + 1,312个附件。（条款单独标记，与附则分开，查询时优先显示条款。）
### 2. 使用CLI直接使用
```bash
python3 koica_search.py search "人事委员会构成" --source 人事规定
python3 koica_search.py get "人事规定" "第11条"
python3 koica_search.py verify "人事规定第11条设立人事委员会"
python3 koica_search.py refs "职制规定" "第9条"
```
### 3. 连接到Claude Desktop
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"koica-reg": {
"command": "/opt/anaconda3/bin/python3",
"args": ["/绝对路径/koica-reg-mcp/koica_mcp_server.py"]
}
}
}
```
> `command`中填写`mcp`包安装的Python绝对路径（可通过`which python3`查看）。
重启Claude Desktop后，在输入框下方工具菜单中会出现`koica-reg`工具。
### 4. 连接到Codex（可选）
```bash
codex mcp add koica-reg -- /opt/anaconda3/bin/python3 /绝对路径/koica-reg-mcp/koica_mcp_server.py
codex mcp list
```
重启Codex后，`koica-reg`命名空间的工具将可见。
---
## 使用示例
```
"KOICA人事规定 채용 결격사유 알려줘"
→ search_regulation + get_article 自动调用，人事规定第19条全文返回
"这份报告中引用的条款是否存在？"
→ verify_citation，将每个引用分类为ok/not_found/unknown_source
"职制规定第9条引用的其他规定有哪些？"
→ find_references，返回传入图表（可视化）
"是否有规定滞后于修订后的母规定？"
→ compliance_radar，返回整备审查对象列表
"将KOICA规定从ALIO同步到最新版本"
→ sync_from_alio，从alio.go.kr获取最新版本并重新索引
```
---
## 11个工具
| 工具 | 输入 | 返回 |
|---|---|---|
| `search_regulation` | `query, category?, source?, limit?, fuzzy?, include_attachments?` | 条款级别搜索（`fuzzy`=音节bi-gram，`include_attachments`=包含附件） |
| `get_article` | `source, article` | 准确的条款全文 |
| `verify_citation` | `text` | 引用存在性验证 + **标题幻觉检测**（存在条款但标题错误 → `content_mismatch`） |
| `find_references` | `source, article, include_mermaid?` | 正向·反向引用关系（`include_mermaid`=流程图代码） |
| `compliance_radar` | `source?` | **规定整备雷达** — 检查实施细则·指南是否滞后于母规定的修订 |
| `list_attachments` | `source?, category?, kind?, include_deleted?` | 附件列表（行政处罚标准表，格式等） |
| `get_attachment` | `source, label` | 附件全文（例："附件1"， "[附件第3号格式]"） |
| `find_questions` | `query?, question_id?` | （可选）考试题目数据 + 自动映射依据条款 |
| `sync_from_alio` | `timeout_sec?` | **从ALIO重新收集现行规定 → 下载 → 提取 → 重建索引** |
| `update` | — | 通过`git pull + build`更新存储库，返回更改摘要 + 各OS重启指南 |
| `list_sources` | `category?` | 已索引的规定列表和条款数量 |
> `category`是规定类型（规定/实施细则/指南/标准/章程）过滤器。大多数查询可以通过规定名称·正文搜索完成。
---
## 规定整备雷达 (`compliance_radar`)
**"母规定已经修订，但实施细则/指南仍然是旧版本？"** — 规定管理员重复进行的整备检查，通过一次调用完成。各下属规定（实施细则·指南）的母规定的名称规则·第1条引用进行比较，检查修订日期并标记为整备审查对象。
```
compliance_radar() → 整备审查对象（示例）
⚠️ 薪酬峰值运营指南（2020.06.22）← 人事规定（2026.06.12） 母规定在~72个月后修订
⚠️ 招聘业务处理指南（2022.06.29）← 工作条例（2026.03.04） 母规定在~45个月后修订
⚠️ 职制规定实施细则（2026.01.19）← 职制规定（2026.06.12） 母规定在~5个月后修订
```
韩国地方条例整顿惯例（上级法修订追踪）移植到KOICA规定体系（规定 ↔ 实施细则 ↔ 指南）。
---
## 现行性维护 — 自动ALIO同步
规定会定期修订。该存储库通过三条路径保持最新。
### ① 自动（推荐）— GitHub Actions每周同步
`.github/workflows/alio-sync.yml` **每周**重新查询ALIO，获取最新版本并 **自动创建PR**（`auto/alio-sync`分支）。用户只需审查和合并PR即可 — 规定变更由人确认并反映是安全的。（main是分支保护对象，因此机器人不会直接推送到main。）
### ② 用户直接 — `sync_from_alio`工具 / CLI
如果立即需要最新版本，可以在Claude中请求"将KOICA规定同步到最新版本"（`sync_from_alio`工具），或在终端中：
```bash
python3 alio_sync.py # ALIO查询→下载→提取→重建索引
python3 alio_sync.py --fresh # 忽略缓存，从头开始
```
> 同步 **需要Node.js**（文档提取使用`npx kordoc`）。查询·搜索本身不需要。所有规定下载和提取需要几分钟。
### ③ 获取最新版本 — `update`
在Claude Desktop聊天中说"将KOICA工具更新到最新版本" → `update`工具自动执行`git pull + 重建索引`。如果仅数据更改，则无需重启即可立即反映；如果`.py`更改，则会输出OS特定的重启指南。
**同步管道** (`alio_sync.py`)：
`ALIO列表查询 → 各规定的现行版本解释 → HWP下载 → kordoc转换为Markdown → 格式A规范化 → data/extracted/*.md + sources.json → 索引重建`
---
## 数据结构
```
data/
├── extracted/ # 规定별 .md提取文本（类型_规定名称.md）
│ ├── 规定_人事规定.md
│ ├── 指南_招聘业务处理指南.md
│ ├── 实施细则_人事规定实施细则.md
│ └── 章程_韩国国际合作团章程.md
├── sources.json # 规定清单（名称·类型·修订日期·fileNo·origin）
├── index.json # 构建产物（gitignored）
└── _cache/ # 同步缓存：HWP·原始md（gitignored）
alio_sync.py # ALIO同步管道
koica_search.py # 索引·搜索引擎 + CLI
koica_mcp_server.py # MCP服务器（10个工具）
```
---
## 新增规定追加·错误报告
ALIO规定列表中新增的规定将自动同步并反映，因此无需单独请求。但是，**提取质量错误**（条款缺失·表格损坏等）或 **ALIO中不存在的文档** 新增问题请报告。
- [BUG·准确性报告](../../issues/new?template=bug-report.md)
- [规定相关请求](../../issues/new?template=regulation-update.md)
---
## 推荐工具
经常在KOICA规定中引用的外部法律（公共机构运营法，国际开发合作基本法，国家公务员法，贿赂禁止法等），如果需要更深入的了解，可以结合使用 [`korean-law-mcp`](https://github.com/chrisryugj/korean-law-mcp）。同时激活两个MCP后，Claude可以在自然语言查询中自动调用两者，实现 **一次查询KOICA规定 + 韩国法律集成答案**。
---
## 技术备忘录
- **搜索引擎**：纯Python + 标准库（依赖：`mcp`包）
- **同步**：`alio_sync.py` — ALIO REST（JSON）查询 + [`kordoc`](https://www.npmjs.com/package/kordoc)（HWP→Markdown，Node）+ 格式A规范化
- **macOS NFD字符分解** 自动规范化
- **支持两种提取格式**：Markdown格式（### 第N条）和平文PDF（第N条(...) ...）
- **搜索算法**：韩语停词去除 + 词频IDF加权子字符串匹配 + 音节bi-gram模糊匹配
- **附件·附件单独索引**：正文条款搜索中删除格式·标准噪音
- **索引缓存**：MCP服务器启动时将所有条款加载到内存，每个调用时重用
---
## 路线图
- [x] v1.0 — 条款级搜索，正文查询，引用验证，相互引用，考试题目映射
- [x] v1.2 — `update`工具：自然语言git pull + build
- [x] v1.3 — 音节bi-gram模糊匹配
- [x] v1.4 — 附件·附件单独索引 + `list_attachments`/`get_attachment`
- [x] v2.0 — **ALIO自动同步**：扩展为149个现行规定，`alio_sync.py`管道 + `sync_from_alio`工具 + 每周GitHub Actions。规定类型基于标签转换。
- [x] v2.1 — **规定整备雷达（compliance_radar）**：实施细则·指南 vs 母规定修订对比。`verify_citation`标题幻觉检测（`content_mismatch`）。`find_references`流程图输出。自动同步转换为PR方式（分支保护对应）+ kordoc版本固定。
- [x] v2.2 — **准确性大手术改进（v2.2）：嵌入式条款缺失修复（3,831→6,392 条款，+67%），附则命名空间分离以解决条款编号冲突，source 准确性优先（兄弟条款不混淆），verify 标题验证强化（幻觉检测未探·定义项误判修正），整备雷达规范化（未探 12→15）+no_parent 暴露，附件标签边界匹配。
- [x] v2.3 — **远程MCP服务器**（`server_http.py`，FastMCP streamable-http）：Fly.io 部署，无需安装即可通过一个连接器URL（`https://koica-reg-mcp.fly.dev/mcp`）访问。公开版显示8个读工具（管理/考试题目除外），本地stdio保留全部11个。
---
## 许可
- **代码**：MIT License（→ [LICENSE](LICENSE)）。Copyright (c) 2026 amnotyoung。
- **规定数据**（`data/extracted/*.md`等）：**不适用** MIT License。原版权归 **韩国国际合作团（KOICA）** 所有，KOICA通过 [ALIO 公共机构经营信息公开系统](https://www.alio.go.kr/item/itemOrganList.do?apbaId=C0146&reportFormRootNo=21110) 公告的资料按条款分类提取和规范化。依据《著作权法》第24条之2（公共作品自由使用）和公共数据使用。
