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協議的支持，提升開發者的工作效率。