# Hephaestus Project Overview

## Project Purpose
Hephaestus is a comprehensive Model Context Protocol (MCP) server for complete Anvil development coverage. It provides intelligent context-aware code generation for all aspects of Anvil development - from fundamental operations to advanced modern architecture patterns.

## Core Philosophy
- **Complete Coverage**: Tools for every aspect of Anvil development
- **Modern by Default**: Material 3 + Reactive + Official Routing + Layouts + Model Classes
- **Production Ready**: Enterprise-grade security, monitoring, testing, and deployment
- **Performance First**: Generate optimal, efficient patterns without compromise
- **Legacy Respectful**: Comprehensive support for all Anvil patterns since v1.0
- **Minimal Toolchain**: Fast, reliable development with modern Python 3.13+

## Project Management

Hephaestus uses **Radicle** as its primary project management system - a decentralized, peer-to-peer code collaboration platform. This means:

- **Issue Tracking**: All project phases and tasks are managed via Radicle issues
- **Code Collaboration**: Development happens through Radicle's decentralized network  
- **GitHub Mirror**: The repository is mirrored to GitHub (https://github.com/empiria/hephaestus) for public access and distribution
- **MCP Integration**: radicle-mcp-server provides seamless Radicle operations within development workflow

### Development Workflow
1. **Project Management**: Track progress via Radicle issues (5-phase implementation plan)
2. **Code Development**: Work with Radicle's decentralized version control
3. **GitHub Sync**: Mirror changes to GitHub for public distribution
4. **Package Publishing**: Publish to PyPI from GitHub Actions (when implemented)

## Tech Stack

### Core Infrastructure
- **Python**: >=3.13 (modern Python features)
- **Build System**: hatchling (minimal, fast builds)
- **MCP Framework**: fastmcp>=0.11.0 (lightweight MCP server)
- **Dependencies**: Minimal core set (attrs, mcp, pyyaml, typer)
- **Project Management**: Radicle (decentralized collaboration via radicle-mcp-server)
- **Publication**: GitHub mirror at https://github.com/empiria/hephaestus

### Development Tools
- **Package Manager**: uv (fast Python package management)
- **Task Runner**: just (command recipes)
- **Linting**: ruff (fast Python linting and formatting)
- **Type Checking**: basedpyright (minimal type checking)
- **Testing**: pytest (minimal testing framework)

### Anvil Technologies Supported
1. Material 3 Theme - Modern Material Design 3 components and layouts
2. Official Routing - Modern routing with data loading and caching
3. Reactive Library - Signals-based state management for automatic UI updates
4. Model Classes - Type-safe, validated data models with automatic serialisation
5. Layouts System - Slot-based layout architecture replacing traditional panels
6. Tabulator Integration - High-performance reactive data tables

## Project Structure
```
hephaestus/
├── src/
│   ├── __init__.py
│   └── server.py          # Main MCP server entry point
├── tests/                 # Test suite (currently empty)
├── docs/                  # Documentation (currently empty)
├── pyproject.toml         # Hatchling-based configuration
├── justfile              # Development commands
├── AGENTS.md             # Technical specifications for AI agents
├── anvil_yaml_reference.md # Anvil YAML component specification
├── opencode.json         # MCP configuration with radicle-mcp-server
├── plan.md              # 5-phase implementation plan
└── README.md             # Project documentation
```

### Radicle Integration
- **Repository ID**: `rad:zwcVaZPYRXt8uA3uaBuUiH8hXzMw`
- **Issue Management**: 5-phase plan tracked via Radicle issues
- **MCP Integration**: radicle-mcp-server for seamless operations
- **GitHub Mirror**: https://github.com/empiria/hephaestus

## Current State
- **Version**: 0.1.0 (in development)
- **Server**: Basic MCP server structure implemented
- **Tools**: TODO - Comprehensive Anvil development tools to be added
- **Tests**: Test structure ready, no tests implemented yet
- **Documentation**: Comprehensive specifications in AGENTS.md
- **Project Management**: 5-phase implementation plan tracked via Radicle issues
- **Radicle Integration**: radicle-mcp-server configured and operational

## Intelligent Context System
Hephaestus uses intelligent project analysis to determine optimal code generation:
- **Modern Apps** (Score 0.8+): Full modern stack
- **Transitioning Apps** (Score 0.4-0.8): Enhanced patterns with strategic modernisation
- **Legacy Apps** (Score 0-0.4): Compatible patterns with modernisation suggestions

## Development Approach
- **Minimal & Focused**: Core functionality first, incremental growth
- **Modern Toolchain**: Python 3.13+, FastMCP, hatchling, minimal dependencies
- **Developer Experience**: Fast, reliable tooling that stays out of your way
- **Quality First**: Built-in validation for Anvil best practices and performance