Skip to main content
Glama

Chroma MCP Server

by djm81
testing-and-build-guide.md6.08 kB
# Rule: Testing and Build Guidelines **Description:** This rule provides essential instructions for testing and building the project correctly, avoiding common pitfalls with test environment management. ## Testing Guidelines ### Always Use Hatch Test Command Standard tests should **always** be run via the built-in Hatch `test` command, not directly with pytest or custom wrappers: ```bash # Run all tests (default matrix, quiet) hatch test # Run tests with coverage report (via run-cov alias) # Select a specific Python version (e.g., Python 3.10): hatch -e hatch-test.py3.10 run run-cov # Generate HTML coverage report (via run-html alias) # Select a specific Python version (e.g., Python 3.10): hatch -e hatch-test.py3.10 run run-html # Run tests for a specific Python version only hatch test --python 3.10 # Combine options and target specific paths hatch test --cover --python 3.12 tests/tools/ ``` ### Run tests with automated workflow capture (via run-autocapture alias) ```bash # Run tests with coverage report and verbose output automatically captured under the hood hatch test --cover -v # Check for completed test transitions hatch run chroma-mcp-client check-test-transitions --workspace-dir . # Clean up processed test artifacts (specific to the completed workflow file) hatch run chroma-mcp-client cleanup-test-artifacts `<path/to/test_workflow_complete_TIMESTAMP.json>` # Note: the `<path/to/test_workflow_complete_TIMESTAMP.json>` is the path to the test workflow complete file, which is created by the `run-autocapture` alias and needs to be provided as an argument to the `cleanup-test-artifacts` command # Or to clean up all completed workflows at once: find logs/tests/workflows -type f -name 'test_workflow_complete_*.json' -exec \ hatch run chroma-mcp-client cleanup-test-artifacts {} \ ; ``` ### Automated Test-Driven Learning The `--auto-capture-workflow` flag enables the automated test-driven learning system which: 1. Automatically captures test failures with context 2. Monitors for transitions from failure to success after code changes 3. Creates validation evidence linking failures, fixes, and chat history 4. Promotes high-quality fixes to derived learnings **Setup required before first use:** ```bash chroma-mcp-client setup-test-workflow --workspace-dir . ``` After running tests with fixes, check for completed workflows: ```bash chroma-mcp-client check-test-transitions --workspace-dir . ``` For complete details, see the [Automated Test Workflow Guide](../usage/automated_test_workflow.md). **Note:** The `--auto-capture-workflow` behavior is automatically applied on all `hatch test`, `run-cov`, and `cov` invocations, so a separate `run-autocapture` alias is no longer necessary. ### Avoid Direct pytest Usage ❌ **Incorrect:** ```bash python -m pytest tests/ ``` ✅ **Correct:** ```bash hatch test ``` Using Hatch ensures: - The proper Python matrix is used - Dependencies are correctly resolved - Environment variables are properly set - Coverage reports are correctly generated ## Build Guidelines Build the package using either: ```bash # Using the provided script (deprecated; removed in v0.3.0) ./scripts/build.sh # Or with the devtools wrapper command (recommended) hatch run build-mcp ``` This generates the distributable files in the `dist/` directory. **Development Scripts:** Script aliases such as `build-mcp`, `publish-mcp`, and others are provided only when you install the `devtools` extra. Install via: ```bash pip install chroma-mcp-server[devtools] ``` Or enable devtools in Hatch by adding `features = ["devtools"]` to your environment settings. ## Installing for IDE and CLI Usage After modifying and testing the MCP server package, you need to rebuild and install it in the Hatch environment for the changes to take effect in Cursor (or any other IDE) or when using the `chroma-mcp-client` CLI: ### Full Version (with AI models for embeddings) Use this approach when you need all embedding models available and have configured them in `mcp.json` or `.env`: ```bash # Replace <version> with the actual version built (e.g., 0.2.7) hatch build && hatch run pip uninstall chroma-mcp-server -y && hatch run pip install 'dist/chroma_mcp_server-<version>-py3-none-any.whl[full,dev]' ``` ### Smaller Version (default embeddings only) Use this lighter approach for faster installation with only fast and accurate embedding variants: ```bash # Replace <version> with the actual version built (e.g., 0.2.7) hatch build && hatch run pip uninstall chroma-mcp-server -y && hatch run pip install 'dist/chroma_mcp_server-<version>-py3-none-any.whl[client,dev]' ``` Please note, that for the MCP to be updated within the IDE, ask the user to manually reload the MCP server as there is no automated way available as of now, before continuing to try to talk to the updated MCP via tools call. ## Development Environment Remember to activate the Hatch environment before making changes: ```bash # Using the script (deprecated from 0.3.0 on) ./scripts/develop.sh # Or directly with Hatch (recommended) hatch shell ``` ## Release Guidelines When preparing a new release or updating the version: 1. **Update CHANGELOG.md** with the new version information: - Add a new section at the top after the `# Changelog` header with the next block of lines, but before the first `## [version] - TIMESTAMP` entry with the new version number and date - Document all significant changes under "Added", "Fixed", "Changed", or "Removed" sections - Use clear, concise language to describe each change ```markdown ## [0.2.x] - YYYY-MM-DD **Added:** - New feature description **Fixed:** - Bug fix description **Changed:** - Change description ``` 2. Ensure the version number is updated in `pyproject.toml` 3. Build the package and verify the correct version appears in the build artifacts 4. Test the new version to ensure all changes worComplete Documentation For comprehensive instructions, refer to the [Developer Guide](../developer_guide.md).

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/djm81/chroma_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server