Chroma

Servidor MCP de Chroma

Una implementación de servidor del Protocolo de Contexto de Modelos (MCP) que proporciona capacidades de base de datos vectorial a través de Chroma. Este servidor permite búsqueda semántica de documentos, filtrado de metadatos y gestión de documentos con almacenamiento persistente.

Requisitos

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

Componentes

Recursos

El servidor proporciona almacenamiento y recuperación de documentos a través de la base de datos vectorial de Chroma:

• Almacena documentos con contenido y metadatos
• Persiste datos en el directorio src/chroma/data
• Soporta búsqueda de similitud semántica

Herramientas

El servidor implementa operaciones CRUD y funcionalidad de búsqueda:

Gestión de Documentos

• create_document: Crear un nuevo documento

  • Requerido: document_id, content
  • Opcional: metadata (pares clave-valor)
  • Devuelve: Confirmación de éxito
  • Error: Ya existe, Entrada no válida

• read_document: Recuperar un documento por ID

  • Requerido: document_id
  • Devuelve: Contenido del documento y metadatos
  • Error: No encontrado

• update_document: Actualizar un documento existente

  • Requerido: document_id, content
  • Opcional: metadata
  • Devuelve: Confirmación de éxito
  • Error: No encontrado, Entrada no válida

• delete_document: Eliminar un documento

  • Requerido: document_id
  • Devuelve: Confirmación de éxito
  • Error: No encontrado

• list_documents: Listar todos los documentos

  • Opcional: limit, offset
  • Devuelve: Lista de documentos con contenido y metadatos

Operaciones de Búsqueda

• search_similar: Encontrar documentos semánticamente similares
  • Requerido: query
  • Opcional: num_results, metadata_filter, content_filter
  • Devuelve: Lista clasificada de documentos similares con puntuaciones de distancia
  • Error: Filtro no válido

Características

• Búsqueda Semántica: Encuentra documentos basados en significado usando los embeddings de Chroma
• Filtrado de Metadatos: Filtra resultados de búsqueda por campos de metadatos
• Filtrado de Contenido: Filtrado adicional basado en el contenido del documento
• Almacenamiento Persistente: Los datos persisten en el directorio local entre reinicios del servidor
• Manejo de Errores: Manejo integral de errores con mensajes claros
• Lógica de Reintentos: Reintentos automáticos para fallos transitorios

Instalación

1. Instalar dependencias:

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

Configuración

Claude Desktop

Agregue la configuración del servidor a su configuración de Claude Desktop:

Windows: C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/MCP/server/community/chroma",
        "run",
        "chroma"
      ]
    }
  }
}

Almacenamiento de Datos

El servidor almacena datos en:

• Windows: src/chroma/data
• MacOS/Linux: src/chroma/data

Uso

1. Inicie el servidor:

uv run chroma

2. Use las herramientas MCP para interactuar con el servidor:

# 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"
    }
})

Manejo de Errores

El servidor proporciona mensajes de error claros para escenarios comunes:

• Document already exists [id=X]
• Document not found [id=X]
• Invalid input: Missing document_id or content
• Invalid filter
• Operation failed: [details]

Desarrollo

Pruebas

1. Ejecute el Inspector MCP para pruebas interactivas:

npx @modelcontextprotocol/inspector uv --directory C:/MCP/server/community/chroma run chroma

2. Use la interfaz web del inspector para:
   • Probar operaciones CRUD
   • Verificar la funcionalidad de búsqueda
   • Comprobar el manejo de errores
   • Monitorear los registros del servidor

Compilación

1. Actualizar dependencias:

uv compile pyproject.toml

2. Compilar el paquete:

uv build

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lea nuestras Pautas de Contribución para detalles sobre:

• Estilo de código
• Requisitos de prueba
• Proceso de solicitudes de extracción

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCIA para más detalles.