get_special_new_books

Retrieve notable new book releases from Aladin, filtered by category, to stay updated on trending and specialized literature.

Instructions

알라딘 주목할 만한 신간 리스트를 조회합니다. 카테고리별로 검색할 수 있습니다.

Input Schema

TableJSON Schema

Name	Required	Description
`categoryId`	No	카테고리 ID (CID) - 특정 카테고리로 검색을 제한할 때 사용
`maxResults`	No	최대 결과 개수
`start`	No	검색 시작 번호

Implementation Reference

src/index.ts:479-532 (handler)

The main handler function for the 'get_special_new_books' tool. It constructs parameters for the Aladin API with QueryType 'ItemNewSpecial', calls the API via callAladinApi, maps the response items to BookSearchResult objects, and returns a formatted text response or error.

async ({ maxResults, start, categoryId }) => {
  try {
    const params: any = {
      QueryType: 'ItemNewSpecial',
      MaxResults: maxResults,
      start: start,
      SearchTarget: 'Book',
      Cover: 'Big'
    };

    if (categoryId) {
      params.CategoryId = categoryId;
    }

    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})` : '';
    
    return {
      content: [{
        type: 'text',
        text: `⭐ 주목할 만한 신간 리스트${categoryText}\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:467-533 (registration)

The server.registerTool call that registers the 'get_special_new_books' tool, including its title, description, input schema, and handler function.

// 주목할 만한 신간 리스트 도구 등록
server.registerTool(
  'get_special_new_books',
  {
    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) - 특정 카테고리로 검색을 제한할 때 사용')
    }
  },
  async ({ maxResults, start, categoryId }) => {
    try {
      const params: any = {
        QueryType: 'ItemNewSpecial',
        MaxResults: maxResults,
        start: start,
        SearchTarget: 'Book',
        Cover: 'Big'
      };

      if (categoryId) {
        params.CategoryId = categoryId;
      }

      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})` : '';
      
      return {
        content: [{
          type: 'text',
          text: `⭐ 주목할 만한 신간 리스트${categoryText}\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:473-477 (schema)

Zod input schema defining parameters for the tool: maxResults, start, and optional categoryId.

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) - 특정 카테고리로 검색을 제한할 때 사용')
}

src/index.ts:122-137 (schema)

TypeScript interface BookSearchResult used to type the processed book data in the handler's result mapping.

interface BookSearchResult {
  title: string;
  author: string;
  publisher: string;
  pubDate: string;
  isbn: string;
  isbn13: string;
  cover: string;
  categoryName: string;
  description: string;
  priceStandard: number;
  priceSales: number;
  link: string;
  pages?: number; // 페이지 수 추가
  pricePerPage?: number; // 쪽단가 추가
}

src/index.ts:147-168 (helper)

Helper function callAladinApi that makes HTTP requests to the Aladin API endpoints, used by the handler to fetch 'ItemList.aspx' with the specified parameters.

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;
  }
}

Aladin Book Search MCP Server