MCP Server

MCP 服务

一个根据主题生成 Master Content Plans（MCP）的服务。该服务会从网络汇总资源，并将其整理为结构化学习路径。

功能

• 为任何主题（不仅限于技术主题）生成学习路径
• 使用网络搜索和抓取功能查找相关资源
• 将资源整理为合理的顺序，并支持自定义节点数量
• 支持多种语言，重点支持葡萄牙语
• 针对 Render 免费套餐进行性能优化
• 缓存系统可加快响应速度
• 返回标准化的 JSON 结构，供客户端应用使用
• 新增：基于 TF-IDF 的资源相关性筛选，确保资源与请求的主题相符
• 新增：在学习树中策略性地分布测验，提供均衡的学习体验
• 新增：集成 YouTube，在学习路径中加入相关视频
• 新增：类别系统，可针对不同类型的主题生成更具体的内容
• 新增：异步任务系统，提供实时进度反馈，改善用户体验并避免超时
• 新增：增强缓存系统，提升性能并缩短响应时间
• 新增：优化网络抓取技术，更有效地利用资源
• 新增：自适应抓取系统，可自动为每个网站选择最高效的方法
• 新增：Puppeteer 实例池，可高效复用浏览器并减少内存用量

技术栈

• Python 3.9+
• FastAPI
• Pyppeteer，用于抓取 JavaScript 内容较多的网站
• Pyppeteer-stealth，用于避免网络抓取时被检测
• Puppeteer 实例池，用于高效复用浏览器
• DuckDuckGo Search API
• BeautifulSoup，用于解析 HTML
• scikit-learn，用于基于 TF-IDF 的资源相关性筛选
• yt-dlp，用于搜索 YouTube 视频并提取元数据
• Redis（可选），用于分布式缓存
• msgpack，用于高效的数据序列化
• cachetools，用于高级内存缓存

安装

1. 克隆代码库：

   git clone https://github.com/yourusername/mcp_server.git
   cd mcp_server
   

2. 创建虚拟环境：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. 安装 Python 依赖：

   pip install -r requirements.txt
   

4. 安装 Node.js 依赖（用于优化抓取系统）：

   npm install
   

5. 安装 Chrome/Chromium，以供 Pyppeteer 使用（如果尚未安装）

用法

本地运行

1. 使用提供的批处理文件启动服务（Windows）：

   run_local.bat
   

   或者使用 uvicorn 手动启动：

   uvicorn main:app --reload --host 0.0.0.0 --port 8000
   

2. 在 http://localhost:8000 访问 API

3. 通过发送 GET 请求生成 MCP：

   GET /generate_mcp?topic=your_topic
   

4. 在 http://localhost:8000/docs 查看 API 文档

生产环境 URL

生产服务可通过以下地址访问：

https://reunemacacada.onrender.com

本 README 中记录的所有端点均可通过本地和生产环境 URL 访问。

测试缓存系统

1. 首次发送请求以生成 MCP（此操作会填充缓存）：

   GET /generate_mcp?topic=python&num_nodes=15&language=pt
   

2. 使用相同参数发送第二次请求（此时应使用缓存）：

   GET /generate_mcp?topic=python&num_nodes=15&language=pt
   

   由于结果会从缓存中获取，第二次请求的速度应明显更快。

文档

详细文档位于 docs 文件夹中：

• API 参考 - 详细的 API 文档
• 端点参考 - 所有端点的完整参考
• Flutter 集成 - 与 Flutter 应用集成的指南
• 异步任务系统 - 异步任务系统文档
• 性能改进 - 性能优化概述
• 缓存系统 - 缓存系统文档
• 网络抓取优化 - 网络抓取优化详情

API 端点

• GET /health - 健康检查端点
• GET /generate_mcp?topic={topic}&max_resources={max_resources}&num_nodes={num_nodes}&min_width={min_width}&max_width={max_width}&min_height={min_height}&max_height={max_height}&language={language}&category={category} - 为指定主题同步生成 MCP
  • topic（必填）：要生成 MCP 的主题（至少 3 个字符）
  • max_resources（可选）：要包含的资源数量上限（默认值：15，最小值：5，最大值：30）
  • num_nodes（可选）：学习路径中要包含的节点数（默认值：15，最小值：10，最大值：30）
  • min_width（可选）：树的最小宽度（第一级的节点数）（默认值：3，最小值：2，最大值：10）
  • max_width（可选）：树在任意层级的最大宽度（默认值：5，最小值：3，最大值：15）
  • min_height（可选）：树的最小高度（深度）（默认值：3，最小值：2，最大值：8）
  • max_height（可选）：树的最大高度（深度）（默认值：7，最小值：3，最大值：12）
  • language（可选）：资源使用的语言（默认值："pt"）
  • category（可选）：主题类别（例如："technology"、"finance"、"health"）。如果未提供，将自动检测。
• POST /generate_mcp_async?topic={topic}&max_resources={max_resources}&num_nodes={num_nodes}&min_width={min_width}&max_width={max_width}&min_height={min_height}&max_height={max_height}&language={language}&category={category} - 启动 MCP 异步生成
• GET /status/{task_id} - 检查异步任务的状态
• GET /tasks - 列出所有任务
• POST /clear_cache?pattern={pattern}&clear_domain_cache={clear_domain_cache} - 根据模式清除缓存
  • pattern（可选）：用于匹配缓存键的模式（默认值："*"，表示全部）
  • clear_domain_cache（可选）：是否同时清除域名方法缓存（默认值：false）
• GET /cache_stats - 获取缓存统计信息，包括域名方法缓存的信息

示例

基本用法（葡萄牙语）

GET /generate_mcp?topic=python

自定义节点数

GET /generate_mcp?topic=machine+learning&num_nodes=20

英语

GET /generate_mcp?topic=javascript&language=en

手动指定类别

GET /generate_mcp?topic=python&category=technology

完全自定义

GET /generate_mcp?topic=história+do+brasil&max_resources=20&num_nodes=25&min_width=4&max_width=8&min_height=4&max_height=8&language=pt

控制树结构

GET /generate_mcp?topic=machine+learning&min_width=2&max_width=4&min_height=5&max_height=10

异步生成

POST /generate_mcp_async?topic=inteligência+artificial&category=technology

检查任务状态

GET /status/550e8400-e29b-41d4-a716-446655440000

清除缓存

POST /clear_cache

清除指定缓存

POST /clear_cache?pattern=mcp:*

性能改进

MCP Server 包含多项性能优化：

• 缓存系统：缓存结果，以缩短重复查询的响应时间
• 异步任务系统：以异步方式处理长时间运行的操作
• 资源筛选：基于 TF-IDF 进行筛选，选出最相关的资源
• 优化的网页抓取：采用高效的网页抓取技术，减少资源使用
• 自适应抓取系统：自动为每个网站选择最高效的抓取方法
• Puppeteer 实例池：复用浏览器实例，以减少内存使用和启动时间
• 域名方法缓存：记住每个域名最适用的抓取方法
• 资源拦截：抓取期间拦截不必要的资源（图片、样式表、字体）

性能提升

• 对已缓存的主题，响应时间缩短 60-80%
• 对新主题，响应时间缩短 30-50%
• 网页抓取期间，内存使用量减少 40-60%
• 并发请求的吞吐量提升 3-5 倍

部署

该服务可部署到各种平台：

使用 Docker

docker build -t mcp-server .
docker run -p 8080:8080 mcp-server

部署到 Render、Fly.io 或其他平台

按照对应平台的说明部署 Docker 容器或 Python 应用。

许可证

专有软件 - 保留所有权利

本软件为专有且机密的软件。严格禁止未经授权复制、分发、修改、公开展示或公开演示本软件。本软件仅供付费订阅用户使用。

© 2024 ReuneMacacada。保留所有权利。

最后一次提交：v1.1.2 - 修复 DuckDuckGo 速率限制和 Puppeteer 相关问题