get_merit_list
Retrieve lists of Korean independence patriots' merit records by filtering criteria like name, birth date, honor grade, or movement affiliation from official archives.
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)Handler logic in MCP call_tool that dispatches get_merit_list, parses arguments, calls the API wrapper, formats response, and returns TextContent
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/tools.py:30-100 (schema)Input schema defining parameters for get_merit_list tool in list_tools
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)Registration of the get_merit_list tool in the list_tools function, decorated with @app.list_tools()
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/api.py:13-151 (helper)Helper function that performs the actual API request to fetch the merit list, with caching and parameter 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)}")