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