Create MCP Docs

AgentDesk MCP文档系统

🚀 用于创建模型上下文协议（MCP）文档服务器的现代工具包，具有智能内容检测、高级搜索优化和漂亮的CLI工具。

该存储库为构建MCP文档服务器提供了一个完整的系统，该服务器可以智能地抓取、索引和搜索具有关键字和语义搜索功能的文档网站。

📦 包裹

核心包

• @agentdesk/mcp-docs -核心文档索引和搜索功能
• create-mcp-docs -用于生成MCP文档服务器的CLI工具

🚀 快速开始

创建新的MCP文档服务器

npx create-mcp-docs my-docs-server

此交互式CLI将：

1. ✨ 指导您完成项目设置（名称和描述）
2. 🌐 收集要爬网的文档URL
3. ⚙️ 让您在FlexSearch（关键字）或Vectra（语义）搜索之间进行选择
4. 📁 生成完整的MCP服务器项目
5. ✅ 提供即用型TypeScript代码

生成的项目结构

packages/my-docs-server/
├── package.json          # Dependencies and scripts
├── src/
│   ├── server.ts         # MCP server implementation
│   └── build-index.ts    # Documentation indexer
├── .env                  # Environment configuration
├── README.md            # Usage instructions
└── ...

启动服务器

cd packages/my-docs-server
pnpm install
pnpm build:index    # Build documentation search index
pnpm start          # Start MCP server

⚡ 搜索提供商比较

根据您的需求选择合适的搜索提供商：

🔍 FlexSearch（关键字搜索）

最适合：更小的文档集，快速设置，精确的术语匹配

优点:

• 闪电般快速的搜索性能
• 不需要API密钥
• 较小的索引大小
• 非常适合包含特定术语的技术文档

缺点:

• 语义理解有限
• 可能会错过概念相关的内容

🧠 Vectra（语义搜索）

最适合：大型文档集、概念查询、内容发现

优点:

• 理解含义和上下文
• 查找概念上相关的内容
• 更适合自然语言查询
• 先进的“后期分块”以保存上下文

缺点:

• 需要OpenAI API密钥
• 更大的索引大小
• 初始索引速度稍慢

🏗️ 系统架构

完整系统概述

graph TB
    subgraph "CLI Layer"
        CLI["create-mcp-docs CLI"]
        CLI --> Setup["Project Setup"]
        CLI --> URLs["URL Collection"]
        CLI --> Provider["Provider Selection"]
        CLI --> Gen["Project Generation"]
    end

    subgraph "Generated MCP Server"
        Server["MCP Server"]
        Index["Index Builder"]
        Config[".env Configuration"]
        Server --> Tool["search_docs tool"]
    end

    subgraph "Core Package (@agentdesk/mcp-docs)"
        CreateIndex["createIndex()"]
        KB["KnowledgeBase"]
        Heuristics["Content Detection"]
        Pipeline["Document Pipeline"]
        Optimizer["Search Optimizer"]
    end

    subgraph "Search Providers"
        FlexSearch["FlexSearch
(Keyword)"]
        Vectra["Vectra
(Semantic)"]
    end

    subgraph "Document Processing"
        Crawler["Playwright Crawler"]
        Parser["Content Parser"]
        Chunker["Chunking Service"]
        ReadabilityJS["Mozilla Readability"]
    end

    subgraph "AI Integration"
        AI["AI Model"]
        MCP["MCP Protocol"]
        OpenAI["OpenAI Embeddings"]
    end

    %% CLI Flow
    Gen --> Server
    Gen --> Index
    Gen --> Config

    %% Core Integration
    Index --> CreateIndex
    Tool --> KB
    CreateIndex --> Heuristics
    CreateIndex --> Pipeline

    %% Processing Pipeline
    Pipeline --> Crawler
    Pipeline --> Parser
    Pipeline --> Chunker
    Parser --> ReadabilityJS

    %% Provider Selection
    CreateIndex --> FlexSearch
    CreateIndex --> Vectra
    Vectra --> OpenAI
    KB --> FlexSearch
    KB --> Vectra
    KB --> Optimizer

    %% AI Integration
    AI --> MCP
    MCP --> Server
    Tool --> AI

    %% Styling
    classDef cli fill:#e1f5fe
    classDef core fill:#f3e5f5
    classDef provider fill:#e8f5e8
    classDef processing fill:#fff3e0
    classDef ai fill:#fce4ec

    class CLI,Setup,URLs,Provider,Gen cli
    class CreateIndex,KB,Heuristics,Pipeline,Optimizer core
    class FlexSearch,Vectra provider
    class Crawler,Parser,Chunker,ReadabilityJS processing
    class AI,MCP,OpenAI ai

用户工作流

sequenceDiagram
    participant User
    participant CLI as create-mcp-docs CLI
    participant Generator as Project Generator
    participant MCP as Generated MCP Server
    participant Indexer as Documentation Indexer
    participant Provider as Search Provider
    participant AI as AI Model

    User->>CLI: npx create-mcp-docs
    CLI->>User: Collect project details & URLs
    CLI->>Generator: Generate project files
    Generator->>MCP: Create MCP server & indexer

    User->>Indexer: pnpm build:index
    Indexer->>Provider: Extract & index documents
    Provider->>Indexer: Search index ready

    User->>MCP: pnpm start
    AI->>MCP: Search documentation
    MCP->>Provider: Execute search query
    Provider->>MCP: Optimized results
    MCP->>AI: Contextual documentation

✨ 主要特点

🧠 智能内容检测

• 使用启发式方法自动检测最佳CSS选择器
• 集成Mozilla可读性用于内容提取
• 提供信心评分和回退选项
• 根据实际页面内容验证选择器

🎨 美丽的CLI体验

基于React的交互式CLI，具有：

• 项目设置：名称和描述输入
• URL集合：添加多个文档源
• 提供者选择：在FlexSearch和Vectra之间进行选择
• 活世代：实时项目创建反馈
• 成功指南：创建后清除后续步骤

🚀 以文档为中心的搜索优化

超越简单关键字匹配的高级搜索优化：

• 完整文档策略：当多个块高度相关时，返回整个文档
• 扩展区块链战略：智能扩展相关内容部分
• 代币预算管理：优化结果以适应AI模型上下文限制
• 保持连贯性：维护文档结构和上下文流

⚡ 高性能索引

• 智能爬行：由Playwright驱动的浏览器自动化
• 内容物清理：Mozilla可读性集成，用于清洁提取
• 弹性分块：传统、语义和后期分块策略
• 并发处理：具有速率限制的可配置并发

🔧 生产就绪服务器

• 遵循既定的MCP服务器模式
• 使用TypeScript构建，实现完全类型安全
• 全面的错误处理和记录
• 基于环境的配置
• 无需额外设置即可部署

🎯 用例

文档团队

# Create a server for your product docs
npx create-mcp-docs product-docs
# URLs: https://docs.yourproduct.com
# Choose FlexSearch for fast, precise searches

大型知识库

# Create a semantic search server for comprehensive docs
npx create-mcp-docs comprehensive-docs
# URLs: Multiple documentation sources
# Choose Vectra for conceptual understanding

API文档

# Create a server for API reference
npx create-mcp-docs api-docs
# URLs: https://api.yourservice.com/docs
# FlexSearch excels at exact API method/parameter searches

🔬 高级功能

后期分块策略

对于Vectra用户来说，我们的“后期分块”实现保留了跨块边界的上下文信息：

• 上下文嵌入：文档在分块之前通过完整上下文进行处理
• 语义边界：尊重文档结构的智能拆分
• 上下文保护：相关信息在块之间保持联系
• 针对文档进行了优化：专门针对技术文档模式进行了调整

_在 @agentdesk/mcp-docs 文档_

以文档为中心的优化

我们的搜索优化器分析原始搜索结果，并智能地决定最佳策略：

// Example optimization strategies
{
  fullDocumentThreshold: 3,      // 3+ chunks = return full document
  expandedChunkMultiplier: 2,    // Expand single chunks by 2x
  targetUtilization: 0.9,        // Use 90% of token budget
}

_详细的算法解释见 核心包文档_

🔧 高级配置

手动创建索引

import { createIndex } from "@agentdesk/mcp-docs";

await createIndex({
  pages: [
    {
      url: "https://docs.example.com",
      mode: "crawl",
      selectors: {
        links: 'a[href^="/docs"]',
        content: "article.prose",
      },
    },
  ],
  // Choose your provider
  provider: {
    type: "vectra",
    embeddings: {
      provider: "openai",
      model: "text-embedding-ada-002",
      apiKey: process.env.OPENAI_API_KEY,
    },
    chunking: {
      strategy: "late-chunking",
      useCase: "documentation",
    },
  },
  outputFile: "docs-vectra-index",
});

知识库搜索

import { KnowledgeBase, getModuleDir } from "@agentdesk/mcp-docs";

const docs = new KnowledgeBase({
  path: getModuleDir(import.meta.url), // Directory containing index
  apiKey: process.env.OPENAI_API_KEY, // For Vectra indices
});

const results = await docs.search({
  query: "How do I authenticate users?",
  tokenLimit: 10000,
});

📚 文档

包文档

• @代理台/mcp文档 -详细的API参考和算法
• 创建mcp文档 -CLI工具实施细节

🛠️ 发展

设置

git clone https://github.com/agentdesk/create-mcp-docs
cd create-mcp-docs
pnpm install
pnpm build

包装开发

# Core package
cd packages/mcp-docs
pnpm dev

# CLI package
cd packages/create-mcp-docs
pnpm build
pnpm link --global
create-mcp-docs test-project

测试

# Run all tests
pnpm test

# Package-specific tests
cd packages/mcp-docs && pnpm test
cd packages/create-mcp-docs && pnpm test

🏷️ 需求

• Node.js >= 16.0.0
• pnpm >=8.0.0（推荐）
• OpenAI API密钥 （仅适用于Vectra语义搜索）

🤝 贡献

我们欢迎捐款！请参阅：

1. 问题 -Bug报告和功能请求
2. 拉取请求 -代码贡献
3. 文档 -改进和示例

开发指南

• 对所有新代码使用TypeScript
• 遵循现有的代码风格和模式
• 为新功能添加全面的测试
• 更新API变更文档

📝 许可证

麻省理工学院-参见 许可证 文件以获取详细信息。

🔗 相关项目

• 模型上下文协议 -此实施的标准
• AgentKit 的 -AI代理开发框架
• AgentDesk 的 -AI代理平台

______________________________________________________________________

内置于❤️ AgentDesk团队