Chroma

Chroma MCP Server

Um servidor Model Context Protocol (MCP) que fornece capacidades de banco de dados vetorial através do Chroma. Este servidor permite busca semântica de documentos, filtragem por metadados e gerenciamento de documentos com armazenamento persistente.

Requisitos

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

Componentes

Recursos

O servidor fornece armazenamento e recuperação de documentos através do banco de dados vetorial do Chroma:

• Armazena documentos com conteúdo e metadados
• Persiste dados no diretório src/chroma/data
• Suporta busca por similaridade semântica

Ferramentas

O servidor implementa operações CRUD e funcionalidade de busca:

Gerenciamento de Documentos

• create_document: Criar um novo documento

  • Obrigatório: document_id, content
  • Opcional: metadata (pares chave-valor)
  • Retorna: Confirmação de sucesso
  • Erro: Já existe, Entrada inválida

• read_document: Recuperar um documento por ID

  • Obrigatório: document_id
  • Retorna: Conteúdo do documento e metadados
  • Erro: Não encontrado

• update_document: Atualizar um documento existente

  • Obrigatório: document_id, content
  • Opcional: metadata
  • Retorna: Confirmação de sucesso
  • Erro: Não encontrado, Entrada inválida

• delete_document: Remover um documento

  • Obrigatório: document_id
  • Retorna: Confirmação de sucesso
  • Erro: Não encontrado

• list_documents: Listar todos os documentos

  • Opcional: limit, offset
  • Retorna: Lista de documentos com conteúdo e metadados

Operações de Busca

• search_similar: Encontrar documentos semanticamente similares
  • Obrigatório: query
  • Opcional: num_results, metadata_filter, content_filter
  • Retorna: Lista classificada de documentos similares com pontuações de distância
  • Erro: Filtro inválido

Recursos

• Busca Semântica: Encontre documentos com base no significado usando os embeddings do Chroma
• Filtragem por Metadados: Filtre resultados de busca por campos de metadados
• Filtragem de Conteúdo: Filtragem adicional baseada no conteúdo do documento
• Armazenamento Persistente: Os dados persistem no diretório local entre reinicializações do servidor
• Tratamento de Erros: Tratamento abrangente de erros com mensagens claras
• Lógica de Reintentos: Reintentos automáticos para falhas transitórias

Instalação

1. Instale as dependências:

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

Configuração

Claude Desktop

Adicione a configuração do servidor ao seu arquivo de configuração do 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"
      ]
    }
  }
}

Armazenamento de Dados

O servidor armazena dados em:

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

Uso

1. Inicie o servidor:

uv run chroma

2. Use as ferramentas MCP para interagir com o 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"
    }
})

Tratamento de Erros

O servidor fornece mensagens de erro claras para cenários comuns:

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

Desenvolvimento

Testes

1. Execute o MCP Inspector para testes interativos:

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

2. Use a interface web do inspector para:
   • Testar operações CRUD
   • Verificar a funcionalidade de busca
   • Verificar o tratamento de erros
   • Monitorar os logs do servidor

Compilação

1. Atualize as dependências:

uv compile pyproject.toml

2. Compile o pacote:

uv build

Contribuindo

Contribuições são bem-vindas! Leia nossas Diretrizes de Contribuição para detalhes sobre:

• Estilo de código
• Requisitos de teste
• Processo de pull request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.