Bookstore MCP Server

# MCP 书店服务器 ## 系统要求 - **Python**: 3.13 或更高版本 - **包管理器**: UV（推荐）或 pip ## 安装 ### 方式一：使用 UV（推荐） 1. **安装 UV**（如果尚未安装）: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh # 或在 Windows 上: # powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` 2. **克隆并导航到项目目录**: ```bash cd mcp-bookstore ``` 3. **安装依赖项**（这会自动安装 python 3.13 和所有用到的依赖到 `.venv` 目录下）: ```bash uv sync ``` ### 方式二：使用 pip 和虚拟环境 1. **导航到项目目录**: ```bash cd mcp-bookstore ``` 2. **创建并激活虚拟环境**: ```bash python -m venv .venv source .venv/bin/activate # 在 Windows 上: venv\Scripts\activate ``` 3. **安装依赖项**: ```bash pip install -e . ``` ## 启动 MCP 服务器 ### HTTP 模式 以 HTTP 模式启动服务器，便于与 Cherry Studio 等 AI 客户端集成： ```bash # 使用 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](https://www.cherry-ai.com/) 是一款功能强大的全能 AI 助手平台，集成了多模型对话、知识库管理、AI 绘画、翻译等功能。通过 MCP（模型上下文协议）支持，Cherry Studio 可以无缝集成本服务，提供图书管理功能。 ### 安装 Cherry Studio 1. **下载客户端**： - 访问 [Cherry Studio 官网](https://docs.cherry-ai.com/cherry-studio/download) 下载适合您系统的版本 - 支持 Windows、macOS 和 Linux 2. **完成安装**： - 按照安装向导完成 Cherry Studio 的安装 - 首次启动时会进入欢迎界面 ### 配置 MCP 服务器 1. **启动书店 MCP 服务器**（以 HTTP 模式）： ```bash 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 官方文档](https://docs.cherry-ai.com/) - [MCP 配置教程](https://docs.cherry-ai.com/advanced-basic/mcp/config)