MCP Llama Sqlite Bridge

🚀 MCP LlamaIndex SQLite 橋接項目

本項目全面展示瞭如何將模型上下文協議（MCP）與 SQLite 數據庫集成，並搭配 LlamaIndex 客戶端使用。項目包含一個簡單演示和一個功能完備的人力資源管理系統，為你呈現瞭如何通過 MCP 服務器將數據庫操作作為工具暴露出來，並通過基於 LlamaIndex 的客戶端與支持 Ollama 的大語言模型進行連接。

🚀 快速開始

前提條件

• Python 3.8 及以上版本
• 已安裝並運行 Ollama
• llama3.2 模型（或其他支持工具調用的模型）

安裝步驟

1. 克隆本倉庫：

git clone https://github.com/ELISHA1994/mcp-llama-sqlite-bridge.git
cd mcp-llama-sqlite-bridge

2. 創建虛擬環境：

python -m venv .venv
source .venv/bin/activate  # 在 Windows 系統上使用：.venv\Scripts\activate

3. 安裝依賴：

pip install -r requirements.txt

4. 拉取所需的 Ollama 模型：

ollama pull llama3.2

使用方法

選項 1：簡單演示

• 啟動簡單服務器：

python server.py --server_type=sse

• 運行簡單客戶端：

python client.py

選項 2：人力資源管理系統

• 啟動 HR 服務器：

python hr_server.py --server_type=sse

• 運行 HR 客戶端：

python hr_client.py

客戶端將執行以下操作：

1. 連接到 MCP 服務器。
2. 顯示可用工具。
3. 啟動交互式會話，你可以使用自然語言與數據庫進行交互。

使用示例

基礎用法

# 簡單演示示例
# 輸入：添加一個名為 John Doe 的人，他 30 歲，職業是工程師
Enter your message: Add a person named John Doe who is 30 years old and works as an Engineer
# 輸出：數據已成功添加到數據庫
Agent: Data has been successfully added to the database.

# 輸入：顯示數據庫中的所有人
Enter your message: Show me all people in the database
# 輸出：以下是數據庫中的所有人
Agent: Here are all the people in the database:
1. John Doe, 30 years old, Engineer

高級用法

# 人力資源管理系統示例
# 輸入：將 Sarah Johnson（sarah.johnson@company.com）添加到工程部門，職位為高級開發人員，薪水為 105,000 美元
HR Assistant> Add Sarah Johnson (sarah.johnson@company.com) to Engineering as Senior Developer with $105,000 salary
# 調用工具：添加員工
🔧 Calling tool: add_employee
# 輸出：員工添加成功
✅ Employee added successfully!
- Employee ID: EMP00001
- Name: Sarah Johnson

# 輸入：查詢 Sarah Johnson 的休假餘額
HR Assistant> 
# 調用工具：檢查員工休假餘額
🔧 Calling tool: check_employee_leave_balance
   Parameters: {
     "employee_name": "Sarah Johnson"
   }
# 輸出：工具調用成功，顯示休假餘額
✅ Tool result received
**Leave Balance for Sarah Johnson (2024)**
- Annual Leave: 21 days remaining
- Sick Leave: 10 days remaining

# 輸入：生成人力資源儀表盤
HR Assistant> Generate HR dashboard
# 調用工具：生成人力資源儀表盤
🔧 Calling tool: generate_hr_dashboard
# 輸出：人力資源儀表盤摘要
**HR Dashboard Summary**
- Total Employees: 45
- Active: 42
- Departments: Engineering (15), Sales (10), Marketing (8)...

✨ 主要特性

核心特性

• 集成 SQLite 的 MCP 服務器架構。
• 使用 LlamaIndex 和 Ollama 實現自然語言接口。
• 服務器和客戶端均支持異步操作。
• 基於工具的數據庫操作方法。

人力資源管理系統特性

• 員工管理：添加、更新、搜索和管理員工記錄。
• 休假管理：申請、批准和跟蹤員工的休假餘額。
• 薪酬管理：更新薪水、生成薪酬報告和進行薪資分析。
• 組織結構管理：創建組織結構圖、管理部門和員工調動。
• 數據分析：提供人力資源儀表盤、人員流動分析和多樣性指標。
• 績效評估：創建和跟蹤績效評估。
• 審計跟蹤：記錄所有人力資源操作，確保合規性。

📚 詳細文檔

組件說明

簡單演示

• server.py：一個基本的 MCP 服務器，為簡單的人員數據庫提供 SQL 工具。
• client.py：一個 LlamaIndex 客戶端，用於通過自然語言與數據庫進行交互。

人力資源管理系統

• hr_server.py：一個高級的 MCP 服務器，提供全面的人力資源工具。
• hr_client.py：一個複雜的客戶端，支持上下文感知的自然語言處理。
• HR_USAGE_GUIDE.md：包含詳細示例的文檔。

數據庫架構

簡單演示架構

demo.db 包含一個 people 表：

人力資源管理系統架構

hr_management.db 包含多個相互關聯的表：

• employees：全面的員工記錄。
• departments：組織結構單元和層級。
• positions：職位名稱和薪資範圍。
• salaries：薪酬歷史記錄。
• leave_types：各種休假類別。
• leave_balances：員工的休假權限。
• leave_requests：休假申請跟蹤。
• performance_reviews：績效評估。
• training_programs：培訓目錄。
• employee_training：培訓完成記錄。
• audit_log：合規性和審計跟蹤。

可用工具

簡單演示工具

• add_data：使用 SQL INSERT 語句添加記錄。
• read_data：使用 SQL SELECT 語句查詢記錄。

人力資源管理工具

簡化工具（可直接使用員工姓名）

• add_employee：添加新員工（必須提供電子郵件地址！）
• check_employee_leave_balance：通過員工姓名檢查休假餘額。
• update_employee_salary：通過員工姓名更新薪水。
• submit_leave_request：通過員工姓名提交休假申請。
• list_all_employees：獲取所有在職員工。
• find_employees_by_department：按部門搜索員工。

高級工具（需要員工 ID）

• manage_employee：添加、更新、終止員工（需要員工 ID）。
• search_employees：使用過濾器進行高級員工搜索。
• get_org_chart：生成組織結構層次結構。
• request_leave：提交休假申請（需要員工 ID）。
• approve_leave：處理休假批准。
• get_leave_balance：檢查休假餘額（需要員工 ID）。
• update_salary：管理薪酬（需要員工 ID）。
• generate_hr_dashboard：生成全面的人力資源指標。
• analyze_turnover：進行人員流動分析。
• calculate_compensation_metrics：計算薪資統計數據。
• record_performance_review：記錄績效評估。

自然語言示例

員工管理

• 添加員工（必須提供電子郵件地址！）

"Add Elisha Bello (elisha.bello@company.com) to Engineering as Senior Software Engineer with salary $420,000"
"Hire John Doe (john.doe@company.com) as Marketing Manager starting January 15, 2024"
"Onboard Alice Chen (alice.chen@company.com) to Sales as Account Executive, phone: 555-0123"

• 搜索和列出員工

"List all employees"
"Find all employees in Engineering department"
"Show me employees hired in the last 6 months"
"Who reports to John Smith?"
"Search for Senior Engineers"

• 更新和更改員工信息

"Update John Doe's phone number to 555-9876"
"Transfer Sarah Johnson from Engineering to Product Management"
"Change Michael Brown's manager to Jennifer Wilson"
"Update Emily Davis's salary to $95,000 effective next month"  ← 直接使用姓名！

休假管理

"Check Sarah Johnson's leave balance"  ← 直接使用員工姓名！
"Submit leave request for John Doe from Dec 20 to Dec 27"  ← 使用姓名！
"Approve leave request #45"
"Show all pending leave requests"
"How many vacation days does Michael Brown have left?"  ← 使用姓名！

薪酬和福利管理

"Generate compensation report for Engineering department"
"Show average salaries by position"
"Calculate total payroll for Q4 2024"
"List employees eligible for salary review"
"Compare department salary ranges"

組織和分析

"Show org chart for Engineering department"
"Generate HR dashboard"
"Analyze turnover for last quarter"
"Show diversity metrics"
"List employees with upcoming work anniversaries"
"Who are the top performers this quarter?"

績效管理

"Create performance review for Sarah Johnson"
"Show pending performance reviews"
"Update performance rating for John Doe to 'Exceeds Expectations'"
"List employees due for annual review"

如需更多示例，請在 HR 客戶端中輸入 'help' 查看交互式幫助。

🔧 技術細節

項目架構

本項目展示瞭如何構建和使用 MCP 服務器，將數據庫操作作為工具暴露出來，並通過基於 LlamaIndex 的客戶端與支持 Ollama 的大語言模型進行連接。項目包含兩個主要部分：簡單演示和人力資源管理系統。

異步支持

服務器和客戶端均支持異步操作，提高了系統的性能和響應速度。

工具化設計

採用基於工具的方法進行數據庫操作，使得系統更加靈活和可擴展。

📄 許可證

本項目採用 MIT 許可證。

⚠️ 重要提示

添加員工時必須提供電子郵件地址

人力資源系統在添加新員工時必須提供電子郵件地址。不包含電子郵件的命令將失敗。

❌ 錯誤示例：Add John Doe to Engineering as Developer
✅ 正確示例：Add John Doe (john.doe@company.com) to Engineering as Developer

如果不提供電子郵件地址，你將看到錯誤信息：❌ Tool failed: Missing required field: email

故障排除

模塊導入錯誤

如果你遇到模塊導入錯誤，請確保所有依賴項都已安裝：

pip install -r requirements.txt

Ollama 模型錯誤

如果你收到關於模型不支持工具的錯誤，請確保你使用的是支持函數調用的模型（如 llama3.2、mistral 或 qwen2.5-coder）。

連接問題

在啟動客戶端之前，請確保 MCP 服務器正在運行。

員工添加失敗問題

如果添加員工的命令不起作用：

• 檢查電子郵件地址：必須提供電子郵件地址，否則員工信息將無法保存。
• 查看錯誤信息：如 ❌ Tool failed: Missing required field: email
• 使用正確的格式：Add Name (email@company.com) to Department as Position
• 始終包含電子郵件地址：firstname.lastname@company.com

工具需要員工 ID 錯誤

如果你在使用員工姓名時遇到錯誤：

• 使用簡化工具：check_employee_leave_balance、update_employee_salary、submit_leave_request
• 這些工具可以直接使用姓名："Check John Doe's leave balance"
• 不要使用：get_leave_balance、update_salary、request_leave 並直接使用姓名
• 簡化工具會自動處理姓名到 ID 的查找。