使用说明

项目简介

Chroma MCP Server 是一个 Model Context Protocol (MCP) 服务器的实现，它专注于为 LLM 应用提供与 ChromaDB 向量数据库交互的标准接口。通过 MCP 协议，客户端可以方便地管理 ChromaDB 中的 collections 和 documents，并利用提供的工具进行数据操作和 AI 应用开发。

主要功能点

Collection 管理: 支持创建、列出、获取、修改和删除 ChromaDB 集合 (Collections)。
Document 操作: 支持向集合中添加、查询、获取、更新和删除文档 (Documents)。
思考工具: 提供了用于 AI 应用的顺序思考 (Sequential Thinking) 工具，帮助记录和分析思考过程。
灵活的客户端类型: 支持多种 ChromaDB 客户端类型，包括 HTTP、Cloud、Persistent 和 Ephemeral。
完善的错误处理和日志: 提供标准化的错误处理和详细的日志记录，方便问题排查和系统监控。

安装步骤

环境准备: 确保你的系统已安装 Python 3.10 或更高版本。

使用 setup 脚本 (推荐): 打开终端，导航到仓库根目录，运行以下命令（适用于 Unix/macOS）：

./setup.sh

或手动执行以下步骤：

python -m venv .venv
source .venv/bin/activate  # Unix/macOS
.venv\Scripts\activate    # Windows
pip install -e ".[dev]"

'setup.sh' 脚本会自动创建虚拟环境、安装依赖并进行开发模式安装。

服务器配置

要将 Chroma MCP Server 配置为 Cursor MCP 服务器，请编辑 Cursor 的 MCP 配置文件 '~/.cursor/mcp.json' (macOS/Linux) 或 '%USERPROFILE%.cursor\mcp.json' (Windows)。添加如下 server 配置到 'mcpServers' 字段中：

{
  "mcpServers": {
    "chroma_mcp_server": {  // 服务器名称，可以自定义
      "command": "/path/to/venv/bin/python",  // Python 解释器路径，请替换为你的虚拟环境路径
      "args": [
        "/path/to/repo/mcp/chroma_mcp_server/run_chroma_mcp.py" // run_chroma_mcp.py 脚本路径，请替换为你的仓库路径
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "PYTHONIOENCODING": "utf-8",
        "PYTHONPATH": "/path/to/repo/mcp/chroma_mcp_server", // PYTHONPATH 环境变量，指向仓库根目录
        "LOG_LEVEL": "WARNING",  // 可选：设置日志级别，例如 DEBUG, INFO, WARNING, ERROR, CRITICAL
        "MCP_LOG_LEVEL": "WARNING" // 可选：设置 MCP 框架日志级别
      }
    }
  }
}

注意:

请将 '/path/to/venv/bin/python' 替换为你实际的虚拟环境 Python 解释器路径。
请将 '/path/to/repo/mcp/chroma_mcp_server/run_chroma_mcp.py' 和 '/path/to/repo/mcp/chroma_mcp_server' 替换为你克隆仓库的实际路径。

基本使用方法

启动服务器: 按照上述配置，Cursor 应该能够自动启动 Chroma MCP Server。你也可以手动运行 'run_chroma_mcp.py' 脚本来启动服务器。
验证服务器: 运行仓库自带的验证脚本 'tests/run_chroma_mcp_test.sh' (Unix/macOS) 以确保服务器正常工作。首先激活虚拟环境：
```
source .venv/bin/activate  # Unix/macOS
.venv\Scripts\activate    # Windows
```
然后运行验证脚本：
```
./tests/run_chroma_mcp_test.sh
```
该脚本会启动服务器，连接到服务器，列出可用工具，并测试集合列表功能，验证服务器是否正常运行。
使用 MCP 客户端: 你可以使用任何 MCP 客户端库（例如 Python 的 'mcp' 库）通过 JSON-RPC 协议与服务器交互，调用工具并管理 ChromaDB 资源。'examples/simple_client.py' 提供了一个简单的 Python 客户端示例，演示了如何连接服务器、创建集合、添加文档和查询文档。

关键词