JinDaGe - mcp-aladin-books-server MCP Details

article

README

🚀 阿拉丁图书搜索 MCP 服务器 (Node.js)

这是一个利用阿拉丁图书搜索 API 的 MCP（Model Context Protocol）服务器，可帮助用户通过多种方式搜索图书信息。

🚀 快速开始

要使用此 MCP 服务器，需先获取阿拉丁的 API 密钥，并完成 DXT 安装与服务器配置。

阿拉丁 API 密钥获取

访问阿拉丁 TTB 网站。
完成注册并登录。
申请 API 密钥。

DXT 安装

下载 DXT 文件。
在云端桌面选择【设置】-【扩展程序】。
将下载的 DXT 文件拖放至指定区域。
输入 API 密钥。

服务器配置

1. 安装依赖并构建项目

npm install
npm run build

2. 在 MCP 客户端输入信息

{
  "mcpServers": {
    "aladin-books": {
      "command": "node",
      "args": [
        "<路径>/mcp-aladin-books-server/dist/index.js"
      ],
      "env": {
        "ALADIN_TTB_KEY": "阿拉丁_TTB_密钥"
      }
    }
  }
}

✨ 主要特性

图书搜索：支持通过书名、作者、出版社和关键词进行图书搜索。
详细信息查询：可根据 ISBN 查询图书详细信息。
畅销书查询：能获取阿拉丁畅销书列表，支持按类别搜索。
类别搜索：可搜索和查看图书类别，优先显示上级类别。

📦 安装指南

依赖安装与构建

npm install
npm run build

MCP 客户端信息配置

{
  "mcpServers": {
    "aladin-books": {
      "command": "node",
      "args": [
        "<路径>/mcp-aladin-books-server/dist/index.js"
      ],
      "env": {
        "ALADIN_TTB_KEY": "阿拉丁_TTB_密钥"
      }
    }
  }
}

💻 使用示例

基础用法

可在 MCP 客户端使用以下代码进行操作：

// 图书搜索
await callTool('search_books', {
  query: 'Python',
  searchType: 'Title',
  maxResults: 5
});

// 图书详细信息
await callTool('get_book_detail', {
  isbn: '9788966262755'
});

// 全部图书畅销书查询
await callTool('get_bestsellers', {
  maxResults: 10
});

// 按类别查询图书畅销书
await callTool('get_bestsellers', {
  maxResults: 10,
  categoryId: '798' // 例如：计算机类别
});

// 查询新书全量列表
await callTool('get_new_books', {
  maxResults: 10
});

// 按类别查询新书
await callTool('get_new_books', {
  maxResults: 10,
  categoryId: '798' // 例如：计算机类别
});

// 查询值得关注的新书列表
await callTool('get_special_new_books', {
  maxResults: 10
});

// 查询编辑推荐列表
await callTool('get_editor_choice', {
  maxResults: 10
});

// 查询博主畅销书列表（仅国内图书）
await callTool('get_blogger_best', {
  maxResults: 10,
  categoryId: '798' // 例如：计算机类别
});

// 搜索图书类别
await callTool('search_categories', {
  searchTerm: '小说',
  maxResults: 10
});

// 查询常用主要类别列表
await callTool('get_popular_categories', {
  limit: 10
});

// 以表格形式显示图书信息（搜索）
await callTool('format_books_table', {
  type: 'search',
  query: 'Python',
  searchType: 'Title',
  maxResults: 5
});

// 以表格形式显示图书信息（畅销书）
await callTool('format_books_table', {
  type: 'bestseller',
  maxResults: 10,
  categoryId: '798'
});

// 以表格形式显示图书信息（新书全量）
await callTool('format_books_table', {
  type: 'new_books',
  maxResults: 10
});

// 以表格形式显示图书信息（值得关注的新书）
await callTool('format_books_table', {
  type: 'special_new_books',
  maxResults: 10
});

// 以表格形式显示图书信息（编辑推荐）
await callTool('format_books_table', {
  type: 'editor_choice',
  maxResults: 10
});

// 以表格形式显示图书信息（博主畅销书）
await callTool('format_books_table', {
  type: 'blogger_best',
  maxResults: 10,
  categoryId: '798'
});

📚 详细文档

工具列表

1. search_books

用于搜索图书。参数：

query (string)：搜索词。
searchType (enum)：搜索类型（Title、Author、Publisher、Keyword）。
maxResults (number)：最大结果数量（1 - 100，默认值：10）。
start (number)：搜索起始编号（默认值：1）。

2. get_book_detail

通过 ISBN 查询图书详细信息。参数：

isbn (string)：图书的 ISBN（10 位或 13 位）。

3. get_bestsellers

查询图书畅销书列表，支持按类别搜索。参数：

maxResults (number)：最大结果数量（1 - 100，默认值：10）。
start (number)：搜索起始编号（默认值：1）。
categoryId (string, optional)：类别 ID（CID） - 限制特定类别搜索。

4. get_new_books

查询新书全量列表，支持按类别搜索。参数：

maxResults (number)：最大结果数量（1 - 100，默认值：10）。
start (number)：搜索起始编号（默认值：1）。
categoryId (string, optional)：类别 ID（CID） - 限制特定类别搜索。

5. get_special_new_books

查询值得关注的新书列表，支持按类别搜索。参数：

maxResults (number)：最大结果数量（1 - 100，默认值：10）。
start (number)：搜索起始编号（默认值：1）。
categoryId (string, optional)：类别 ID（CID） - 限制特定类别搜索。

6. get_editor_choice

查询编辑推荐列表，支持按类别搜索。参数：

maxResults (number)：最大结果数量（1 - 100，默认值：10）。
start (number)：搜索起始编号（默认值：1）。
categoryId (string, optional)：类别 ID（CID） - 限制特定类别搜索。

7. get_blogger_best

查询博主畅销书列表（仅国内图书），支持按类别搜索。参数：

maxResults (number)：最大结果数量（1 - 100，默认值：10）。
start (number)：搜索起始编号（默认值：1）。
categoryId (string, optional)：类别 ID（CID） - 限制特定类别搜索。

8. search_categories

搜索图书类别，优先显示上级类别。参数：

searchTerm (string)：要搜索的类别名称。
maxResults (number)：最大结果数量（1 - 50，默认值：20）。

9. get_popular_categories

查询常用主要类别列表，优先显示上级类别。参数：

limit (number)：要显示的类别数量（1 - 50，默认值：20）。

10. format_books_table

将图书信息整理成表格形式显示，支持搜索、ISBN 查询和各种图书列表查询。参数：

type (enum)：查询类型（search、isbn、bestseller、new_books、special_new_books、editor_choice、blogger_best）。
query (string, optional)：搜索词（当 type 为 search 时必填）。
isbn (string, optional)：ISBN（当 type 为 isbn 时必填）。
searchType (enum)：搜索类型（Title、Author、Publisher、Keyword，默认值：Title）。
maxResults (number)：最大结果数量（1 - 50，默认值：10）。
categoryId (string, optional)：类别 ID（列表查询时限制类别）。

🔧 技术细节

项目结构

server/
├── src/
│   ├── index.ts                     # 主服务器文件
│   └── aladin_book_categories.json  # 类别信息文件（大容量）
├── dist/                            # 构建结果
├── package.json                     # 包配置
├── tsconfig.json                    # TypeScript 配置
├── env.example                      # 环境变量示例
├── test.js                          # 测试文件
└── README.md                        # 文档

技术栈

Node.js：运行时环境。
TypeScript：类型安全（目标 ES2020，模块 ESNext）。
@modelcontextprotocol/sdk：MCP 协议实现。
axios：HTTP 客户端。
zod：模式验证。

开发依赖

tsx：TypeScript 开发执行器。
@types/node：Node.js 类型定义。

构建配置

目标：ES2020
模块：ESNext
输出目录：dist/
源映射：包含
声明文件：生成
JSON 模块：支持

环境变量

# 阿拉丁 TTB 密钥（必填）
ALADIN_TTB_KEY=your_aladin_ttb_key_here

📄 许可证

ISC

mcp-aladin-books-server