korean-bill-debate-mcp

# Korean Bill & Debate MCP > **Connecting fragmented National Assembly records into one legislative bill flow.** > This tool links the bill's content and processing status, subcommittee meeting minutes, expert reports, and lawmakers' and government officials' actual statements into a single investigative flow. `v0.7.0` · Korean-centered · Your own Open Assembly API key · Real-time search · Apache-2.0 [English](README.en.md) · [MCP Connection](docs/mcp-clients.md) · [Data Sources](docs/data-sources.md) · [Architecture](docs/architecture.md)  ## National Assembly information is publicly available, but answers are scattered Bill pages have processing status, committee pages have meeting information, and actual issues are buried in PDF meeting minutes and expert reports. Lawmakers' questions and government responses are separate, and multiple bills dealing with the same issue appear as separate documents. Korean Bill & Debate MCP connects these records through **bill-examination-person-speech-response-evidence** relationships. Users can ask questions in natural language and receive investigative results linked to official original texts. ### A single question answers the four axes of National Assembly investigation - **Where is it now?** — Latest bill status and committee/subcommittee examination stages - **Why is it stuck, and what are the issues?** — Subcommittee meeting minutes and expert reports - **Who said what?** — Lawmakers' and government officials' actual statements and preceding and following questions and responses - **What is the evidence?** — Official bill and meeting minutes URLs and original text locations The tool does not just list documents; it connects bills, meetings, people, speeches, and responses to provide verifiable investigative results. ## For those creating, responding to, and researching legislation inside and outside the National Assembly Different users need different answers depending on their work. This MCP allows **legislators, responders, and researchers** to directly link their questions to official evidence. | User | Required judgment | Directly connected evidence | |---|---|---| | National Assembly staff and aides | Examination preparation, issue consolidation, and query writing | Similar bills, subcommittee meeting minutes, expert reports, and ministry responses | | Corporate policy, legal, and government affairs teams | Regulatory direction and business impact, response timing | Latest status, lawmakers' concerns, government acceptance, and implementation issues | | Public institutions and associations | Responding to related bills and preparing official opinions | Related bills, committee discussions, stakeholder statements, and original text citations | | Civil society organizations | Legislative monitoring, opinion papers, and campaigns | Clause-specific issues, supporting and opposing statements, examination progress, and official meeting minutes | | Journalists | Statement verification, issue timelines, and fact-checking | Actual statements, preceding and following context, date-specific events, and source locations | | Researchers | Long-term and comparative policy change and discourse analysis | Structured bill-meeting-speech relationships and reproducible citations | ## Example queries ```text [Legislative examination] “Summarize similar bills, subcommittee issues, expert reviews, and ministry responses for this bill.” [Corporate response] “Where is the platform labor regulation bill, and what are the key issues affecting businesses?” [Civil society] “How has the victim protection clause changed during examination, and what opinions were expressed?” [Journalistic inquiry] “Compare opposing statements on the supplementary investigation authority abolition with context and official original text.” [Research] “Connect AI policy-related bills and committee discussions in a timeline and identify recurring issues.” [Bill tracking] “Find the latest processing status and connected meeting minutes and expert reports for bill 2219564.” ``` ## Returns an investigative flow, not just search results The MCP queries the official Open Assembly API when asked. It searches related bills and processing status, finds relevant committees and timelines, and downloads necessary official meeting minutes to restore speakers, queries, responses, and follow-up questions. ```text Natural language query → Real-time query of official bill and processing status → Confirmation and search of related expert reports → Exploration of related committees, plenary sessions, and subcommittees → Download and parsing of necessary meeting minutes → Connection of bill-meeting-person-speech-response → Return of official bill and meeting minutes URLs and original text locations ``` ## What experienced National Assembly staff see after processing status Experienced staff do not stop at processing status when tracking a bill's progress. They also review **subcommittee meeting minutes** and **expert reports**. ### 1. Subcommittee meeting minutes — Where did it actually get stuck? - Clause-specific pros and cons, amendments, and alternative proposals - Relevant ministry responses and acceptance status - Negotiation context leading to postponement, continued examination, and alternative reflection ### 2. Expert reports — What are the examination issues? - Legislative consistency and conflicts with other laws - Implementation feasibility, costs, and anticipated side effects - Key issues and necessary amendments for committee examination This MCP does not predetermine a bill's future. Instead, it connects bill status, subcommittee meeting minutes, expert reports, and lawmakers' and government officials' statements with official original text evidence. Expert reports are not mass-collected in advance. When a user queries a related bill, the tool checks and downloads the report PDF from the official bill information system and searches for necessary documents. Local installations store these in a personal cache to avoid re-downloading the same documents. ## What sets it apart - **Real-time priority** — Does not rely solely on prepared past snapshots; rechecks official bill and status APIs when queried. - **Searching for relationships, not documents** — Connects bills, meetings, people, speeches, and responses to restore the flow of the same issue. - **Preserves speech context** — Provides not just a single sentence but also preceding questions, government responses, and follow-up questions. - **Verifiable results** — Includes official URLs and original text locations for all citations, allowing users to verify directly. - **User-controlled data** — Uses individual Open Assembly API keys; web connections store no original keys, only personal tokens. ## Connecting to AI in 3 minutes This MCP does not require learning separate programs. Once connected, users can query as usual, and the tool will find the necessary official National Assembly records. ### Method 1: Using Claude.ai, ChatGPT on the web — No installation First, obtain your Open Assembly Information Open API key from [here](https://open.assembly.go.kr/portal/openapi/openApiNaListPage.do) and visit **https://korean-bill-debate-mcp.vercel.app** in your browser. 1. Enter your Open Assembly API key. 2. Click **Create personal MCP link**. 3. Copy the entire generated `https://.../mcp?token=...` address. 4. Paste it into the custom MCP server URL in your web app. #### Claude.ai 1. Go to **Settings → Connectors → Add custom connector**. 2. Name it `Korean Bill & Debate`, and enter your personal MCP link as the URL. 3. Activate it in chat with `+ → Connector`. #### ChatGPT 1. Enable developer mode in **Settings → Apps → Advanced settings**. 2. Choose **Create app**. 3. Name it `Korean Bill & Debate`, and enter your personal MCP link as the server URL. 4. Connect the app and select it from the `+` menu in chat. > Do not paste just the `/mcp` link without a key; it will not connect. Use the **entire personal MCP link** generated with your key. ### Method 2: Local installation for Claude Desktop, Claude Code, Codex, Gemini CLI 1. Obtain an [Open Assembly API key](https://open.assembly.go.kr/portal/openapi/openApiNaListPage.do) and install `uv` and Poppler: macOS `brew install uv poppler` 2. Install the release. ```bash uv tool install git+https://github.com/epoko77-ai/korean-bill-debate-mcp.git@v0.7.0 ``` 3. Choose and execute one app. ```bash kbd setup --client claude-desktop kbd setup --client claude-code kbd setup --client codex kbd setup --client gemini ``` 4. Reopen the app and query. ```text Connect the content and latest processing status of bill 2219564, subcommittee meeting minutes, expert reports, and related lawmakers' and government officials' statements with official original text. ``` See the **[MCP Connection Guide](docs/mcp-clients.md)** for detailed paths and manual settings. ## MCP Tools | Tool | Real-time investigation content | |---|---| | `explore_issue` | Investigates issues, bills, status, expert reports, meetings, speeches, and context in one go | | `search_bills` | Searches bills, then connects relevant parts of expert reports and official original text | | `get_bill_status` | Reconfirms official processing status and connects bill examination reports | | `search_speeches` | Explores related meetings, collects necessary minutes, and searches speeches | | `get_speech` | Confirms cached speech text and official source | | `get_speech_context` | Restores preceding and following questions, responses, and follow-up questions | | `list_committees` | Confirms committees from official meeting metadata | | `list_meetings` | Searches official meetings by date, committee, and type | ## Cache is a supplementary means No entire National Assembly DB or prepared search index is distributed. The local installation's `SQLite` cache reuses already queried API responses, meeting minutes, and structured speeches to speed up repeated requests. Web connection caches use only server instance temporary space and do not store original user API keys. - New queries re-explore candidates from official APIs. - Bill processing status prioritizes official status APIs. - API cache expires after 15 minutes by default. - Meeting minutes original text is preserved with official URLs and SHA-256. - Local default cache location is `~/.local/share/korean-bill-debate-mcp`. - Can change location with `KBD_DATA_DIR`. ## Development ```bash uv sync --extra dev ASSEMBLY_OPEN_API_KEY=your_key uv run kbd research "Abolition of supplementary investigation authority" uv run pytest uv run ruff check . uv run mypy src ``` Fixture tests run without API keys. Actual API smoke tests use repository Secrets or developer environment variables and do not output keys. ## Scope and verification principles This project is an investigative tool that searches and connects official evidence. It does not presume lawmakers' positions and provides actual statements and context. All citations must verify original text with `citation.official_url` and `source_locator`. Free-text full meeting minutes search not provided by Open Assembly API first narrows related bills, committees, and timelines, then dynamically analyzes a limited number of meeting minutes. Initial queries may be slow due to PDF download and parsing; subsequent same materials reuse local cache.