Docsearch Mcp

docsearch-mcp

一套本地优先的文档搜索与索引系统，可通过模型上下文协议（MCP）对本地文件（包括 PDF）和 Confluence 页面进行语义与关键词混合搜索。非常适合 Claude Code/Desktop 等 AI 助手访问你的文档、代码库和研究资料。

✨ 功能

• 🔍 混合搜索：结合全文搜索（FTS）与向量相似度，获得最佳结果
• 📁 多来源：为本地文件（代码、文档、PDF、办公文档、电子书、音频/视频）和 Confluence 空间建立索引
• 📄 PDF 支持：提取并搜索 PDF 文档中的文本，同时保留元数据
• 📝 办公文档：提取并搜索 DOCX、XLSX、PPTX 文件中的文本，也可通过 OnlyOffice 转换旧版 DOC、XLS、PPT 文件
• 📚 EPUB 支持：对电子书文件进行按章节解析和索引
• 🎵 音频/视频：提取媒体元数据，并可选用 Whisper API 转录
• 🖼️ 图像搜索：借助 AI 描述和搜索图表、屏幕截图及图形
• 🗄️ 数据库灵活性：支持 SQLite（本地优先）、PostgreSQL（可扩展）和 VectorChord（高性能向量搜索）
• 🤖 MCP 集成：与 Claude Code 及其他兼容 MCP 的工具无缝集成
• 💻 CLI 工具：独立的命令行界面，支持多种输出格式
• ⚡ 实时更新：监视文件并自动重新建立索引
• 🎯 智能分块：针对代码、文档、PDF、电子书和音频转录文本进行智能文本分块
• 📊 多种输出格式：支持文本、JSON 和 YAML 输出，并提供特定于格式的元数据
• 🔒 安全：API 密钥和敏感数据保留在你的设备上

🚀 安装与使用

npm 包

# Install globally
npm install -g docsearch-mcp

# Or use with npx
npx docsearch-mcp --help

Docker 容器

# Pull the image
docker pull ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

# Run the MCP server with proper permissions
docker run --rm -i \
  -v /path/to/your/documents:/app/documents \
  -v /path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

MCP 服务用法

添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "docsearch": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"]
    }
  }
}

本地开发环境设置（可选）

用于开发或自定义：

# Clone the repository
git clone https://github.com/patrickkoss/docsearch-mcp.git
cd docsearch-mcp

# Quick setup with Make
make setup

# Or manual setup
pnpm install
cp .env.example .env
# Edit .env with your API keys and configuration

基本用法

CLI 工具

# Ingest documents
docsearch-mcp ingest files              # Index local files
docsearch-mcp ingest confluence         # Index Confluence pages
docsearch-mcp ingest all --watch        # Index all sources with file watching

# Search documents
docsearch-mcp search "your query"       # Basic search
docsearch-mcp search "typescript" -k 5 -o json  # JSON output, top 5 results
docsearch-mcp search "API docs" -s confluence   # Search only Confluence

# Get help
docsearch-mcp --help
docsearch-mcp search --help

MCP 服务

# Run the MCP server directly
npx docsearch-mcp start

# Or if installed globally
docsearch-mcp start

Docker 用法

# Run with official Docker image (recommended)
docker run --rm -i \
  -v /path/to/your/documents:/app/documents \
  -v /path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

# Run CLI commands with Docker
docker run --rm -i \
  -v /path/to/your/documents:/app/documents \
  -v /path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2 \
  npx docsearch-mcp search "your query"

# Alternative: Use Docker volumes (simpler but less control)
docker run --rm \
  -v ./documents:/app/documents \
  -v docsearch-data:/app/data \
  --env-file .env \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

# For development (requires cloning repo)
docker-compose up -d docsearch-mcp

⚙️ 配置

Docker 配置

使用官方 Docker 镜像时，请创建 .env 文件：

echo "OPENAI_API_KEY=your-openai-key" > .env
echo "FILE_ROOTS=/app/documents" >> .env

Docker 部署的注意事项：

• 文档卷：将文档目录挂载到容器中的 /app/documents
• 数据持久化：将数据目录挂载到 /app/data，以持久化 SQLite 数据库
• 用户权限：使用 --user $(id -u):$(id -g)，避免挂载卷的权限问题
• 环境变量：通过 .env 文件或环境变量传递配置
• 官方镜像：生产部署请使用 ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

使用官方 Docker 镜像

推荐方式：正确设置权限：

# Basic usage with user permissions (avoids file ownership issues)
docker run --rm -i \
  -v /absolute/path/to/documents:/app/documents \
  -v /absolute/path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.5

# For MCP server integration (background service)
docker run -d --name docsearch-mcp \
  -v /absolute/path/to/documents:/app/documents \
  -v /absolute/path/to/data:/app/data \
  --env-file .env \
  --user $(id -u):$(id -g) \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.5

替代方式：使用 Docker 卷：

# Using Docker volumes (simpler but less direct file access)
docker run --rm \
  -v ./documents:/app/documents \
  -v docsearch-data:/app/data \
  --env-file .env \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.2

Docker 权限说明：

• --user $(id -u):$(id -g)：以你的用户 ID 和组 ID 运行容器，避免文件权限问题
• 动态创建用户：容器会自动创建与挂载卷权限匹配的用户
• 自动设置文件所有权：容器文件会自动归属于正确的用户
• 跨平台兼容性：在不同的主机系统上都能保持一致的运行方式

本地开发配置

从 .env.example 创建 .env 文件并进行配置：

嵌入（必需）

EMBEDDINGS_PROVIDER=openai
OPENAI_API_KEY=your_openai_key
OPENAI_EMBED_MODEL=text-embedding-3-small

文件索引

FILE_ROOTS=.
FILE_INCLUDE_GLOBS=**/*.{ts,js,py,md,txt,pdf,png,jpg,jpeg,gif,svg,webp}
FILE_EXCLUDE_GLOBS=**/node_modules/**,**/dist/**

图像搜索（可选）

ENABLE_IMAGE_TO_TEXT=true
IMAGE_TO_TEXT_PROVIDER=openai
IMAGE_TO_TEXT_MODEL=gpt-4o-mini

数据库配置

# Use SQLite (default, local-first)
DB_TYPE=sqlite
DB_PATH=./data/index.db

# OR use PostgreSQL with pgvector (for scalability)
DB_TYPE=postgresql
POSTGRES_CONNECTION_STRING=postgresql://user:password@localhost:5432/docsearch

# OR use PostgreSQL with VectorChord (high-performance vector search)
DB_TYPE=vectorchord
POSTGRES_CONNECTION_STRING=postgresql://user:password@localhost:5432/docsearch
# Optional VectorChord tuning (shown with defaults)
VECTORCHORD_RESIDUAL_QUANTIZATION=true
VECTORCHORD_LISTS=100
VECTORCHORD_SPHERICAL_CENTROIDS=true
VECTORCHORD_BUILD_THREADS=4
VECTORCHORD_PROBES=10

VectorChord 是 PostgreSQL 扩展，与 pgvector 的 IVFFlat 相比，它使用 RaBitQ 压缩和分层 K-means，实现更快的索引速度和更低的存储成本。它完全兼容 pgvector，并要求在 PostgreSQL 实例中安装 vchord 扩展（或使用 tensorchord/vchord-suite Docker 镜像）。

Confluence（可选）

CONFLUENCE_BASE_URL=https://yourcompany.atlassian.net
[email protected]
CONFLUENCE_API_TOKEN=your_confluence_token
CONFLUENCE_SPACES=SPACE1,SPACE2

# Advanced filtering (all optional)
# Filter by parent page IDs - only index pages under these parent pages
CONFLUENCE_PARENT_PAGES=12345678,87654321

# Title patterns to include (supports * wildcards)
CONFLUENCE_TITLE_INCLUDES=API*,User Guide,*Documentation*

# Title patterns to exclude (supports * wildcards)
CONFLUENCE_TITLE_EXCLUDES=Draft*,*Archive*,Test*

Confluence 筛选选项：

• 父页面筛选：指定页面 ID，仅索引特定文件夹层级中的页面
• 标题包含模式：定义模式，仅索引标题匹配的页面
• 标题排除模式：定义模式，跳过标题匹配的页面
• 通配符支持：使用 * 进行灵活的模式匹配（例如，API* 匹配所有以“API”开头的标题）

支持的文件类型

系统会自动检测并处理不同的文件类型：

• 代码文件：.ts、.js、.py、.go、.rs、.java、.cpp、.c、.rb、.php、.kt、.swift
• 文档：.md、.mdx、.txt、.rst、.adoc、.yaml、.yml、.json
• PDF：.pdf 文件会自动解析，并提取文本和保留元数据
• Office 文档：.docx、.xlsx、.pptx 文件支持文本提取和特定格式的元数据；.doc、.xls、.ppt 文件通过 OnlyOffice 转换
• 电子书：.epub 文件支持按章节解析和元数据提取
• 音频：.mp3、.wav、.flac、.ogg、.m4a、.aac 文件支持元数据提取和可选的转录
• 视频：.mp4、.webm、.mkv、.avi、.mov 文件支持元数据提取和可选的转录
• 图像：.png、.jpg、.jpeg、.gif、.svg、.webp 文件支持可选的 AI 驱动描述生成

PDF 文件的处理方式：

• 使用高级解析进行文本提取
• 保留元数据（页数、文档信息）
• 智能文本规范化和分块
• 处理损坏或加密文件时进行错误处理

Office 文档的处理方式：

• DOCX：通过 mammoth 提取文本和段落，同时保留文档结构
• XLSX：从所有工作表中提取单元格文本（最多 100 个工作表，每个工作表最多 10,000 行），并添加工作表名称前缀
• PPTX：提取幻灯片文本，并添加幻灯片编号前缀
• 旧版格式（DOC、XLS、PPT）：通过 OnlyOffice Conversion API 转换为现代格式，然后使用上述解析器处理

OnlyOffice 设置（用于支持旧版 DOC/XLS/PPT）

旧版 Office 格式需要运行中的 OnlyOffice Document Server：

docker run -d --name onlyoffice -p 8080:80 onlyoffice/documentserver

然后在 .env 中配置：

ONLYOFFICE_URL=http://localhost:8080
# ONLYOFFICE_JWT_SECRET=your-secret    # if JWT auth is enabled on your server
# ONLYOFFICE_TIMEOUT=30000             # conversion timeout in ms (default: 30000)

未设置 ONLYOFFICE_URL 时，摄取过程中会静默跳过旧版 Office 文件。

Docling 设置（基于机器学习的文档解析与 OCR）

如需使用 OCR、布局分析和表格提取来实现更出色的 PDF 解析，可以使用 Docling 作为文档解析器：

# Run docling-serve as a Docker container
docker run -d --name docling -p 5001:5001 quay.io/docling-project/docling-serve

# For CPU-only (smaller image):
docker run -d --name docling -p 5001:5001 quay.io/docling-project/docling-serve-cpu

然后在 .env 中配置：

DOCUMENT_PARSER=docling
DOCLING_URL=http://localhost:5001

Docling 支持：PDF、DOCX、PPTX、XLSX、HTML、图像（PNG、JPG、TIFF）和 EPUB。无论此设置如何，音频、视频和代码文件始终使用内置解析器。

如果未设置 DOCUMENT_PARSER 或将其设为 builtin，则会使用现有的轻量级解析器（pdf-parse、mammoth 等）。

EPUB 文件的处理方式如下：

• 逐章提取 HTML 内容并转换为文本
• 按章节分块（分块不会跨越章节边界）
• 提取元数据（标题、作者、语言、章节数）

音频/视频文件的处理方式如下：

• 元数据提取：通过 music-metadata 提取时长、比特率、采样率、编解码器、艺术家、专辑、标题和流派
• 可选转录：通过 OpenAI Whisper API（或兼容的端点）进行语音转文本，使用 ENABLE_AUDIO_TRANSCRIPTION=true 启用
• 保留时间戳：转录文本分块包含时间范围，便于在原始文件中定位内容
• 文件大小限制：超过 25MB 的文件仅使用元数据进行索引（Whisper API 的限制）
• 配置：WHISPER_API_KEY（默认为 OPENAI_API_KEY）、WHISPER_BASE_URL、WHISPER_MODEL（默认为 whisper-1）

图像文件支持可选的 AI 图像描述生成：

• 视觉模型集成：使用 OpenAI 视觉模型（或兼容的 API）生成详细描述
• 可配置处理：通过 ENABLE_IMAGE_TO_TEXT 环境变量启用或禁用图像转文本
• 回退支持：禁用视觉处理时，按文件名为图像建立索引
• 保留元数据：存储图像尺寸、文件大小和描述元数据
• 搜索集成：将图像描述作为可搜索的文本内容建立索引

📖 使用方法

CLI 工具

CLI 工具提供了一种便捷的方式，可直接通过命令行摄取和搜索文档：

CLI 命令和标志

所有 CLI 标志均支持以下配置优先级：CLI 参数 > 环境变量 > 配置文件

全局选项（适用于所有命令）

标志	环境变量	默认值	描述
-c, --config <file>	-	.env	配置文件路径
--embeddings-provider <provider>	EMBEDDINGS_PROVIDER	openai	嵌入提供商（openai 或 tei）
--openai-api-key <key>	OPENAI_API_KEY	-	OpenAI API 密钥
--openai-base-url <url>	OPENAI_BASE_URL	-	OpenAI 基础 URL（用于自定义端点）
--openai-embed-model <model>	OPENAI_EMBED_MODEL	text-embedding-3-small	OpenAI 嵌入模型
--openai-embed-dim <dimension>	OPENAI_EMBED_DIM	1536	OpenAI 嵌入维度
--tei-endpoint <url>	TEI_ENDPOINT	-	Text Embeddings Inference 端点
--enable-image-to-text	ENABLE_IMAGE_TO_TEXT	false	启用图像转文本处理
--image-to-text-provider <provider>	IMAGE_TO_TEXT_PROVIDER	openai	图像转文本提供商
--image-to-text-model <model>	IMAGE_TO_TEXT_MODEL	gpt-4o-mini	图像转文本模型
--confluence-base-url <url>	CONFLUENCE_BASE_URL	-	Confluence 基础 URL
--confluence-email <email>	CONFLUENCE_EMAIL	-	Confluence 电子邮箱
--confluence-api-token <token>	CONFLUENCE_API_TOKEN	-	Confluence API 令牌
--confluence-spaces <spaces>	CONFLUENCE_SPACES	-	Confluence 空间（以逗号分隔）
--file-roots <roots>	FILE_ROOTS	.	要编入索引的文件根目录（以逗号分隔）
--file-include-globs <globs>	FILE_INCLUDE_GLOBS	**/*.{go,ts,tsx,js,py,rs,java,md,mdx,txt,yaml,yml,json,pdf}	文件包含模式
--file-exclude-globs <globs>	FILE_EXCLUDE_GLOBS	**/{.git,node_modules,dist,build,target}/**	文件排除模式
--db-type <type>	DB_TYPE	sqlite	数据库类型（sqlite、postgresql 或 vectorchord）
--db-path <path>	DB_PATH	./data/index.db	SQLite 数据库路径
--postgres-connection-string <string>	POSTGRES_CONNECTION_STRING	-	PostgreSQL 连接字符串

Ingest 命令

docsearch ingest [source] [options]

参数：

• source - 要摄取的来源：files、confluence 或 all（默认：all）

选项：

• -w, --watch - 监视文件更改并重新索引

示例：

# Basic ingestion with environment config
docsearch ingest files
docsearch ingest confluence
docsearch ingest all --watch

# Override config with CLI args
docsearch ingest files --file-roots "./src,./docs" --openai-api-key sk-xxx

# Use custom config file and database
docsearch --config prod.env --db-path /data/prod.db ingest all

# Ingest with custom file patterns
docsearch ingest files \
  --file-include-globs "**/*.{ts,md,py}" \
  --file-exclude-globs "**/node_modules/**,**/venv/**"

# Use PostgreSQL instead of SQLite
docsearch ingest all \
  --db-type postgresql \
  --postgres-connection-string "postgresql://user:pass@localhost:5432/docs"

Search 命令

docsearch search <query> [options]

参数：

• query - 搜索查询（必填）

选项：

标志	默认值	说明
-k, --top-k <number>	10	返回的结果数量（1-100）
-s, --source <source>	-	按来源筛选：file 或 confluence
-r, --repo <repo>	-	按仓库名称筛选
-p, --path-prefix <prefix>	-	按路径前缀筛选
-m, --mode <mode>	auto	搜索模式：auto、vector 或 keyword
-o, --output <format>	text	输出格式：text、json 或 yaml
--include-images	-	在搜索结果中包含图片
--images-only	-	仅搜索图片

示例：

# Basic search
docsearch search "typescript interface"

# Limit results and format as JSON
docsearch search "API documentation" --top-k 5 --output json

# Search only Confluence with repository filter
docsearch search "deployment guide" --source confluence --repo backend-docs

# Semantic search only with path filtering
docsearch search "authentication" --mode vector --path-prefix src/auth/

# Override database and output as YAML
docsearch --db-path /custom/index.db search "error handling" --output yaml

# Complex search with multiple filters
docsearch search "React hooks" \
  --source file \
  --repo frontend \
  --path-prefix src/components/ \
  --mode auto \
  --top-k 20 \
  --output json

# Search including images (architecture diagrams, screenshots)
docsearch search "user authentication flow" --include-images

# Search only images for diagrams and charts
docsearch search "system architecture" --images-only --output json

CLI 配置

CLI 支持多个配置来源，并按优先级顺序读取：

1. 命令行参数（优先级最高）
2. 自定义配置文件（--config path/to/.env）
3. .env.local 文件
4. .env 文件（优先级最低）

CLI 输出格式

• Text（默认）：提供带图标和格式的易读输出
• JSON：包含时间戳的结构化数据，便于集成
• YAML：清晰的分层格式，适用于配置或文档

MCP 集成

MCP（Model Context Protocol）服务可与 Claude Code 及其他兼容 MCP 的工具无缝集成。

MCP 配置选项

所有配置选项均通过环境变量传递给 MCP 服务：

必需配置

环境变量	默认值	说明
EMBEDDINGS_PROVIDER	openai	嵌入提供方（openai 或 tei）
OPENAI_API_KEY	-	OpenAI API 密钥（使用 OpenAI 时必填）

可选配置

环境变量	默认值	描述
OPENAI_BASE_URL	-	OpenAI 基础 URL（用于自定义端点）
OPENAI_EMBED_MODEL	text-embedding-3-small	OpenAI 嵌入模型
OPENAI_EMBED_DIM	1536	OpenAI 嵌入维度
TEI_ENDPOINT	-	Text Embeddings Inference 端点
FILE_ROOTS	.	要建立索引的文件根目录（以逗号分隔）
FILE_INCLUDE_GLOBS	**/*.{go,ts,tsx,js,py,rs,java,md,mdx,txt,yaml,yml,json,pdf}	文件包含模式
FILE_EXCLUDE_GLOBS	**/{.git,node_modules,dist,build,target}/**	文件排除模式
CONFLUENCE_BASE_URL	-	Confluence 基础 URL
CONFLUENCE_EMAIL	-	Confluence 邮箱
CONFLUENCE_API_TOKEN	-	Confluence API 令牌
CONFLUENCE_SPACES	-	Confluence 空间（以逗号分隔）
DB_TYPE	sqlite	数据库类型（sqlite、postgresql 或 vectorchord）
DB_PATH	./data/index.db	SQLite 数据库路径
POSTGRES_CONNECTION_STRING	-	PostgreSQL 连接字符串

快速设置

1. 安装软件包：

   npm install -g docsearch-mcp
   

2. 创建配置：

   # Create a .env file in your project directory
   echo "OPENAI_API_KEY=your-openai-key" > .env
   echo "FILE_ROOTS=." >> .env
   

3. 添加到 Claude Code MCP 设置：

   {
     "mcpServers": {
       "docsearch": {
         "command": "npx",
         "args": ["docsearch-mcp", "start"],
         "env": {
           "OPENAI_API_KEY": "your-openai-key",
           "EMBEDDINGS_PROVIDER": "openai",
           "FILE_ROOTS": ".,../other-project",
           "DB_PATH": "/path/to/your/index.db"
         }
       }
     }
   }
   

Docker 集成

方法 1：直接运行 Docker

{
  "mcpServers": {
    "docsearch": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/your/documents:/app/documents",
        "-v",
        "docsearch-data:/app/data",
        "--env-file",
        ".env",
        "ghcr.io/patrickkoss/docsearch-mcp:v0.0.2"
      ]
    }
  }
}

方法 2：使用 Docker Compose

创建一个 docker-compose.yml 文件：

version: '3.8'
services:
  docsearch-mcp:
    image: ghcr.io/patrickkoss/docsearch-mcp:v0.0.5
    volumes:
      - ./documents:/app/documents
      - docsearch-data:/app/data
    env_file:
      - .env
    stdin_open: true
volumes:
  docsearch-data:

然后配置 MCP：

{
  "mcpServers": {
    "docsearch": {
      "command": "docker",
      "args": ["exec", "-i", "docsearch-mcp", "node", "dist/src/server/mcp.js"]
    }
  }
}

高级 MCP 配置示例

多项目设置

{
  "mcpServers": {
    "docsearch-work": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "FILE_ROOTS": "/work/projects/frontend,/work/projects/backend",
        "FILE_INCLUDE_GLOBS": "**/*.{ts,tsx,js,py,md,yaml}",
        "DB_PATH": "/work/data/work-index.db",
        "CONFLUENCE_BASE_URL": "https://company.atlassian.net",
        "CONFLUENCE_SPACES": "DEV,API,DOCS"
      }
    },
    "docsearch-personal": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "FILE_ROOTS": "/home/user/projects,/home/user/documents",
        "DB_PATH": "/home/user/.docsearch/personal.db",
        "EMBEDDINGS_PROVIDER": "tei",
        "TEI_ENDPOINT": "http://localhost:8080/embeddings"
      }
    }
  }
}

PostgreSQL 设置

{
  "mcpServers": {
    "docsearch": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "DB_TYPE": "postgresql",
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/docsearch",
        "FILE_ROOTS": ".,/other/projects"
      }
    }
  }
}

VectorChord 设置（高性能）

{
  "mcpServers": {
    "docsearch": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "DB_TYPE": "vectorchord",
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/docsearch",
        "FILE_ROOTS": ".,/other/projects",
        "VECTORCHORD_PROBES": "20"
      }
    }
  }
}

MCP 工具

MCP 服务为 Claude Code 提供以下工具：

doc-search

搜索已建立索引的文档，并可选择输出格式。

参数：

• query（字符串，必填）：搜索查询
• topK（数字，可选）：返回结果数量（默认值：10，最大值：100）
• source（字符串，可选）：按来源筛选（file 或 confluence）
• repo（字符串，可选）：按仓库名称筛选
• pathPrefix（字符串，可选）：按路径前缀筛选
• mode（字符串，可选）：搜索模式（auto、vector、keyword，默认值：auto）
• outputFormat（字符串，可选）：输出格式（text、json、yaml，默认值：text）
• includeImages（布尔值，可选）：在搜索结果中包含图片
• imagesOnly（布尔值，可选）：仅搜索图片

示例：

Use the doc-search tool to find "TypeScript interfaces" with JSON output format, limited to 5 results from file sources only.

doc-ingest

从文件或 Confluence 导入文档。

参数：

• source（字符串，必填）：要导入的来源（files、confluence 或 all）
• watch（布尔值，可选）：监视文件更改并重新索引（默认值：false）

示例：

Use the doc-ingest tool to index all local files and Confluence pages.

doc-ingest-status

获取索引统计信息和状态。

无需参数。

示例：

Use the doc-ingest-status tool to check how many documents are currently indexed.

MCP 资源

该服务还通过 URI 提供分块资源：

• docchunk://{chunk_id}：按 ID 检索特定文档分块的完整内容

📚 实用示例

完整设置工作流

快速设置工作流

# 1. Install globally
npm install -g docsearch-mcp

# 2. Configure with your API key
echo "OPENAI_API_KEY=sk-your-key-here" > .env
echo "FILE_ROOTS=.,../other-project" >> .env

# 3. Index your documents
docsearch-mcp ingest all --watch &

# 4. Test search
docsearch-mcp search "how to deploy" --output json --top-k 3

# 5. Test MCP server
npx docsearch-mcp start

Docker 生产环境工作流

# 1. Setup production environment
echo "OPENAI_API_KEY=sk-your-key" > .env
echo "FILE_ROOTS=/app/documents" >> .env
# Add other configuration as needed

# 2. Create documents directory
mkdir -p documents
cp -r /path/to/your/docs/* documents/

# 3. Run the official Docker image
docker run -d \
  --name docsearch-mcp \
  -v $(pwd)/documents:/app/documents \
  -v docsearch-data:/app/data \
  --env-file .env \
  ghcr.io/patrickkoss/docsearch-mcp:v0.0.5

# 4. Index documents
docker exec docsearch-mcp npx docsearch-mcp ingest all

# 5. Test search
docker exec docsearch-mcp npx docsearch-mcp search "authentication" -o json

常见用例

代码文档搜索

TypeScript/React 项目的设置：

# CLI configuration
docsearch-mcp ingest files \
  --file-roots "./src,./docs,./README.md" \
  --file-include-globs "**/*.{ts,tsx,md,yaml,json}" \
  --file-exclude-globs "**/node_modules/**,**/dist/**,**/.git/**"

# Search for React patterns
docsearch-mcp search "useEffect hook patterns" --source file --top-k 10
docsearch-mcp search "TypeScript interface" --mode vector --output json

MCP 配置：

{
  "mcpServers": {
    "project-docs": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "FILE_ROOTS": "./src,./docs,./README.md",
        "FILE_INCLUDE_GLOBS": "**/*.{ts,tsx,md,yaml,json}",
        "FILE_EXCLUDE_GLOBS": "**/node_modules/**,**/dist/**",
        "DB_PATH": "./project-search.db"
      }
    }
  }
}

多代码仓库设置

团队文档中心：

{
  "mcpServers": {
    "team-knowledge": {
      "command": "npx",
      "args": ["docsearch-mcp", "start"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "FILE_ROOTS": "/team/frontend,/team/backend,/team/mobile,/team/docs",
        "CONFLUENCE_BASE_URL": "https://company.atlassian.net",
        "CONFLUENCE_SPACES": "TEAM,API,ARCH,DEPLOY",
        "CONFLUENCE_EMAIL": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your-token",
        "DB_TYPE": "postgresql",
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost/team_docs"
      }
    }
  }
}

个人研究设置：

# Index academic papers and personal notes
docsearch-mcp ingest files \
  --file-roots "/home/user/papers,/home/user/notes,/home/user/projects" \
  --file-include-globs "**/*.{pdf,md,txt,py,ipynb}" \
  --embeddings-provider tei \
  --tei-endpoint "http://localhost:8080/embeddings"

# Search across all personal knowledge
docsearch-mcp search "machine learning optimization" --mode auto --top-k 15

# Search for diagrams and technical images
docsearch-mcp search "neural network architecture" --include-images --top-k 10
docsearch-mcp search "flowchart" --images-only --output json

PDF 密集型工作流

# Setup for research document collection
docsearch-mcp ingest files \
  --file-roots "/research/papers,/research/reports" \
  --file-include-globs "**/*.{pdf,docx,md,txt}" \
  --openai-embed-model "text-embedding-3-large" \
  --openai-embed-dim 3072

# Search through research papers
docsearch-mcp search "neural network architectures" \
  --mode vector \
  --top-k 20 \
  --output yaml

高级搜索示例

复杂筛选

# Search only TypeScript files in components directory
docsearch-mcp search "button component" \
  --source file \
  --path-prefix src/components/ \
  --mode auto

# Find Confluence deployment docs from specific space
docsearch-mcp search "kubernetes deployment" \
  --source confluence \
  --repo DEVOPS \
  --mode keyword

# Semantic search across all sources with high precision
docsearch-mcp search "error handling patterns" \
  --mode vector \
  --top-k 50 \
  --output json | jq '.results[] | select(.score > 0.8)'

# Search for architecture diagrams and flowcharts
docsearch-mcp search "system design diagram" \
  --images-only \
  --mode vector \
  --output json

# Include images when searching for UI/UX content
docsearch-mcp search "user interface design" \
  --include-images \
  --path-prefix docs/ \
  --top-k 20

输出格式示例

文本输出（便于阅读）：

docsearch-mcp search "authentication middleware" --output text

JSON 输出（用于脚本）：

# Get results for further processing
RESULTS=$(docsearch-mcp search "API rate limiting" --output json)
echo "$RESULTS" | jq '.results[].path' | head -5

YAML 输出（用于文档）：

# Generate documentation from search results
docsearch-mcp search "configuration options" --output yaml > config-docs.yml

故障排除示例

调试搜索质量

# Compare search modes
docsearch-mcp search "async function" --mode keyword --top-k 5
docsearch-mcp search "async function" --mode vector --top-k 5
docsearch-mcp search "async function" --mode auto --top-k 5

# Check what's indexed
docsearch-mcp ingest-status

性能优化

# Use smaller embedding model for speed
docsearch-mcp ingest all \
  --openai-embed-model "text-embedding-3-small" \
  --openai-embed-dim 1536

# Use local TEI for privacy/speed
docker run -d --name tei -p 8080:80 \
  ghcr.io/huggingface/text-embeddings-inference:cpu-1.2 \
  --model-id sentence-transformers/all-MiniLM-L6-v2

docsearch-mcp ingest all \
  --embeddings-provider tei \
  --tei-endpoint http://localhost:8080/embeddings

集成示例

CI/CD 工作流集成

# .github/workflows/docs-index.yml
name: Update Documentation Index
on:
  push:
    paths: ['docs/**', 'src/**/*.md', 'README.md']

jobs:
  update-index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - name: Install dependencies
        run: npm install -g pnpm && pnpm install
      - name: Build docsearch
        run: pnpm build
      - name: Update search index
        run: |
          pnpm start:cli ingest files \
            --file-roots "." \
            --openai-api-key "${{ secrets.OPENAI_API_KEY }}" \
            --db-path "./search-index.db"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

脚本集成

#!/bin/bash
# update-docs.sh - Automated documentation indexing

# Check if API key is set
if [ -z "$OPENAI_API_KEY" ]; then
    echo "Please set OPENAI_API_KEY environment variable"
    exit 1
fi

# Index all project documentation
echo "Indexing project documentation..."
docsearch-mcp ingest files \
    --file-roots "./src,./docs,./examples" \
    --file-include-globs "**/*.{ts,js,md,yaml,json}" \
    --db-path "./project-index.db"

# Generate search summary
echo "Search index updated. Statistics:"
docsearch-mcp ingest-status --output json | jq '.documents'

搜索模式

• Auto（默认）：混合关键字搜索与语义搜索
• Keyword：仅全文搜索
• Vector：仅语义搜索

Make 命令

运行 make help 查看所有可用命令：

# Development Commands
make install                    # Install dependencies
make dev                        # Start development server for MCP
make dev-ingest                 # Start development ingestion
make setup                      # Setup project for development

# Build Commands
make build                      # Build the project
make clean                      # Clean all generated files

# Quality Assurance
make lint                       # Run linter
make lint-fix                   # Run linter with auto-fix
make format                     # Format code with Prettier
make typecheck                  # Run TypeScript type checking
make test                       # Run tests
make test-run                   # Run tests once
make test-unit                  # Run unit tests only
make test-integration           # Run integration tests (requires Docker)
make check-all                  # Run all quality checks

# Production Commands
make start                      # Start production MCP server
make start-ingest               # Start production ingestion

# Data Management
make ingest-files               # Ingest local files
make ingest-confluence          # Ingest Confluence pages
make watch                      # Watch for file changes and re-index
make clean-data                 # Clean data directory

NPM 脚本（替代方案）

# CLI Tool
pnpm dev:cli                    # CLI development mode
pnpm start:cli                  # CLI production mode (after build)

# Ingestion (legacy scripts)
pnpm dev:ingest files           # Index local files
pnpm dev:ingest confluence      # Index Confluence pages
pnpm dev:ingest watch           # Watch for file changes

# MCP Server
pnpm dev:mcp                    # Development server
pnpm start:mcp                  # Production server

# Quality
pnpm lint                       # Run linter
pnpm test                       # Run tests
pnpm test:unit                  # Run unit tests only
pnpm test:integration           # Run integration tests (requires Docker)
pnpm build                      # Build project

🏗️ 架构

系统采用清晰的端口与适配器（六边形）架构：

┌─────────────────┐    ┌─────────────────┐
│   Local Files   │    │   Confluence    │
└─────────┬───────┘    └─────────┬───────┘
          │                      │
          ▼                      ▼
    ┌─────────────────────────────────┐
    │        Ingestion Engine         │
    │   • Content extraction         │
    │   • Smart chunking             │
    │   • Embedding generation       │
    └─────────────┬───────────────────┘
                  │
                  ▼
    ┌─────────────────────────────────┐
    │      Database Layer             │
    │   SQLite (sqlite-vec) OR        │
    │   PostgreSQL (pgvector) OR      │
    │   PostgreSQL (VectorChord)      │
    │   • Document metadata          │
    │   • Text chunks                │
    │   • Vector embeddings          │
    │   • Full-text search index     │
    └─────────────┬───────────────────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
┌─────────────────┐  ┌─────────────────┐
│   CLI Tool      │  │   MCP Server    │
│ • Text output   │  │ • Tool calls    │
│ • JSON output   │  │ • Resources     │
│ • YAML output   │  │ • Claude integration │
│ • Config mgmt   │  │ • Ingestion tools     │
└─────────────────┘  └─────────────────┘

核心组件

• 领域层：核心接口和业务逻辑
• 适配器：配置、数据库和输出格式化
• CLI：支持多种输出格式的命令行界面
• MCP 服务：与 Claude Code 集成的 Model Context Protocol

🤝 参与贡献

欢迎贡献！欢迎提交 Pull Request。

开发工作流

1. Fork 项目

2. 创建功能分支（git checkout -b feature/AmazingFeature）

3. 设置开发环境：

   make setup
   

4. 进行修改并确保质量：

   make check-all          # Run linter, typecheck, and tests
   make format             # Format your code
   

5. 提交更改（git commit -m 'Add some AmazingFeature'）

6. 将更改推送到分支（git push origin feature/AmazingFeature）

7. 创建 Pull Request

🚀 部署（VM 上的 Postgres / VectorChord）

SQLite 是本地开发的默认选项，无需额外基础设施。准备在生产 VM 上运行 Postgres 或 VectorChord 时，请使用 deploy/ansible/ 中的 Ansible playbook。

它会处理：

• Docker 安装
• TLS（实验环境使用自签名证书，生产环境使用 Let's Encrypt）
• 可配置 CIDR 的 UFW 防火墙
• 通过 ansible-vault 管理凭据
• 每晚执行 pg_dump 备份，并可选择上传至 S3
• Molecule 测试，验证部署后数据库可访问

完整的运维指南请参阅 deploy/ansible/README.md。

📝 许可证

本项目采用 Apache License Version 2 许可，详情请参阅 LICENSE 文件。

🙏 致谢

• Model Context Protocol 提供集成标准
• sqlite-vec 提供向量搜索功能
• VectorChord 提供高性能 PostgreSQL 向量搜索
• Claude Code 带来 AI 驱动的开发体验