Doc Indexer MCP

文档索引器mcp

用Rust编写的本地文档索引器MCP（模型上下文协议）服务器。使用Qdrant矢量数据库和Voyage AI嵌入对PDF、Excel、SQL/PL-SQL、Markdown和HTML文件进行语义搜索。专为与Claude Code CLI和其他MCP兼容工具集成而设计。

基于 Rust 编写的本地文档索引 MCP（模型上下文协议）服务器。使用 Qdrant 向量数据库和 Voyage AI 嵌入模型，支持对 PDF、Excel、SQL/PL-SQL、Markdown 和 HTML 文件进行语义搜索。专为 Claude Code CLI 及其他 MCP 兼容工具集成设计。

Rust 中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长MCP（Model Context Protocol）服务器。Qdrant 矢量数据库和Voyage AI 使用嵌入式PDF、Excel、SQL/PL-SQL、Markdown、HTML 实现文件语义检索。Claude Code CLI 或者其他MCP 设计与兼容工具集成。

特性

• PDF解析：用途 pdftotext （poppler）用于文本提取，完全支持Unicode
• Excel解析：本地Rust解析通过 calamine （.xlsx、.xls、.xlsm、.ods）
• SQL/PL-SQL解析：提取过程、函数、包和触发器
• Markdown解析：文档的节意识分块
• HTML解析：从web应用程序快照中提取UI文本
• 向量搜索：用于语义相似性搜索的Qdrant向量数据库
• 嵌入：Voyage AI或OpenAI兼容嵌入API
• MCP协议：使用完整的MCP服务器实现 rmcp 0.13
• 完全可配置：通过环境变量进行所有设置

先决条件

1. Rust 2024版 （锈蚀1.85+）
2. Qdrant 向量数据库
3. pdft文本 （来自poppler-utils）用于PDF解析
4. Voyage AI API密钥 （或OpenAI兼容端点）

安装依赖项

# macOS
brew install poppler

# Download Qdrant (macOS ARM64)
curl -LO https://github.com/qdrant/qdrant/releases/download/v1.14.0/qdrant-aarch64-apple-darwin.tar.gz
tar xzf qdrant-aarch64-apple-darwin.tar.gz

配置

所有设置都可以通过环境变量进行配置。复制 .env.example 到 .env:

# Embedding API Configuration
VOYAGE_API_KEY=your-voyage-api-key
EMBEDDING_MODEL=voyage-3-large

# Vector Database Configuration
QDRANT_URL=http://localhost:6334
QDRANT_COLLECTION=doc_index

# Document Paths Configuration
DOCS_PATH=/path/to/your/documents
INDEX_SUBDIRS=docs

# Chunk Settings
PDF_CHUNK_SIZE=1000
PDF_CHUNK_OVERLAP=200
EXCEL_ROWS_PER_CHUNK=50
SQL_MAX_CHUNK_SIZE=4000

# Search Settings
SEARCH_TOP_K=10

# Logging
RUST_LOG=info

块尺寸建议

建筑

# Development build
cargo build

# Release build (optimized)
cargo build --release

测试

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test module
cargo test parsers::pdf::tests
cargo test parsers::excel::tests
cargo test parsers::sql::tests

跑步

1. 启动Qdrant：

./qdrant

1. 运行MCP服务器：

cargo run --release

服务器按照MCP协议通过stdio进行通信。

MCP工具

支持的文件类型

与Claude Code CLI集成

步骤1：构建服务器

cd /path/to/doc-indexer-mcp
cargo build --release

步骤2：配置Claude代码CLI

将MCP服务器添加到Claude Code配置文件中 ~/.claude.json:

{
  "mcpServers": {
    "doc-indexer": {
      "command": "/path/to/doc-indexer-mcp/target/release/doc-indexer-mcp",
      "env": {
        "VOYAGE_API_KEY": "your-voyage-api-key",
        "EMBEDDING_MODEL": "voyage-3-large",
        "QDRANT_URL": "http://localhost:6334",
        "QDRANT_COLLECTION": "doc_index",
        "DOCS_PATH": "/path/to/your/documents",
        "INDEX_SUBDIRS": "docs",
        "PDF_CHUNK_SIZE": "1000",
        "PDF_CHUNK_OVERLAP": "200",
        "RUST_LOG": "info"
      }
    }
  }
}

步骤3：使用Claude代码进行测试

使用 /mcp Claude Code中的命令来测试您的MCP服务器：

claude
> /mcp

这将显示所有可用的MCP工具。然后，您可以测试单个工具：

> Search for "user authentication" in the indexed documents
> Index all documents in the docs folder

步骤4：项目特定设置（可选）

创建 settings.json 在项目根目录中获取项目特定权限：

{
  "permissions": {
    "allow": [
      "mcp__doc-indexer__index_document",
      "mcp__doc-indexer__index_directory",
      "mcp__doc-indexer__search_documents",
      "mcp__doc-indexer__get_stats",
      "mcp__doc-indexer__delete_document"
    ]
  }
}

DOCS_PATH的目录结构

在配置的子目录中组织文档：

/your/docs/path/
├── docs/                    # Design documents, specifications
│   ├── design_spec.pdf
│   ├── test_spec.pdf
│   └── schema.md
└── sql/                     # SQL and PL/SQL files
    ├── procedures.sql
    └── packages.pkb

建筑

src/
├── main.rs              # Entry point
├── config.rs            # Configuration from environment
├── embedding/
│   └── client.rs        # Embeddings API client (Voyage AI)
├── mcp/
│   ├── server.rs        # MCP server setup
│   └── tools.rs         # Tool implementations
├── parsers/
│   ├── mod.rs           # Parser trait and common types
│   ├── pdf.rs           # PDF parser (pdftotext)
│   ├── excel.rs         # Excel parser (calamine)
│   ├── sql.rs           # SQL/PL-SQL parser
│   ├── markdown.rs      # Markdown parser
│   └── html.rs          # HTML parser
└── vector_store/
    └── qdrant.rs        # Qdrant vector database client

自定义分块逻辑

每个解析器 src/parsers/ 为其文档类型实现智能分块。您可以通过修改节标记和模式来定制分块行为。

PDF解析器(src/parsers/pdf.rs)

PDF解析器使用节标记将文档拆分为逻辑块：

// Major section markers - customize for your document format
const MAJOR_SECTION_MARKERS: &[&str] = &[
    "【Initial Display】", "【On Display】", "【On Save】",
    // Add your own section markers here
];

// Sub-section headers
const SUB_SECTION_HEADERS: &[&str] = &[
    "Action Definition", "Screen Definition", "Error Check",
    // Add your own sub-section patterns
];

要自定义的关键功能：

• classify_line() -确定行类型（节标题、内容等）
• should_start_new_block() -决定块边界
• split_into_blocks() -主要分块逻辑

Excel解析器(src/parsers/excel.rs)

Excel解析器处理具有表和嵌套部分的结构化文档：

// Bracketed section markers
const MAJOR_SECTION_MARKERS: &[&str] = &[
    "【Initial Display】", "【Data Items】", "【Conditions】",
    // Add markers matching your Excel templates
];

// Row type classification
enum RowType {
    BracketedSection,    // 【Section】
    MajorSection,        // 1. Section
    SubSection,          // 1.1. Sub Section
    TableHeader,         // No | Item Name | ...
    // Add custom row types
}

要自定义的关键功能：

• classify_row() -按类型对Excel行进行分类
• should_start_new_block() -确定块边界
• rows_to_markdown() -将行转换为可搜索文本

HTML解析器(src/parsers/html.rs)

HTML解析器从web应用程序快照中提取UI文本：

// CSS class patterns to extract text from
let patterns = [
    ("title", "ui-dialog-title"),
    ("button", "a-Button-label"),
    ("column", "a-GV-headerLabel"),
    // Add patterns matching your UI framework
];

要自定义的关键功能：

• detect_component_type() -标识UI组件类型
• extract_texts() -通过CSS类模式提取文本

SQL解析器(src/parsers/sql.rs)

SQL解析器提取PL/SQL对象（过程、函数、包）：

要自定义的关键功能：

• 数据库模式的对象检测模式
• 包装/程序边界检测

添加新解析器

1. 在中创建新文件 src/parsers/ （例如。， xml.rs)
2. 实施 DocumentParser 特质：

#[async_trait::async_trait]
impl DocumentParser for XmlParser {
    async fn parse(&self, file_path: &str) -> Result> {
        // Your parsing logic here
    }

    fn supported_extensions(&self) -> Vec {
        vec!["xml"]
    }
}

1. 注册于 src/parsers/mod.rs
2. 添加到 src/mcp/tools.rs 在 get_parser()

故障排除

Claude Code CLI中没有可见的日志

MCP服务器登录到stderr，这在Claude Code CLI中可能不可见。要调试，请执行以下操作：

1. 集 RUST_LOG=debug 在您的配置中
2. 手动运行服务器以查看日志：

   RUST_LOG=debug ./target/release/doc-indexer-mcp

Qdrant连接问题

确保Qdrant正在配置的端口上运行（默认值：6334）：

./qdrant
# Check: curl http://localhost:6334/collections

PDF解析错误

确保 pdftotext 已安装：

which pdftotext
# If not found: brew install poppler

测试MCP连接

使用克劳德代码 /mcp 用于验证服务器是否已连接的命令：

claude
> /mcp

这将列出所有可用的MCP服务器及其工具。

许可证

MIT许可证-请参阅 许可证 文件。