Korean Bill & Debate

흩어진 국회 기록을, 법안 하나로 연결했습니다.

법안 내용과 처리상태부터 소위원회 회의록, 전문위원 검토보고서, 의원과 정부의 실제 발언까지 하나의 조사 흐름으로 이어서 확인합니다.

v1.1.0 · 제1대~제22대 · 발의자 역할 검색 · MCP + 웹 입법조사 워크스페이스 · Apache-2.0

English · MCP 연결 · 데이터 출처 · 아키텍처

설치 없이, 한 화면에서 바로 조사할 수 있습니다

국회 입법조사 워크스페이스 열기

열린국회 API 키와 OpenAI 또는 Anthropic API 키를 입력하면, 별도 프로그램이나 MCP 연결 설정 없이 질문 한 줄로 공식 자료 조사와 답변 생성을 실행합니다. 법안·처리상태·전문위원 검토보고서·소위원회 회의록·의원과 정부의 질의답변을 연결하고, 사용자가 직접 확인할 공식 원문 카드를 함께 보여줍니다.

두 키는 요청 처리 중에만 분리해 사용합니다. URL·DB·파일·쿠키·브라우저 저장소에 남기지 않으며, 질문과 조사된 공식 자료는 답변 생성을 위해 사용자가 선택한 LLM 제공자로 전송됩니다. 현재 워크스페이스는 계정과 저장 기록이 없는 한국어 알파이며 한 번의 HTTP 요청 안에서 실행됩니다. v1.1.0의 백그라운드 작업·재시도·완전성 추적은 MCP 연결 경로에 먼저 적용됐습니다. 자세한 구조와 한계는 워크스페이스 문서를 참고하세요.

국회 정보는 공개돼 있습니다. 하지만 답은 흩어져 있습니다

의안 페이지에는 처리상태가 있고, 위원회 페이지에는 회의 정보가 있으며, 실제 쟁점은 PDF 회의록과 검토보고서 안에 묻혀 있습니다. 의원의 질문과 정부의 답변은 서로 떨어져 있고, 같은 사안을 다룬 여러 법안은 별개의 문서처럼 보입니다.

Korean Bill & Debate MCP는 이 기록들을 법안–심사–사람–발언–답변–근거의 관계로 연결합니다. 사용자는 사이트와 PDF를 오가며 문서를 맞추는 대신, 자연어로 질문하고 공식 원문까지 이어지는 조사 결과를 받을 수 있습니다.

한 질문에, 국회 조사의 네 축을 함께 답합니다

• 지금 어디까지 왔나 — 최신 의안 상태와 위원회·소위원회 심사 단계
• 왜 멈췄고 무엇이 쟁점인가 — 소위 회의록과 전문위원 검토보고서
• 누가 무엇을 말했나 — 의원·정부의 실제 발언과 바로 앞뒤 질의·답변
• 무엇으로 확인하나 — 공식 의안·회의록 URL과 원문 위치

문서를 나열하는 데서 끝나지 않습니다. 법안–회의–사람–발언–답변을 연결해, 다시 확인하고 인용할 수 있는 조사 결과로 돌려줍니다.

국회 안팎에서 입법을 만들고, 대응하고, 연구하는 사람들을 위해

같은 국회 기록도 업무에 따라 필요한 답은 다릅니다. 이 MCP는 입법을 만들고, 대응하고, 연구하는 사람들이 각자의 질문에서 바로 공식 근거로 들어갈 수 있게 합니다.

사용자	필요한 판단	바로 연결되는 근거
국회 직원·보좌진	심사 준비, 쟁점 정리, 질의 작성	유사 의안, 소위 회의록, 검토보고서, 부처 답변
기업 정책·법무·대관팀	규제 방향과 사업 영향, 대응 시점	최신 상태, 의원별 문제의식, 정부 수용 여부, 집행 쟁점
공공기관·협회	소관 법안 대응과 공식 의견 준비	관련 의안, 위원회 논의, 이해관계자 발언, 원문 인용
시민단체	입법 감시, 의견서·논평·캠페인	조문별 쟁점, 찬반 발언, 심사 경과, 공식 회의록
언론인	발언 검증, 쟁점 시계열, 팩트체크	실제 발언, 앞뒤 문맥, 날짜별 사건, 출처 위치
연구자	정책 변화와 담론의 장기·비교 분석	구조화된 법안·회의·발언 관계와 재현 가능한 인용

실제로 이렇게 물어볼 수 있습니다

[입법 심사] “이 법안과 같은 취지의 의안, 소위 쟁점, 전문위원 검토와 부처 답변을 정리해줘”
[기업 대응] “플랫폼 노동 규제 법안이 어디까지 왔고 기업에 영향을 줄 쟁점은 무엇이야?”
[시민사회] “피해자 보호 조항이 심사 과정에서 어떻게 바뀌었고 누가 어떤 의견을 냈어?”
[언론 취재] “보완수사권 폐지에 대한 상반된 발언을 앞뒤 맥락과 공식 원문으로 비교해줘”
[연구] “인공지능 정책 관련 법안과 위원회 논의를 시계열로 연결하고 반복되는 쟁점을 찾아줘”
[의안 추적] “2219564번 의안의 최신 처리상태와 연결된 회의록·검토자료 원문을 찾아줘”
[발의자 검색] “제18대 강명순 의원이 대표발의한 법안과 연결 회의를 전부 찾아줘”
[장기 비교] “제헌국회부터 제5대까지 경제 관련 법안과 본회의 논의를 대수별로 비교해줘”

제1대부터 현재 국회까지, 자료가 있는 만큼 정확하게

v1.1.0은 제1대(제헌국회)부터 제22대까지의 공식 임기 경계를 사용합니다. 제18대, 제18대부터 제22대까지, 1961년 5월부터 1964년 1월까지처럼 대수나 날짜를 쓰면 실제 국회 임기와 교차하는 범위를 모두 조사합니다. 대수·날짜를 쓰지 않은 질문은 빠른 현재 조사를 위해 제22대를 기본값으로 사용합니다.

모든 공식 데이터셋이 같은 시점부터 제공되는 것은 아닙니다. 현재 열린국회 API 실측상 본회의 자료는 제1대부터, 위원회 자료는 제2대부터, 법안·처리상태 자료는 제10대부터, 전용 소위원회 목록은 제16대부터 확인됩니다. 전용 소위 목록이 0건이어도 위원회 자료에 소위 기록이 있을 수 있으므로 두 경로를 함께 확인합니다. 전문위원 검토보고서는 의안별 공식 페이지에서 공개 여부를 각각 확인합니다.

결과의 source_availability는 자료·대수별로 다음 상태를 공개합니다.

• records_found — 해당 열린국회 데이터셋에서 원자료 확인
• no_records — API 호출은 정상 완료됐지만 해당 데이터셋에서 확인된 자료 0건
• incomplete — 호출이나 수집이 끝나지 않아 자료 유무를 단정할 수 없음

따라서 0건을 장애로 숨기지 않고, 장애를 0건으로 바꾸지도 않습니다. coverage.complete=true인 최종 결과가 0건이면 “해당 열린국회 데이터셋에서 확인된 자료 없음”으로 종료하고, coverage가 불완전하면 자료가 없다고 단정하지 않습니다.

대표발의자·공동발의자·전체 발의자를 구분합니다

대표발의는 공식 RST_PROPOSER, 공동발의는 PUBL_PROPOSER, 역할을 지정하지 않은 발의는 두 필드의 합집합에서 이름 전체를 정확히 일치시킵니다. 이름과 주제를 함께 쓰면 두 조건을 모두 만족한 법안만 남깁니다. 이후 회의록은 같은 주제라는 이유로 붙이지 않고, 선택된 법안의 정확한 의안번호가 공식 안건에 있는 회의만 연결합니다.

검색 결과가 아니라, 조사 흐름을 돌려줍니다

MCP는 질문할 때 열린국회 공식 API를 조회합니다. 관련 의안과 처리상태에서 소관 위원회와 시점을 찾고, 필요한 공식 회의록만 내려받아 발언자·질의·답변·후속질의를 복원합니다.

자연어 질문
  → 공식 의안·처리상태 실시간 조회
  → 관련 전문위원 검토보고서 확인·검색
  → 관련 위원회·본회의·소위원회 후보 탐색
  → 필요한 회의록만 다운로드·파싱
  → 법안–회의–사람–발언–답변 연결
  → 공식 의안·회의록 URL과 원문 위치 반환

v1.1.0: 빠른 답과 빠진 답을 구분합니다

광범위한 조사는 한 번의 긴 MCP 요청으로 버티지 않습니다. 먼저 작업을 만들고 진행 상태를 확인한 뒤, 먼저 확인된 핵심 후보 → 전체 자료 지도 → 핵심 원문 → 사용자가 선택한 원문 순서로 읽습니다. 첫 후보 지도는 공식 API 각 범주의 첫 페이지에서 검증된 항목을 먼저 보여 주되 metadata_inventory_complete=false로 남습니다. 같은 작업이 뒤에서 전체 페이지를 계속 수집하며, 사용자가 전건 확인을 요구한 경우에만 전체 근거 목록과 모든 긴 원문까지 순회합니다.

start_research
  → get_research_status          조사 중에는 같은 research_id를 다시 확인
  → get_research_overview        관련 법안·회의·문서 전체 지도와 핵심 근거
  → get_evidence_document        핵심 또는 사용자가 선택한 공식 원문
  → get_research_page            전건 요청일 때만 exhaustive=true로 전체 목록 순회

빠른 첫 지도는 임의의 top-N이 아니라 공식 첫 페이지 전체를 같은 기준으로 판정한 관측 목록입니다. 아직 보지 못한 페이지가 있으므로 결론이나 전체 목록으로 쓰지 않습니다. 이후 metadata_inventory_complete=true가 되면 catalog의 next_offset으로 전체 법안·회의 후보를 확인할 수 있습니다. 긴 원문은 잘린 미리보기 대신 길이·해시·근거 ID를 반환해 get_evidence_document에서 최대 5만 자씩 손실 없이 이어 읽습니다. coverage.complete가 거짓이면 누락 사유를 밝힌 부분 조사이며, 종합 조사가 끝났다고 표현하지 않습니다.

공식 API 범주별 첫 페이지가 준비되면 get_research_status가 최대 100건의 overview_preview를 함께 돌려주므로 Claude.ai와 ChatGPT는 전체 수집을 기다리지 않고 확인된 후보를 먼저 보여 줄 수 있습니다. 이 미리보기는 최대 100건의 단일 orientation 페이지이며, metadata_inventory_complete=false이면 페이지를 섞어 읽지 말고 반드시 같은 research_id를 계속 확인합니다. 전체 메타데이터 지도가 준비된 뒤에만 next_offset으로 끝까지 순회합니다. 이때 next_action의 view_source_hash까지 그대로 사용하면 조사 도중 최종 결과가 완성돼도 서로 다른 후보 지도의 페이지가 섞이지 않습니다.

영어로 질문하고, 영어로 답을 받을 수 있습니다

v0.8.0부터 영어 질문을 그대로 보존하면서 실제 열린국회 검색에는 한국어 입법 키워드를 연결합니다. Claude·ChatGPT는 한국어 공식 기록을 근거로 영어 답변을 작성하고, 번역한 인용과 원문 URL을 함께 제시할 수 있습니다.

In July 2026, compare bills and opposing views on abolishing prosecutors'
supplementary investigation authority. Include surrounding Q&A and official sources.

공식 의안명·회의록·검토보고서의 원문 언어는 한국어입니다. 결과에는 원래 영어 질문과 실제 검색에 사용한 search_query_ko, 원문 언어 source_language: ko가 표시되어 번역과 원문을 구분할 수 있습니다.

국회 경험자가 처리상태 다음에 보는 것

국회 경험이 있는 사람들은 법안의 다음 흐름을 볼 때 처리상태에서 멈추지 않습니다. 실제 협상이 기록된 소위원회 회의록과 심사 쟁점을 구조화한 전문위원 검토보고서를 함께 봅니다.

1. 소위원회 회의록 — 실제로 어디서 막혔는가

• 조문별 찬반, 수정안과 대안
• 소관 부처의 답변과 수용 여부
• 보류·계속심사·대안반영에 이르는 협상 맥락

2. 전문위원 검토보고서 — 무엇이 심사 쟁점이 되는가

• 법체계 정합성과 다른 법률과의 충돌
• 집행 가능성, 비용, 예상되는 부작용
• 위원들이 심사할 핵심 쟁점과 수정 필요사항

이 MCP는 법안의 미래를 임의로 단정하지 않습니다. 대신 향후 흐름을 판단할 수 있도록 의안 상태, 소위원회 회의록, 전문위원 검토보고서, 의원·정부 발언을 공식 원문 근거로 연결합니다.

검토보고서를 미리 대량 수집하지 않습니다. 사용자가 관련 법안을 질문할 때 공식 의안정보시스템에서 보고서 PDF를 확인하고 필요한 문서만 내려받아 검색합니다. 로컬 설치는 이를 개인 캐시에 보관해 같은 문서를 다시 다운로드하지 않습니다.

무엇이 다른가

• 실시간 우선 — 준비된 과거 스냅샷에만 의존하지 않고 질문할 때 공식 의안·상태 API를 다시 확인합니다.
• 문서가 아닌 관계를 검색 — 법안, 회의, 사람, 발언, 질문과 답변을 연결해 같은 쟁점의 흐름을 복원합니다.
• 발언을 잘라내지 않음 — 한 문장만 보여주지 않고 바로 앞 질문, 정부 답변, 후속질의까지 함께 제공합니다.
• 검증 가능한 결과 — 모든 인용에 공식 URL과 원문 위치를 붙여 사용자가 직접 재확인할 수 있습니다.
• 사용자 통제형 데이터 — 운영자의 공용 키를 공유하지 않고 각자 자신의 열린국회 API 키를 사용합니다. 로컬 설치는 개인 캐시를, 웹 연결은 원문 키를 저장하지 않는 개인 토큰을 사용합니다.

3분이면 사용하는 AI에 연결할 수 있습니다

이 MCP는 별도 프로그램을 배울 필요가 없습니다. 한 번 연결한 뒤 사용하는 AI에 평소처럼 질문하면 필요한 국회 공식 기록을 도구가 찾아옵니다.

방법 1: Claude.ai·ChatGPT 웹에서 바로 사용 — 설치 없음

먼저 열린국회정보 Open API에서 본인의 키를 발급받습니다. Claude.ai와 ChatGPT 모두 아래 공용 MCP 주소로 연결합니다.

https://korean-bill-debate-mcp.vercel.app/mcp

Claude.ai

Claude Pro·Max·Team·Enterprise의 원격 커스텀 커넥터 기능을 사용합니다. 자세한 최신 화면은 Anthropic 공식 안내를 확인하세요.

1. 설정 → 커넥터 → 커스텀 커넥터 추가로 이동합니다. Team·Enterprise에서는 소유자가 조직 커넥터를 먼저 허용해야 할 수 있습니다.
2. 이름은 Korean Bill & Debate, URL은 위 공용 주소를 정확히 입력합니다.
3. Claude가 연결 승인을 요청하면 열린 화면에 본인의 열린국회 API 키를 입력합니다.
4. 연결 후 새 채팅을 열고 **검색 및 도구(Search and tools)**에서 커넥터와 필요한 도구를 활성화합니다. 도구 접근 설정이 보이면 신뢰하는 읽기 도구만 항상 허용할 수 있습니다.

Claude에는 /mcp/t/... 개인 링크를 넣지 마세요. Claude가 표준 OAuth로 서버를 발견하고, 승인 화면에서 받은 키를 암호화된 접근 토큰으로 바꿉니다. 키 원문은 서버의 DB나 파일에 저장하지 않습니다.

ChatGPT

현재 OpenAI 공식 안내상 전체 MCP 앱 기능은 ChatGPT Business·Enterprise·Edu의 웹 환경에 제공됩니다. Pro도 개발자 모드에서 읽기·가져오기(read/fetch) MCP를 연결할 수 있으며, 이 서버의 모든 도구는 MCP 스키마에 읽기 전용으로 선언돼 있습니다. 관리자 정책과 역할에 따라 메뉴가 보이지 않을 수 있습니다. OpenAI 공식 개발자 모드 안내를 먼저 확인하세요.

1. 관리자는 워크스페이스 설정 → Apps → Create에서 개발자 모드를 허용합니다. 권한을 받은 사용자는 설정 → Apps → Advanced settings에서 개발자 모드를 켭니다. 한국어 개인 UI가 설정 → 보안 및 로그인 → 개발자 모드, **플러그인 → +**로 보이면 같은 기능이므로 그 경로를 사용합니다.
2. Apps → Create 또는 **플러그인 → +**에서 이름은 Korean Bill & Debate, MCP 서버 URL은 위 공용 주소를 입력합니다.
3. Scan Tools를 누르고, 열린 연결 승인 화면에 본인의 열린국회 API 키를 입력합니다. OAuth 완료 뒤 13개 도구 스캔이 끝날 때까지 기다린 다음 Create를 누릅니다.
4. 새 채팅에서 + → More로 앱을 선택하거나 @로 호출합니다.

서버 도구가 업데이트된 뒤 ChatGPT에 새 도구가 보이지 않으면 앱의 Refresh에서 변경된 actions를 다시 불러오고 사용 설정을 검토하세요. ChatGPT는 승인된 도구 스냅샷을 자동으로 갱신하지 않을 수 있습니다.

연결됨 표시만으로는 이 대화에서 활성화된 것이 아닙니다. 새 채팅을 열고 입력창 아래 + 또는 도구 메뉴에서 Korean Bill & Debate를 선택한 뒤 질문하세요. AI가 “이 대화에서는 MCP가 호출 가능한 도구로 잡히지 않는다”고 말하면 이 단계가 빠진 것입니다.

기존 ?token=... 또는 /mcp/t/... 주소를 Claude.ai나 ChatGPT에 등록했다면 해당 연결을 삭제하고 위의 공용 /mcp 주소로 다시 등록하세요. 개인 링크는 OAuth를 지원하지 않는 클라이언트와의 하위 호환을 위해 계속 지원하지만 비밀번호처럼 보관해야 합니다.

공용 /mcp는 OAuth 승인 화면에서 키를 받아 접근·갱신 토큰으로 바꿉니다. 반면 첫 화면의 호환용 /connect 폼은 키를 열린국회에 실제로 확인한 뒤 /mcp/t/... 개인 링크를 만듭니다. Claude.ai와 ChatGPT에는 호환용 개인 링크를 넣지 않습니다.

방법 2: Claude Desktop·Claude Code·Codex·Gemini CLI에 로컬 설치

1. 열린국회 API 키를 발급받고 uv를 설치합니다: macOS brew install uv. Poppler(brew install poppler)를 함께 설치하면 PDF 처리가 더 빠르며, 없어도 내장 Python 추출기로 동작합니다.
2. 릴리스를 설치합니다.

uv tool install git+https://github.com/epoko77-ai/[email protected]

3. 사용하는 앱 하나만 골라 실행합니다.

kbd setup --client claude-desktop
kbd setup --client claude-code
kbd setup --client codex
kbd setup --client gemini

4. 앱을 다시 열고 질문합니다.

2219564번 의안의 내용과 최신 처리상태, 소위원회 회의록,
전문위원 검토보고서와 관련 의원·정부 발언을 공식 원문과 함께 연결해줘.

상세 화면 경로와 수동 설정은 **MCP 연결 가이드**를 참고하세요.

자동 설정 결과의 registration.installed가 true인지 확인하세요. 앱 실행 파일을 찾지 못하거나 등록 명령이 실패하면 kbd setup은 오류 코드로 종료하며 원인을 표시합니다. 키는 --api-key, ASSEMBLY_OPEN_API_KEY, 대화형 가림 입력 순서로 읽습니다. 비대화형 환경에서 키가 없으면 기다리지 않고 즉시 실패합니다. --credentials-file로 경로를 바꾸면 자동 등록에도 그 절대 경로를 전달합니다.

MCP 도구

완전한 durable hosted 설정은 기존 호환 도구 8개에 조사 도구 5개를 더한 13개를 노출합니다. 로컬 kbd setup의 live-cache 호환 서버는 현재 8개 도구를 노출합니다.

구분	도구	역할
durable	start_research	광범위한 조사를 한 번만 시작하고 research_id 반환
durable	get_research_status	같은 작업의 진행·완료·부분완료와 coverage 확인
durable	get_research_overview	전체 법안·회의·문서 지도와 핵심 근거를 bounded page로 반환
durable	get_research_page	안정적인 커서로 전체 근거 ID 목록 순회
durable	get_evidence_document	선택한 근거의 공식 원문을 해시·locator와 함께 손실 없이 이어 읽기
호환	explore_issue	durable 서버에서는 새 조사를 시작하고, 로컬 서버에서는 bounded live 조사
호환	search_bills	법안 검색 후 전문위원 검토보고서와 공식 원문 연결
호환	get_bill_status	공식 처리상태와 연결된 검토보고서 확인
호환	search_speeches	관련 회의를 탐색하고 필요한 회의록의 발언 검색
호환	get_speech	캐시에 저장된 발언 전문과 공식 출처 확인
호환	get_speech_context	발언 전후 질의·답변·후속질의 복원
호환	list_committees	공식 회의 메타데이터에서 위원회 확인
호환	list_meetings	날짜·위원회·회의 종류로 공식 회의 탐색

웹 연결에서 8개만 보이면 현재 배포가 durable worker·artifact 설정 없이 호환 모드로 실행 중인 것입니다. 이 상태에서는 5개 durable 조사 도구를 쓸 수 없으며, 이를 완전한 durable 조사로 가장하지 않습니다.

캐시는 보조 수단입니다

완성된 전체 국회 DB를 패키지에 묶어 배포하지 않습니다. 로컬 설치의 SQLite 캐시는 사용자가 이미 조회한 API 응답, 회의록, 구조화 발언을 재사용해 반복 요청을 빠르게 합니다. 웹 연결의 호환 캐시는 서버 인스턴스의 임시 공간만 사용하며 사용자 API 키 원문은 저장하지 않습니다. durable 경로는 작업 artifact와 공개 원문을 별도 객체 저장소에 보존하되 자격증명 원문은 넣지 않습니다.

• 새 질문은 공식 API에서 후보를 다시 탐색합니다.
• 법안 처리상태는 공식 상태 API를 우선합니다.
• API 캐시는 기본 15분 후 만료됩니다.
• 회의록 원문은 공식 URL과 SHA-256을 함께 보존합니다.
• 로컬 기본 캐시 위치는 ~/.local/share/korean-bill-debate-mcp입니다.
• KBD_DATA_DIR로 위치를 바꿀 수 있습니다.

개발

uv sync --extra dev --extra deploy
ASSEMBLY_OPEN_API_KEY=본인키 uv run kbd research "검찰 보완수사권 폐지"
uv run pytest
uv run ruff check .
uv run mypy src

fixture 테스트는 API 키 없이 실행됩니다. 실제 API smoke test는 저장소 Secret 또는 개발자의 환경변수를 사용하며, 키를 출력하지 않습니다.

범위와 검증 원칙

이 프로젝트는 공식 근거를 검색하고 연결하는 조사 도구입니다. 의원의 찬반 입장을 임의로 추정하지 않으며 실제 발언과 앞뒤 문맥을 제공합니다. 모든 인용은 citation.official_url과 source_locator로 원문을 확인해야 합니다.

열린국회 API가 검색 조건으로 제공하지 않는 자유어 전체 회의록 검색은 관련 법안·위원회· 시점을 먼저 좁힌 뒤 제한된 수의 회의록을 동적으로 분석합니다. 첫 조회는 PDF 다운로드와 파싱 때문에 느릴 수 있으며, 이후 같은 자료는 로컬 캐시를 재사용합니다.

v1.1.0에는 내용 주소화된 corpus revision을 연결하는 선택 경로가 들어 있지만, 전체 공식 자료 corpus를 공개 운영 환경에 구축·배포하고 전수 검증하는 작업은 아직 끝나지 않았습니다. corpus revision이 없거나 조사 범위 전체를 증명하지 못하면 broad query를 complete로 과장하지 않고 partial과 coverage gap을 반환합니다. 따라서 현재 버전은 “국회 전체 기록을 항상 빠짐없이 검색하는 완성 인덱스”를 주장하지 않습니다.

공개 /mcp 주소는 Claude.ai와 ChatGPT 각각의 Origin으로 동적 클라이언트 등록, PKCE 승인, refresh token, 13개 read-only 도구 노출까지 운영 smoke를 통과했습니다. 다만 각 서비스의 요금제·관리자 정책·승인된 도구 스냅샷은 외부 설정이므로, 새 도구가 보이지 않으면 기존 연결을 새로고침하거나 삭제 후 다시 등록해야 합니다.