Skip to content

CLAUDE.md

Latest commit

 

History

History
164 lines (123 loc) · 5.52 KB

CLAUDE.md

File metadata and controls

164 lines (123 loc) · 5.52 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Installation and Setup

# Using uv (recommended)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Using pip
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Dependency Rules

  • Keep Python dependency specifiers exact where this repository already pins them, including test extras and build-system.
  • If pyproject.toml changes affect resolved packages, verify the result through the lock/install path used by CI.
  • Do not introduce floating versions in CI or release automation when exact pins are practical.

Running the MCP Server

# Basic run with stdio transport
python src/codealive_mcp_server.py

# With debug mode enabled
python src/codealive_mcp_server.py --debug

# With SSE transport
python src/codealive_mcp_server.py --transport sse --host 0.0.0.0 --port 8000

# With custom API key and base URL
python src/codealive_mcp_server.py --api-key YOUR_KEY --base-url https://custom.url

Docker Usage

# Build Docker image
docker build -t codealive-mcp .

# Run with Docker
docker run --rm -i -e CODEALIVE_API_KEY=your_key_here codealive-mcp

Testing

Quick Smoke Test

After making local changes, quickly verify everything works:

# Using make (recommended)
make smoke-test

# Or directly
python smoke_test.py

# With valid API key for full testing
CODEALIVE_API_KEY=your_key python smoke_test.py

The smoke test:

  • ✓ Verifies server starts and connects via stdio
  • ✓ Checks all tools are registered correctly
  • ✓ Tests each tool responds appropriately
  • ✓ Validates parameter handling
  • ✓ Runs in ~5 seconds

Unit Tests

Run comprehensive unit tests with pytest:

# Using make
make unit-test

# Or directly
pytest src/tests/ -v

# With coverage
pytest src/tests/ -v --cov=src

All Tests

Run both smoke tests and unit tests:

make test

Architecture

This is a Model Context Protocol (MCP) server that provides AI clients with access to CodeAlive's semantic code search and analysis capabilities.

Core Components

  • codealive_mcp_server.py: Main server implementation using FastMCP framework
  • Three main tools: codebase_consultant, codebase_search, get_data_sources
  • CodeAliveContext: Manages HTTP client and API credentials
  • Async lifespan management: Handles client setup/teardown

Key Architectural Patterns

  1. FastMCP Framework: Uses modern async Python MCP implementation with lifespan context management
  2. HTTP Client Management: Single persistent httpx.AsyncClient with proper connection pooling
  3. Streaming Support: Implements streaming chat completions with proper chunk parsing
  4. Environment Configuration: Supports both .env files and command-line arguments with precedence
  5. Error Handling: Comprehensive HTTP status code handling with user-friendly error messages
  6. N8N Middleware: Strips extra parameters (sessionId, action, chatInput, toolCallId) from n8n tool calls before validation

Data Flow

  1. AI client connects to MCP server via stdio/SSE transport
  2. Client calls tools (get_data_sources → codebase_search → codebase_consultant)
  3. MCP server translates tool calls to CodeAlive API requests
  4. CodeAlive API returns semantic search results or chat completions
  5. Server formats and returns results to AI client

Environment Variables

  • CODEALIVE_API_KEY: Required API key for CodeAlive service
  • CODEALIVE_BASE_URL: API base URL (defaults to https://app.codealive.ai)
  • CODEALIVE_IGNORE_SSL: Set to disable SSL verification (debug mode)

Data Source Types

  • Repository: Individual code repositories with URL and repository ID
  • Workspace: Collections of repositories accessible via workspace ID
  • Tool calls can target specific repositories or entire workspaces for broader context

Integration Patterns

The server is designed to integrate with:

  • Claude Desktop/Code (via settings.json configuration)
  • Cursor (via MCP settings panel)
  • VS Code with GitHub Copilot (via settings.json)
  • Continue (via config.yaml)
  • n8n (via AI Agent node with MCP tools)
  • Any MCP-compatible AI client

Key integration considerations:

  • AI clients should use get_data_sources first to discover available repositories/workspaces, then use those IDs for targeted search and chat operations
  • n8n Integration: The server includes middleware to automatically strip n8n's extra parameters (sessionId, action, chatInput, toolCallId) from tool calls, so n8n works out of the box without any special configuration

Publishing and Releases

Version Management

When making significant changes, consider incrementing the version in pyproject.toml:

version = "0.3.0"  # Increment for new features, bug fixes, or breaking changes

Automated Publishing

The project uses automated publishing:

  • Trigger: Push version change to main branch
  • Process: Tests → Build → Docker → MCP Registry → GitHub Release
  • Result: Available at io.github.codealive-ai/codealive-mcp in MCP Registry

Version Guidelines

  • Patch (0.2.0 → 0.2.1): Bug fixes, minor improvements
  • Minor (0.2.0 → 0.3.0): New features, enhancements
  • Major (0.2.0 → 1.0.0): Breaking changes, major releases

When implementing features or fixes, evaluate if they warrant a version bump for users to benefit from the changes through the MCP Registry.