Bucketeer Docs Local MCP Server

Bucketeer Docs 本地 MCP 服务

概述

此项目为 Bucketeer 文档提供 Model Context Protocol（MCP）服务。它提供了一个接口，用于搜索和检索 Bucketeer 功能标志与实验平台文档中的内容，使 AI 助手能够准确介绍 Bucketeer 的功能和用法。

环境设置

要求

• Node.js 18+
• npm

安装步骤

1. 克隆代码库：

git clone <repository-url>
cd bucketeer-docs-local-mcp-server

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

4. 构建文档索引：

npm run build:index

启动服务

npm start

文档来源

此服务会自动从 bucketeer-io/bucketeer-docs 代码库获取并索引文档：

• GitHub 代码库集成：

  • 自动从 docs/ 目录及其所有子目录获取 .mdx 文件
  • 处理 frontmatter 和 Markdown 内容，以优化搜索索引
  • 使用 SHA 哈希缓存获取的内容，仅在文件修改时更新
  • 支持递归遍历目录，以收录所有文档文件

• 智能索引：

  • 从标题、描述、标题栏和内容中提取关键词
  • 构建可搜索索引，根据关键词匹配和全文搜索计算相关性评分
  • 针对 Bucketeer 专用术语（功能标志、实验、SDK、定向等）进行优化
  • 处理 MDX 文件中的 frontmatter 提取（标题、描述）

• 缓存管理：

  • 文件以 JSON 文件形式缓存在本地 files/docs/ 目录中
  • 文档索引存储在 files/index/document-index.json
  • GitHub 缓存存储在 files/docs/github_cache.json 中，并基于 SHA 检测变更
  • 使用 npm run build:index:force 强制重建整个索引

使用 npx

首次设置

1. 构建文档索引：

npx @bucketeer/docs-local-mcp-server build-index

2. 按照下一节所示，在 MCP 配置中使用。

更新索引

若要更新文档索引（例如，有新文档可用时）：

npx @bucketeer/docs-local-mcp-server build-index --force

Cursor 和 Claude Desktop 配置

参考 Cursor（https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers）和 Claude Desktop（https://modelcontextprotocol.io/quickstart/user）的文档，将以下内容添加到 mcp.json 或 claude_desktop_config.json 文件中，以配置 MCP 服务：

使用 Cursor Deeplink 快速安装

Cursor 用户可以使用下方的 deeplink，一键安装 MCP 服务：

这会自动在 Cursor 设置中配置 MCP 服务。点击链接后，Cursor 会提示你安装该服务。

选项 1：使用 npx（推荐）

{
  "mcpServers": {
    "bucketeer-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["@bucketeer/docs-local-mcp-server"]
    }
  }
}

选项 2：使用本地安装

{
  "mcpServers": {
    "bucketeer-docs": {
      "type": "stdio",
      "command": "npm",
      "args": ["start", "--prefix", "/path/to/bucketeer-docs-local-mcp-server"]
    }
  }
}

用法

MCP 服务运行后，可使用以下工具：

1. search_docs - 搜索 Bucketeer 文档

• 参数：query（string）- 搜索查询
• 参数：limit（number，可选）- 要返回的最大结果数（默认值：5）

示例：

{
  "name": "search_docs",
  "arguments": {
    "query": "feature flags SDK integration",
    "limit": 5
  }
}

响应：返回搜索结果数组，包含标题、URL、路径、描述、摘录和相关性评分。

2. get_document - 获取特定文档内容

• 参数：path（string）- 从搜索结果中获取的文档路径

示例：

{
  "name": "get_document",
  "arguments": {
    "path": "getting-started/create-feature-flag"
  }
}

响应：返回完整文档内容，包括标题、描述、URL 和完整的 Markdown 内容。

开发命令

• npm run build - 将 TypeScript 文件编译到 dist/ 目录
• npm run build:index - 从 GitHub 仓库构建/更新文档索引
• npm run build:index:force - 强制重建整个索引（忽略缓存）
• npx @bucketeer/docs-local-mcp-server build-index - 使用 npx 构建索引
• npx @bucketeer/docs-local-mcp-server build-index --force - 使用 npx 强制重建索引
• npm run dev:index - 在开发模式下构建并更新索引
• npm run dev - 在开发模式下构建并启动服务
• npm run lint - 运行 Biome 代码检查
• npm run lint:fix - 运行 Biome 代码检查并修复检查错误

配置

服务通过 src/config/index.ts 配置：

• siteName: "Bucketeer"
• websiteUrl: "https://docs.bucketeer.io"
• githubRepo: "https://github.com/bucketeer-io/bucketeer-docs"
• docsDirectory: "docs"（GitHub 仓库中包含文档的目录）
• searchLimitDefault: 5（默认搜索结果数量）
• useGithubSource: true（始终使用 GitHub 作为来源）

文件结构

files/
├── docs/           # Cached JSON files from GitHub repository
├── index/          # Document search index
│   └── document-index.json
└── [created automatically when building index]

架构

该服务由几个关键组件组成：

1. GithubDocumentFetcher：从 GitHub 仓库递归获取 .mdx 文件
2. IndexManager：构建和管理可搜索的文档索引
3. SearchService：提供关键字匹配和全文搜索功能
4. MCP Server：通过 Model Context Protocol 提供工具

许可证

Apache License 2.0，详见 LICENSE。

贡献

我们 ❤️ 欢迎你为 Bucketeer 做出贡献并帮助改进它！任何人都可以使用并享受它！

请参阅我们的贡献指南此处。