Chroma

🚀 Chroma MCP 服務器

Chroma MCP 服務器是一個藉助 Chroma 實現的 Model Context Protocol (MCP) 服務器，具備向量數據庫功能。它支持語義文檔搜索、元數據過濾和文檔管理，還能進行持久化存儲，為用戶提供高效的文檔處理體驗。

🚀 快速開始

安裝依賴

uv venv
uv sync --dev --all-extras

啟動服務器

python -m mcp_server.main --host 0.0.0.0 --port 5000

✨ 主要特性

• 語義搜索：藉助 Chroma 的嵌入技術，依據文檔意義進行查找。
• 元數據過濾：可按照元數據字段對搜索結果進行過濾。
• 內容過濾：能夠基於文檔內容進行額外過濾。
• 持久化存儲：在本地目錄之間重啟服務器時，數據可得以保留。
• 錯誤處理：擁有全面的錯誤處理機制，提供清晰的錯誤消息。
• 重試邏輯：可自動重試瞬時故障。

📦 安裝指南

安裝依賴

uv venv
uv sync --dev --all-extras

💻 使用示例

基礎用法

文檔管理

# 創建新文檔
create_document(document_id="1", content="這是一個測試文檔", metadata={"category": "測試"})

# 根據 ID 檢索文檔
read_document(document_id="1")

# 更新現有文檔
update_document(document_id="1", content="這是更新後的測試文檔", metadata={"category": "更新測試"})

# 刪除文檔
delete_document(document_id="1")

# 列出所有文檔
list_documents()

搜索操作

# 找到語義相似的文檔
search_similar(query="測試文檔", num_results=5, metadata_filter={"category": "測試"})

📚 詳細文檔

組件

資源

該服務器藉助 Chroma 的向量數據庫提供文檔存儲和檢索功能：

• 可存儲帶內容和元數據的文檔。
• 在 src/chroma/data 目錄中進行持久化數據存儲。
• 支持語義相似性搜索。

工具

該服務器實現了 CRUD 操作和搜索功能：

文檔管理

• create_document：創建新文檔

  • 必填：document_id，content
  • 可選：metadata（鍵值對）
  • 返回：成功確認
  • 錯誤：已存在，無效輸入

• read_document：根據 ID 檢索文檔

  • 必填：document_id
  • 返回：文檔內容和元數據
  • 錯誤：未找到

• update_document：更新現有文檔

  • 必填：document_id，content
  • 可選：metadata
  • 返回：成功確認
  • 錯誤：未找到，無效輸入

• delete_document：刪除文檔

  • 必填：document_id
  • 返回：成功確認
  • 錯誤：未找到

• list_documents：列出所有文檔

  • 可選：limit，offset
  • 返回：包含內容和元數據的文檔列表

搜索操作

• search_similar：找到語義相似的文檔
  • 必填：query
  • 可選：num_results，metadata_filter，content_filter
  • 返回：帶距離分數的相似文檔 ranked 列表
  • 錯誤：無效過濾器

配置

Claude Desktop

將服務器配置添加到您的 Claude Desktop 配置中：

Windows: C:\Users\<username>\AppData\Local\Claude Labs\Claude 2\config.json

在文件末尾添加以下內容：

{
  "mcp-server": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 5000
  }
}

Windows 系統服務配置

1. 創建一個新文件 mcp-service.json，內容如下：

{
  "name": "MCP Server",
  "description": "Chroma MCP Server",
  "start_command": "uvicorn mcp_server.main:app --host 0.0.0.0 --port 5000",
  "working_directory": "%USERPROFILE%",
  "autostart": true,
  "display": false
}

2. 將文件保存在 C:\ProgramData\uvx 目錄中。

錯誤處理

• 常見錯誤：請檢查端口是否被佔用或配置是否正確。

開發測試

1. 克隆倉庫：

git clone https://github.com/your-repository.git
cd mcp_server
pip install -r requirements.txt

2. 啟動服務器進行開發：

uvicorn mcp_server.main:app --reload

貢獻指南

1. Fork 倉庫。
2. 創建功能分支。
3. 提交更改。
4. 創建 Pull Request。

📄 許可證

此項目受 LICENSE 文件中的許可證約束。