# Hephaestus: Complete Anvil MCP Server

![Python Version](https://img.shields.io/badge/python-3.13+-blue.svg)
![Licence](https://img.shields.io/badge/licence-MIT-green.svg)
![Status](https://img.shields.io/badge/status-in%20development-orange.svg)

The comprehensive Model Context Protocol (MCP) server for complete Anvil development coverage - from fundamental operations to advanced modern architecture patterns.

## Quick Start

Hephaestus provides intelligent tools for every aspect of Anvil development:

- **Modern Apps**: Material 3 + Reactive + Official Routing + Layouts + Model Classes
- **Legacy Apps**: Comprehensive support with guided modernisation paths
- **All Operations**: Data tables, authentication, forms, deployment, and beyond

### Installation

#### Preferred Method: uvx (Multi-Session Support)

For users who need multiple concurrent sessions or the latest version:

```bash
# Install uvx if you don't have it
pip install uvx

# Run Hephaestus MCP server
uvx hephaestus-mcp-server
```

**Why uvx?** Unlike global installation, uvx creates isolated environments that support multiple concurrent sessions without conflicts.

#### Alternative: Global Installation (Single Session Only)

```bash
pip install hephaestus-mcp-server
hephaestus-mcp-server
```

> **Note**: Global installation only supports single sessions and may cause conflicts with multiple concurrent MCP connections.

### MCP Client Configuration

Add Hephaestus to your MCP client configuration:

#### OpenCode
```json
{
  "mcpServers": {
    "hephaestus": {
      "command": "uvx",
      "args": ["hephaestus-mcp-server"]
    }
  }
}
```

#### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "hephaestus": {
      "command": "uvx", 
      "args": ["hephaestus-mcp-server"]
    }
  }
}
```

#### Global Installation Alternative
If using global installation:
```json
{
  "mcpServers": {
    "hephaestus": {
      "command": "hephaestus-mcp-server"
    }
  }
}
```

## Usage

Once configured, Hephaestus provides intelligent tools for:

### New Projects
```
Create a complete modern Anvil app with Material 3 + Reactive + Routing
```

### Existing Projects  
```
Analyse your app's patterns and get modernisation recommendations
```

### Component Generation
```
Generate reactive pages, forms, and data tables with optimal patterns
```

### Migration Support
```
Upgrade legacy code with guided step-by-step modernisation
```

## Key Capabilities

**Foundation Development**
- Data table operations (CRUD, search, relationships, validation)
- User authentication and management (login, signup, permissions, MFA)
- Client-server communication (callable functions, error handling, security)
- Form creation and navigation (basic forms, complex workflows, data binding)
- File and media management (upload, download, processing, storage)

**Advanced UI/UX Development**
- Custom component creation (HTML components, JavaScript integration)
- Theme and CSS manipulation (Material Design, responsive design)
- Interactive interfaces (drag-and-drop, animations, dynamic layouts)
- Cross-platform compatibility (mobile web, PWA features, accessibility)

**Business Logic & Integration**
- Email services (transactional emails, templates, incoming messages)
- Payment processing (Stripe integration, subscriptions, financial workflows)
- External API integration (REST clients, webhook handlers, data sync)
- Background task processing (long-running jobs, queues, progress tracking)

**Production Operations**
- Testing and quality assurance (unit tests, UI automation, performance)
- Monitoring and analytics (performance tracking, user behaviour, error reporting)
- Security and compliance (vulnerability scanning, GDPR tools, audit logging)
- Deployment and DevOps (CI/CD pipelines, environment management, scaling)

## Modern Architecture

Hephaestus specializes in modern Anvil development patterns:

### Core Technologies
1. **[Material 3 Theme](https://anvil.works/dependencies/4UK6WHQ6UX7AKELK)** - Modern Material Design 3 components
2. **[Official Routing](https://anvil.works/dependencies/3PIDO5P3H4VPEMPL)** - Modern routing with data loading
3. **[Reactive Library](https://anvil.works/dependencies/N7KFE4YBWMGWJ5OX)** - Signals-based state management
4. **Model Classes** - Type-safe, validated data models with relationships
5. **Layouts System** - Slot-based layout architecture
6. **Tabulator Integration** - High-performance reactive data tables

### Intelligent Generation

Hephaestus analyzes your project to determine optimal patterns:

- **Modern Apps** (Score 0.8+): Full modern stack with enterprise features
- **Transitioning Apps** (Score 0.4-0.8): Enhanced patterns with strategic modernisation
- **Legacy Apps** (Score 0-0.4): Compatible patterns with modernisation suggestions

## For Developers

Development documentation, architecture details, and contribution guidelines are available in [CONTRIBUTING.md](CONTRIBUTING.md).

## Project Management

This project uses **Radicle** as its primary project management system with GitHub mirroring:

- **Radicle Repository**: `rad:zwcVaZPYRXt8uA3uaBuUiH8hXzMw`
- **Browse Repository**: https://app.radicle.xyz/nodes/rosa.radicle.xyz/rad%3AzwcVaZPYRXt8uA3uaBuUiH8hXzMw
- **GitHub Mirror**: https://github.com/empiria/hephaestus
- **Issue Tracking**: Managed via Radicle issues

## Licence

This project is licensed under the MIT Licence - see the [LICENCE](LICENCE) file for details.

## Acknowledgements

- **Anvil Team**: For creating an amazing platform and continuously pushing forward with modern technologies
- **MCP Community**: For developing the Model Context Protocol that makes intelligent tooling possible

---

*Hephaestus: Forging the future of Anvil development, one perfectly crafted component at a time.*