fuel-mcp-server

🚀 燃油网络文档检索系统

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

🚀 快速开始

本系统的使用主要包含环境配置、项目构建启动等步骤，下面为你详细介绍。

✨ 主要特性

• 完整解决方案：提供了从文档索引到检索的一站式服务。
• 高效检索：基于QdrantDB向量数据库和余弦相似度计算，实现对技术文档的高效搜索和查询。
• 多模块集成：包含文档索引、向量嵌入生成以及与支持MCP协议的IDE集成等多个功能模块。
• 扩展性强：未来计划增加多模态支持、分布式架构和增量索引等功能。

📦 安装指南

依赖项

• 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协议集成

与IDE的交互

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

扩展性设计

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

维护与优化

性能调优

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

npm run benchmark

日志管理

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

🔧 技术细节

本系统基于QdrantDB向量数据库和MCP协议（Model Context Protocol）构建。QdrantDB是一个高性能的向量数据库，用于存储和检索高维向量。MCP协议则用于与支持该协议的IDE进行集成，实现代码编辑过程中的文档检索功能。

在文档索引方面，系统支持Markdown格式的文件解析，通过自动识别和提取代码块、段落等结构化内容，实现文本分块和向量生成。在检索方面，系统采用余弦相似度进行向量对比，根据匹配程度对检索结果进行动态排序，并基于相邻块的信息提升检索结果的相关性。

📄 许可证

文档未提及相关信息，故跳过该章节。

项目贡献

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

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