AI导哈

ClickHouse文档搜索服务

一个基于FastMCP和SQLite FTS5的ClickHouse文档全文搜索服务，支持BM25排序和MDX解析。

  • by martoc
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 martoc/mcp-clickhouse-documentation

使用说明

MCP ClickHouse文档服务器

模型上下文协议（MCP）服务器，使Claude能够搜索和阅读ClickHouse官方文档。采用FastMCP和SQLite FTS5构建，可实现BM25排名的高效全文搜索。

特性

  • 全文搜索 跨ClickHouse文档和知识库
  • MDX解析 -使用JSX组件处理Docusaurus MDX文件
  • BM25排名 -相关性排名搜索结果
  • 分段过滤 -在特定文档部分搜索
  • 多目录索引 -涵盖两者 docs/ 和 knowledgebase/
  • 快速MCP集成 -准备好使用克劳德桌面和克劳德代码

快速开始

安装

# Clone repository
git clone https://github.com/martoc/mcp-clickhouse-documentation.git
cd mcp-clickhouse-documentation

# Initialise development environment
make init

# Index ClickHouse documentation
make index

MCP配置

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "clickhouse-documentation": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-clickhouse-documentation",
        "run",
        "mcp-clickhouse-documentation"
      ]
    }
  }
}

Docker容器

运行带有索引文档的预构建容器：

# Pull the image
docker pull martoc/mcp-clickhouse-documentation:latest

# Run the server
docker run --rm -i martoc/mcp-clickhouse-documentation:latest

Docker的MCP配置：

{
  "mcpServers": {
    "clickhouse-documentation": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "martoc/mcp-clickhouse-documentation:latest"
      ]
    }
  }
}

可用标签：

  • latest -具有预索引文档的最新稳定版本
  • v0.3.0 -特定版本发布
  • main -主分支机构的最新提交

用法

配置后，Claude可以：

  1. 搜索文档：

    • “在ClickHouse文档中搜索SELECT语句”
    • “查找有关Kafka集成的信息”
    • “如何使用ARRAY函数？”

  2. 阅读完整文档：

    • “阅读完整的SELECT引用”
    • “给我看完整的Kafka集成指南”

工具

MCP服务器提供两个工具：

search_documentation

使用全文搜索搜索ClickHouse文档。

参数：

  • query （必填）：搜索查询
  • section （可选）：按部分筛选（例如，“sql引用”、“知识库集成”）
  • limit （可选）：最大结果（默认值：10）

退货：

  • title：文档标题
  • url：完整文档URL
  • path：相对文件路径
  • section：文件部分
  • snippet：突出显示匹配项的内容片段
  • relevance_score：BM25相关性得分

read_documentation

阅读文档页面的完整内容。

参数：

  • path （必填）：搜索结果中的文档路径

退货：

  • path：文档路径
  • title：文档标题
  • description：文档描述
  • section：文件部分
  • url：完整文档URL
  • content：完整的文档内容（清理过的MDX/Markdown）

建筑

mcp-clickhouse-documentation/
├── src/mcp_clickhouse_documentation/
│   ├── models.py          # Data models
│   ├── parser.py          # MDX/Markdown parser
│   ├── database.py        # SQLite FTS5 operations
│   ├── indexer.py         # Documentation indexer
│   ├── server.py          # FastMCP server
│   └── cli.py             # Command-line interface
├── tests/                 # Test suite
├── Makefile               # Build automation
└── pyproject.toml         # Project configuration

发展

先决条件

  • Python 3.12+
  • uv包管理器
  • Git

命令

# Initialise environment
make init

# Run tests
make test

# Run linting and type checking
make build

# Format code
make format

# Index documentation
make index

# View statistics
make stats

# Run MCP server
make run

# Clean artifacts
make clean

测试

# Run all tests with coverage
make test

# Run specific test file
uv run pytest tests/test_parser.py -v

# Run with coverage report
uv run pytest --cov=src/mcp_clickhouse_documentation --cov-report=html

技术细节

MDX解析

解析器通过以下方式处理Docusaurus MDX文件：

  1. 提取YAML前体（标题、描述）
  2. 删除JSX导入和导出
  3. 剥离JSX组件和表达式
  4. 清理HTML标签和注释
  5. 保留Markdown格式

数据库模式

带FTS5虚拟表的SQLite：

  • 主表： documents -存储完整的文档数据
  • FTS表： documents_fts -全文搜索索引
  • BM25排名： 标题（5.0）、描述（2.0）、内容（1.0）
  • 触发器： 表之间的自动同步

存储库索引

  • 稀疏结账： 只有克隆 docs/ 和 knowledgebase/ 目录
  • 浅层克隆： 用途 --depth 1 更快的克隆
  • 文件类型： 索引两者 .md 和 .mdx 文件
  • URL模式： 匹配ClickHouse文档的干净URL（无扩展名）

统计

索引后，查看统计信息：

make stats

输出示例：

ClickHouse Documentation Index Statistics
==================================================
Total documents: 856

Documents by section:
--------------------------------------------------
  sql-reference                   324 ( 37.9%)
  operations                      156 ( 18.2%)
  knowledgebase-integrations      128 ( 15.0%)
  engines                          98 ( 11.4%)
  interfaces                       87 ( 10.2%)
  development                      63 (  7.4%)
==================================================

Docker部署

塑造形象

Docker镜像包括一个预先索引的文档数据库，可供立即使用：

# Build multi-platform image
make docker-build

# Or manually
docker build -t martoc/mcp-clickhouse-documentation:latest .

多阶段构建过程：

  1. 建设者阶段 -安装依赖项、克隆文档和索引文档
  2. 运行阶段 -复制索引数据库并运行MCP服务器

发布到容器注册表

# Tag with version
docker tag martoc/mcp-clickhouse-documentation:latest \
  martoc/mcp-clickhouse-documentation:v0.3.0

# Push to Docker Hub
docker push martoc/mcp-clickhouse-documentation:latest
docker push martoc/mcp-clickhouse-documentation:v0.3.0

集装箱特征

  • ✅ 预索引数据库 -立即准备使用
  • ✅ 多架构 -支持AMD64和ARM64
  • ✅ 优化图层 -高效缓存和最小大小
  • ✅ 片段过滤 -无错误的干净索引
  • ✅ 快速启动 -包含数据库，无需索引

图像大小

  • 压缩的：~50-70 MB
  • 未压缩：~150-200MB
  • 包含：Python运行时、依赖关系和索引文档

故障排除

找不到数据库

# Re-index documentation
make index --force

搜索未返回任何结果

# Check database statistics
make stats

# Verify database exists
ls -lh ~/.cache/mcp-clickhouse-documentation/

分析器错误

检查日志中的特定文件解析错误：

# Run indexer with verbose logging
uv run clickhouse-docs-index index

贡献

  1. 克隆该仓库
  2. 创建要素分支
  3. 进行更改
  4. 运行测试： make build
  5. 提交拉取请求

许可证

MIT许可证-详见许可证文件。

另见

相关 MCP