Youth Activity Information MCP Server

Instructions

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"],
  },