MCP 书店服务器

系统要求

• Python: 3.13 或更高版本
• 包管理器: UV（推荐）或 pip

安装

方式一：使用 UV（推荐）

1. 安装 UV（如果尚未安装）:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   # 或在 Windows 上:
   # powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. 克隆并导航到项目目录:

   cd mcp-bookstore
   

3. 安装依赖项（这会自动安装 python 3.13 和所有用到的依赖到 .venv 目录下）:

   uv sync
   

方式二：使用 pip 和虚拟环境

1. 导航到项目目录:

   cd mcp-bookstore
   

2. 创建并激活虚拟环境:

   python -m venv .venv
   source .venv/bin/activate  # 在 Windows 上: venv\Scripts\activate
   

3. 安装依赖项:

   pip install -e .
   

启动 MCP 服务器

HTTP 模式

以 HTTP 模式启动服务器，便于与 Cherry Studio 等 AI 客户端集成：

# 使用 UV
uv run fastmcp run src/bookstore_mcp/server.py -t http --port 8000

# 使用已激活的虚拟环境
fastmcp run src/bookstore_mcp/server.py -t http --port 8000

服务器启动后会显示：

INFO     Starting MCP server 'BookStore' with transport 'http' on http://127.0.0.1:8000/mcp

服务器配置

• HTTP 端点: http://localhost:8000/mcp
• 端口: 8000（可通过 --port 标志配置）
• 数据文件: data/books.json（包含图书库存的 JSON 文件）

Cherry Studio 集成

Cherry Studio 是一款功能强大的全能 AI 助手平台，集成了多模型对话、知识库管理、AI 绘画、翻译等功能。通过 MCP（模型上下文协议）支持，Cherry Studio 可以无缝集成本服务，提供图书管理功能。

安装 Cherry Studio

1. 下载客户端：

   • 访问 Cherry Studio 官网 下载适合您系统的版本
   • 支持 Windows、macOS 和 Linux

2. 完成安装：

   • 按照安装向导完成 Cherry Studio 的安装
   • 首次启动时会进入欢迎界面

配置 MCP 服务器

1. 启动书店 MCP 服务器（以 HTTP 模式）：

   uv run fastmcp run src/bookstore_mcp/server.py -t http --port 8000
   

2. 打开 Cherry Studio：

   • 启动 Cherry Studio 应用程序
   • 进入 设置 → MCP 服务器

3. 添加 MCP 服务器配置：

   • 点击 添加服务器
   • 填写以下配置信息：
     • 名称: 书城 MCP
     • 类型: streamableHttp
     • URL: http://localhost:8000/mcp
     • 描述: 书城管理和搜索工具（可选）

4. 保存并测试连接：

   • 点击 保存 保存配置
   • 点击 测试连接 确认服务器连接正常
   • 连接成功后，工具将自动可用

使用书店 MCP 工具

连接成功后，您可以在 Cherry Studio 的对话中使用以下功能。当前书店库存包含10本经典文学作品。

可用的 MCP 工具

本书店服务器提供以下工具：

工具名称	功能描述	参数
get_all_books	获取所有书籍列表	无
get_book_by_id	根据ID获取特定书籍	book_id (整数)
search_books_by_title	按书名搜索	title_query (字符串)
search_books_by_author	按作者搜索	author_query (字符串)
get_books_in_stock	获取有库存的书籍	无
buy_book	购买书籍	book_id (整数), quantity (整数，默认1)
check_availability	检查库存可用性	book_id (整数), quantity (整数，默认1)
restock_book	补充库存	book_id (整数), quantity (整数)

使用示例

以下是常用的查询和操作示例：

浏览和搜索功能

• 显示书店中的所有书籍
• 搜索书名包含"Great"的书籍
• 查找书名里包含"Hobbit"的图书
• 查找George Orwell的所有作品
• 搜索J.R.R. Tolkien写的书
• 找一找Harper Lee的书籍
• 显示目前有库存的所有书籍
• 哪些书还有现货？

书籍信息查询

• 显示ID为1的书籍详细信息
• 查看书籍编号3的详情
• 检查《The Great Gatsby》是否有库存
• ID为7的书籍还有多少本？
• 确认《Animal Farm》能否购买2本

购买和库存管理

• 购买一本《To Kill a Mockingbird》
• 买2本ID为3的书籍
• 我要买《Pride and Prejudice》
• 为《The Catcher in the Rye》补货10本
• 给ID为8的书籍增加5本库存
• 补充《Fahrenheit 451》的库存数量15本

实际对话示例

以下是使用书城MCP工具的实际对话记录，展示了如何通过自然语言与书城系统进行交互：

用户： 书城有什么书

GLM-4.5-Flash | 智譜開放平台：

我来帮您查看书城有哪些书。

书城MCP : get_all_books 已完成

书城有以下书籍：

• The Great Gatsby (了不起的盖茨比) - F. Scott Fitzgerald，库存：15本
• To Kill a Mockingbird (杀死一只知更鸟) - Harper Lee，库存：8本
• Animal Farm (动物农场) - George Orwell，库存：14本
• Pride and Prejudice (傲慢与偏见) - Jane Austen，库存：12本
• The Catcher in the Rye (麦田里的守望者) - J.D. Salinger，库存：6本
• Lord of the Flies (蝇王) - William Golding，库存：10本
• The Hobbit (霍比特人) - J.R.R. Tolkien，库存：18本
• Fahrenheit 451 (华氏451度) - Ray Bradbury，库存：7本
• Jane Eyre (简·爱) - Charlotte Brontë，库存：9本
• The Chronicles of Narnia (纳尼亚传奇) - C.S. Lewis，库存：13本

书城共有10种书籍，涵盖了经典文学作品，库存总数为112本。如果您想了解某本书的详细信息或购买，请告诉我书名或ID。

用户： 买两本 Ray Bradbury 的书

GLM-4.5-Flash | 智譜開放平台：

我需要先找到Ray Bradbury的书籍ID，然后为您购买两本。

书城MCP : search_books_by_author 已完成

书城MCP : buy_book 已完成

已成功购买2本Ray Bradbury的《Fahrenheit 451》！

用户： Fahrenheit 451 还有多少本

GLM-4.5-Flash | 智譜開放平台：

书城MCP : check_availability 已完成

《Fahrenheit 451》目前还有 5本 在库。

更多资源

• Cherry Studio 官方文档
• MCP 配置教程