Llm MCP Tools

🚀 LLM MCP Tools - 智能工具調度系統

LLM MCP Tools 是基於 Model Context Protocol (MCP) 和 FastMCP 2.0 構建的智能工具調度系統。藉助大模型的 Function Calling 能力，AI 可自主選擇和調用各類工具，實現從簡單計算到複雜知識圖譜分析的全流程自動化。

🚀 快速開始

環境要求

• Python 3.10+
• MySQL 5.7+（可選，用於數據庫工具）
• 通義千問 API Key

1. 克隆項目

git clone https://github.com/houmingya/LLM_MCP_TOOLS.git
cd LLM_MCP_TOOLS

2. 創建虛擬環境

# 使用 conda
conda create -n mcp-demo python=3.10 -y
conda activate mcp-demo

# 或使用 venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

3. 安裝依賴

pip install -r requirements.txt

4. 配置環境變量

重要：項目使用環境變量管理敏感配置，請勿直接修改代碼中的配置！

複製環境變量模板：

cp .env.example .env

編輯 .env 文件，填入你的配置：

# ========================
# 大模型配置（必填）
# ========================
# 通義千問 API Key（必須配置）
# 獲取地址：https://dashscope.console.aliyun.com/apiKey
LLM_API_KEY=your_qwen_api_key_here

# 模型名稱（可選：qwen-plus, qwen-turbo, qwen-max）
LLM_MODEL_NAME=qwen-plus

# ========================
# MySQL 數據庫配置（可選）
# ========================
# 如果不使用數據庫工具，可以不配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_mysql_password_here
DB_DATABASE=test_db

# ========================
# 服務端口配置
# ========================
WEB_PORT=8000
MCP_PORT=8001

詳細配置說明請查看： 配置指南

5. 驗證配置

運行配置測試：

python test_config.py

如果看到 "✅ 配置驗證通過"，說明配置成功！

6. 啟動服務服務

方式一：一鍵啟動（推薦）

python run.py

這將同時啟動：

• MCP Server: http://localhost:8001/mcp
• Web App: http://localhost:8000

方式二：分別啟動（開發調試）

# 終端1 - 啟動 MCP Server
python run_mcp_server.py

# 終端2 - 啟動 Web App
python run.py --mode webapp

7. 訪問應用

瀏覽器打開：http://localhost:8000

✨ 主要特性

🔧 豐富的工具生態

總計：26+ 個工具函數

🎨 獨特優勢

✅ 解耦架構：MCP Server 和 Web App 完全分離，支持獨立部署和擴展
✅ 自動發現：新增工具自動註冊，無需修改客戶端代碼
✅ 知識圖譜：自動提取實體關係，支持圖譜可視化和路徑查詢
✅ 即時進度：文檔處理過程即時顯示，用戶體驗友好
✅ 向量搜索：基於 ChromaDB 的高效文檔檢索
✅ 多輪對話：支持上下文理解和會話管理
✅ 標準協議：遵循 MCP 標準，易於擴展和集成

🏗️ 系統架構

架構圖

┌─────────────────────────────────────────────────────────────┐
│                     用戶瀏覽器                                 │
│                 (http://localhost:8000)                      │
└────────────────────────┬────────────────────────────────────┘
                         │ WebSocket (即時通信)
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                    Web App (FastAPI)                         │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  WebSocket  │  │  MCP Client  │  │  LLM Client  │       │
│  │   Handler   │→ │  (HTTP調用)  │→ │ (通義千問)   │       │
│  └─────────────┘  └──────────────┘  └──────────────┘       │
│                          ↓                                   │
└──────────────────────────┼───────────────────────────────────┘
                           │ HTTP (MCP Protocol)
                           ↓
┌─────────────────────────────────────────────────────────────┐
│               MCP Server (FastMCP 2.0)                       │
│  ┌───────────────────────────────────────────────────────┐  │
│  │             工具註冊中心 (@mcp.tool())                  │  │
│  └───────────────────────────────────────────────────────┘  │
│         ↓              ↓              ↓              ↓       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ 數據庫工具 │  │ 知識庫工具 │  │ 知識圖譜  │  │ 計算工具  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└──────┬──────────────┬──────────────┬──────────────┬─────────┘
       │              │              │              │
       ↓              ↓              ↓              ↓
   MySQL      ChromaDB(向量)  NetworkX(圖譜)   外部API

技術棧

• 後端框架：FastAPI + FastMCP 2.0
• 大模型：通義千問 Qwen（支持 Function Calling）
• 數據庫：MySQL（結構化數據） + ChromaDB（向量數據庫）
• 知識圖譜：NetworkX（圖存儲） + OpenAI API（實體抽取）
• 通信協議：WebSocket（即時通信） + HTTP（MCP協議）
• 前端：原生 JavaScript + Marked.js（Markdown渲染）

💻 使用示例

基礎用法

👤 你好，你能做什麼？
🤖 我可以幫您：
   • 查詢員工和部門信息
   • 上傳和搜索文檔
   • 構建和查詢知識圖譜
   • 進行數學計算和統計分析
   • 獲取時間信息和進行日期計算
   • 發起HTTP請求和查詢天氣

高級用法

數據庫查詢

👤 查詢銷售部有多少員工，平均薪資是多少？
🤖 [調用 query_employees_by_department(department_id=2)]
   [調用 get_department_statistics()]
   
   銷售部共有 15 名員工，平均薪資為 8,500 元。

文檔上傳與檢索

👤 幫我上傳這份產品說明書
🤖 [調用 upload_document(file)]
   📤 正在上傳文檔...
   📝 已分割為 23 個文本塊
   🧠 正在分析第 1/5 個文本塊...
   🧠 正在分析第 2/5 個文本塊...
   ✅ 知識圖譜構建完成！
   
   文檔上傳成功！已提取 18 個實體和 25 條關係。

👤 這份文檔裡提到的主要功能有哪些？
🤖 [調用 search_documents(query="主要功能")]
   
   根據文檔，主要功能包括：
   1. 數據採集與存儲
   2. 即時監控與告警
   3. 數據分析與可視化
   ...

知識圖譜查詢

👤 浪潮雲洲和哪些項目有關係？
🤖 [調用 query_entity(entity_name="浪潮雲洲")]
   
   浪潮雲洲在知識圖譜中有以下關係：
   • 開發 → 雲洲數據治理系統
   • 提供 → 數據可視化平臺
   • 應用於 → 金川產業情報平臺
   ...

👤 浪潮雲洲和金川集團之間有什麼聯繫？
🤖 [調用 find_entity_path(source="浪潮雲洲", target="金川集團")]
   
   找到關係路徑：
   浪潮雲洲 → 開發 → 決策支持平臺 → 應用於 → 金川集團

計算與分析

👤 計算 (123 + 456) * 2 - 89
🤖 [調用 calculate(expression="(123 + 456) * 2 - 89")]
   
   計算結果：1,069

👤 幫我分析一下這組數據的統計特徵：[23, 45, 67, 89, 12, 34, 56, 78]
🤖 [調用 statistics_analysis(data=[23,45,67,89,12,34,56,78])]
   
   統計分析結果：
   • 平均值：50.5
   • 中位數：50.5
   • 標準差：26.4
   • 最小值：12，最大值：89

📚 詳細文檔

• 知識圖譜技術深度解析
• 知識圖譜應用說明
• 文本塊處理進度功能說明
• MCP API完整對照表

外部資源

• FastMCP 官方文檔
• MCP 協議規範
• FastAPI 文檔
• ChromaDB 文檔
• NetworkX 文檔

🔧 技術細節

添加新工具

只需在 mcp_server/server.py 中添加：

@mcp.tool()
def my_new_tool(param1: str, param2: int = 10) -> Dict[str, Any]:
    """
    工具描述（會自動作為工具的說明）
    
    Args:
        param1: 參數1的說明
        param2: 參數2的說明，默認值10
        
    Returns:
        返回值說明
    """
    # 實現你的邏輯
    result = do_something(param1, param2)
    
    return {
        "success": True,
        "data": result,
        "message": "執行成功"
    }

重啟 MCP Server，Web App 會自動識別新工具！✨
無需修改 main.py、工具列表或前端代碼。

工具開發最佳實踐

1. 清晰的文檔字符串：會作為工具描述傳遞給大模型
2. 類型註解：幫助自動生成工具參數schema
3. 統一的返回格式：建議包含 success、data、message 字段
4. 錯誤處理：捕獲異常並返回友好的錯誤信息

本地開發

# 安裝開發依賴
pip install -r requirements-dev.txt

# 運行測試
pytest tests/

# 代碼格式化
black .
isort .

# 類型檢查
mypy .

❓ 常見問題

Q: ChromaDB 報錯 "Insert of existing embedding ID"？

A: 這是重複上傳文檔導致的。已在新版本中修復，使用 upsert 替代 add。

Q: 端口被佔用怎麼辦？

A: 修改 config/settings.py 中的端口配置：

class WebConfig:
    PORT = 8000  # 改成其他端口如 8080

class MCPServerConfig:
    PORT = 8001  # 改成其他端口如 8081

Q: 知識圖譜構建很慢？

A: 這是正常的，因為需要調用大模型API進行實體抽取。文檔越長，需要的時間越長。新版本已支持即時進度顯示。

Q: 如何不使用數據庫工具？

A: 數據庫工具是可選的。如果不需要，可以在 mcp_server/server.py 中註釋掉相關工具的註冊即可。

Q: 支持哪些大模型？

A: 理論上支持所有兼容 OpenAI API 格式的大模型。只需修改 config/settings.py 中的 LLMConfig：

class LLMConfig:
    API_KEY = "your_api_key"
    API_BASE = "https://api.openai.com/v1"  # 或其他端點
    MODEL_NAME = "gpt-4"  # 或其他模型

🤝 參與貢獻

我們歡迎所有形式的貢獻！無論是新功能、Bug修復、文檔改進還是問題反饋。

貢獻方式

1. Fork 本倉庫
2. 創建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 開啟 Pull Request

開發規範

• 遵循 PEP 8 代碼規範
• 添加必要的註釋和文檔
• 編寫單元測試
• 確保所有測試通過

📄 許可證

本項目採用 MIT License 開源協議。

🙏 致謝

• FastMCP - 優秀的 MCP 實現框架
• FastAPI - 現代化的 Python Web 框架
• ChromaDB - 簡單易用的向量數據庫
• NetworkX - 強大的圖分析庫
• 通義千問 - 阿里雲大模型服務

📧 聯繫方式

• GitHub: @houmingya
• Issues: 項目問題反饋

支持鼓勵

如果這個項目對你有幫助，請給個 ⭐️ Star 支持一下！

Made with ❤️ by houmingya