[RFC] MCP 도구 계층 재구조화 및 네이밍 컨벤션 정립

[StatPan]

[RFC] MCP 도구 계층 재구조화 및 네이밍 컨벤션 정립

배경

외부 피드백:

"일반인을 위한 건지, 개발자를 위한 건지 모르겠다"

PlayMCP 대회 출품을 앞두고, 도구 구조의 명확한 계층화와 일관된 네이밍이 필요.

---

제안: 3계층 도구 구조

레이어	접두어	용도	타겟
Composite	analyze_	여러 데이터 조합, 완성된 결과	일반 사용자
Atomic	get_, search_, list_	단일 리소스 조회	중급 사용자
Raw	raw_	270개 API 직접 탐색/호출	개발자

LLM 사용 우선순위: Composite → Atomic → Raw

---

Breaking Changes

도구 이름 변경

현재	변경	사유
call_api_raw	raw_call	접두어 통일
list_api_services	raw_list	Raw 레이어 명시
get_api_spec	raw_spec	Raw 레이어 명시
get_assembly_info	info	메타 도구 단순화 (검토 필요)

---

신규 도구 (Composite 레이어)

analyze_bill

• 입력: bill_id 또는 keyword
• 출력: 의안 기본정보 + 제안이유 + 회의록 목록 + 발의자 정보
• 내부: get_bill_details + get_meeting_records + get_member_info 조합

analyze_member

• 입력: 의원명
• 출력: 의원 정보 + 최근 발의 의안 + 소속 위원회
• 내부: get_member_info + search_bills + get_committee_list 조합

analyze_legislation_trends (선택)

• 입력: 기간, 키워드(선택)
• 출력: 발의 건수, 주요 키워드, 처리 현황 통계
• 비고: 범위 제한 필요 (최근 30일, 상위 10개 등)

---

유지 도구 (Atomic 레이어)

변경 없음:

• get_bill_details
• get_bill_info
• get_recent_bills
• search_bills
• get_member_info
• get_committee_list
• get_committee_members
• get_meeting_records
• search_meetings
• get_plenary_schedule

---

최종 도구 목록 (예상 14개)

# Composite (3개)
analyze_bill
analyze_member
analyze_legislation_trends

# Atomic (10개)
get_bill_details
get_bill_info
get_recent_bills
search_bills
get_member_info
get_committee_list
get_committee_members
get_meeting_records
search_meetings
get_plenary_schedule

# Raw (3개)
raw_call
raw_list
raw_spec

# Meta (1개)
info (또는 ping 유지)

---

마이그레이션 계획

1. 신규 도구 먼저 추가 (non-breaking)
2. 기존 Raw 도구에 deprecation 경고 추가
3. 다음 마이너 버전에서 이름 변경 적용
4. README/가이드 업데이트

---

논의 필요 사항

• get_assembly_info → info 변경 여부
• ping 도구 유지 여부
• analyze_legislation_trends 구현 범위
• 버전 전략 (semver major bump?)

---

관련

• PlayMCP 대회 마감: 2025-01-18
• 심사 기준: 창의성, 편의성, 기술적 안정성