task-crusader-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

Task Crusader MCP is a campaign and task management system designed for AI coding assistants. It provides a Model Context Protocol (MCP) server with 24 tools for organizing work into campaigns and tasks with dependency tracking, acceptance criteria, and progress monitoring.

Key Interfaces:

• MCP Server (crusader-mcp): stdio-based MCP server for AI assistants
• CLI (crusader): Command-line interface using Typer
• TUI (crusader-tui): Terminal UI using Textual

Development Commands

Build and Test

# Run all CI checks (required before pushing)
./scripts/check_ci.sh

# Run tests
pytest                                    # All tests
pytest tests/unit/                        # Unit tests only
pytest tests/integration/                 # Integration tests only
pytest -m database                        # Database tests only
pytest path/to/test.py::test_name -v     # Single test

# Run tests with coverage
pytest --cov --cov-report=html            # Generate HTML coverage report
pytest --cov --cov-fail-under=65          # Enforce minimum coverage (CI requirement)

# Linting and formatting
ruff check src/ tests/                    # Lint code
black src/ tests/                         # Format code
isort src/ tests/                         # Sort imports
mypy src/                                 # Type checking (optional)

Package Management

# Install for development
pip install -e .[dev]

# Build package
python -m build

# Version is managed by setuptools-scm (git tags)
# The _version.py file is auto-generated - never edit it

Database

# Database location: ~/.crusader/database.db
# Set custom path: export CRUSADER_DB_PATH=/path/to/db.db

# Reset development database
rm ~/.crusader/database.db  # Will be recreated on next run

# Migrations are automatic via Alembic on first run
# Tests use isolated temporary databases