内容
# Chroma MCP Server
一个模型上下文协议（MCP）服务器实现，通过Chroma提供向量数据库功能。该服务器支持语义文档搜索、元数据过滤和具有持久存储的文档管理。
## Requirements
- Python 3.8+
- Chroma 0.4.0+
- MCP SDK 0.1.0+
## Components
### Resources
该服务器通过Chroma的向量数据库提供文档存储和检索：
- 存储包含内容和元数据的文档
- 将数据持久化在 `src/chroma/data` 目录中
- 支持语义相似性搜索
### Tools
该服务器实现了CRUD操作和搜索功能：
#### Document Management
- `create_document`: 创建一个新文档
- Required: `document_id`, `content`
- Optional: `metadata` (键值对)
- Returns: 成功确认
- Error: 已存在, 无效输入
- `read_document`: 通过ID检索文档
- Required: `document_id`
- Returns: 文档内容和元数据
- Error: 未找到
- `update_document`: 更新现有文档
- Required: `document_id`, `content`
- Optional: `metadata`
- Returns: 成功确认
- Error: 未找到, 无效输入
- `delete_document`: 删除文档
- Required: `document_id`
- Returns: 成功确认
- Error: 未找到
- `list_documents`: 列出所有文档
- Optional: `limit`, `offset`
- Returns: 包含内容和元数据的文档列表
#### Search Operations
- `search_similar`: 查找语义上相似的文档
- Required: `query`
- Optional: `num_results`, `metadata_filter`, `content_filter`
- Returns: 具有距离分数的相似文档的排序列表
- Error: 无效过滤器
## Features
- **Semantic Search**: 使用Chroma的嵌入，根据含义查找文档
- **Metadata Filtering**: 按元数据字段过滤搜索结果
- **Content Filtering**: 基于文档内容的额外过滤
- **Persistent Storage**: 数据在服务器重启之间持久保存在本地目录中
- **Error Handling**: 具有清晰消息的全面错误处理
- **Retry Logic**: 针对瞬时故障的自动重试
## Installation
1. 安装依赖项:
```bash
uv venv
uv sync --dev --all-extras
```
## Configuration
### Claude Desktop
将服务器配置添加到您的Claude Desktop配置中：
Windows: `C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json`
MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"chroma": {
"command": "uv",
"args": [
"--directory",
"C:/MCP/server/community/chroma",
"run",
"chroma"
]
}
}
}
```
### Data Storage
服务器将数据存储在：
- Windows: `src/chroma/data`
- MacOS/Linux: `src/chroma/data`
## Usage
1. 启动服务器:
```bash
uv run chroma
```
2. 使用MCP工具与服务器交互：
```python
# Create a document
create_document({
"document_id": "ml_paper1",
"content": "Convolutional neural networks improve image recognition accuracy.",
"metadata": {
"year": 2020,
"field": "computer vision",
"complexity": "advanced"
}
})
# Search similar documents
search_similar({
"query": "machine learning models",
"num_results": 2,
"metadata_filter": {
"year": 2020,
"field": "computer vision"
}
})
```
## Error Handling
服务器为常见场景提供清晰的错误消息：
- `Document already exists [id=X]`
- `Document not found [id=X]`
- `Invalid input: Missing document_id or content`
- `Invalid filter`
- `Operation failed: [details]`
## Development
### Testing
1. 运行MCP Inspector进行交互式测试：
```bash
npx @modelcontextprotocol/inspector uv --directory C:/MCP/server/community/chroma run chroma
```
2. 使用检查器的Web界面来：
- 测试CRUD操作
- 验证搜索功能
- 检查错误处理
- 监控服务器日志
### Building
1. 更新依赖项:
```bash
uv compile pyproject.toml
```
2. 构建包:
```bash
uv build
```
## Contributing
欢迎贡献！请阅读我们的[Contributing Guidelines](CONTRIBUTING.md)以获取有关以下内容的详细信息：
- 代码风格
- 测试要求
- 拉取请求流程
## License
该项目已获得MIT许可 - 有关详细信息，请参见[LICENSE](LICENSE)文件。
MCP 市场
