From 178e3477b4a91d5b55afe470e1ef0454f44730af Mon Sep 17 00:00:00 2001
From: Thomas Payet <thomas@meilisearch.com>
Date: Fri, 6 Jun 2025 12:33:18 +0200
Subject: [PATCH] Update documentation with comprehensive development
 guidelines
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add detailed TDD workflow and testing requirements to CLAUDE.md
- Include mandatory test execution and incremental development guidelines
- Enhance README.md with development setup and testing instructions
- Add comprehensive contribution guidelines with testing requirements
- Clarify when tests are required vs optional for different types of work
- Document test simulation framework and best practices

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md |  99 +++++++++++++++++++++++++++++++++++++++++--------
 README.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 188 insertions(+), 19 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 93f314a..0c0a225 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,55 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## 🚨 IMPORTANT: Development Workflow Guidelines
+
+**Before starting any task, agents MUST assess if tests are needed for the work requested.**
+
+### Test-Driven Development (TDD) Approach
+
+When working on this repository, follow these **mandatory** guidelines:
+
+1. **Assessment Phase**: Before writing any code, determine if the work requires tests:
+   - ✅ **Tests Required**: New features, bug fixes, API changes, tool modifications
+   - ❌ **Tests Optional**: Documentation updates, minor refactoring without behavior changes
+
+2. **TDD Workflow** (when tests are required):
+   ```bash
+   # 1. Write failing tests FIRST
+   python -m pytest tests/test_new_feature.py -v  # Should fail
+   
+   # 2. Write minimal code to make tests pass
+   # Edit source files...
+   
+   # 3. Run tests to verify they pass
+   python -m pytest tests/test_new_feature.py -v  # Should pass
+   
+   # 4. Refactor and repeat
+   ```
+
+3. **Pre-commit Requirements**:
+   - **ALWAYS run all tests locally** before committing any changes
+   - **ALL tests must pass** before pushing to remote
+   - **Format code** with Black before committing
+   - **Work incrementally** with small, atomic commits
+
+4. **Incremental Development**:
+   - Make small, focused changes
+   - Commit frequently with descriptive messages
+   - Each commit should represent a working state
+   - Push regularly to avoid conflicts
+
+### Mandatory Test Execution
+
+```bash
+# Before ANY commit, run:
+python -m pytest tests/ -v                    # All tests must pass
+black src/ tests/                            # Format code
+python -m pytest --cov=src tests/           # Verify coverage
+```
+
+**⚠️ Never commit or push if tests are failing or not written for new functionality.**
+
 ## Project Overview
 
 This is a **Model Context Protocol (MCP) server** for Meilisearch, allowing LLM interfaces like Claude to interact with Meilisearch search engines. The project implements a Python-based MCP server that provides comprehensive tools for index management, document operations, search functionality, and system monitoring.
@@ -19,26 +68,29 @@ uv pip install -e .
 uv pip install -r requirements-dev.txt
 ```
 
-### Testing
+### Testing (MANDATORY for all development)
 ```bash
-# Run all tests
+# Run all tests (required before any commit)
 python -m pytest tests/ -v
 
 # Run specific test file
-python -m pytest tests/test_mcp_integration.py -v
+python -m pytest tests/test_mcp_client.py -v
 
-# Run tests with coverage
+# Run tests with coverage (required for new features)
 python -m pytest --cov=src tests/
 
-# Run integration tests (requires running Meilisearch)
-python -m pytest tests/test_mcp_integration.py -v
+# Watch mode for development (optional)
+pytest-watch tests/
 ```
 
-### Code Quality
+### Code Quality (MANDATORY before commit)
 ```bash
-# Format code (Black >=23.0.0)
+# Format code (required before commit)
 black src/ tests/
 
+# Check formatting without applying
+black --check src/ tests/
+
 # Run the MCP server locally for testing
 python -m src.meilisearch_mcp
 
@@ -94,21 +146,38 @@ All MCP tools follow a consistent pattern:
 ## Testing Strategy
 
 ### Test Structure
-- **Integration Tests** (`test_mcp_integration.py`): End-to-end MCP tool execution with real Meilisearch
-- **Synchronous Tests** (`test_mcp_sync.py`, `test_mcp_simple.py`): Simplified testing avoiding async complications
-- **Unit Tests** (`test_server.py`): Basic server instantiation
+- **Integration Tests** (`test_mcp_client.py`): End-to-end MCP tool execution with real Meilisearch
+- **Unit Tests** (`test_server.py`): Basic server instantiation and configuration
+
+### Test Categories by Development Task
+
+#### When Tests are REQUIRED:
+- **New MCP Tools**: Add tests to `test_mcp_client.py` using `simulate_tool_call()`
+- **Existing Tool Changes**: Update corresponding test methods
+- **Manager Class Changes**: Test through MCP tool integration
+- **Bug Fixes**: Add regression tests to prevent reoccurrence
+- **API Changes**: Update tests to reflect new interfaces
+
+#### When Tests are OPTIONAL:
+- **Documentation Updates**: README.md, CLAUDE.md changes
+- **Code Formatting**: Black formatting, comment changes
+- **Minor Refactoring**: Internal reorganization without behavior changes
 
-### Tool Simulation
+### Tool Simulation Framework
 Tests use `simulate_tool_call()` function that:
 - Directly invokes server tool handlers
-- Bypasses MCP protocol overhead
+- Bypasses MCP protocol overhead  
 - Returns proper `TextContent` responses
 - Provides comprehensive coverage of all 20+ tools
+- Enables fast test execution without MCP protocol complexity
 
-### Test Isolation
+### Test Isolation and Best Practices
 - **Unique Index Names**: Timestamped index names prevent test interference
-- **Cleanup Fixtures**: Automatic test environment cleanup
+- **Cleanup Fixtures**: Automatic test environment cleanup after each test
 - **Service Dependencies**: Tests require running Meilisearch instance
+- **Test Naming**: Use descriptive test method names (e.g., `test_create_index_with_primary_key`)
+- **Assertions**: Test both success cases and error handling
+- **Coverage**: New tools must have comprehensive test coverage
 
 ## Environment Configuration
 
diff --git a/README.md b/README.md
index b6fe928..91e26e2 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,9 @@ cd meilisearch-mcp
 uv venv
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 uv pip install -e .
+
+# Install development dependencies (for testing and development)
+uv pip install -r requirements-dev.txt
 ```
 
 ## Requirements
@@ -33,6 +36,68 @@ uv pip install -e .
 - Running Meilisearch instance
 - Node.js (for testing with MCP Inspector)
 
+## Development Setup
+
+### Prerequisites
+
+1. **Start Meilisearch server**:
+   ```bash
+   # Using Docker (recommended for development)
+   docker run -d -p 7700:7700 getmeili/meilisearch:v1.6
+   
+   # Or using brew (macOS)
+   brew install meilisearch
+   meilisearch
+   
+   # Or download from https://github.com/meilisearch/meilisearch/releases
+   ```
+
+2. **Install development tools**:
+   ```bash
+   # Install uv for Python package management
+   pip install uv
+   
+   # Install Node.js for MCP Inspector testing
+   # Visit https://nodejs.org/ or use your package manager
+   ```
+
+### Running Tests
+
+This project includes comprehensive integration tests that verify MCP tool functionality:
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Run specific test file
+python -m pytest tests/test_mcp_client.py -v
+
+# Run tests with coverage report
+python -m pytest --cov=src tests/
+
+# Run tests in watch mode (requires pytest-watch)
+pytest-watch tests/
+```
+
+**Important**: Tests require a running Meilisearch instance on `http://localhost:7700`. The tests will:
+- Create temporary test indices with unique names
+- Test all MCP tools end-to-end
+- Clean up test data automatically
+- Verify error handling and edge cases
+
+### Code Quality
+
+```bash
+# Format code with Black
+black src/ tests/
+
+# Run type checking (if mypy is configured)
+mypy src/
+
+# Lint code (if flake8 is configured)
+flake8 src/ tests/
+```
+
 ## Usage
 
 ### Environment Variables
@@ -182,10 +247,45 @@ npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp
 
 ## Contributing
 
-1. Fork repository
-2. Create feature branch
-3. Commit changes
-4. Create pull request
+We welcome contributions! Please follow these guidelines:
+
+1. **Fork and clone** the repository
+2. **Set up development environment** following the Development Setup section above
+3. **Create a feature branch** from `main`
+4. **Write tests first** if adding new functionality (Test-Driven Development)
+5. **Run tests locally** to ensure all tests pass before committing
+6. **Format code** with Black and ensure code quality
+7. **Commit changes** with descriptive commit messages
+8. **Push to your fork** and create a pull request
+
+### Development Workflow
+
+```bash
+# Create feature branch
+git checkout -b feature/your-feature-name
+
+# Make your changes, write tests first
+# Edit files...
+
+# Run tests to ensure everything works
+python -m pytest tests/ -v
+
+# Format code
+black src/ tests/
+
+# Commit and push
+git add .
+git commit -m "Add feature description"
+git push origin feature/your-feature-name
+```
+
+### Testing Guidelines
+
+- All new features should include tests
+- Tests should pass before submitting PRs
+- Use descriptive test names and clear assertions
+- Test both success and error cases
+- Ensure Meilisearch is running before running tests
 
 ## License