Skip to content

CLAUDE.md

Latest commit

 

History

History
168 lines (129 loc) · 6.71 KB

CLAUDE.md

File metadata and controls

168 lines (129 loc) · 6.71 KB
Raw

CLAUDE.md - AI Assistant Context & Instructions

This file provides essential context for AI assistants working on the MCPEG project.

Project Overview

MCPEG (Model Context Protocol Enablement Gateway) is a lightweight service that provides a Model Context Protocol (MCP) API on one side and integrates with external services via API calls or binary invocations on the other side.

Key Context for AI Assistants

Development Methodology: XVC Framework

This project follows the XVC (Extreme Vibe Coding) principles for human-LLM collaboration:

  1. Single Source of Truth: Every piece of information exists in exactly one place
  2. No Redundancy: Eliminate duplication across all systems
  3. Surgical Precision: Every change is intentional and well-documented
  4. Bar-Raising Solutions: Only implement patterns that improve the overall system
  5. Forward Progress Only: No regression, always building on solid foundations
  6. Always Solve Never Mask: Address root causes, not symptoms

Current Architecture

  • Unified Binary: Single mcpeg binary with subcommands (gateway, codegen, validate)
  • API-First: All functionality derives from OpenAPI specifications
  • Single Source of Truth Build: All build logic centralized in scripts/build.sh
  • Module Path: github.com/osakka/mcpeg

Essential Patterns

  1. Build System: Always use scripts/build.sh or delegate via Makefile
  2. CLI Interface: Use mcpeg <subcommand> pattern consistently
  3. Logging: LLM-optimized structured logging for complete debuggability
  4. Error Handling: Comprehensive error context for troubleshooting
  5. Documentation: All decisions documented in ADRs

Standardized "Wrapup" Checklist

When completing any significant task, execute this checklist when the user mentions 'wrapup':

1. Code Quality & Consistency

  • Run linting and formatting tools
  • Verify all imports use correct module path (github.com/osakka/mcpeg)
  • Ensure unified binary usage throughout codebase
  • Check for any remaining separate binary references

2. Documentation Updates

  • Create or update relevant ADR if architectural decisions were made
  • Update CHANGELOG.md with changes (Added/Changed/Fixed sections)
  • Verify README.md reflects current functionality
  • Update project structure documentation if needed
  • Check all documentation for module path consistency

3. Testing & Validation

  • Build and test the unified binary functionality
  • Verify all subcommands work correctly
  • Run any existing tests
  • Validate OpenAPI specifications if modified

4. Git Operations

  • Stage all relevant changes
  • Create descriptive commit message following project patterns
  • Include "🤖 Generated with Claude Code" footer
  • Add "Co-Authored-By: Claude" line
  • Push to remote repository (if requested)

5. Communication

  • Summarize what was accomplished
  • Note any breaking changes or migration requirements
  • Highlight any remaining work or follow-up tasks

Common Patterns to Follow

Commit Message Format

feat: implement [feature description]

[Detailed explanation of changes]

Changes:
- Bullet point list of specific changes
- Focus on the "what" and "why"

Benefits:
- List of benefits or improvements

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

File Structure Principles

  • cmd/: Application entry points only
  • internal/: Private application code
  • pkg/: Public reusable packages
  • api/: OpenAPI specifications
  • docs/: All documentation with clear categorization
  • scripts/: Build and utility scripts
  • build/: Build artifacts (gitignored)

Development Workflow

  1. Always read existing code to understand patterns
  2. Use existing utilities and frameworks
  3. Follow single source of truth principle
  4. Document architectural decisions in ADRs
  5. Update CHANGELOG.md for all changes
  6. Maintain unified binary architecture

Build System Usage

# Standard commands
./scripts/build.sh build      # Build unified binary
./scripts/build.sh dev        # Start development server  
./scripts/build.sh test       # Run tests
./scripts/build.sh validate   # Validate OpenAPI specs

# Via Makefile (delegates to build script)
make build
make dev
make test
make validate

Current Status

  • ✅ Unified binary architecture implemented
  • ✅ Single source of truth build system
  • ✅ Service registry and routing
  • ✅ OpenAPI-based code generation
  • ✅ MCP Plugin Integration (Phases 1-4)
    • ✅ Phase 1: Plugin access control and routing consistency
    • ✅ Phase 2: Plugin discovery with capability analysis
      • ✅ Capability Analysis Engine with semantic categorization
      • ✅ Plugin Discovery Engine with dependency resolution
      • ✅ Capability Aggregation Engine with conflict resolution
      • ✅ Capability Validation Engine with automated remediation
    • ✅ Phase 3: Inter-plugin communication with message passing and event bus
    • ✅ Phase 4: Hot plugin reloading with versioning and operation tracking
  • ✅ MCP endpoints for plugin management and inter-plugin communication
  • ✅ Plugin ecosystem with reloading operations
  • ✅ MCP Testing Infrastructure: Test client, integration tests, and MCP Inspector configuration
  • ✅ Concurrency Implementation: Thread-safe capability analysis with mutex synchronization
  • ✅ Documentation Improvements: Comprehensive package-level documentation with LLM-optimized structure
  • ✅ MIT License: Open source licensing for community development
  • ✅ Truth in Documentation: Removed false production-ready claims, added experimental disclaimer
  • ✅ Complete MCP Resources/Read Implementation: Full protocol compliance with plugin resource access via URI
  • ✅ Comprehensive ADR Timeline: Complete architectural decision records from project inception (ADR-001 to ADR-027)
  • ✅ Single Source of Truth Validation: Eliminated duplicate data files and enforced path standardization

Important Notes

  • Never create separate binaries - always use unified mcpeg binary
  • Always check module paths - use github.com/osakka/mcpeg
  • Build system is source of truth - modify scripts/build.sh not Makefile
  • Document decisions - create ADRs for architectural changes
  • LLM-optimized logging - every log entry should provide complete context

Code Style and Conventions

  • We don't use - we always use -- for long flags

Project Details

  • Project Characteristics:
    • This is an MCP server

This context file should be consulted before making any significant changes to ensure consistency with project principles and patterns.