MCP 服务器

MCP Server

一个服务器，通过聚合网络资源并将它们组织成结构化的学习路径，来生成任何主题的“主内容计划”（MCP）。

README

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 用于高级内存缓存

安装

克隆存储库：

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

创建一个虚拟环境：

python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

安装 Python 依赖项：
```
pip install -r requirements.txt
```
安装 Node.js 依赖项（用于优化的抓取系统）：
```
npm install
```
安装 Chrome/Chromium for Pyppeteer (如果尚未安装)

用法

本地运行

使用提供的批处理文件启动服务器 (Windows)：
```
run_local.bat
```
或者手动使用 uvicorn：
```
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
在 http://localhost:8000 访问 API
通过向以下地址发出 GET 请求来生成 MCP：
```
GET /generate_mcp?topic=your_topic
```
在 http://localhost:8000/docs 查看 API 文档

生产 URL

生产服务器位于：

https://reunemacacada.onrender.com

此 README 中记录的所有端点都可以在本地和生产 URL 上使用。

测试缓存系统

发出第一个请求以生成 MCP（这将填充缓存）：
```
GET /generate_mcp?topic=python&num_nodes=15&language=pt
```
使用相同的参数发出第二个请求（这应该使用缓存）：
```
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 应用程序。

许可证

本软件是专有和机密的。严禁未经授权复制、分发、修改、公开展示或公开执行本软件。本软件仅供在付费订阅模式下使用。

上次提交：v1.1.2 - 修复了 DuckDuckGo 速率限制和 Puppeteer 的问题