circus-mcp: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

CircusMCP is a Domain-Driven Design (DDD) process management system that integrates Circus process manager with the Model Context Protocol (MCP). It enables AI agents to control development applications through standardized MCP tools and resources.

Architecture

The system follows a layered DDD architecture:

Controller → Service → Domain ← Infrastructure

• Controller Layer (src/controller/): MCP protocol handling and external interfaces
• Service Layer (src/service/): Application logic and use cases
• Domain Layer (src/domain/): Business logic and domain models (framework-independent)
• Infrastructure Layer (src/infrastructure/): Data access and external system integration

Key components:

• ProcessService: Manages Circus watchers and process lifecycle
• LogService: Background log processing with pattern classification
• MCPController: JSON-RPC 2.0 protocol implementation for AI agent communication
• Repository Pattern: Abstracted data access (currently in-memory, extensible to file/database)

Development Commands

Installation and Setup

# Install dependencies with uv
uv sync

# Install development dependencies
uv sync --extra dev

# Initialize project structure
uv run python main.py init --create-dirs

# Validate configuration
uv run python main.py validate

# Start Circus daemon (in separate terminal)
uv run circusd config/circus.ini

Running the Application

# Start MCP server (main application)
uv run python app.py

# Alternative CLI interface
uv run python main.py start

# Check status
uv run python main.py status

Testing

# Run all tests
uv run pytest tests/ -v

# Run specific test categories
uv run pytest tests/test_new_architecture.py -v
uv run pytest tests/ -m "not slow"
uv run pytest tests/ -m integration

# Run with coverage
uv run pytest tests/ --cov=src --cov-report=html

# Run single test
uv run pytest tests/test_new_architecture.py::TestNewArchitectureIntegration::test_full_stack_integration -v