JinDaGe - medical-sql-mcp MCP Details

article

README

🚀 医疗 SQL MCP 服务器

这是一个基于模型上下文协议（MCP）的服务器，其主要作用是连接大语言模型（LLM）与医疗/医院管理数据库。借助该服务器，AI 助手能够通过结构化工具探索数据库架构、执行 SQL 查询，并获取实时数据。

🚀 快速开始

前置要求

Node.js（v16 或更高版本）
MySQL 数据库实例
OpenAI API 密钥（用于首次启动时生成语义化的目录结构）

安装

克隆项目并安装依赖：

npm install

配置

在项目根目录创建 .env 文件，配置以下环境变量：

# 数据库连接信息
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_password
DB_DATABASE=hospital_management

# MCP 服务器端口
PORT=3000

# OpenAI 配置 (用于构建虚拟目录树)
OPENAI_API_KEY=sk-your_key_here
OPENAI_BASE_URL=https://api.openai.com/v1

# 安全配置
# false: 仅允许 SELECT 查询 (推荐)
# true: 允许所有 SQL 操作
ALLOW_NON_SELECT_QUERIES=false

运行

开发模式：

npm run dev

构建并运行：

npm run build
npm start

✨ 主要特性

虚拟文件系统导航 (schema_ls)：将扁平的数据库表结构转化为语义化的虚拟目录树（例如：/患者服务/挂号表），帮助 LLM 更直观地理解业务领域。
智能 Schema 检索 (get_table_schema)：允许按需获取特定表的详细字段定义，减少上下文占用。
安全可控的 SQL 执行 (query_database)：
- 支持执行 SQL 查询以获取数据。
- 安全模式：通过环境变量 ALLOW_NON_SELECT_QUERIES 控制是否允许非 SELECT 操作（如 INSERT, UPDATE, DELETE），默认开启只读保护。
时间感知 (get_current_time)：提供精确的服务器当前时间，确保处理“今天”、“近三天”等相对时间查询时的准确性。

💻 使用示例

基础用法

以下是使用 schema_ls 工具浏览数据库虚拟文件系统的示例：

# 假设已经有相应的调用方式，这里只是示意
call schema_ls('/')

高级用法

以下是使用 query_database 工具执行复杂 SQL 查询的示例：

# 假设已经有相应的调用方式，这里只是示意
call query_database('SELECT * FROM patients WHERE age > 60')

📚 详细文档

工具列表 (MCP Tools)

| 工具名称 | 描述 | 参数 | | ---- | ---- | ---- | | schema_ls | 浏览数据库的虚拟文件系统。这是探索数据库结构的第一步。 | path：路径 (默认为 /) | | get_table_schema | 获取指定表的详细列信息（字段名、类型等）。 | tableName：表名 | | query_database | 执行 SQL 查询。请先使用 schema_ls 确认表结构。 | sql：SQL 语句 | | get_current_time | 获取当前系统时间。处理时间相关查询前必须调用。 | 无 |

项目结构

src/mcp-server.ts：MCP 服务器入口，定义了工具 (Tools) 和资源 (Resources) 的处理逻辑。
src/mapping.ts：负责将数据库元数据转换为虚拟文件系统树结构。
src/db.ts：MySQL 数据库连接池封装。
src/llm-logger.ts：LLM 调用日志记录。
schema-cache.json：缓存生成的虚拟目录结构，避免重复调用 LLM 生成。

🔧 技术细节

该项目基于 Model Context Protocol (MCP) 构建，通过一系列工具实现了大语言模型与医疗/医院管理数据库的交互。服务器使用 Node.js 开发，利用 MySQL 数据库存储数据，借助 OpenAI API 生成语义化的目录结构。在安全方面，通过环境变量 ALLOW_NON_SELECT_QUERIES 对 SQL 操作进行了严格的控制，确保数据的安全性。同时，使用 schema-cache.json 缓存虚拟目录结构，避免了重复调用 LLM 带来的性能开销。

📄 注意事项

首次运行时，系统会读取数据库表结构并调用 LLM 生成语义化路径，这可能需要几秒钟，结果会被缓存到 schema-cache.json。
建议始终保持 ALLOW_NON_SELECT_QUERIES=false 以确保数据安全，除非你明确需要 AI 修改数据。

⚠️ 重要提示

首次运行时系统会读取数据库表结构并调用 LLM 生成语义化路径，此过程可能需几秒，结果会缓存到 schema-cache.json。同时，建议始终将 ALLOW_NON_SELECT_QUERIES 设置为 false 以保障数据安全，除非你明确需要 AI 修改数据。

💡 使用建议

为确保数据安全，尽量保持 ALLOW_NON_SELECT_QUERIES=false，仅在必要时允许 AI 修改数据。在执行 SQL 查询前，先使用 schema_ls 工具确认表结构。

medical-sql-mcp