CoordMCP: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents (like OpenCode, Cursor, Claude Code) working on the CoordMCP codebase.

Project Overview

CoordMCP is a FastMCP-based Model Context Protocol server for multi-agent code coordination. It provides:

• Long-term memory for projects (decisions, tech stack, changes)
• Multi-agent context management and file locking
• Architecture guidance with rule-based pattern recommendations
• Task management and agent messaging
• Zero external API calls - all analysis is local

Build & Test Commands

# Install in development mode
pip install -e ".[dev]"

# Run all tests
python -m pytest src/tests/ -v

# Run unit tests only
python -m pytest src/tests/unit/ -v -m unit

# Run integration tests
python -m pytest src/tests/ -v -m integration

# Run end-to-end tests
python -m pytest src/tests/e2e/ -v

# Run with coverage
python -m pytest src/tests/ --cov=coordmcp --cov-report=html

# Run specific test file
python -m pytest src/tests/unit/test_memory/test_json_store.py -v

# Run server locally
python -m coordmcp

# Check version
coordmcp --version

Code Style

• Python Version: 3.10+ (uses modern type hints)
• Formatting: Follow PEP 8
• Type Hints: Required on all public functions
• Docstrings: Google-style docstrings with examples
• Line Length: 100 characters max
• Imports: Absolute imports from coordmcp.*

Example Function

async def save_decision(
    title: str,
    description: str,
    rationale: str,
    project_id: Optional[str] = None,
    tags: Optional[List[str]] = None
) -> Dict[str, Any]:
    """
    Save an architectural decision to project memory.
    
    Args:
        title: Decision title (e.g., "Use PostgreSQL")
        description: Detailed description
        rationale: Why this decision was made
        project_id: Project ID (optional if resolved by context)
        tags: Categorization tags
        
    Returns:
        Dictionary with decision_id and success status
        
    Example:
        result = await save_decision(
            title="Use FastAPI",
            description="FastAPI for REST API",
            rationale="Async support, type hints, auto docs"
        )
    """