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