Skip to content

CLAUDE.md

Latest commit

 

History

History
94 lines (71 loc) · 4.13 KB

CLAUDE.md

File metadata and controls

94 lines (71 loc) · 4.13 KB

CLAUDE.md

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

🤓 MCP-Tools

  • use rust-crate-doc tool to query specific info on crates, traits, etc.
  • use context7 for information on all other documentation
  • use sequential thinking for small step by step planning
  • use taskmaster-ai for big picture phases

Project Overview

This is just-mcp, a production-ready MCP (Model Context Protocol) server for Justfile integration. Current Status: 67% complete (8/12 core tasks done) with full rmcp 0.3.0 integration already implemented and tested.

✅ Major Milestones Completed

  • ✅ Complete MCP Server - Full rmcp 0.3.0 integration with MCP 2024-11-05 protocol
  • ✅ Recipe Discovery & Execution - Parse, list, and execute Justfile recipes with parameters
  • ✅ Comprehensive Testing - 33 passing tests including integration and unit test suites
  • ✅ Environment Management - .env file support and variable expansion
  • ✅ Production Ready - Structured error handling, async support, JSON-RPC compliance

Architecture

The project is designed to be a Rust-based MCP server that provides:

  • Justfile parsing and introspection
  • Recipe execution with structured output
  • LSP-style completion and validation
  • JSON-RPC interface for LLM integration

Based on TODO.pm, the planned architecture includes:

  • just-mcp binary crate (CLI interface)
  • just-mcp-lib library crate (core functionality)
  • 12-phase development roadmap from basic parsing to full MCP protocol compliance

Development Environment

This project follows the b00t development methodology as documented in AGENTS.md:

Tech Stack

  • Rust: Stable 1.82+ with cargo CLI
  • Error Handling: Use snafu crate for structured error management
  • Development Tools: just command runner, uv/uvx for Python tooling

Development Practices

  • TDD: Add tests first, then implement code
  • Git Workflow: Never work directly on main/dev branch - always create feature branches
  • 6C Turbo-Agile: Use contextual comments → commit code → cleanup/cull pattern for refactoring
  • Branch Naming: Use feature/, fix/, or chore/ prefixes with GitHub issue numbers

Commands

The project has a fully functional build system with justfile automation:

  1. Build: cargo build or just build
  2. Test: cargo test or just test (runs 33 tests)
  3. Run MCP Server: cargo run -- --stdio or just server
  4. Clean: cargo clean or just clean
  5. Integration Testing: cargo test --test basic_mcp_test or cargo test --test mcp_integration_working

Code Style

  • Use ? operator for error propagation
  • Implement modular error types with snafu
  • Provide laconic, clear error messages
  • Never modify Cargo.toml directly - use cargo CLI commands
  • Use xtask patterns for complex build tasks

Current Status: 67% Complete ✅

The project is production-ready with comprehensive functionality:

✅ Implemented (8/12 tasks)

  • Complete MCP Server (src/main.rs, just-mcp-lib/src/mcp_server.rs)
  • Justfile Parser (just-mcp-lib/src/parser.rs)
  • Recipe Executor (just-mcp-lib/src/executor.rs)
  • Validation System (just-mcp-lib/src/validator.rs)
  • Environment Support (just-mcp-lib/src/environment.rs)
  • Full Test Coverage (tests/ directory with 33 passing tests)

🎯 Next Priority Tasks (4 remaining)

  1. LSP-Style Completion System - Intelligent autocompletion for recipes/parameters
  2. Enhanced Diagnostics - Advanced syntax error reporting
  3. Virtual File System - Support for stdin/remote sources
  4. Release Preparation - Documentation, CI/CD, crate publication

🧪 Testing Infrastructure

  • tests/basic_mcp_test.rs - Direct protocol compliance testing
  • tests/mcp_integration_working.rs - Type-safe SDK integration testing
  • Unit tests - Parser, executor, validator, environment modules
  • 33 total tests - All passing with comprehensive coverage

🚀 Ready for Production Use

The MCP server is fully functional and can be integrated with Claude Desktop or other MCP clients immediately.