MCP LlamaIndex SQLite Bridge

A comprehensive demonstration of Model Context Protocol (MCP) with SQLite integration and LlamaIndex client, featuring both a simple demo and a full-featured HR Management System.

Overview

This project showcases how to build and use MCP servers that expose database operations as tools, connected via LlamaIndex-based clients with Ollama LLM support. It includes:

1. Simple Demo - Basic SQLite server with simple people table

2. HR Management System - Advanced natural language HR system with employee management, leave tracking, compensation, and analytics

Components

Simple Demo:

• server.py: Basic MCP server with SQL tools for a simple people database

• client.py: LlamaIndex client for natural language database interactions

HR Management System:

• hr_server.py: Advanced MCP server with comprehensive HR tools

• hr_client.py: Sophisticated client with context-aware natural language processing

• HR_USAGE_GUIDE.md: Detailed documentation with examples

Features

Core Features

• MCP server architecture with SQLite integration

• Natural language interface using LlamaIndex and Ollama

• Async support for both server and client

• Tool-based approach for database operations

HR Management System Features

• Employee Management: Add, update, search, and manage employee records

• Leave Management: Request, approve, and track employee leave balances

• Compensation: Salary updates, compensation reports, and payroll analytics

• Organization Structure: Org charts, department management, and transfers

• Analytics: HR dashboards, turnover analysis, and diversity metrics

• Performance Reviews: Create and track performance evaluations

• Audit Trail: Complete logging of all HR actions for compliance

Prerequisites

• Python 3.8+

• Ollama installed and running

• llama3.2 model (or another model that supports tool calling)

⚠️ Critical Requirements

Email is REQUIRED When Adding Employees

The HR system requires an email address when adding new employees. Commands without email will fail.

❌ WRONG: Add John Doe to Engineering as Developer
✅ CORRECT: Add John Doe (john.doe@company.com) to Engineering as Developer

Without email, you'll see: ❌ Tool failed: Missing required field: email

Installation

1. Clone this repository:

2. Create a virtual environment:

3. Install dependencies:

4. Pull the required Ollama model:

Usage

Option 1: Simple Demo

Starting the Simple Server

Running the Simple Client

Option 2: HR Management System

Starting the HR Server

Running the HR Client

The client will:

1. Connect to the MCP server

2. Display available tools

3. Start an interactive session where you can use natural language to interact with the database

Example Interactions

Simple Demo:

HR Management System:

⚠️ IMPORTANT: Email is REQUIRED when adding employees!

Natural Language Examples

Employee Management

Adding Employees (Email Required!):

Searching & Listing:

Updates & Changes:

Leave Management

Compensation & Benefits

Organization & Analytics

Performance Management

For more examples, try the interactive help in the HR client by typing 'help'.

Database Schema

Simple Demo Schema

The demo.db contains a people table:

• id: INTEGER PRIMARY KEY AUTOINCREMENT

• name: TEXT NOT NULL

• age: INTEGER NOT NULL

• profession: TEXT NOT NULL

HR Management System Schema

The hr_management.db contains multiple interconnected tables:

• employees: Comprehensive employee records

• departments: Organizational units and hierarchy

• positions: Job titles and salary ranges

• salaries: Compensation history

• leave_types: Various leave categories

• leave_balances: Employee leave entitlements

• leave_requests: Leave request tracking

• performance_reviews: Performance evaluations

• training_programs: Training catalog

• employee_training: Training completion records

• audit_log: Compliance and audit trail

Available Tools

Simple Demo Tools

• add_data: Add records using SQL INSERT

• read_data: Query records using SQL SELECT

HR Management Tools

Simplified Tools (Use These - They Accept Employee Names!)

• add_employee: Add new employees (EMAIL REQUIRED!)

• check_employee_leave_balance: Check leave balance by employee NAME

• update_employee_salary: Update salary by employee NAME

• submit_leave_request: Submit leave request by employee NAME

• list_all_employees: Get all active employees

• find_employees_by_department: Search by department

Advanced Tools (Require Employee IDs)

• manage_employee: Add, update, terminate employees (requires employee_id)

• search_employees: Advanced employee search with filters

• get_org_chart: Generate organizational hierarchy

• request_leave: Submit leave requests (requires employee_id)

• approve_leave: Process leave approvals

• get_leave_balance: Check leave balances (requires employee_id)

• update_salary: Manage compensation (requires employee_id)

• generate_hr_dashboard: Comprehensive HR metrics

• analyze_turnover: Turnover analytics

• calculate_compensation_metrics: Salary statistics

• record_performance_review: Performance evaluations

• And many more...

Troubleshooting

ModuleNotFoundError

If you encounter module import errors, ensure all dependencies are installed:

Ollama Model Error

If you get an error about the model not supporting tools, ensure you're using a model that supports function calling (like llama3.2, mistral, or qwen2.5-coder).

Connection Issues

Ensure the MCP server is running before starting the client.

Employee Not Added Issue

If your command to add an employee doesn't work:

• Check for email: Email is REQUIRED. Without it, the employee won't be saved.

• Look for error messages: "❌ Tool failed: Missing required field: email"

• Correct format: Add Name (email@company.com) to Department as Position

• Always include email: firstname.lastname@company.com

Tool Expects Employee ID Error

If you get errors when using employee names:

• Use the simplified tools: check_employee_leave_balance, update_employee_salary, submit_leave_request

• These accept names directly: "Check John Doe's leave balance"

• Don't use: get_leave_balance, update_salary, request_leave with names

• The simplified tools handle name-to-ID lookup automatically

License

MIT License