Chroma MCP 服务器

一个通过 Chroma 实现的 Model Context Protocol (MCP) 服务器，提供向量数据库功能。此服务器支持语义文档搜索、元数据过滤和文档管理，并且支持持久化存储。

需求

• Python 3.8+
• Chroma 0.4.0+
• MCP SDK 0.1.0+

组件

资源

该服务器通过 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 列表
  • 错误：无效过滤器

功能

• 语义搜索：根据意义查找文档，使用 Chroma 的嵌入
• 元数据过滤：按元数据字段过滤搜索结果
• 内容过滤：基于文档内容的额外过滤
• 持久化存储：在本地目录之间重启服务器时保留数据
• 错误处理：全面的错误处理和清晰的消息
• 重试逻辑：自动重试瞬时故障

安装

1. 安装依赖：

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

配置

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. 启动服务器：

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

错误处理

• 常见错误：请检查端口是否被占用或配置是否正确。

开发测试

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 文件中的许可证约束。