search_youth_activities
Search youth activity programs in South Korea by program name, organization, region, or date range to find suitable opportunities.
Instructions
청소년 활동 프로그램을 검색합니다. 프로그램명, 기관명, 지역, 기간 등으로 필터링 가능합니다
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageNo | No | 페이지 번호 (기본값: 1) | |
| numOfRows | No | 한 페이지 결과 수 (기본값: 10) | |
| atName | No | 프로그램명 (선택사항) | |
| orgName | No | 주최자(기관명) (선택사항) | |
| sido | No | 시도명 (선택사항, 예: 서울, 부산광역시) | |
| startDate | No | 일활동기간시작일 (선택사항, YYYYMMDD 형식) | |
| endDate | No | 일활동기간종료일 (선택사항, YYYYMMDD 형식) |
Implementation Reference
- src/index.ts:274-336 (handler)Main execution handler for the 'search_youth_activities' tool. Extracts parameters from input arguments, calls the YouthApiClient.searchActivities method, formats the search results into a readable text summary, and returns it as MCP content.case "search_youth_activities": { const params = { pageNo: (args?.pageNo as number) || 1, numOfRows: (args?.numOfRows as number) || 10, atName: args?.atName as string | undefined, orgName: args?.orgName as string | undefined, sido: args?.sido as string | undefined, startDate: args?.startDate as string | undefined, endDate: args?.endDate as string | undefined, }; const result = await youthApiClient.searchActivities(params); let resultText = `🎯 청소년 활동 검색 결과 (전체 ${result.totalCount}개)\n\n`; if (Array.isArray(result.items)) { result.items.forEach((item: any, index: number) => { const itemNum = (params.pageNo - 1) * params.numOfRows + index + 1; resultText += `${itemNum}. ${item.actTitle || "제목 없음"}\n`; if (item.organNm) resultText += ` 기관: ${item.organNm}\n`; if (item.actBeginDt || item.actEndDt) resultText += ` 기간: ${item.actBeginDt || "미정"} ~ ${ item.actEndDt || "미정" }\n`; if (item.actPlace) resultText += ` 장소: ${item.actPlace}\n`; if (item.actTarget) resultText += ` 대상: ${item.actTarget}\n`; if (item.actPart) resultText += ` 분야: ${item.actPart}\n`; if (item.youthPolicyShortIntro) resultText += ` 소개: ${item.youthPolicyShortIntro}\n`; resultText += "\n"; }); } else if (result.items) { resultText += `1. ${result.items.actTitle || "제목 없음"}\n`; if (result.items.organNm) resultText += ` 기관: ${result.items.organNm}\n`; if (result.items.actBeginDt || result.items.actEndDt) resultText += ` 기간: ${result.items.actBeginDt || "미정"} ~ ${ result.items.actEndDt || "미정" }\n`; if (result.items.actPlace) resultText += ` 장소: ${result.items.actPlace}\n`; resultText += "\n"; } else { resultText += "검색된 활동이 없습니다.\n\n"; } resultText += `페이지: ${params.pageNo}/${Math.ceil( result.totalCount / params.numOfRows )}`; return { content: [ { type: "text", text: resultText, }, ], }; }
- src/index.ts:97-133 (registration)Tool registration in the ListTools response, including name, description, and complete input schema definition for 'search_youth_activities'.{ 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 형식)", }, }, }, },
- src/index.ts:100-132 (schema)Input schema definition specifying parameters and types for the 'search_youth_activities' tool.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 형식)", }, }, },
- src/youthApiClient.ts:122-176 (helper)Helper method in YouthApiClient class that performs the actual API request to the public data portal for youth activities search, parses the XML response, handles errors, and returns structured data.async searchActivities(params: { pageNo?: number; numOfRows?: number; atName?: string; // 프로그램명 orgName?: string; // 주최자(기관명) sido?: string; // 시도 startDate?: string; // 일활동기간시작일 (YYYYMMDD) endDate?: string; // 일활동기간종료일 (YYYYMMDD) }): Promise<any> { try { const response = await this.client.get("/getJtvtsProgrmList", { params: { serviceKey: this.serviceKey, pageNo: params.pageNo || 1, numOfRows: params.numOfRows || 10, atName: params.atName, orgName: params.orgName, sido: params.sido, startDate: params.startDate, endDate: params.endDate, }, }); 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: params.pageNo || 1, numOfRows: params.numOfRows || 10, }; } throw new Error("예상치 못한 응답 형식"); } catch (error) { if (axios.isAxiosError(error)) { throw new Error( `API 호출 실패: ${error.message}${ error.response?.data ? ` - ${error.response.data}` : "" }` ); } throw error; } }