get_merit_list
Retrieve lists of Korean independence activists' merit records by filtering with criteria like name, birth date, award year, or achievement details.
Instructions
독립유공자 공훈록 목록을 조회합니다
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page_index | No | 페이지 번호 | |
| count_per_page | No | 페이지 당 데이터 건수 (최대 50건) | |
| mng_no | No | 관리번호 | |
| name_ko | No | 성명(한글) | |
| name_ch | No | 성명(한자) | |
| diff_name | No | 이명 | |
| birthday | No | 생년월일 (YYYYMMDD, 년(1945), 년월(194501), 년월일(19450101)) | |
| lastday | No | 사망년월일 (YYYYMMDD, 년(1945), 년월(194501), 년월일(19450101)) | |
| sex | No | 성별 (0: 여, 1: 남) | |
| register_large_div | No | 본적대분류 | |
| register_mid_div | No | 본적중분류 | |
| judge_year | No | 포상년도 | |
| hunkuk | No | 훈격 | |
| workout_affil | No | 운동계열 | |
| achivement | No | 공훈록 |
Implementation Reference
- src/gonghun_mcp/tools.py:246-279 (handler)MCP tool handler dispatch for get_merit_list: parses arguments, calls fetch_merit_list API wrapper, formats response as JSON text.
if name == "get_merit_list": # 공훈록 목록 조회 if not isinstance(arguments, dict): arguments = {} data = await fetch_merit_list( page_index=arguments.get("page_index", 1), count_per_page=min(arguments.get("count_per_page", 10), 50), response_type="JSON", mng_no=arguments.get("mng_no"), name_ko=arguments.get("name_ko"), name_ch=arguments.get("name_ch"), diff_name=arguments.get("diff_name"), birthday=arguments.get("birthday"), lastday=arguments.get("lastday"), sex=arguments.get("sex"), register_large_div=arguments.get("register_large_div"), register_mid_div=arguments.get("register_mid_div"), judge_year=arguments.get("judge_year"), hunkuk=arguments.get("hunkuk"), workout_affil=arguments.get("workout_affil"), achivement=arguments.get("achivement") ) result_json = format_response(data) logger.debug(f"공훈록 목록 조회 결과: {result_json}") return [ TextContent( type="text", text=result_json ) ] - src/gonghun_mcp/api.py:13-151 (handler)Core handler function that fetches merit list data from external API, implements caching, query param building, response parsing (JSON/XML), and error handling.
async def fetch_merit_list( page_index: int = 1, count_per_page: int = 10, response_type: str = "JSON", mng_no: Optional[str] = None, name_ko: Optional[str] = None, name_ch: Optional[str] = None, diff_name: Optional[str] = None, birthday: Optional[str] = None, lastday: Optional[str] = None, sex: Optional[str] = None, register_large_div: Optional[str] = None, register_mid_div: Optional[str] = None, judge_year: Optional[str] = None, hunkuk: Optional[str] = None, workout_affil: Optional[str] = None, achivement: Optional[str] = None ) -> Dict[str, Any]: """ 독립유공자 공훈록 목록을 조회합니다. Args: page_index: 페이지 번호 count_per_page: 페이지 당 데이터 건수 (최대 50건) response_type: 응답 형식 (JSON/XML) mng_no: 관리번호 name_ko: 성명(한글) name_ch: 성명(한자) diff_name: 이명 birthday: 생년월일 lastday: 사망년월일 sex: 성별 register_large_div: 본적대분류 register_mid_div: 본적중분류 judge_year: 포상년도 hunkuk: 훈격 workout_affil: 운동계열 achivement: 공훈록 Returns: 공훈록 목록 정보를 담은 딕셔너리 Raises: RuntimeError: API 호출 중 오류가 발생한 경우 """ # 캐시 키 생성 cache_params = [ f"page_{page_index}", f"count_{count_per_page}" ] if mng_no: cache_params.append(f"mng_{mng_no}") if name_ko: cache_params.append(f"name_ko_{name_ko}") if name_ch: cache_params.append(f"name_ch_{name_ch}") if diff_name: cache_params.append(f"diff_{diff_name}") if birthday: cache_params.append(f"birth_{birthday}") if lastday: cache_params.append(f"last_{lastday}") if sex: cache_params.append(f"sex_{sex}") if register_large_div: cache_params.append(f"reg_l_{register_large_div}") if register_mid_div: cache_params.append(f"reg_m_{register_mid_div}") if judge_year: cache_params.append(f"year_{judge_year}") if hunkuk: cache_params.append(f"hunkuk_{hunkuk}") if workout_affil: cache_params.append(f"workout_{workout_affil}") if achivement: cache_params.append(f"achi_{achivement}") cache_key = f"merit_list_{'_'.join(cache_params)}" # 캐시 확인 cached_data = cache_manager.get(cache_key) if cached_data: return cached_data # API 요청 파라미터 구성 params = build_query_params( nPageIndex=page_index, nCountPerPage=count_per_page, type=response_type, mngNo=mng_no, nameKo=name_ko, nameCh=name_ch, diffName=diff_name, birthday=birthday, lastday=lastday, sex=sex, registerLargeDiv=register_large_div, registerMidDiv=register_mid_div, judgeYear=judge_year, hunkuk=hunkuk, workoutAffil=workout_affil, achivement=achivement ) # API 요청 endpoint = f"{BASE_URL}/contribuMeritList.do" logger.info(f"공훈록 목록 요청: {endpoint}, 파라미터: {params}") try: async with httpx.AsyncClient(timeout=30.0) as client: response = await client.get(endpoint, params=params) response.raise_for_status() # 응답 형식에 따라 처리 if response_type.upper() == "JSON": result = response.json() else: # XML # XML 응답 파싱 result = parse_xml_response(response.text) if "error" not in result: # 캐시 저장 cache_manager.set(cache_key, result) return result except httpx.TimeoutException: logger.error("API 요청 시간 초과") raise RuntimeError("API 요청 시간이 초과되었습니다. 잠시 후 다시 시도해주세요.") except httpx.HTTPStatusError as e: logger.error(f"HTTP 상태 오류: {e.response.status_code} - {str(e)}") raise RuntimeError(f"HTTP 상태 오류: {e.response.status_code}. 요청을 처리할 수 없습니다.") except httpx.HTTPError as e: logger.error(f"HTTP 요청 오류: {str(e)}") raise RuntimeError(f"HTTP 요청 오류: {str(e)}") except Exception as e: logger.error(f"공훈록 목록 조회 중 오류 발생: {str(e)}") raise RuntimeError(f"공훈록 목록 조회 중 오류 발생: {str(e)}") - src/gonghun_mcp/tools.py:30-100 (schema)Input schema defining parameters for get_merit_list tool, including pagination, search filters like name, dates, codes, with types, descriptions, defaults, enums.
inputSchema={ "type": "object", "properties": { "page_index": { "type": "integer", "description": "페이지 번호", "default": 1 }, "count_per_page": { "type": "integer", "description": "페이지 당 데이터 건수 (최대 50건)", "default": 10, "maximum": 50 }, "mng_no": { "type": "string", "description": "관리번호" }, "name_ko": { "type": "string", "description": "성명(한글)" }, "name_ch": { "type": "string", "description": "성명(한자)" }, "diff_name": { "type": "string", "description": "이명" }, "birthday": { "type": "string", "description": "생년월일 (YYYYMMDD, 년(1945), 년월(194501), 년월일(19450101))" }, "lastday": { "type": "string", "description": "사망년월일 (YYYYMMDD, 년(1945), 년월(194501), 년월일(19450101))" }, "sex": { "type": "string", "description": "성별 (0: 여, 1: 남)", "enum": ["0", "1"] }, "register_large_div": { "type": "string", "description": "본적대분류" }, "register_mid_div": { "type": "string", "description": "본적중분류" }, "judge_year": { "type": "string", "description": "포상년도" }, "hunkuk": { "type": "string", "description": "훈격", "enum": list(HUNKUK_CODES.keys()) }, "workout_affil": { "type": "string", "description": "운동계열", "enum": list(WORKOUT_AFFIL_CODES.keys()) }, "achivement": { "type": "string", "description": "공훈록" } } } - src/gonghun_mcp/tools.py:27-101 (registration)Registers the get_merit_list tool in the MCP list_tools() function with name, description, and full input schema.
Tool( name="get_merit_list", description="독립유공자 공훈록 목록을 조회합니다", inputSchema={ "type": "object", "properties": { "page_index": { "type": "integer", "description": "페이지 번호", "default": 1 }, "count_per_page": { "type": "integer", "description": "페이지 당 데이터 건수 (최대 50건)", "default": 10, "maximum": 50 }, "mng_no": { "type": "string", "description": "관리번호" }, "name_ko": { "type": "string", "description": "성명(한글)" }, "name_ch": { "type": "string", "description": "성명(한자)" }, "diff_name": { "type": "string", "description": "이명" }, "birthday": { "type": "string", "description": "생년월일 (YYYYMMDD, 년(1945), 년월(194501), 년월일(19450101))" }, "lastday": { "type": "string", "description": "사망년월일 (YYYYMMDD, 년(1945), 년월(194501), 년월일(19450101))" }, "sex": { "type": "string", "description": "성별 (0: 여, 1: 남)", "enum": ["0", "1"] }, "register_large_div": { "type": "string", "description": "본적대분류" }, "register_mid_div": { "type": "string", "description": "본적중분류" }, "judge_year": { "type": "string", "description": "포상년도" }, "hunkuk": { "type": "string", "description": "훈격", "enum": list(HUNKUK_CODES.keys()) }, "workout_affil": { "type": "string", "description": "운동계열", "enum": list(WORKOUT_AFFIL_CODES.keys()) }, "achivement": { "type": "string", "description": "공훈록" } } } ), - src/gonghun_mcp/tools.py:13-18 (helper)Imports the fetch_merit_list helper function from api module used in tool execution.
from .api import fetch_merit_list, fetch_public_report from .cache import cache_manager from .utils import format_response, create_error_response @app.list_tools() async def list_tools() -> List[Tool]: