MedifinderMCP 服务器

一个用于药品库存查询的 MCP (模型上下文协议) 服务器，旨在与 Claude 等 AI 助手一起使用。

概述

MedifinderMCP 服务器提供工具和资源，用于通过模型上下文协议 (MCP) 查询药品库存数据库。它允许 AI 助手和其他客户端：

• 按名称或位置搜索药品
• 检查不同医疗机构的药品可用性
• 获取特定药品的库存信息
• 查看按地区划分的药品可用性统计信息
• 分析整个医疗系统的库存状态

数据库模式

该应用程序使用规范化的数据库模式：

Region
  - region_id (PK)
  - name
  - code
  - created_at
  - updated_at

MedicalCenter
  - center_id (PK)
  - code
  - name
  - region_id (FK -> Region)
  - category
  - reporter_name
  - institution_type
  - reporter_type
  - address
  - latitude
  - longitude
  - created_at
  - updated_at

ProductType
  - type_id (PK)
  - code
  - name
  - description
  - created_at
  - updated_at

Product
  - product_id (PK)
  - code
  - name
  - type_id (FK -> ProductType)
  - description
  - dosage_form
  - strength
  - created_at
  - updated_at

Inventory
  - inventory_id (PK)
  - center_id (FK -> MedicalCenter)
  - product_id (FK -> Product)
  - current_stock
  - avg_monthly_consumption
  - accumulated_consumption_4m
  - measurement
  - last_month_consumption
  - last_month_stock
  - status_indicator
  - cpma_12_months_ago
  - cpma_24_months_ago
  - cpma_36_months_ago
  - accumulated_consumption_12m
  - report_date
  - status
  - created_at
  - updated_at

User
  - user_id (PK)
  - phone_number
  - name
  - preferred_location
  - created_at
  - updated_at

SearchHistory
  - search_id (PK)
  - user_id (FK -> User)
  - product_query
  - location_query
  - search_radius
  - results_count
  - created_at

项目结构

medifinder-mcp/
├── app/
│   ├── __init__.py
│   ├── config.py            # 配置管理
│   ├── db/
│   │   ├── __init__.py
│   │   ├── connection.py    # 数据库连接处理
│   │   └── queries.py       # SQL 查询
│   ├── models/
│   │   ├── __init__.py
│   │   ├── base.py          # 带有时间戳字段的基础模型
│   │   ├── region.py        # 地区模型
│   │   ├── medical_center.py # 医疗中心模型
│   │   ├── product_type.py  # 产品类型模型
│   │   ├── product.py       # 产品模型
│   │   ├── inventory.py     # 库存模型
│   │   ├── user.py          # 用户模型
│   │   └── search_history.py # 搜索历史模型
│   ├── mcp/
│   │   ├── __init__.py
│   │   ├── server.py        # MCP 服务器设置
│   │   ├── tools.py         # 工具实现
│   │   ├── resources.py     # 资源实现
│   │   └── prompts.py       # 提示模板
│   └── utils/
│       ├── __init__.py
│       └── helpers.py       # 辅助函数
├── main.py                  # 应用程序入口点
├── requirements.txt         # 依赖项
└── README.md                # 文档

MCP 功能

工具

• search_medicines: 按名称或位置搜索药品
• get_medicine_locations: 查找药品可用的位置
• get_medicine_stock: 获取特定药品的库存信息
• get_regional_statistics: 获取按地区划分的药品统计信息
• get_medicine_status: 获取总体药品统计信息
• diagnose_database: 检查数据库连接和内容
• troubleshoot_connection: 详细的数据库连接诊断
• create_database_schema: 基于模型创建数据库表

资源

• product://{id}: 按 ID 获取产品详细信息
• stock://{name}: 按名称获取产品的库存信息
• locations://{region}: 获取特定地区的医疗中心
• statistics://stock: 获取总体库存统计信息
• statistics://regions: 获取区域统计信息

提示

• medicine_search_prompt: 按名称搜索药品的模板
• medicine_availability_prompt: 检查药品可用性的模板
• medicine_statistics_prompt: 分析药品统计信息的模板
• regional_availability_prompt: 分析区域药品可用性的模板

安装

1. 克隆存储库：

   git clone https://github.com/yourusername/medifinder-mcp.git
   cd medifinder-mcp
   

2. 创建一个虚拟环境并安装依赖项：

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
   pip install -r requirements.txt
   

3. 通过创建 .env 文件来设置环境变量：

   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=medifinderbot
   DB_USER=your_user
   DB_PASSWORD=your_password
   DEBUG=True
   ENV=development
   SERVER_NAME=MedifinderMCP
   SERVER_VERSION=1.0.0
   MCP_SERVER_NAME=MedifinderMCP
   MCP_SERVER_DESCRIPTION=MCP 服务器，用于药品库存查询
   MAX_SEARCH_RESULTS=50
   SEARCH_SIMILARITY_THRESHOLD=0.3
   

4. 创建数据库：

   # 连接到 PostgreSQL
   psql -U postgres
   
   # 创建数据库和用户
   CREATE DATABASE medifinderbot;
   CREATE USER your_user WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE medifinderbot TO your_user;
   
   # 退出 PostgreSQL
   \q
   

5. 初始化数据库模式： 启动服务器后，使用 create_database_schema 工具创建表。

用法

在本地运行服务器

您可以直接运行 MCP 服务器：

python main.py

使用 MCP Inspector

对于开发和测试，MCP Inspector 提供了一种与服务器交互的便捷方式：

1. 安装 MCP CLI：

   pip install mcp[cli]
   

2. 在开发模式下运行服务器：

   python -m mcp dev main.py
   

3. MCP Inspector 将在您的浏览器中打开，允许您：

   • 测试工具和资源
   • 查看诊断工具的输出
   • 尝试不同的查询

与 Claude Desktop 集成

要将服务器与 Claude Desktop 一起使用：

1. 创建一个用于可靠启动的批处理文件 (run-mcp-server.bat)：

   @echo off
   cd /d %~dp0
   call venv\Scripts\activate.bat
   python main.py
   

2. 在 Claude Desktop 中安装服务器：

   mcp install run-mcp-server.bat -f .env
   

3. 或者，手动编辑 Claude Desktop 的配置文件：

   {
     "mcpServers": {
       "MedifinderMCP": {
         "command": "C:\\path\\to\\project\\venv\\Scripts\\python.exe",
         "args": ["C:\\path\\to\\project\\main.py"],
         "env": {
           "DB_HOST": "localhost",
           "DB_PORT": "5432",
           "DB_NAME": "medifinderbot",
           "DB_USER": "your_user",
           "DB_PASSWORD": "your_password",
           "DEBUG": "True",
           "ENV": "development",
           "SERVER_NAME": "MedifinderMCP",
           "SERVER_VERSION": "1.0.0",
           "MCP_SERVER_NAME": "MedifinderMCP",
           "MCP_SERVER_DESCRIPTION": "MCP 服务器，用于药品库存查询",
           "MAX_SEARCH_RESULTS": "50",
           "SEARCH_SIMILARITY_THRESHOLD": "0.3"
         }
       }
     }
   }
   

4. 在 Claude Desktop 中，从服务器下拉列表中选择 MedifinderMCP 服务器，以在您的对话中启用它。

故障排除

常见问题

1. 数据库连接问题:

   • 使用 troubleshoot_connection 工具诊断连接问题
   • 验证 .env 文件中的数据库凭据
   • 确保 PostgreSQL 在指定的端口上运行

2. 缺少表:

   • 使用 create_database_schema 工具创建数据库表
   • 检查日志中是否有模式创建期间的任何错误

3. 空结果:

   • 如果查询没有返回任何结果，则可能您的表中没有任何数据
   • 您需要使用您的数据提取过程将数据导入到表中

4. 会话绑定错误:

   • 如果您看到“实例未绑定到会话”错误，请确保模型实例在活动会话中转换为字典
   • 有关示例，请参见 queries.py 文件中如何处理此问题

5. 缺少依赖项:

   • 运行 pip install -r requirements.txt 以确保安装所有依赖项
   • 常见的缺失依赖项包括：mcp、python-dotenv、psycopg2-binary

诊断工具

在进行故障排除时，请使用以下内置诊断工具：

1. diagnose_database: 检查是否：

   • 数据库连接有效
   • 表存在
   • 表包含数据

2. troubleshoot_connection: 提供有关以下方面的详细信息：

   • 数据库连接设置
   • 连接错误
   • 表结构
   • 推荐的修复方法

3. create_database_schema: 创建数据库表并提供：

   • 已创建表的列表
   • 发生的任何错误
   • 测试记录创建结果

许可证

MIT 许可证

贡献者

• Lenin Carrasco - 初始工作