MCP Llama Sqlite Bridge

🚀 MCP LlamaIndex SQLite Bridge

このプロジェクトは、SQLiteと統合したModel Context Protocol (MCP) とLlamaIndexクライアントを用いた包括的なデモンストレーションです。シンプルなデモと、本格的な人事管理システムの両方を提供しています。

🚀 クイックスタート

このプロジェクトは、データベース操作をツールとして公開するMCPサーバーを構築し、LlamaIndexベースのクライアントを介してOllama LLMをサポートする方法を紹介しています。

✨ 主な機能

コア機能

• SQLiteと統合したMCPサーバーアーキテクチャ
• LlamaIndexとOllamaを使用した自然言語インターフェース
• サーバーとクライアントの両方で非同期サポート
• データベース操作のためのツールベースのアプローチ

人事管理システムの機能

• 社員管理：社員レコードの追加、更新、検索、管理
• 休暇管理：社員の休暇残高の申請、承認、追跡
• 報酬管理：給与の更新、報酬レポート、給与分析
• 組織構造管理：組織図、部署管理、異動
• 分析：人事ダッシュボード、離職率分析、多様性指標
• 業績評価：業績評価の作成と追跡
• 監査トレイル：すべての人事アクションの完全なログ記録

📦 インストール

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: 人事管理システム

人事管理サーバーの起動

python hr_server.py --server_type=sse

人事管理クライアントの実行

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 には people テーブルが含まれています：

• id: INTEGER PRIMARY KEY AUTOINCREMENT
• name: TEXT NOT NULL
• age: INTEGER NOT NULL
• profession: TEXT NOT NULL

人事管理システムのスキーマ

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: 社員の追加、更新、解雇 (employee_idが必要です)
• search_employees: フィルターを使用した高度な社員検索
• get_org_chart: 組織階層を生成
• request_leave: 休暇申請を提出 (employee_idが必要です)
• approve_leave: 休暇承認を処理
• get_leave_balance: 休暇残高を確認 (employee_idが必要です)
• update_salary: 報酬を管理 (employee_idが必要です)
• generate_hr_dashboard: 包括的な人事指標
• analyze_turnover: 離職率分析
• calculate_compensation_metrics: 給与統計
• record_performance_review: 業績評価
• その他多数...

🔧 技術詳細

トラブルシューティング

ModuleNotFoundError

モジュールのインポートエラーが発生した場合は、すべての依存関係がインストールされていることを確認してください：

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を検索します。

📄 ライセンス

MIT License