科技百科全书

用于技术文档爬行的高保真代理数据管道

](https://github.com/NoManNayeem/TechCyclopedia) ](https://nomanayeem.github.io/TechCyclopedia) ![License](LICENSE) ![Python](https://python.org)

TechCyclopedia是一个智能MCP（模型上下文协议）服务器，提供高级网络爬行功能，包括交互式配置、实时进度跟踪和技术文档的后台任务管理。

特性

智能文档发现：自动查找20多种流行工具（Python、React、FastAPI等）的文档
智能URL处理：传递工具名称或URL-自动发现和验证
交互式配置：具有持久存储的智能用户偏好系统
实时进度跟踪：实时更新爬行进度，并显示详细状态
后台任务：继续聊天时在后台运行爬网
有组织的产出：按域进行干净、结构化的文件组织
内容过滤：自动删除样板和内容优化
全面的错误处理：强大的验证、详细的错误消息、优雅的降级
文件大小管理：自动尺寸检查和过滤（10MB限制）
持久首选项：基于SQLite的用户偏好存储
深度爬行：BFS综合文档提取策略

🌐 现场演示

访问实时网站:

该网站展示了TechCyclopedia的功能、使用示例，并提供了全面的文档。

v2.0中的新增功能🎉

🎯 智能工具发现：只需键入 python 或 react 而不是完整的URL
✅ 增强验证：全面的URL验证，包含详细的错误消息
🛡️ 更好的错误处理：优雅的故障处理，详细的错误报告
📊 丰厚的回报价值：从所有操作中获取详细的统计数据和元数据
🔍 新工具: discover_docs 和 list_supported_tools 用于勘探
📏 文件大小管理：自动尺寸检查（10MB限制）
🐛 错误修复：修复了日期时间弃用警告

看改进.md 详细文档。

快速开始

先决条件

Python 3.9+
pip包管理器

安装

克隆仓库:

   git clone https://github.com/NoManNayeem/TechCyclopedia.git
   cd TechCyclopedia

创建虚拟环境:

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

安装依赖项:

pip install -r requirements.txt
playwright install

启动服务器:

   python server/server.py

用法

MCP工具可用

TechCyclopedia提供了几个强大的MCP工具：

1. `crawl_tech_docs` -智能文档抓取

通过自动URL发现和验证抓取技术文档。

新：现在支持工具名称！传递“python”而不是完整的URL。

参数：

urls：URL或工具名称列表（例如，\[“python”、“react”、“https://example.com"\])
output_dir：保存MD文件的目录路径
user_id：首选项的用户标识符（默认值：“默认”）

示例：

// Using tool names (NEW!)
{
  "tool": "crawl_tech_docs",
  "parameters": {
    "urls": ["python", "fastapi"],
    "output_dir": "results",
    "user_id": "default"
  }
}

// Using direct URLs (still works)
{
  "tool": "crawl_tech_docs",
  "parameters": {
    "urls": ["https://docs.python.org/3/tutorial/"],
    "output_dir": "results",
    "user_id": "default"
  }
}

// Mix both!
{
  "tool": "crawl_tech_docs",
  "parameters": {
    "urls": ["python", "https://custom-docs.com"],
    "output_dir": "results"
  }
}

退货：

{
  "success": true,
  "task_id": "uuid",
  "urls_processed": 3,
  "files_created": 45,
  "output_directory": "/path/to/results",
  "files": ["file1.md", "file2.md", ...],
  "inputs_processed": ["Found 3 documentation URL(s) for 'python'"],
  "validation_errors": null
}

2. `start_background_crawl` -后台任务

启动一个后台爬网任务，该任务可以在用户继续聊天时运行。

参数：

urls：文档爬网的起始URL列表
output_dir：保存MD文件的目录路径
user_id：首选项的用户标识符

退货： 用于跟踪后台任务的任务ID

3. `check_task_status` -监控进度

检查后台爬网任务的状态。

参数：

task_id：start_background_crawl返回的任务ID

退货： 包含任务状态和进度信息的词典

4. `get_all_tasks` -查看所有任务

获取所有爬行任务及其状态。

退货： 所有任务及其状态信息的列表

5. `set_dont_ask_again` -保存首选项

为用户偏好设置“不再询问”标志。

参数：

user_id：用户标识符

退货： 如果设置成功，则为True

6. `discover_docs` -查找文档URL（新增！）

在不启动爬网的情况下发现特定工具的文档URL。

参数：

tool_name：工具/框架的名称（例如，“python”、“react”）

例子：

{
  "tool": "discover_docs",
  "parameters": {
    "tool_name": "python"
  }
}

退货：

{
  "success": true,
  "tool_name": "python",
  "urls": [
    "https://docs.python.org/3/",
    "https://docs.python.org/3/tutorial/",
    "https://docs.python.org/3/library/"
  ],
  "count": 3
}

7. `list_supported_tools` -列出可用工具（新增！）

获取具有内置文档发现功能的所有工具的列表。

无需参数

退货：

{
  "success": true,
  "tools": ["python", "react", "fastapi", "docker", ...],
  "count": 20,
  "categories": {
    "Programming Languages": ["python", "typescript", "rust", "go"],
    "Web Frameworks": ["react", "next.js", "vue", "angular", ...],
    ...
  }
}

配置选项

TechCyclopedia提供灵活的配置选项：

爬行策略

深度爬行 （默认）：抓取域内的所有相关页面
浅爬行：仅抓取提供的特定URL
单页：只需从给定的URL中提取内容

内容处理

移除锅炉板：自动删除导航、页脚、广告
按域组织：创建特定于域的子目录
内容优化：提取干净、LLM就绪的标记

高级选项

最大深度：爬行深度（1-10级）
最大页数：要爬网的最大页数
包括外部链接：关注其他域名的链接

输出结构

results/
├── docs.python.org/
│   ├── tutorial_index.md
│   ├── introduction.md
│   └── ...
├── ai-sdk.dev/
│   ├── docs_ai-sdk-ui.md
│   └── ...
└── ...

建筑

系统概述

TechCyclopedia建立在模块化架构之上，由以下组件组成：

┌─────────────────────────────────────────────────────────────┐
│                     LLM Agent / Client                       │
│                  (MCP Protocol Consumer)                     │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Tool Call
                         │ crawl_tech_docs(urls, output_dir)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  FastMCP2 Server (server.py)                 │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  @mcp.tool async def crawl_tech_docs()               │   │
│  │  - Input validation                                  │   │
│  │  - Progress reporting via ctx.info()                 │   │
│  │  - Resource URI generation (MD5 hashing)            │   │
│  └────────────────────┬─────────────────────────────────┘   │
└────────────────────────┼─────────────────────────────────────┘
                         │ async/await
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              Crawl4ai Engine (AsyncWebCrawler)               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  BFSDeepCrawlStrategy                                │   │
│  │  - Breadth-first link discovery                      │   │
│  │  - Domain scoping (include_external=False)          │   │
│  │  - max_depth=5, max_pages=500                       │   │
│  └────────────────────┬─────────────────────────────────┘   │
│                       │                                      │
│  ┌────────────────────▼─────────────────────────────────┐   │
│  │  Playwright Headless Browser                         │   │
│  │  - JavaScript rendering                              │   │
│  │  - Dynamic content handling                          │   │
│  └────────────────────┬─────────────────────────────────┘   │
└────────────────────────┼─────────────────────────────────────┘
                         │ Raw HTML
                         ▼
┌─────────────────────────────────────────────────────────────┐
│            Multi-Stage Content Filter Pipeline               │
│                                                              │
│  Stage 1: HTML Pre-Exclusion                                │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Remove: nav, footer, header, script, style          │   │
│  └────────────────────┬─────────────────────────────────┘   │
│                       │                                      │
│  Stage 2: PruningContentFilter                              │
│  ┌────────────────────▼─────────────────────────────────┐   │
│  │  Heuristics:                                          │   │
│  │  - Text density scoring                               │   │
│  │  - Link density penalty                               │   │
│  │  - Structural context analysis                        │   │
│  │  - Dynamic threshold adjustment                       │   │
│  │  - min_word_threshold=20                             │   │
│  └────────────────────┬─────────────────────────────────┘   │
│                       │                                      │
│  Stage 3: Global Refinement                                 │
│  ┌────────────────────▼─────────────────────────────────┐   │
│  │  exclude_external_links=True                          │   │
│  └────────────────────┬─────────────────────────────────┘   │
└────────────────────────┼─────────────────────────────────────┘
                         │ Clean Markdown
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  Fit Markdown Output                         │
│  - 60-80% token reduction vs raw HTML                       │
│  - Semantic structure preserved                             │
│  - Technical details intact                                 │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                Storage Layer (results/)                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  MD5-hashed filenames (deterministic)                 │   │
│  │  Example: 8a1b2c3d4e5f6789abcdef0123456789.md        │   │
│  └────────────────────┬─────────────────────────────────┘   │
└────────────────────────┼─────────────────────────────────────┘
                         │ Resource URIs
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              MCP Resources (for Agent Retrieval)             │
│  Agent can read specific resources by URI                   │
└─────────────────────────────────────────────────────────────┘

组件详细信息

1.FastMCP2服务器层

文件: server/server.py
职责：MCP协议处理、异步工具执行、输入验证、进度报告、资源URI生成

2.增强型爬行器

文件: server/enhanced_crawler.py
职责：具有进度跟踪、有组织的输出、内容过滤功能的高级爬行

3.用户偏好系统

文件: server/user_preferences.py
职责：基于SQLite的偏好存储、用户配置管理

4.交互式配置

文件: server/interactive_config.py
职责：用户交互处理、配置选择、偏好管理

5.进度跟踪器

文件: server/progress_tracker.py
职责：任务管理、进度监控、后台任务协调

6.爬行器配置

文件: server/crawler_config.py
职责：深度抓取策略定义、URL过滤、内容过滤器配置

测试

运行测试

测试核心组件:

   python tests/simple_test.py

测试MCP服务器:

   python tests/mcp_test.py

快速测试:

   python tests/quick_test.py

测试覆盖率

测试套件包括：

增强的爬虫功能
用户首选项系统
进度跟踪器
交互式配置
MCP工具注册
直接函数调用
刀具参数处理

MCP客户端集成

TechCyclopedia适用于任何兼容MCP的客户端。以下是常见客户端的详细设置说明：

Claude桌面集成

1. 查找Claude桌面配置

Windows位置：

C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json

2. 添加TechCyclopedia配置

创建或编辑配置文件：

{
  "mcpServers": {
    "techcyclopedia": {
      "command": "python",
      "args": ["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

3. 替代方案：使用虚拟环境

如果要使用项目的虚拟环境：

{
  "mcpServers": {
    "techcyclopedia": {
      "command": "C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

4. 保存并重新启动

保存配置文件
完全关闭克劳德桌面
重新打开克劳德桌面
TechCyclopedia工具将可用

5. 在Claude Desktop中进行测试

在Claude Desktop中尝试以下命令：

"Use TechCyclopedia to crawl https://docs.python.org/3/tutorial/ and save the results to a folder called 'test_results'"

继续（VS代码扩展）

1. 配置文件

创建或编辑： ~/.continue/config.json

{
  "mcpServers": {
    "techcyclopedia": {
      "command": "python",
      "args": ["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"]
    }
  }
}

2. VS代码中的用法

在VS Code中打开继续面板
问：“使用MCP工具crawl_tech_docs获取Python文档”
继续将自动调用TechCyclopedia

游标IDE集成

1. 配置文件

创建或编辑： ~/.cursor/mcp.json

{
  "servers": {
    "techcyclopedia": {
      "command": "python",
      "args": ["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"],
      "transport": "stdio"
    }
  }
}

Python MCP客户端

1. 安装MCP SDK

pip install mcp

2. 客户端代码示例

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def crawl_with_techcyclopedia():
    server_params = StdioServerParameters(
        command="python",
        args=["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"],
        env=None
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {tools}")
            
            # Call the crawl_tech_docs tool
            result = await session.call_tool(
                "crawl_tech_docs",
                arguments={
                    "urls": ["https://docs.python.org/3/"],
                    "output_dir": "results",
                    "user_id": "my_user"
                }
            )
            print(f"Crawl result: {result}")
            
            # Check background task
            task_id = await session.call_tool(
                "start_background_crawl",
                arguments={
                    "urls": ["https://ai-sdk.dev/docs/ai-sdk-ui"],
                    "output_dir": "background_results",
                    "user_id": "my_user"
                }
            )
            print(f"Background task started: {task_id}")

asyncio.run(crawl_with_techcyclopedia())

JavaScript/TypeScript MCP客户端

1. 安装MCP SDK

npm install @modelcontextprotocol/sdk

2. 客户端代码示例

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function crawlWithTechCyclopedia() {
  const transport = new StdioClientTransport({
    command: "python",
    args: ["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"],
  });

  const client = new Client(
    { name: "techcyclopedia-client", version: "1.0.0" },
    { capabilities: {} }
  );

  await client.connect(transport);
  
  // List available tools
  const tools = await client.listTools();
  console.log("Available tools:", tools);
  
  // Call crawl_tech_docs tool
  const result = await client.callTool({
    name: "crawl_tech_docs",
    arguments: {
      urls: ["https://docs.python.org/3/"],
      output_dir: "results",
      user_id: "my_user"
    },
  });

  console.log("Crawl result:", result);
  
  // Start background task
  const taskId = await client.callTool({
    name: "start_background_crawl",
    arguments: {
      urls: ["https://ai-sdk.dev/docs/ai-sdk-ui"],
      output_dir: "background_results",
      user_id: "my_user"
    },
  });
  
  console.log("Background task started:", taskId);
  
  await client.close();
}

crawlWithTechCyclopedia().catch(console.error);

自定义MCP客户端集成

1. 基本协议流

1. Client → Server: Initialize request
2. Server → Client: Initialize response  
3. Client → Server: List tools
4. Server → Client: Tools list
5. Client → Server: Call tool
6. Server → Client: Tool result

2. 示例：最小Python客户端

import subprocess
import json

class SimpleMCPClient:
    def __init__(self, command, args):
        self.process = subprocess.Popen(
            [command] + args,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )
        self.msg_id = 0

    def send_message(self, method, params=None):
        self.msg_id += 1
        message = {
            "jsonrpc": "2.0",
            "id": self.msg_id,
            "method": method,
            "params": params or {}
        }
        self.process.stdin.write(json.dumps(message) + "\n")
        self.process.stdin.flush()

        # Read response
        response = self.process.stdout.readline()
        return json.loads(response)

    def call_tool(self, name, arguments):
        return self.send_message("tools/call", {
            "name": name,
            "arguments": arguments
        })

# Usage
client = SimpleMCPClient("python", ["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"])
client.send_message("initialize", {"clientInfo": {"name": "simple", "version": "1.0"}})
result = client.call_tool("crawl_tech_docs", {
    "urls": ["https://docs.python.org/3/"],
    "output_dir": "results",
    "user_id": "my_user"
})
print(result)

测试您的集成

1. 使用MCP检查器

npm install -g @modelcontextprotocol/inspector
mcp-inspector python C:\Users\lenovo\Desktop\Mamdo\dumpo\server\server.py

2. 手动测试

# Test the server directly
python C:\Users\lenovo\Desktop\Mamdo\dumpo\server\server.py

3. 配置示例

通用MCP客户端配置：

{
  "servers": {
    "techcyclopedia": {
      "command": "python",
      "args": ["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"],
      "transport": "stdio",
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

使用虚拟环境：

{
  "command": "C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\venv\\Scripts\\python.exe",
  "args": ["C:\\Users\\lenovo\\Desktop\\Mamdo\\dumpo\\server\\server.py"]
}

故障排除

常见问题：

未找到路径：使用绝对路径（以开头的完整路径 C:\)
未找到Python：使用Python可执行文件的完整路径
权限不足：以管理员身份运行客户端
未找到模块：确保安装了所有依赖项

调试步骤：

手动测试服务器： python server/server.py
检查文件路径是否正确
验证Python环境
检查客户端日志是否有错误
确保MCP协议兼容性

快速入门指南

1. 安装

git clone https://github.com/NoManNayeem/TechCyclopedia.git
cd TechCyclopedia
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. 测试服务器

python server/server.py

3. 配置您的MCP客户端

从上面的集成示例中选择您的首选客户端，并按照设置说明进行操作。

4. 开始爬行

使用客户端中的MCP工具抓取技术文档：

命令示例：

“使用TechCyclopedia抓取Python文档”
“启动React文档的后台抓取”
“检查我的爬网任务的状态”

建筑

核心组件

server/server.py：带工具定义的FastMCP服务器
server/enhanced_crawler.py：具有进度跟踪功能的高级爬行
server/user_preferences.py：基于SQLite的首选项存储
server/interactive_config.py：用户友好的配置提示
server/progress_tracker.py：实时进度监控

数据流

User Request → MCP Client → TechCyclopedia Server → Enhanced Crawler → File System
     ↓              ↓              ↓                    ↓              ↓
Configuration → Tool Call → Progress Updates → Content Processing → Organized Output

贡献

我们欢迎捐款！请查看我们的贡献指南了解详情。

开发设置

分叉存储库
创建要素分支
进行更改
添加测试
提交拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

支持

问题:
讨论:
文档: 网站直播

______________________________________________________________________

科技百科全书 -将网络文档转化为干净、AI就绪的内容，以适应智能系统的未来。

Tech Cyclopedia

快速接入

详细介绍

科技百科全书

特性

🌐 现场演示

v2.0中的新增功能🎉

快速开始

先决条件

安装

用法

MCP工具可用

1. crawl_tech_docs -智能文档抓取

2. start_background_crawl -后台任务

3. check_task_status -监控进度

4. get_all_tasks -查看所有任务

5. set_dont_ask_again -保存首选项

6. discover_docs -查找文档URL（新增！）

7. list_supported_tools -列出可用工具（新增！）

配置选项

爬行策略

内容处理

高级选项

输出结构

建筑

系统概述

组件详细信息

1.FastMCP2服务器层

2.增强型爬行器

3.用户偏好系统

4.交互式配置

5.进度跟踪器

6.爬行器配置

测试

运行测试

测试覆盖率

MCP客户端集成

Claude桌面集成

1. 查找Claude桌面配置

2. 添加TechCyclopedia配置

3. 替代方案：使用虚拟环境

4. 保存并重新启动

5. 在Claude Desktop中进行测试

继续（VS代码扩展）

1. 配置文件

2. VS代码中的用法

游标IDE集成

1. 配置文件

Python MCP客户端

1. 安装MCP SDK

2. 客户端代码示例

JavaScript/TypeScript MCP客户端

1. 安装MCP SDK

2. 客户端代码示例

自定义MCP客户端集成

1. 基本协议流

2. 示例：最小Python客户端

测试您的集成

1. 使用MCP检查器

2. 手动测试

3. 配置示例

故障排除

常见问题：

调试步骤：

快速入门指南

1. 安装

2. 测试服务器

3. 配置您的MCP客户端

4. 开始爬行

建筑

核心组件

数据流

贡献

开发设置

许可证

支持

目录标签

接入字段

权限和风险

来源信息

1. `crawl_tech_docs` -智能文档抓取

2. `start_background_crawl` -后台任务

3. `check_task_status` -监控进度

4. `get_all_tasks` -查看所有任务

5. `set_dont_ask_again` -保存首选项

6. `discover_docs` -查找文档URL（新增！）

7. `list_supported_tools` -列出可用工具（新增！）