Aladin Book Search MCP Server

Instructions

Implementation Reference

• src/index.ts:330-396 (handler)

  The handler function that implements the core logic for the 'get_bestsellers' tool. It constructs parameters for Aladin's ItemList API with QueryType 'Bestseller', optionally includes categoryId, year, month, week filters, fetches data via callAladinApi, maps results to standardized BookSearchResult format, and returns formatted text output.
  async ({ maxResults, start, categoryId, year, month, week }) => { try { const params: any = { QueryType: 'Bestseller', MaxResults: maxResults, start: start, SearchTarget: 'Book', Cover: 'Big' }; if (categoryId) { params.CategoryId = categoryId; } if (year) { params.Year = year; } if (month) { params.Month = month; } if (week) { params.Week = week; } const result = await callAladinApi('ItemList.aspx', params); const books: BookSearchResult[] = result.item?.map((item: any) => ({ title: item.title || '', author: item.author || '', publisher: item.publisher || '', pubDate: item.pubDate || '', isbn: item.isbn || '', isbn13: item.isbn13 || '', cover: item.cover || '', categoryName: item.categoryName || '', description: item.description || '', priceStandard: item.priceStandard || 0, priceSales: item.priceSales || 0, link: item.link || '', pages: item.subInfo?.itemPage || undefined, pricePerPage: (item.priceStandard > 0 && item.subInfo?.itemPage > 0) ? parseFloat((item.priceStandard / item.subInfo.itemPage).toFixed(2)) : undefined })) || []; const categoryText = categoryId ? ` (카테고리: ${categoryId})` : ''; const timeText = (year && month && week) ? ` (${year}년 ${month}월 ${week}주)` : ''; return { content: [{ type: 'text', text: `📈 베스트셀러 목록${categoryText}${timeText}\n\n검색된 도서 수: ${books.length}권\n\n${JSON.stringify(books, null, 2)}` }] }; } catch (error) { logger.error(`베스트셀러 조회 중 오류 발생: ${error}`); return { content: [{ type: 'text', text: `베스트셀러 조회 중 오류가 발생했습니다: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } }
• src/index.ts:318-329 (schema)

  The input schema definition for the 'get_bestsellers' tool using Zod validators for parameters including maxResults, start, optional categoryId, year, month, and week.
  { title: '도서 베스트셀러', description: '알라딘 도서 베스트셀러 목록을 조회합니다. 카테고리별로 검색할 수 있으며, 특정 주간의 베스트셀러를 조회할 수 있습니다. 특정 주간을 조회할 때는 연도, 월, 주를 모두 입력해주세요.', inputSchema: { maxResults: z.number().min(1).max(100).default(10).describe('최대 결과 개수'), start: z.number().min(1).default(1).describe('검색 시작 번호'), categoryId: z.string().optional().describe('카테고리 ID (CID) - 특정 카테고리로 검색을 제한할 때 사용'), year: z.number().min(2000).max(2030).optional().describe('조회할 연도 (예: 2025) - 생략하면 현재 주간'), month: z.number().min(1).max(12).optional().describe('조회할 월 (1-12) - 생략하면 현재 주간'), week: z.number().min(1).max(5).optional().describe('조회할 주 (1-5) - 생략하면 현재 주간') } },
• src/index.ts:316-397 (registration)

  The registration of the 'get_bestsellers' tool using McpServer.registerTool, including the tool name, schema, and handler function.
  server.registerTool( 'get_bestsellers', { title: '도서 베스트셀러', description: '알라딘 도서 베스트셀러 목록을 조회합니다. 카테고리별로 검색할 수 있으며, 특정 주간의 베스트셀러를 조회할 수 있습니다. 특정 주간을 조회할 때는 연도, 월, 주를 모두 입력해주세요.', inputSchema: { maxResults: z.number().min(1).max(100).default(10).describe('최대 결과 개수'), start: z.number().min(1).default(1).describe('검색 시작 번호'), categoryId: z.string().optional().describe('카테고리 ID (CID) - 특정 카테고리로 검색을 제한할 때 사용'), year: z.number().min(2000).max(2030).optional().describe('조회할 연도 (예: 2025) - 생략하면 현재 주간'), month: z.number().min(1).max(12).optional().describe('조회할 월 (1-12) - 생략하면 현재 주간'), week: z.number().min(1).max(5).optional().describe('조회할 주 (1-5) - 생략하면 현재 주간') } }, async ({ maxResults, start, categoryId, year, month, week }) => { try { const params: any = { QueryType: 'Bestseller', MaxResults: maxResults, start: start, SearchTarget: 'Book', Cover: 'Big' }; if (categoryId) { params.CategoryId = categoryId; } if (year) { params.Year = year; } if (month) { params.Month = month; } if (week) { params.Week = week; } const result = await callAladinApi('ItemList.aspx', params); const books: BookSearchResult[] = result.item?.map((item: any) => ({ title: item.title || '', author: item.author || '', publisher: item.publisher || '', pubDate: item.pubDate || '', isbn: item.isbn || '', isbn13: item.isbn13 || '', cover: item.cover || '', categoryName: item.categoryName || '', description: item.description || '', priceStandard: item.priceStandard || 0, priceSales: item.priceSales || 0, link: item.link || '', pages: item.subInfo?.itemPage || undefined, pricePerPage: (item.priceStandard > 0 && item.subInfo?.itemPage > 0) ? parseFloat((item.priceStandard / item.subInfo.itemPage).toFixed(2)) : undefined })) || []; const categoryText = categoryId ? ` (카테고리: ${categoryId})` : ''; const timeText = (year && month && week) ? ` (${year}년 ${month}월 ${week}주)` : ''; return { content: [{ type: 'text', text: `📈 베스트셀러 목록${categoryText}${timeText}\n\n검색된 도서 수: ${books.length}권\n\n${JSON.stringify(books, null, 2)}` }] }; } catch (error) { logger.error(`베스트셀러 조회 중 오류 발생: ${error}`); return { content: [{ type: 'text', text: `베스트셀러 조회 중 오류가 발생했습니다: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } );
• src/index.ts:147-168 (helper)

  Shared helper function used by get_bestsellers to make HTTP requests to the Aladin API.
  async function callAladinApi(endpoint: string, params: Record<string, any>): Promise<any> { if (!ALADIN_TTB_KEY || ALADIN_TTB_KEY.length === 0) { throw new Error('알라딘 API 키가 설정되지 않았습니다. ALADIN_TTB_KEY 환경변수를 올바르게 설정해주세요.'); } const baseParams = { ttbkey: ALADIN_TTB_KEY, output: 'js', version: '20131101' }; const finalParams = { ...baseParams, ...params }; const url = `${ALADIN_BASE_URL}/${endpoint}`; try { const response = await axios.get(url, { params: finalParams }); return response.data; } catch (error) { logger.error(`알라딘 API 호출 오류: ${error}`); throw error; } }