Fuel MCP Server

🚀 燃油网络文档检索系统

本项目提供了一套完整的文档检索解决方案，基于QdrantDB向量数据库和MCP协议（Model Context Protocol）。用户可通过整合本地运行的Qdrant实例，实现对技术文档内容的高效搜索和查询。系统涵盖文档索引、向量嵌入生成以及与支持MCP协议的IDE集成等多个功能模块。

🚀 快速开始

本项目提供了一套完整的文档检索解决方案，基于QdrantDB向量数据库和MCP协议。通过整合本地运行的Qdrant实例，用户能够对技术文档内容进行高效搜索和查询。

✨ 主要特性

• 完整解决方案：提供涵盖文档索引、向量嵌入生成等多个功能模块的完整文档检索方案。
• 多格式支持：文档索引器支持Markdown格式，能自动识别和提取代码块、段落等结构化内容。
• 智能分块：基于目标词数进行智能文本分块，确保内容完整性和检索效率。
• 高效检索：检索引擎采用余弦相似度进行向量对比，根据匹配程度对结果动态排序，并基于相邻块信息扩展上下文。
• MCP协议集成：可无缝对接支持MCP协议的开发环境，如VS Code、IntelliJ IDEA等，方便在代码编辑时触发文档检索。
• 扩展性强：未来计划增加多模态支持、分布式架构部署和增量索引等功能。

📦 安装指南

依赖项

• Node.js：版本要求v16.0.0或更高。
• Docker：用于运行QdrantDB容器。
• Python Transformers库：用于文本嵌入生成。
• File Watchers：可选，用于自动索引文件变更。

必要环境变量

# Qdrant数据库配置
export QDRANT_URL=http://localhost:6333  # 默认本地运行地址
export QDRANT_API_KEY=your_api_key       # 根据实际API密钥填写

# 模型相关配置
export EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2  # 默认文本嵌入模型

构建与启动步骤

初始化项目

git clone [your-repository-url]
cd fuel-network-document-system
npm install

启动QdrantDB服务

# 使用Docker启动本地Qdrant实例
docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage \
    qdrant/qdrant

启动文档索引服务

# 删除旧数据库（可选）
rm -rf qdrant_storage

# 启动索引服务，默认使用本地Qdrant实例
npm run dev

💻 使用示例

基础用法

文档索引

# 基本使用
bun run indexer -- docsDir ./docs collectionName my_docs modelname your_model_name targetChunkSize 1500

# 可选环境变量配置
export QDRANT_URL=http://your-qdrant-host:6333
export QDRANT_API_KEY=your_api_key

文档检索

# 基本查询
bun run query --run "你的搜索问题"

高级用法

文档检索

# 高级选项
QDRANT_COLLECTION=my_collection \
NUM_RESULTS=10 \
EMBEDDING_MODEL=another_model \
bun run query --run "高级搜索问题"

📚 详细文档

核心功能模块

文档索引器

• 文件解析：支持Markdown格式，自动识别和提取代码块、段落等结构化内容。
• 文本分块：基于目标词数进行智能分块，确保内容完整性和检索效率。
• 向量生成：利用Transformers.js库将文本转换为高维向量表示。

检索引擎

• 相似度计算：采用余弦相似度进行向量对比，返回最相关的文档片段。
• 结果排序：根据匹配程度对检索结果进行动态排序。
• 上下文扩展：基于相邻块的信息提升检索结果的相关性。

MCP协议集成

通过实现MCP协议，本系统可无缝对接支持该协议的开发环境，例如VS Code、IntelliJ IDEA等。用户可以在代码编辑过程中直接触发文档检索功能，快速获取所需技术资料。

扩展性设计

• 多模态支持：未来计划增加对图像和音频等内容类型的处理能力。
• 分布式架构：正在规划基于Kubernetes的微服务化部署方案。
• 增量索引：开发中实时文件变更检测与自动索引更新功能。

维护与优化

性能调优

建议根据实际硬件配置调整向量维度和分块策略。可以通过以下命令进行性能测试：

npm run benchmark

日志管理

系统提供详细的日志记录功能，便于排查问题和监控运行状态。

🔧 技术细节

本项目基于QdrantDB向量数据库和MCP协议（Model Context Protocol）构建。QdrantDB用于存储文档的向量表示，通过向量相似度计算实现高效的文档检索。MCP协议则实现了与支持该协议的IDE的集成，方便开发者在代码编辑过程中直接检索文档。

在文档索引阶段，系统会对Markdown文件进行解析，提取结构化内容，并将其分块。然后利用Transformers.js库将文本转换为高维向量，存储到QdrantDB中。

检索时，系统会将用户的查询文本转换为向量，与QdrantDB中的向量进行余弦相似度计算，根据匹配程度对结果进行排序，并通过上下文扩展提升检索结果的相关性。

📄 许可证

文档中未提及相关信息。

项目贡献

欢迎社区开发者参与项目开发！请通过以下方式提交代码修改或反馈问题：

• GitHub仓库：[your-github-repository]
• 邮件列表：[your-email-list]

本项目旨在为技术文档管理和检索提供一个高效、灵活的解决方案，同时通过与MCP协议的支持，提升开发者的工作效率。