内容
# 药房库存 MCP 服务器 — SQLite + Claude 桌面版
一个适合初学者的 **模型上下文协议（MCP）** 服务器，连接 AI 助手到药房库存数据库。
本项目将第一个基于 JSON 的 MCP 演示升级为一个真正的 **支持 SQLite 的库存助手**。它允许 **Claude 桌面版** 等 AI 客户端调用预定义的工具进行库存检查、补货分析、到期检查、商品搜索、库存更新和库存摘要生成。
## 目录
- [概述](#概述)
- [架构](#架构)
- [功能](#功能)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [暴露给 AI 客户端的工具](#暴露给-ai-客户端的工具)
- [设置说明](#设置说明)
- [使用 MCP Inspector 运行](#使用-mcp-inspector-运行)
- [连接到 Claude 桌面版](#连接到-claude-桌面版)
- [提示示例](#提示示例)
- [手动查看 SQLite 数据库](#手动查看-sqlite-数据库)
- [故障排除](#故障排除)
- [安全注意事项](#安全注意事项)
- [未来改进](#未来改进)
## 概述
本项目演示了 AI 助手如何通过 MCP 服务器安全地执行与库存相关的操作。
MCP 服务器没有直接提供数据库访问权限，而是暴露了一组受控的工具。AI 客户端可以发现这些工具，请求用户批准，调用相关工具，并以自然语言返回结果。
### 示例用户
```text
给我看看库存最低的药品。
```
AI 客户端可以调用：
```text
get_lowest_stock_item
```
MCP 服务器然后查询 SQLite 数据库并返回匹配的库存记录。
## 架构
```text
Claude 桌面版 / MCP Inspector
|
| MCP 工具调用
v
药房库存 MCP 服务器
|
| SQL 查询
v
SQLite 数据库
inventory.db
|
v
inventory_items 表
```
### 旧版本
```text
MCP 工具 -> inventory.json
```
### 新版本
```text
MCP 工具 -> SQLite 数据库 -> inventory_items 表
```
## 功能
- SQLite 数据库集成
- 自动数据库和表创建
- 首次运行插入种子库存数据
- 用于库存、到期、补货、搜索和摘要操作的 MCP 工具
- Claude 桌面版集成
- MCP Inspector 支持本地测试
- 适合初学者和作品集使用的简单结构
- 不需要外部数据库服务器
## 技术栈
| 组件 | 技术 |
|---|---|
| 语言 | Python |
| 协议 | 模型上下文协议 |
| MCP 框架 | FastMCP / MCP Python SDK |
| 数据库 | SQLite |
| AI 客户端 | Claude 桌面版 |
| 测试工具 | MCP Inspector |
## 项目结构
```text
pharmacy-mcp-server-sqlite/
│
├── server.py # 主要的 MCP 服务器和工具定义
├── requirements.txt # Python 依赖项
├── inventory.db # SQLite 数据库文件，首次运行后自动创建
├── README.md # 项目文档
└── pharmacy_mcp/ # Python 虚拟环境，本地创建
```
> 注意：`pharmacy_mcp/` 和 `inventory.db` 是本地生成的，不需要提交到 Git。
## 暴露给 AI 客户端的工具
### 1. `get_lowest_stock_item()`
返回库存中可用库存最低的商品。
示例提示：
```text
给我看看库存最低的商品。
```
### 2. `get_low_stock_items(limit=5)`
按库存数量升序返回有限数量的库存商品。
示例提示：
```text
给我看看 5 种库存最低的药品。
```
### 3. `get_items_below_reorder_level()`
返回当前库存低于或等于补货级别的所有商品。
示例提示：
```text
哪些商品需要补货？
```
### 4. `search_inventory_item(search_text)`
按名称、类别或供应商搜索库存商品。
示例输入：
```json
{
"search_text": "tablet"
}
```
示例提示：
```text
在库存中搜索 tablet 类型的商品。
```
### 5. `get_near_expiry_items(days=30)`
返回在给定天数内到期的商品。
示例输入：
```json
{
"days": 30
}
```
示例提示：
```text
哪些药品将在接下来的 30 天内到期？
```
### 6. `get_expired_items()`
返回已经到期的商品。
示例提示：
```text
给我看看所有已经到期的药品。
```
### 7. `update_stock(item_id, new_quantity)`
更新特定库存商品的库存数量。
示例输入：
```json
{
"item_id": 3,
"new_quantity": 40
}
```
示例提示：
```text
更新 ID 为 3 的商品库存数量为 40。
```
### 8. `add_inventory_item(...)`
将新商品添加到库存数据库。
示例输入：
```json
{
"name": "布洛芬 400mg",
"category": "片剂",
"quantity_in_stock": 60,
"reorder_level": 25,
"supplier": "PainRelief 分销商",
"unit_price": 7.5,
"manufacture_date": "2025-09-01",
"expiry_date": "2027-09-01"
}
```
示例提示：
```text
添加布洛芬 400mg 作为新的片剂商品，库存数量为 60。
```
### 9. `get_inventory_summary()`
返回库存状态的高级摘要。
示例提示：
```text
给我一个库存摘要。
```
## 设置说明
### 1. 打开项目文件夹
```bash
cd pharmacy-mcp-server-sqlite
```
### 2. 创建 Python 虚拟环境
```bash
python3 -m venv pharmacy_mcp
```
### 3. 激活虚拟环境
```bash
source pharmacy_mcp/bin/activate
```
您的终端提示符应显示类似的内容：
```text
(pharmacy_mcp) yoosufahamed@Yoosufs-MacBook-Air pharmacy-mcp-server-sqlite %
```
### 4. 安装依赖项
```bash
pip install -r requirements.txt
```
## 使用 MCP Inspector 运行
MCP Inspector 对于在连接 AI 客户端之前测试 MCP 工具非常有用。
```bash
mcp dev server.py
```
这应该会在您的浏览器中打开 MCP Inspector。
如果 Inspector 尝试使用 `uv` 但失败，请手动设置连接字段：
```text
传输类型：STDIO
命令：python
参数：server.py
```
然后点击 **连接**。
## 测试 MCP Inspector 中的工具
### 获取最低库存商品
工具：
```text
get_lowest_stock_item
```
### 搜索库存
工具：
```text
search_inventory_item
```
输入：
```json
{
"search_text": "tablet"
}
```
### 更新库存
工具：
```text
update_stock
```
输入：
```json
{
"item_id": 3,
"new_quantity": 40
}
```
### 添加商品
工具：
```text
add_inventory_item
```
输入：
```json
{
"name": "布洛芬 400mg",
"category": "片剂",
"quantity_in_stock": 60,
"reorder_level": 25,
"supplier": "PainRelief 分销商",
"unit_price": 7.5,
"manufacture_date": "2025-09-01",
"expiry_date": "2027-09-01"
}
```
## 连接到 Claude 桌面版
Claude 桌面版可以通过配置文件运行本地 MCP 服务器。
### 1. 获取您的 Python 路径
在激活的虚拟环境中运行：
```bash
which python
```
示例输出：
```text
/Users/name/Desktop/Projects/pharmacy_mcp_sever Project/pharmacy-mcp-server-sqlite/pharmacy_mcp/bin/python
```
### 2. 获取您的项目路径
运行：
```bash
pwd
```
示例输出：
```text
/Users/name/Desktop/Projects/pharmacy_mcp_sever Project/pharmacy-mcp-server-sqlite
```
您的 `server.py` 路径将是：
```text
/Users/name/Desktop/Projects/pharmacy_mcp_sever Project/pharmacy-mcp-server-sqlite/server.py
```
### 3. 打开 Claude 桌面版配置
在 macOS 上：
```bash
open -a TextEdit "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
```
如果文件不存在：
```bash
mkdir -p "$HOME/Library/Application Support/Claude"
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
open -a TextEdit "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
```
### 4. 添加 MCP 服务器配置
如果您的配置文件已经有一个 `preferences` 对象，请添加 `mcpServers` 作为另一个顶级键。
示例：
```json
{
"preferences": {
"quickEntryShortcut": "double-tap-option",
"sidebarMode": "chat"
},
"mcpServers": {
"pharmacy-inventory": {
"command": "/Users/name/Desktop/Projects/pharmacy_mcp_sever Project/pharmacy-mcp-server-sqlite/pharmacy_mcp/bin/python",
"args": [
"/Users/name/Desktop/Projects/pharmacy_mcp_sever Project/pharmacy-mcp-server-sqlite/server.py"
]
}
}
}
```
用您的实际 `which python` 输出替换 `command` 值。
用您的实际 `server.py` 路径替换 `args` 值。
### 5. 重启 Claude 桌面版
完全退出 Claude 桌面版：
```text
Command + Q
```
然后重新打开 Claude 桌面版。
Claude 现在应该检测到 `pharmacy-inventory` MCP 服务器及其工具。
## 提示示例
连接 Claude 桌面版后，尝试这些提示。
### 库存检查
```text
使用药房库存工具，给我看看库存最低的商品。
```
```text
给我看看 5 种库存最低的药品。
```
```text
哪些库存商品低于补货级别？
```
### 到期检查
```text
哪些药品已经过期？
```
```text
哪些药品将在接下来的 30 天内到期？
```
### 搜索
```text
在库存中搜索 tablet 类型的商品。
```
```text
查找所有由 HealthCare 供应商提供的商品。
```
### 库存更新
```text
更新 ID 为 3 的商品库存数量为 40。
```
### 添加新商品
```text
添加一种名为布洛芬 400mg 的新药品。类别为片剂，数量为 60，补货级别为 25，供应商为 PainRelief 分销商，单价为 7.5，生产日期为 2025-09-01，到期日期为 2027-09-01。
```
### 摘要
```text
给我一个完整的库存摘要，并告诉我需要注意什么。
```
## 手动查看 SQLite 数据库
您可以使用 SQLite 命令行界面检查数据库。
```bash
sqlite3 inventory.db
```
显示表：
```sql
.tables
```
查看库存记录：
```sql
SELECT id, name, quantity_in_stock, reorder_level FROM inventory_items;
```
退出 SQLite：
```sql
.quit
```
您还可以使用 **DB Browser for SQLite** 等 GUI 工具以可视化方式检查 `inventory.db`。
## 故障排除
### 问题：`spawn uv ENOENT`
原因：
MCP Inspector 尝试运行 `uv` 但 `uv` 未安装。
解决方法：
在 MCP Inspector 中手动设置：
```text
传输类型：STDIO
命令：python
参数：server.py
```
### 问题：`No module named mcp`
原因：
Claude 桌面版使用错误的 Python 解释器。
解决方法：
使用激活的虚拟环境中的 Python 路径：
```bash
source pharmacy_mcp/bin/activate
which python
```
将该输出粘贴到 Claude 配置的 `command` 字段中。
### 问题：Claude 未显示 MCP 工具
可能原因：
- Claude 桌面版未完全重启
- JSON 配置文件有无效语法
- Python 路径错误
- `server.py` 路径错误
- MCP 服务器在启动期间崩溃
解决方法：
1. 验证配置文件格式。
2. 使用 `which python` 确认 Python 路径。
3. 使用 `pwd` 确认项目路径。
4. 完全退出 Claude 桌面版。
5. 重新打开 Claude 桌面版。
### 问题：JSON 配置文件在编辑后损坏
仅使用一个外部 JSON 对象。
正确结构：
```json
{
"preferences": {
"sidebarMode": "chat"
},
"mcpServers": {
"pharmacy-inventory": {
"command": "/path/to/python",
"args": [
"/path/to/server.py"
]
}
}
}
```
## 安全注意事项
本项目用于学习和本地测试。
对于生产系统：
- 不要暴露原始 SQL 执行工具
- 验证所有用户输入
- 添加身份验证和授权
- 在可能的情况下使用只读工具
- 记录库存更新等写入操作
- 在破坏性操作前请求用户确认
- 避免暴露敏感的客户、处方或员工数据
- 按角色和权限级别限制数据库访问
安全设计原则是：
```text
AI 决定请求哪个工具。
MCP 服务器控制实际允许的操作。
```
## 未来改进
- 用 PostgreSQL 或 MySQL 替换 SQLite
- 连接到 Django ORM
- 连接到 MongoDB
- 添加基于角色的访问控制
- 添加库存更新的审计日志
- 添加供应商补货报告生成
- 添加 PDF/CSV 报告生成
- 添加仪表盘 API 集成
- 添加只读和启用写入的工具分离
- 为每个 MCP 工具添加单元测试
- 添加 Docker 支持
- 部署为远程 MCP 服务器
## 演示工作流
1. 用户提示 Claude 桌面版
2. Claude 调用 MCP 工具
3. MCP 服务器查询/更新 SQLite
4. 审计日志记录操作
5. Claude 解释结果
---
