Medical Sql MCP

🚀 醫療 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)

項目結構

• 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 工具確認表結構。