MCP LlamaIndex SQLite Bridge

MCP LlamaIdex SQLite桥

模型上下文协议（MCP）与SQLite集成和LlamaIdex客户端的全面演示，包括简单演示和功能齐全的人力资源管理系统。

概述

本项目展示了如何构建和使用MCP服务器，这些服务器将数据库操作作为工具公开，通过基于LlamaIdex的客户端与Ollama LLM支持连接。它包括：

1. 简单演示 -带简单人员表的基本SQLite服务器
2. 工资计算系统 -先进的自然语言人力资源系统，具有员工管理、休假跟踪、薪酬和分析功能

组件

简单演示：

• 服务器.py：用于简单人员数据库的带SQL工具的基本MCP服务器
• 客户端.py：用于自然语言数据库交互的LlamaIndex客户端

人力资源管理系统：

• hr_server.py：配备全面人力资源工具的高级MCP服务器
• hr_client.py：具有上下文感知自然语言处理功能的复杂客户端
• HR_USAGE_GUIDE.md：附有示例的详细文档

特性

核心功能

• 集成SQLite的MCP服务器架构
• 使用LlamaIndex和Ollama的自然语言界面
• 异步支持服务器和客户端
• 基于工具的数据库操作方法

人力资源管理系统功能

• 员工管理：添加、更新、搜索和管理员工记录
• 休假管理：请求、批准和跟踪员工假期余额
• 补偿：工资更新、薪酬报告和工资分析
• 组织结构：组织结构图、部门管理和调动
• 分析：人力资源仪表板、人员流动分析和多样性指标
• 绩效考核：创建和跟踪绩效评估
• 审计跟踪：完成所有人力资源行动的合规记录

先决条件

• Python 3.8+
• 没有 已安装并正在运行
• llama3.2模型（或支持工具调用的其他模型）

⚠️ 关键要求

添加员工时需要电子邮件

人力资源系统 需要电子邮件地址 在增加新员工时。没有电子邮件的命令将失败。

❌ 错误: Add John Doe to Engineering as Developer\ ✅ 正确: Add John Doe (john.doe@company.com) to Engineering as Developer

如果没有电子邮件，您将看到： ❌ Tool failed: Missing required field: email

安装

1. 克隆此存储库：

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

1. 创建虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

1. 安装依赖项：

pip install -r requirements.txt

1. 拉取所需的Olama模型：

ollama pull llama3.2

用法

选项1：简单演示

启动简单服务器

python server.py --server_type=sse

运行简单客户端

python client.py

选项2：人力资源管理系统

启动人力资源服务器

python hr_server.py --server_type=sse

运行HR客户端

python hr_client.py

客户将：

1. 连接到MCP服务器
2. 显示可用工具
3. 启动一个交互式会话，您可以在其中使用自然语言与数据库进行交互

交互示例

简单演示：

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

人力资源管理系统：

⚠️ 重要提示：添加员工时需要电子邮件！

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

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)...

自然语言示例

员工管理

添加员工（需要电子邮件！）：

"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"  ← Uses name directly!

休假管理

"Check Sarah Johnson's leave balance"  ← Uses employee name directly!
"Submit leave request for John Doe from Dec 20 to Dec 27"  ← Uses name!
"Approve leave request #45"
"Show all pending leave requests"
"How many vacation days does Michael Brown have left?"  ← Uses name!

薪酬与福利

"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”尝试交互式帮助。

数据库模式

简单演示模式

这 demo.db 包含a people 表：

• id：整数主键自动递增
• name：文本不能为空
• age：整数不能为空
• profession：文本不能为空

人力资源管理系统架构

这 hr_management.db 包含多个相互连接的表：

• 员工：全面的员工记录
• 部门：组织单位和等级
• 位置：职位名称和薪资范围
• 薪水：薪酬历史
• 休假类型：各种休假类别
• 休假平衡：员工休假权利
• 离开请求：休假申请跟踪
• 性能审查：绩效评估
• 培训计划：培训目录
• 员工培训：培训完成记录
• audit_log：合规和审计跟踪

可用工具

简单演示工具

• add_data：使用SQL INSERT添加记录
• read_data：使用SQL SELECT查询记录

人力资源管理工具

简化工具（使用这些工具-它们接受员工姓名！）

• add_员工：添加新员工（需要电子邮件！）
• 检查_员工_休假：按员工姓名检查假期余额
• 更新_员工_薪资：按员工姓名更新薪资
• 提交离开请求：按员工姓名提交休假申请
• 列表_所有_员工：让所有在职员工
• 查找_员工_部门：按部门搜索

高级工具（需要员工ID）

• 经理_员工：添加、更新、终止员工（需要employee_id）
• 搜索_员工：使用过滤器进行高级员工搜索
• get_org_chart：生成组织层次结构
• 请求离开：提交休假申请（需要employee_id）
• 批准_离开：处理休假审批
• get_leave_balance：检查假期余额（需要employee_id）
• update_salary：管理薪酬（需要employee_id）
• generate_hr_dashboard：全面的人力资源指标
• 分析翻转：营业额分析
• 计算补偿信息：工资统计
• record_performance_review：绩效评估
• 还有更多。..

故障排除

模块声音错误

如果遇到模块导入错误，请确保安装了所有依赖项：

pip install -r requirements.txt

Ollama模型误差

如果你得到一个关于模型不支持工具的错误，请确保你使用的模型支持函数调用（如llama3.2、mistral或qwen2.5编码器）。

连接问题

启动客户端之前，请确保MCP服务器正在运行。

员工未添加问题

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

• 检查电子邮件：需要电子邮件。没有它，员工就不会得救。
• 查找错误消息: "❌ 工具失败：缺少必填字段：电子邮件“
• 格式正确: Add Name (email@company.com) to Department as Position
• 始终包含电子邮件：firstname.lastname@company.com

工具预期员工ID错误

如果使用员工姓名时出错：

• 使用简化的工具：check_employee_leave_balance，update_employee_salary，submit_leave_request
• 这些直接接受名称：“查看John Doe的假期余额”
• 不使用：get_leave_balance、update_salary、request_leave及其名称
• 简化的工具自动处理名称到ID的查找

许可证

MIT许可证