MCP 书店服务器

系统要求

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

安装

方式一：使用 UV（推荐）

安装 UV（如果尚未安装）:
curl -LsSf https://astral.sh/uv/install.sh | sh # 或在 Windows 上: # powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
克隆并导航到项目目录:
cd mcp-bookstore
安装依赖项（这会自动安装 python 3.13 和所有用到的依赖到 .venv 目录下）:
uv sync

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

导航到项目目录:
cd mcp-bookstore
创建并激活虚拟环境:
python -m venv .venv source .venv/bin/activate # 在 Windows 上: venv\Scripts\activate
安装依赖项:
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

下载客户端：
- 访问 Cherry Studio 官网下载适合您系统的版本
- 支持 Windows、macOS 和 Linux
完成安装：
- 按照安装向导完成 Cherry Studio 的安装
- 首次启动时会进入欢迎界面

配置 MCP 服务器

启动书店 MCP 服务器（以 HTTP 模式）：
uv run fastmcp run src/bookstore_mcp/server.py -t http --port 8000
打开 Cherry Studio：
- 启动 Cherry Studio 应用程序
- 进入设置 → MCP 服务器
添加 MCP 服务器配置：
- 点击 添加服务器
- 填写以下配置信息：
  - 名称: 书城 MCP
  - 类型: streamableHttp
  - URL: http://localhost:8000/mcp
  - 描述: 书城管理和搜索工具（可选）
保存并测试连接：
- 点击保存保存配置
- 点击 测试连接 确认服务器连接正常
- 连接成功后，工具将自动可用

使用书店 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本在库。

Bookstore MCP Server