foundry-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

Foundry MCP is a CLI tool and MCP server for deterministic project management and AI coding assistant integration. It manages project specifications in ~/.foundry/ directory structure, storing project context outside of actual codebases to prevent directory pollution.

Development Commands

Build & Test Commands

# Build the project
cargo build

# Build in release mode
cargo build --release

# Run all tests (166 tests currently passing)
cargo test

# Run with verbose test output
cargo test -- --nocapture

# Run integration tests specifically
cargo test --test integration_tests

# Run specific test
cargo test test_function_name

# Run Clippy (strict linting - all warnings denied)
cargo clippy -- -D warnings

# Format code
cargo fmt

Running the CLI

# Run as MCP server (default behavior)
cargo run

# Run CLI commands during development
cargo run -- --help
cargo run -- create-project "test-project" "vision content" "tech stack content"
cargo run -- list-projects
cargo run -- load-spec "project-name" "spec-id"

# Run with custom foundry directory for testing
cargo run -- --config-dir ./test-config serve --verbose

Architecture Overview

Core Module Structure

• src/main.rs - CLI entry point that dispatches to command handlers
• src/lib.rs - Library exports and foundry_dir() utility function
• src/cli/ - Command-line interface with arguments and command implementations
• src/core/ - Core business logic for projects, specs, and validation
• src/types/ - Type definitions for requests, responses, and data structures
• src/utils/ - Utility functions for paths, timestamps, and formatting

File System Organization

All project data stored in ~/.foundry/ directory:

~/.foundry/PROJECT_NAME/
├── vision.md      # High-level product vision
├── tech-stack.md  # Technology decisions
├── summary.md     # Concise summary for context loading
└── specs/
    └── YYYYMMDD_HHMMSS_FEATURE_NAME/
        ├── spec.md        # Feature specification
        ├── task-list.md   # Implementation checklist
        └── notes.md       # Additional context