Knowledge Graph Toolkit

---

📖 简介

LLM MCP Tools 是一个基于 Model Context Protocol (MCP) 和 FastMCP 2.0 构建的智能工具调度系统。它通过大模型的 Function Calling 能力，让 AI 能够自主选择和调用各种工具，实现从简单计算到复杂知识图谱分析的全流程自动化。

🎯 适用场景

• 🏢 企业知识管理：文档上传、向量检索、知识图谱构建
• 💼 业务数据分析：员工信息查询、部门统计、数据可视化
• 🤖 智能助手开发：多轮对话、工具调度、实时反馈
• 📚 MCP 协议学习：解耦架构、标准化接口、工具注册

---

✨ 核心特性

🔧 丰富的工具生态

类别	工具数量	主要功能
📊 数据库工具	6个	员工查询、部门统计、薪资分析
📚 知识库工具	3个	文档上传、向量搜索、文档管理
🧠 知识图谱工具	7个	实体抽取、关系构建、图谱查询、路径分析
🧮 计算工具	3个	数学运算、统计分析、单位转换
⏰ 时间工具	4个	当前时间、日期计算、时区转换
🌐 API工具	3个	HTTP请求、天气查询、外部接口

总计：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渲染）

---

🚀 快速开始

环境要求

• 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

---

💡 使用示例

基础对话

👤 你好，你能做什么？
🤖 我可以帮您：
   • 查询员工和部门信息
   • 上传和搜索文档
   • 构建和查询知识图谱
   • 进行数学计算和统计分析
   • 获取时间信息和进行日期计算
   • 发起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

---

📁 项目结构

LLM_MCP_TOOLS/
├── 📄 README.md                     # 项目说明文档
├── 📄 requirements.txt              # Python依赖列表
├── 📄 .env.example                  # 环境变量示例
├── 📄 .gitignore                    # Git忽略文件
│
├── 🚀 run.py                        # 统一启动入口
├── 🚀 run_decoupled.py             # 解耦模式启动（同时启动两服务）
├── 🚀 run_mcp_server.py            # 单独启动 MCP Server
│
├── ⚙️ config/                       # 配置模块
│   ├── __init__.py
│   └── settings.py                 # 配置中心（数据库、LLM、端口等）
│
├── 🔧 mcp_server/                   # MCP Server (port 8001)
│   ├── __init__.py
│   ├── server.py                   # 🎯 工具注册中心 (@mcp.tool())
│   ├── prompts.py                  # 提示词模板
│   └── tools/                      # 工具实现
│       ├── __init__.py
│       ├── database_tools.py       # 数据库工具（6个函数）
│       ├── knowledge_tools.py      # 知识库工具（3个函数）
│       ├── knowledge_graph_tools.py # 知识图谱工具（7个函数）
│       ├── calculation_tools.py    # 计算工具（3个函数）
│       ├── time_tools.py          # 时间工具（4个函数）
│       └── api_tools.py           # API工具（3个函数）
│
├── 🌐 web_app/                      # Web App (port 8000)
│   ├── __init__.py
│   ├── main.py                     # 🎯 FastAPI应用 + WebSocket + LLM
│   ├── mcp_client.py              # 🎯 MCP Client（HTTP通信）
│   └── static/                    # 前端静态文件
│       ├── index.html             # 主页面
│       ├── knowledge-graph.html   # 知识图谱可视化
│       ├── css/
│       │   └── style.css         # 样式文件
│       └── js/
│           ├── app.js            # 应用初始化
│           ├── websocket.js      # WebSocket连接管理
│           ├── chat.js           # 聊天功能
│           ├── message-handler.js # 消息处理（含进度显示）
│           ├── file-upload.js    # 文件上传
│           ├── knowledge-graph.js # 知识图谱可视化
│           └── utils.js          # 工具函数
│
├── 📚 docs/                         # 文档目录
│   ├── 知识图谱技术深度解析.md
│   ├── 知识图谱应用说明.md
│   ├── 文本块处理进度功能说明.md
│   └── MCP_API_完整对照表.md
│
├── 📤 uploads/                      # 文档上传目录（.gitignore）
├── 💾 chroma_db/                    # ChromaDB数据目录（.gitignore）
└── 🧠 knowledge_graph_data/         # 知识图谱数据（.gitignore）

---

🔧 开发指南

添加新工具

只需在 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 .

---

📚 文档

• 知识图谱技术深度解析
• 知识图谱应用说明
• 文本块处理进度功能说明
• MCP API完整对照表

外部资源

• FastMCP 官方文档
• MCP 协议规范
• FastAPI 文档
• ChromaDB 文档
• NetworkX 文档

---

❓ 常见问题

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: 项目问题反馈

---