get_sigungu_list
Retrieve a list of administrative districts (sigungu) within a specific province or metropolitan city in South Korea to enable regional filtering for youth activity searches.
Instructions
특정 시도의 시군구(기초자치단체) 목록을 조회합니다
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sido | Yes | 시도명 (예: 서울, 부산광역시, 경기도) | |
| pageNo | No | 페이지 번호 (기본값: 1) | |
| numOfRows | No | 한 페이지 결과 수 (기본값: 100) |
Implementation Reference
- src/index.ts:235-272 (handler)MCP tool handler for 'get_sigungu_list': extracts 'sido', 'pageNo', 'numOfRows' from arguments, calls youthApiClient.getSigunguList(), formats the paginated list of sigungu (districts) with names and codes into a numbered text response.case "get_sigungu_list": { const sido = args?.sido as string; const pageNo = (args?.pageNo as number) || 1; const numOfRows = (args?.numOfRows as number) || 100; const result = await youthApiClient.getSigunguList( sido, pageNo, numOfRows ); let resultText = `📍 시군구 목록 (전체 ${result.totalCount}개)\n\n`; if (Array.isArray(result.items)) { result.items.forEach((item: any, index: number) => { resultText += `${index + 1}. ${item.sigunguNm || "N/A"} (코드: ${ item.sigunguCode || "N/A" })\n`; }); } else if (result.items) { resultText += `1. ${result.items.sigunguNm || "N/A"} (코드: ${ result.items.sigunguCode || "N/A" })\n`; } else { resultText += "조회된 항목이 없습니다.\n"; } resultText += `\n페이지: ${pageNo}/${Math.ceil( result.totalCount / numOfRows )}`; return { content: [ { type: "text", text: resultText, }, ], }; }
- src/index.ts:75-96 (schema)Tool schema definition including name, description, and inputSchema specifying required 'sido' (province name) and optional pagination parameters.{ name: "get_sigungu_list", description: "특정 시도의 시군구(기초자치단체) 목록을 조회합니다", inputSchema: { type: "object", properties: { sido: { type: "string", description: "시도명 (예: 서울, 부산광역시, 경기도)", }, pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, required: ["sido"], }, },
- src/index.ts:54-188 (registration)Registration of the tool in the MCP server's ListToolsRequestSchema handler, listing 'get_sigungu_list' among available tools.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ // 청소년 활동 API 관련 도구 { name: "get_sido_list", description: "청소년 활동 정보 시도(광역자치단체) 목록을 조회합니다", inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, }, }, { name: "get_sigungu_list", description: "특정 시도의 시군구(기초자치단체) 목록을 조회합니다", inputSchema: { type: "object", properties: { sido: { type: "string", description: "시도명 (예: 서울, 부산광역시, 경기도)", }, pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, required: ["sido"], }, }, { name: "search_youth_activities", description: "청소년 활동 프로그램을 검색합니다. 프로그램명, 기관명, 지역, 기간 등으로 필터링 가능합니다", inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 10)", }, atName: { type: "string", description: "프로그램명 (선택사항)", }, orgName: { type: "string", description: "주최자(기관명) (선택사항)", }, sido: { type: "string", description: "시도명 (선택사항, 예: 서울, 부산광역시)", }, startDate: { type: "string", description: "일활동기간시작일 (선택사항, YYYYMMDD 형식)", }, endDate: { type: "string", description: "일활동기간종료일 (선택사항, YYYYMMDD 형식)", }, }, }, }, { name: "get_facility_group_list", description: "청소년 시설 그룹 목록을 조회합니다. 시도, 기관명, 기관유형으로 필터링 가능합니다", inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 10)", }, sido: { type: "string", description: "시도명 (선택사항)", }, stName: { type: "string", description: "기관명 (선택사항)", }, gName: { type: "string", description: "기관유형명 (선택사항)", }, }, }, }, // 기본 유틸리티 도구 { name: "echo", description: "입력받은 메시지를 그대로 반환합니다", inputSchema: { type: "object", properties: { message: { type: "string", description: "반환할 메시지", }, }, required: ["message"], }, }, { name: "get_time", description: "현재 시간을 반환합니다", inputSchema: { type: "object", properties: {}, }, }, ], }; });
- src/youthApiClient.ts:240-286 (helper)Helper method in YouthApiClient that makes HTTP GET to public API endpoint '/getSigunguList' with serviceKey and params, parses XML response, validates resultCode, and returns structured data with totalCount and items array.async getSigunguList( sido: string, pageNo: number = 1, numOfRows: number = 100 ): Promise<any> { try { const response = await this.client.get("/getSigunguList", { params: { serviceKey: this.serviceKey, sido, pageNo, numOfRows, }, }); const parsedData = await this.parseXmlResponse(response.data); if (parsedData.response) { const header = parsedData.response.header; const body = parsedData.response.body; if (header?.resultCode !== "00") { throw new Error( `API 오류: ${header?.resultMsg || "알 수 없는 오류"}` ); } return { totalCount: parseInt(body?.totalCount || "0"), items: body?.items?.item || [], pageNo, numOfRows, }; } throw new Error("예상치 못한 응답 형식"); } catch (error) { if (axios.isAxiosError(error)) { throw new Error( `API 호출 실패: ${error.message}${ error.response?.data ? ` - ${error.response.data}` : "" }` ); } throw error; } }