get_sigungu_list
Retrieve a list of 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 parameters from args, calls youthApiClient.getSigunguList, formats the paginated list of sigungu (districts) with names and codes into a readable 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 (registration)Tool registration in ListTools handler: defines name, description, and input schema requiring 'sido' (province name) with optional pagination.
{ 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/youthApiClient.ts:240-286 (helper)YouthApiClient method that performs the actual API call to '/getSigunguList', sends params including serviceKey and sido (province name), parses XML response, validates resultCode, extracts totalCount and items, handles errors.
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; } } - src/index.ts:78-95 (schema)Input schema definition for the tool: object with required 'sido' string, optional 'pageNo' and 'numOfRows' numbers.
inputSchema: { type: "object", properties: { sido: { type: "string", description: "시도명 (예: 서울, 부산광역시, 경기도)", }, pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, required: ["sido"], },