Metadata-Version: 2.4
Name: chroma-mcp-server
Version: 0.2.27
Summary: Chroma MCP Server - Vector Database Integration for LLM Applications
Project-URL: Homepage, https://github.com/djm81/chroma_mcp_server
Project-URL: Repository, https://github.com/djm81/chroma_mcp_server.git
Project-URL: Documentation, https://github.com/djm81/chroma_mcp_server#readme
Author-email: Nold Coaching & Consulting <info@noldcoaching.de>
License-Expression: MIT
License-File: LICENSE.md
Keywords: chroma,embeddings,llm,mcp,vector-database
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: chromadb>=1.0.4
Requires-Dist: fastapi>=0.115.0
Requires-Dist: mcp>=1.6.0
Requires-Dist: numpy<2.0.0
Requires-Dist: onnxruntime>=1.21.0
Requires-Dist: pydantic>=2.11.3
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: sentence-transformers>=4.1.0
Requires-Dist: transformers~=4.41.0
Requires-Dist: uvicorn>=0.34.1
Provides-Extra: aimodels
Requires-Dist: boto3>=1.37.34; extra == 'aimodels'
Requires-Dist: cohere>=5.15.0; extra == 'aimodels'
Requires-Dist: google-generativeai>=0.8.4; extra == 'aimodels'
Requires-Dist: huggingface-hub>=0.30.2; extra == 'aimodels'
Requires-Dist: ollama>=0.4.7; extra == 'aimodels'
Requires-Dist: openai>=1.74.0; extra == 'aimodels'
Requires-Dist: voyageai>=0.3.2; extra == 'aimodels'
Provides-Extra: client
Requires-Dist: gitpython>=3.1.44; extra == 'client'
Provides-Extra: dev
Requires-Dist: black>=25.1.0; extra == 'dev'
Requires-Dist: isort>=6.0.1; extra == 'dev'
Requires-Dist: mypy>=1.15.0; extra == 'dev'
Requires-Dist: pylint>=3.3.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20250402; extra == 'dev'
Provides-Extra: devtools
Requires-Dist: black>=25.1.0; extra == 'devtools'
Requires-Dist: isort>=6.0.1; extra == 'devtools'
Requires-Dist: mypy>=1.15.0; extra == 'devtools'
Requires-Dist: pylint>=3.3.6; extra == 'devtools'
Requires-Dist: types-pyyaml>=6.0.12.20250402; extra == 'devtools'
Provides-Extra: full
Requires-Dist: boto3>=1.37.34; extra == 'full'
Requires-Dist: cohere>=5.15.0; extra == 'full'
Requires-Dist: gitpython>=3.1.44; extra == 'full'
Requires-Dist: google-generativeai>=0.8.4; extra == 'full'
Requires-Dist: httpx>=0.28.1; extra == 'full'
Requires-Dist: huggingface-hub>=0.30.2; extra == 'full'
Requires-Dist: ollama>=0.4.7; extra == 'full'
Requires-Dist: openai>=1.74.0; extra == 'full'
Requires-Dist: voyageai>=0.3.2; extra == 'full'
Provides-Extra: server
Requires-Dist: httpx>=0.28.1; extra == 'server'
Description-Content-Type: text/markdown

# Chroma MCP Server

[![CI](https://github.com/djm81/chroma_mcp_server/actions/workflows/tests.yml/badge.svg)](https://github.com/djm81/chroma_mcp_server/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/djm81/chroma_mcp_server/branch/main/graph/badge.svg)](https://codecov.io/gh/djm81/chroma_mcp_server)
[![PyPI - Version](https://img.shields.io/pypi/v/chroma-mcp-server?color=blue)](https://pypi.org/project/chroma-mcp-server)

A Model Context Protocol (MCP) server integration for [Chroma](https://www.trychroma.com/), the open-source embedding database.

## Overview

Chroma MCP Server creates a persistent, searchable "working memory" for AI-assisted development:

- **Automated Context Recall:** AI assistants can query relevant information from past sessions
- **Developer-Managed Persistence:** Store key decisions and insights in ChromaDB via MCP
- **Second Brain Integration:** Integrates with IDE workflows to create a unified knowledge hub

Key features:

- **Automated Codebase Indexing:** Track and index code changes
- **Automated Chat Logging:** Log AI interactions with enhanced context capture (code diffs, tool sequences)
- **Bidirectional Linking:** Connect discussions to code changes for tracing feature evolution
- **Semantic Code Chunking:** Preserve logical code structures for more meaningful context retrieval
- **Working Memory Tools:** MCP commands for capturing and retrieving development context
- **Validation System:** Evidence-based validation for code changes and learning promotions
- **Automated Test-Driven Learning:** Fully automated workflow from test failure to verified fix and learning promotion. See the [Pytest Plugin Usage Guide](docs/integration/pytest_plugin_usage.md) to integrate this into your projects.

See the [Getting Started with your Second Brain guide](docs/getting_started_second_brain.md) for more details.

## Quick Start

### Installation

```bash
# Basic installation
pip install chroma-mcp-server

# Full installation with all embedding models
pip install "chroma-mcp-server[full]"
```

### Running

```bash
# With in-memory storage (data lost on restart)
chroma-mcp-server --client-type ephemeral

# With persistent storage
chroma-mcp-server --client-type persistent --data-dir ./my_data
```

### Cursor Integration

Add or modify `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "chroma": {
      "command": "uvx",
      "args": [
        "chroma-mcp-server"
      ],
      "env": {
        "CHROMA_CLIENT_TYPE": "persistent",
        "CHROMA_DATA_DIR": "/path/to/your/data",
        "CHROMA_LOG_DIR": "/path/to/your/logs",
        "LOG_LEVEL": "INFO",
        "MCP_LOG_LEVEL": "INFO",
        "MCP_SERVER_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

## Recent Improvements

- **Enhanced Context Capture:** Automatically extracts code diffs, tool sequences, and assigns confidence scores
- **Bidirectional Linking:** Creates navigable connections between chat discussions and code changes
- **Semantic Code Chunking:** Uses logical boundaries (functions, classes) instead of fixed-size chunks
- **Server-Side Timestamp Enforcement:** Ensures consistent timestamps across all collections
- **Automatic Collection Creation:** Essential collections (e.g., `chat_history_v1`, `codebase_v1`) are automatically created on server startup if they don't exist.
- **Enhanced Logging System:** Per-execution log files prevent contamination of JSON communication in stdio mode
- **Embedding Function Management:** Tools to update collection metadata when changing embedding functions
- **Collection Setup Command:** Simplifies creation of multiple collections with consistent configuration
- **Auto-Promote Workflow:** Streamlined derived learning promotion with automatic handling of high-confidence entries
- **Smart Defaults:** Interactive promotion with intelligent defaults for all fields based on context
- **Low Confidence Warnings:** Visual indicators for entries that may need more careful review
- **Automated Test Workflow:** Fully automated capture of test failures, monitoring for fixes, and validated learning promotion

## Documentation

Comprehensive documentation is available in the [docs directory](docs/):

- [Main Documentation](docs/README.md) - Complete guide to installation, configuration, and usage
- [Getting Started](docs/getting_started.md) - Detailed setup instructions
- [Developer Guide](docs/developer_guide.md) - For contributors and developers
- [IDE & Tool Integration Guides](docs/integration/README.md) - Guides for integrating with IDEs and other tools.
- [Automated Chat Logging](docs/integration/automated_chat_logging.md) - Enriched chat history with bidirectional linking
- [Usage Guides](docs/usage/README.md) - Detailed guides on how to use specific features and workflows.
- [Enhanced Context Capture](docs/usage/enhanced_context_capture.md) - Details on code diff extraction and tool sequencing
- [Semantic Code Chunking](docs/usage/semantic_chunking.md) - Logic-preserving code chunking for meaningful retrieval
- [Automated Test Workflow (Pytest Plugin Usage)](docs/integration/pytest_plugin_usage.md) - Test-driven learning with automatic validation
- [Thinking Tools & Utilities](docs/thinking_tools/README.md) - Documentation for structured thinking and memory tools.
- [Client and Developer Scripts](docs/scripts/README.md) - Guides for CLI tools and developer scripts.
- [Logging Documentation](docs/logging/README.md) - Overview of logging features and configuration.
- [Server Logging](docs/logging/server_logging.md) - Details on the improved logging system
- [Automation Documentation](docs/automation/README.md) - Guides on automating development tasks.
- [Project Rules & Guidelines](docs/rules/README.md) - Development rules, guidelines, and best practices.
- [Refactoring Plans](docs/refactoring/README.md) - Documentation on various refactoring efforts and architectural plans.
- [API Reference](docs/api_reference.md) - Available MCP tools and parameters

## License

Chroma MCP Server is licensed under the MIT License with Commons Clause. This means you can:

✅ **Allowed**:

- Use Chroma MCP Server for any purpose (personal, commercial, academic)
- Modify the code
- Distribute copies
- Create and sell products built using Chroma MCP Server

❌ **Not Allowed**:

- Sell Chroma MCP Server itself
- Offer Chroma MCP Server as a hosted service
- Create competing products based on Chroma MCP Server

See the [LICENSE.md](LICENSE.md) file for the complete license text.
