AssemblyMCP

대한민국 국회 정보공개 OpenAPI를 MCP(Model Context Protocol) 도구로 제공하는 서버입니다. LLM 클라이언트가 의안, 의원, 위원회, 회의, 표결, 국회 보고서 데이터를 조회하고 검증형 워크플로로 조합할 수 있게 합니다.

English README

먼저 호출할 도구

LLM 클라이언트는 세션 시작 시 get_legislative_research_kit()을 먼저 호출하는 것을 권장합니다. 이 도구는 공개 도구 목록, 네이밍 규칙, 권장 워크플로, 실패 마커 계약을 구조화 데이터로 반환합니다.

실패 마커는 다음 형태로 반환됩니다.

Marker	의미
[NOT_FOUND]	실제 조회했지만 일치 데이터가 없음
[AMBIGUOUS]	후보가 여러 개라 사용자가 식별자를 좁혀야 함
[VERIFY_FAILED]	데이터는 찾았지만 기대 필드와 불일치
[API_FAILED]	국회 API 또는 서버 호출 중 오류
[PARTIAL]	복합 워크플로 일부 단계 실패, 나머지는 사용 가능

워크플로 중심 도구

Tool	목적
verify_legislative_claims(citations_or_text, age="22", limit=5)	의안, 의원, 위원회, 표결 주장/인용을 국회 데이터로 검증
issue_brief(topic, age="22", limit=5)	주제별 의안, 위원회, 회의, 보고서, 표결 신호를 통합
bill_timeline(bill_id, age=None)	의안의 발의, 회부, 회의, 표결, 최종 처리 이벤트를 정규화
legislative_impact_map(target, target_type="auto", age="22", limit=5)	주제 또는 의안 중심 관계 그래프(nodes/edges/mermaid) 생성
watch_action_plan(topic, age="22", limit=5)	지속 모니터링을 위한 후속 MCP 호출 계획 생성

검증 입력 예시

[
  {"type": "bill", "value": "PRC_SAMPLE", "expected": {"status": "위원회 심사"}},
  {"type": "member", "value": "홍길동"},
  {"type": "committee", "value": "법제사법위원회"},
  {"type": "vote", "bill_id": "PRC_SAMPLE", "expected": {"yes": 180}}
]

JSON이 아닌 일반 텍스트를 넣으면 auto claim으로 처리되어 의안, 의원, 위원회 후보를 순차 확인합니다.

조회 및 분석 도구

Tool	목적
search_bills(...)	키워드, 의안 ID, 발의자, 처리상태 등으로 의안 검색
get_bill_details(bill_id, age=None)	의안 상세, 주요 내용, 제안 이유 조회
get_bill_history(bill_id)	기존 호환용 의안 이력 타임라인
analyze_legislative_issue(topic, limit=5)	주제별 기존 종합 분석
get_legislative_reports(keyword, limit=5)	NABO 보고서와 국회 뉴스 검색
get_committee_work_summary(committee_name)	위원회별 계류 의안과 보고서 요약
get_member_info(name)	국회의원 인적사항 검색
get_representative_report(member_name)	의원 기본 정보, 발의 법안, 위원회 경력, 표결 이력 통합
search_meetings(...)	의안 또는 위원회 기준 회의 검색
get_plenary_schedule(unit_cd=None, page=1, limit=10)	본회의 일정 조회
get_committee_info(...)	위원회 목록, 위원회 상세, 위원 명단 조회
get_bill_voting_results(bill_id)	의안별 본회의 표결 결과와 정당별 샘플 경향
analyze_voting_trends(topic)	주제별 표결 경향 분석
get_member_voting_history(...)	의원 또는 의안 기준 개별 표결 기록

Raw API 탐색 도구

AssemblyMCP는 고수준 도구에 없는 데이터도 국회 OpenAPI 메타데이터를 통해 직접 탐색할 수 있습니다.

Tool	목적
list_api_services(keyword="")	사용 가능한 국회 API 서비스 검색
get_api_spec(service_id)	서비스 파라미터, 응답 구조, 샘플 데이터 확인
call_api_raw(service_id, params="{}")	특정 OpenAPI 서비스 직접 호출
get_api_code_guide()	UNIT_CD, 처리상태 코드 등 공통 코드 확인
get_assembly_info()	서버 상태와 사용 가이드 확인
ping()	서버 생존 확인

권장 탐색 순서:

list_api_services(keyword) -> get_api_spec(service_id) -> call_api_raw(service_id, params)

빠른 시작

1. API 키 발급

공공데이터포털(data.go.kr)에서 국회사무처 관련 API 활용 신청 후 인증키를 발급받습니다.

2. Claude Desktop 설정

Claude Desktop 설정 파일에 다음 항목을 추가합니다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "assembly": {
      "command": "uvx",
      "args": ["git+https://github.com/StatPan/AssemblyMCP"],
      "env": {
        "ASSEMBLY_API_KEY": "your_api_key_here"
      }
    }
  }
}

설정 후 Claude Desktop을 재시작합니다.

3. 로컬 실행

export ASSEMBLY_API_KEY="your_api_key_here"
uvx git+https://github.com/StatPan/AssemblyMCP

Streamable HTTP 모드로 실행하려면:

export ASSEMBLY_API_KEY="your_api_key_here"
export MCP_TRANSPORT=http
export MCP_PORT=8000
export MCP_PATH=/mcp
uvx git+https://github.com/StatPan/AssemblyMCP

개발

요구사항

• Python 3.12 이상
• uv

설치 및 테스트

git clone https://github.com/StatPan/AssemblyMCP.git
cd AssemblyMCP
uv sync

export ASSEMBLY_API_KEY="your_api_key_here"
uv run assemblymcp

품질 확인:

uv run ruff check .
uv run ruff format .
uv run pytest

환경 변수

변수	설명	기본값
ASSEMBLY_API_KEY	국회 OpenAPI 인증키	없음
ASSEMBLY_LOG_LEVEL	로깅 레벨	INFO
ASSEMBLY_LOG_JSON	JSON 구조화 로깅	False
ASSEMBLY_ENABLE_CACHING	인메모리 캐싱	False
ASSEMBLY_CACHE_TTL_SECONDS	캐시 TTL	300
ASSEMBLY_CACHE_MAX_SIZE	최대 캐시 항목 수	100
MCP_TRANSPORT	stdio 또는 http	stdio
MCP_HOST	HTTP 바인드 호스트	0.0.0.0
MCP_PORT	HTTP 포트	8000
MCP_PATH	HTTP MCP 경로	/mcp

배포

Dockerfile이 포함되어 있으며 Cloud Run, Railway, Fly.io 등에 배포할 수 있습니다.

gcloud run deploy assembly-mcp \
  --source . \
  --region asia-northeast3 \
  --allow-unauthenticated \
  --set-env-vars ASSEMBLY_API_KEY="your_key",ASSEMBLY_LOG_JSON="true",ASSEMBLY_ENABLE_CACHING="true"

HTTP 배포 시 MCP 엔드포인트 기본 경로는 /mcp입니다.

라이선스

MIT