MCP服务器

一个基于主题生成主内容计划 (MCP) 的服务器。该服务器聚合来自网络的资源，并将它们组织成结构化的学习路径。

特性

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

技术栈

• Python 3.9+
• FastAPI
• Pyppeteer 用于 JavaScript 繁重的网络抓取
• Pyppeteer-stealth 用于避免在网络抓取期间被检测到
• Puppeteer 实例池，用于高效的浏览器重用
• DuckDuckGo 搜索 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  # 在 Windows 上：venv\Scripts\activate
   

3. 安装 Python 依赖项：

   pip install -r requirements.txt
   

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

   npm install
   

5. 安装 Chrome/Chromium for 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 服务器包括多项性能优化：

• 缓存系统: 缓存结果以提高重复查询的响应时间
• 异步任务系统: 长时间运行的操作以异步方式处理
• 资源过滤: 基于 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 的问题