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 的查找。