# Basic Usage Examples for Hephaestus MCP Server

## Project Analysis

### Analyze a Project
```bash
# Call the analyse_project_context tool
mcp call analyse_project_context --project_path "/path/to/your/anvil/project"
```

### Example Response
```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": []
  }
}
```

## Form Generation

### Generate a Basic Form
```bash
# Call the create_anvil_form tool
mcp call create_anvil_form --form_config '{
  "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"
      }
    }
  ]
}' --output_path "./UserForm.yaml"
```

### Example Response
```json
{
  "success": true,
  "message": "Form generated successfully at UserForm.yaml",
  "output_path": "./UserForm.yaml"
}
```

## Modernisation Suggestions

### Get Modernisation Suggestions
```bash
# Call the suggest_modernisations tool
mcp call suggest_modernisations --project_context '{
  "theme_type": "classic",
  "has_reactive": false,
  "data_layer": "raw-tables"
}'
```

### Example Response
```json
{
  "success": true,
  "suggestions": [
    {
      "type": "theme",
      "suggestion": "Upgrade to Material 3",
      "benefit": "Modern design, better UX, accessibility",
      "effort": "medium"
    },
    {
      "type": "reactive",
      "suggestion": "Add reactive library",
      "benefit": "Automatic UI updates, better state management",
      "effort": "low"
    }
  ],
  "total_suggestions": 2
}
```

## Configuration

### Using Custom Configuration
```bash
# Create a custom config file
cat > my-hephaestus.yaml << EOF
default_theme: "classic"
enable_reactive: false
output_directory: "./my-generated"
EOF

# Run server with custom config
hephaestus-mcp-server --config my-hephaestus.yaml
```

## Error Handling

All tools provide structured error responses:

### Validation Error Example
```json
{
  "success": false,
  "error": "Validation failed: Invalid component type: InvalidComponent",
  "error_type": "VALIDATION_ERROR",
  "suggestion": "Please check your input parameters and try again"
}
```

### Analysis Error Example
```json
{
  "success": false,
  "error": "Project not found",
  "error_type": "ANALYSIS_ERROR",
  "suggestion": "Please check that the project path is correct and the project is a valid Anvil project"
}
```

## Integration with Development Workflow

### 1. Project Setup
```bash
# Create new Anvil project
mkdir my-new-app
cd my-new-app

# Initialize as Hephaestus project
hephaestus-mcp-server --init --name "MyApp" --description "My new Anvil application"
```

### 2. Iterative Development
```bash
# Analyze existing project
hephaestus-mcp-server analyse_project_context --project_path .

# Generate forms based on analysis
hephaestus-mcp-server create_anvil_form --form_config "$(cat form-config.json)"

# Get modernisation suggestions
hephaestus-mcp-server suggest_modernisations --project_context "$(hephaestus-mcp-server analyse_project_context --project_path . | jq -r .context)"
```

### 3. Testing
```bash
# Run tests
uv run pytest tests/

# Lint and format
uv run ruff check src/ && uv run ruff format src/

# Type check
uv run basedpyright check src/
```

## Best Practices

1. **Always validate form configurations** before generation
2. **Use project analysis** to determine optimal generation approach
3. **Start with simple forms** and gradually add complexity
4. **Test generated forms** in Anvil before deployment
5. **Use configuration management** for consistent settings across projects
6. **Leverage modernisation suggestions** to improve existing projects incrementally