# Hephaestus MCP Server API Documentation

## Overview

Hephaestus is a Model Context Protocol (MCP) server that provides comprehensive tools for Anvil development. It uses intelligent project analysis to determine the optimal generation approach for each project.

## Available Tools

### Project Analysis Tools

#### `analyse_project_context`
Analyzes an existing Anvil project to determine patterns, modernisation opportunities, and generation mode.

**Parameters:**
- `project_path` (string, required): Path to the Anvil project directory

**Returns:**
```json
{
  "success": true,
  "context": {
    "theme_type": "material-3",
    "routing_system": "official", 
    "has_reactive": true,
    "data_layer": "model-classes",
    "layout_system": "layouts",
    "modernisation_score": 0.8,
    "generation_mode": "modern",
    "performance_opportunities": ["reactive-optimisation", "layout-improvements"],
    "breaking_change_risks": []
  }
}
```

**Error Response:**
```json
{
  "success": false,
  "error": "Project not found",
  "error_type": "ANALYSIS_ERROR"
}
```

### Form Generation Tools

#### `create_anvil_form`
Generates Anvil form YAML from configuration with validation.

**Parameters:**
- `form_config` (object, required): Form configuration dictionary
- `output_path` (string, required): Output file path for generated YAML

**Form Configuration Example:**
```json
{
  "name": "UserForm",
  "container": {
    "type": "ColumnPanel",
    "properties": {"spacing": "medium"}
  },
  "components": [
    {
      "name": "textbox_name",
      "type": "TextBox",
      "properties": {
        "placeholder": "Enter your name",
        "role": "outlined"
      },
      "layout_properties": {
        "grid_position": "0,0"
      }
    },
    {
      "name": "button_submit",
      "type": "Button",
      "properties": {
        "text": "Submit",
        "role": "raised-button"
      },
      "layout_properties": {
        "grid_position": "1,0"
      },
      "event_bindings": {
        "click": "button_submit_click"
      }
    }
  ]
}
```

**Returns:**
```json
{
  "success": true,
  "message": "Form generated successfully at UserForm.yaml",
  "output_path": "UserForm.yaml"
}
```

### Modernisation Tools

#### `suggest_modernisations`
Suggests modernisation improvements based on project analysis.

**Parameters:**
- `project_context` (object, required): Project context from analysis

**Returns:**
```json
{
  "success": true,
  "suggestions": [
    {
      "type": "data_layer",
      "suggestion": "Migrate to model classes",
      "benefit": "Type safety, validation, automatic serialisation",
      "effort": "medium"
    }
  ],
  "total_suggestions": 1
}
```

## Generation Modes

The server automatically determines the generation mode based on project modernisation score:

- **Modern** (0.8+): Full M3 + Reactive + Routing + Layouts + Model Classes
- **Hybrid** (0.4-0.8): Enhanced patterns respecting existing architecture
- **Legacy-Compatible** (0-0.4): Compatible patterns with comprehensive support

## Error Handling

All tools return structured responses with consistent error handling:

- **Success Response**: `{"success": true, "data": {...}}`
- **Error Response**: `{"success": false, "error": "...", "error_type": "...", "suggestion": "..."}`

## Configuration

The server supports configuration via `hephaestus.yaml`:

```yaml
default_theme: "material-3"
default_routing: "official"
enable_reactive: true
output_directory: "./generated"
validation_strict: true
auto_backup: true
```

## Integration

The server integrates with FastMCP and provides:
- Real component validation against Anvil API
- Dependency injection for testability
- Comprehensive error handling with actionable messages
- Zero mocking except for file I/O when necessary