koica-reg-mcp

# Tool List **149 KOICA regulations searchable and browsable with MCP.** Internal KOICA regulations are searchable + directly queryable + citation verifiable (including title hallucinations) + cross-reference graph + **Regulation Radar** for MCP compatible clients (Claude Desktop, claude.ai, Claude Code, Codex, Cursor, etc.). The original regulations are **automatically synchronized** from [ALIO (Public Institution Management Information Disclosure System)](https://www.alio.go.kr/item/itemOrganList.do?apbaId=C0146&reportFormRootNo=21110). [](https://modelcontextprotocol.io) [](LICENSE) ## 🚀 Quick Start — No Installation Needed **This is a pre-deployed remote MCP server.** No `clone`, `pip`, or `build` required. Just register the following URL in your client: ``` https://koica-reg-mcp.fly.dev/mcp ``` | Client | Registration Method | |---|---| | **Claude Desktop / claude.ai (Web)** | Settings → Connector → *Custom Connector* → enter the above URL in "Remote MCP Server 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` | After registration and restart, ask about regulations in natural language — e.g., *"Find KOICA promotion regulations"*, *"Show me Article 11 of the personnel regulations"*. No authentication or tokens are required. > 🛠️ **No need to clone if you don't plan to modify the source.** Cloning and building are only necessary for development and contributions (→ [Quick Start](#quick-start) for local installation and [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md)). ## What Problems Does It Solve - **Reduced Reference Time** — Instead of manually searching through 149 regulations with Ctrl+F, find results with a single natural language query. - **Always Up-to-Date** — Periodically collect and index the latest versions of KOICA regulations from ALIO. - **Citation Verification** — Automatically verify if cited regulations exist (preventing LLM hallucinations). - **Cross-Reference Graph** — Visualize bidirectional references between regulations. - **Exam Preparation** — Assist KOICA recruitment and promotion exam candidates in verifying their answers with relevant regulations. ## Indexing Scope (149 Current Regulations, Approximately 6,392 Articles) Automatically collect and index all current KOICA regulations listed on ALIO (`apbaId=C0146`). Designed for direct search by regulation name and full-text search. | Regulation Type | Number of Regulations | Examples | |---|---|---| | Regulations | 49 | Personnel, remuneration, and service regulations, accounting regulations, project regulations, procurement and contract regulations, etc. | | Guidelines | 86 | Recruitment guidelines, performance evaluation guidelines, environmental and social safeguard guidelines, etc. | | Enforcement Rules | 11 | Personnel regulation enforcement rules, organizational regulation enforcement rules, global training project regulation enforcement rules, etc. | | Articles of Association, Standards, and Rules | 3 | KOICA articles of association, ODA expert qualification management standards, etc. | > Regulation types are automatically derived from regulation names and can be used as a `category` filter. Most queries are sufficient with regulation name and full-text search. > External laws (Public Institution Operation Act, Basic International Development Cooperation Act, State Public Officials Act, etc.) are not part of KOICA regulations and are not covered by this tool. Use [`korean-law-mcp`](https://github.com/chrisryugj/korean-law-mcp) in conjunction for comprehensive coverage. ## Quick Start > ⭐ **Easiest Method — Remote Connector (No Installation):** Add a custom connector in Claude Desktop/Web (claude.ai) with the URL `https://koica-reg-mcp.fly.dev/mcp`. No Python, cloning, or building required. > > - 8 tools provided: `search_regulation`, `get_article`, `verify_citation`, `find_references`, `compliance_radar`, `list_attachments`, `get_attachment`, `list_sources` > - Management tools (`update`, `sync_from_alio`) and test questions (`find_questions`) are excluded from the public remote version — use local installation for all 11 tools. > - The server may have a delayed response if not used for a while due to automatic power saving. For local installation (all 11 tools + direct ALIO synchronization): ### 1. Installation ```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 ``` ### 2. CLI Usage ```bash python3 koica_search.py search "Personnel Committee Composition" --source Personnel Regulations python3 koica_search.py get "Personnel Regulations" "Article 11" python3 koica_search.py verify "Personnel Regulations Article 11 establishes a personnel committee" python3 koica_search.py refs "Organizational Regulations" "Article 9" ``` ### 3. Connect to 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": ["/absolute/path/koica-reg-mcp/koica_mcp_server.py"] } } } ``` ### 4. Connect to Codex (Optional) ```bash codex mcp add koica-reg -- /opt/anaconda3/bin/python3 /absolute/path/koica-reg-mcp/koica_mcp_server.py codex mcp list ``` ## Usage Examples ``` "Tell me KOICA personnel regulation disqualification reasons" → Automatically call `search_regulation` and `get_article`, return personnel regulation Article 19 text "Verify citations in this report" → `verify_citation`, classify each citation as ok/not_found/unknown_source "Find other regulations citing Organizational Regulation Article 9" → `find_references`, return incoming graph (visualizable with `include_mermaid`) "Check if there are outdated enforcement rules or guidelines" → `compliance_radar`, return a list of regulations for review "Synchronize KOICA regulations from ALIO" → `sync_from_alio`, re-collect and re-index the latest regulations from ALIO ``` ## 11 Tools | Tool | Input | Output | |---|---|---| | `search_regulation` | `query, category?, source?, limit?, fuzzy?, include_attachments?` | Article-level search (with fuzzy search and attachment inclusion options) | | `get_article` | `source, article` | Full text of an exact article | | `verify_citation` | `text` | Citation verification + **title hallucination detection** | | `find_references` | `source, article, include_mermaid?` | Bidirectional citation relationships (with optional mermaid visualization) | | `compliance_radar` | `source?` | **Regulation Radar** — Identify outdated enforcement rules and guidelines | | `list_attachments` | `source?, category?, kind?, include_deleted?` | List of attachments (e.g., tables, forms) | | `get_attachment` | `source, label` | Full text of an attachment | | `find_questions` | `query?, question_id?` | Test questions and corresponding regulations | | `sync_from_alio` | `timeout_sec?` | **Synchronize latest regulations from ALIO** | | `update` | — | Update repository and rebuild index | | `list_sources` | `category?` | List of indexed regulations | ## Regulation Radar (`compliance_radar`) **"Has a parent regulation been updated, but the enforcement rule or guideline has not?"** — Perform a one-call check to identify outdated regulations. ## Maintaining Currency — Automatic ALIO Synchronization Regulations are periodically updated. This repository maintains currency through: ### ① Automatic (Recommended) — Weekly GitHub Actions Synchronization `.github/workflows/alio-sync.yml` queries ALIO weekly, retrieves the latest versions, and creates a **PR for review** if changes are detected. ### ② Manual — `sync_from_alio` Tool / CLI ```bash python3 alio_sync.py # ALIO query → download → extraction → rebuild python3 alio_sync.py --fresh # Ignore cache and start from scratch ``` ### ③ Update — `update` Request a Claude Desktop user to update: `koica-reg-mcp` tool performs `git pull + rebuild`. **Synchronization Pipeline** (`alio_sync.py`): `ALIO List Query → Latest Version Retrieval → HWP Download → kordoc Markdown Extraction → Format A Normalization → data/extracted/*.md + sources.json → Index Rebuild` ## Data Structure ``` data/ ├── extracted/ # Regulation-specific .md extractions │ ├── Regulation_Personnel_Regulations.md │ ├── Guideline_Recruitment_Guidelines.md │ ├── Enforcement_Rules_Personnel_Regulation_Enforcement_Rules.md │ └── Articles_of_Association_KOICA_Articles_of_Association.md ├── sources.json # Regulation manifest (name, type, date, fileNo, origin) ├── index.json # Build output (gitignored) └── _cache/ # Synchronization cache: HWP, raw md (gitignored) alio_sync.py # ALIO synchronization pipeline koica_search.py # Indexing, search engine, and CLI koica_mcp_server.py # MCP server (10 tools) ``` ## Adding New Regulations / Reporting Errors Regulations listed on ALIO are automatically reflected. Report extraction quality issues or add missing documents via issues. - [Bug/Accuracy Report](../../issues/new?template=bug-report.md) - [Regulation Update Request](../../issues/new?template=regulation-update.md) ## Recommended Companion Tools For external laws frequently cited in KOICA regulations (e.g., Public Institution Operation Act, Basic International Development Cooperation Act, State Public Officials Act), use [`korean-law-mcp`](https://github.com/chrisryugj/korean-law-mcp) in conjunction. ## Technical Memo - **Search Engine**: Pure Python (dependencies: `mcp` package only) - **Synchronization**: `alio_sync.py` — ALIO REST(JSON) query + [`kordoc`](https://www.npmjs.com/package/kordoc) (HWP→Markdown, Node) + Format A normalization - **macOS NFD Unicode Normalization** - **Support for Two Extraction Formats**: Markdown (`### Article N`) and plain text PDF (`Article N(...) ...`) - **Search Algorithm**: Korean stopword removal + token IDF weighted substring matching + syllable bi-gram fuzzy matching - **Separate Indexing of Attachments**: Noise reduction in article search with tables and forms - **Index Caching**: Load all articles into memory at MCP server startup for reuse ## Roadmap - [x] v1.0 — Search by clause unit, main text inquiry, citation verification, cross-reference, and test question mapping - [x] v1.2 — `update` tool: git pull + build with natural language - [x] v1.3 — Syllable bi-gram fuzzy matching - [x] v1.4 — Separate indexing of annexes and appendices + `list_attachments`/`get_attachment` - [x] v2.0 — **ALIO automatic synchronization**: Expanded to 149 current regulations, `alio_sync.py` pipeline + `sync_from_alio` tool + weekly GitHub Actions. Switched to regulation type-based tagging. - [x] v2.1 — **Compliance Radar** (`compliance_radar`): Implementation rules and guidelines vs. main regulation revision comparison. `verify_citation` title hallucination detection (`content_mismatch`). `find_references` mermaid graph output. Switched to PR-based automatic synchronization (branch protection対応) + fixed kordoc version. - [x] v2.2 — **Major Accuracy Surgery** (reflecting adversarial review): Mass correction of inline main text clause omissions (3,831→6,392 clauses, +67%), separation of supplementary provisions (附則) namespace to resolve clause number conflicts, source exact match priority (blocking sibling regulation mix-ups), enhanced verify title verification (hallucination undetection and definition incorrect detection correction), compliance radar normalization (undetection 12→15) + no_parent exposure, and annex label boundary matching. - [x] v2.3 — **Remote MCP Server** (`server_http.py`, FastMCP streamable-http): Deployment on Fly.io for connection with a single connector URL (`https://koica-reg-mcp.fly.dev/mcp`) without installation. Public version exposes 8 tools (excluding management and test questions), while local stdio maintains all 11 tools. --- ## License - **Code**: MIT License (→ [LICENSE](LICENSE)). Copyright (c) 2026 amnotyoung. - **Regulation Data** (`data/extracted/*.md` etc.): Not subject to MIT License. The original copyright is owned by **Korea International Cooperation Agency (KOICA)**, and it is extracted and normalized from the data published by KOICA through [ALIO Public Institution Management Information Disclosure System](https://www.alio.go.kr/item/itemOrganList.do?apbaId=C0146&reportFormRootNo=21110) on a clause-by-clause basis. The basis for use is Article 24-2 (Free Use of Public Works) of the Copyright Act and public data use. The distinction between code and data, source, and disclaimer is summarized in [NOTICE](NOTICE). > ⚠️ This data is for reference and work assistance and does not guarantee accuracy. **Official and latest regulations with legal effect must be confirmed on [ALIO](https://www.alio.go.kr) or KOICA official channels**.