# Modyo MCP Tools Summary

## Documentation Updated

This document summarizes the tools created and documentation updated based on the NeoBank implementation and clarification of Modyo's three page types.

## Key Learnings

### Page Types in Modyo
Modyo has **three distinct page types**, each with different capabilities:

1. **Widget Pages** (default/home) - Grid layouts, accept custom widgets
2. **Content Pages** (content/entry) - Connected to Content API, Liquid only, automatic drops
3. **Origination Pages** - Multi-step forms, no custom widgets

**Critical:** Custom widgets can ONLY be added to Widget Pages (type: default or home).

## Tools Created

### 1. Release Management Tools

#### `release-get-elements-to-publish`
- **Purpose**: Get list of unpublished elements (templates, pages, widgets, menus)
- **Use Case**: Check what needs publishing before creating release
- **Parameters**: platformSlug, siteId
- **Returns**: Arrays of publishable elements with IDs and metadata

#### `release-create`
- **Purpose**: Publish selected elements immediately or scheduled
- **Use Case**: Deploy widgets, templates, pages to production
- **Parameters**: platformSlug, siteId, data (element selections), publish_at, unpublish_at
- **Returns**: Success message after publishing

**Workflow:**
```typescript
// 1. Get publishable elements
release-get-elements-to-publish({ platformSlug, siteId })

// 2. Create release with selected elements
release-create({
  platformSlug,
  siteId,
  data: {
    widgetDefinition: [
      { id: 86713, selected: true },
      { id: 86714, selected: true }
    ]
  }
})
```

### 2. Widget Management Tools

#### `widget-get-custom-widgets`
- **Purpose**: List published custom widgets with their definition UUIDs
- **Use Case**: Get UUIDs needed for adding widgets to pages
- **Parameters**: platformSlug, siteId, query, sort_by, order, page, per_page
- **Returns**: Array of published widgets with definition_uuid (OID format)
- **Note**: Only shows PUBLISHED widgets (use release tools first)

**Workflow:**
```typescript
// After publishing widgets via release-create
widget-get-custom-widgets({ platformSlug, siteId })

// Extract definition_uuid from response
// Use UUID with page-add-widgets
```

### 3. Page Widget Management Tools

#### `page-add-widgets`
- **Purpose**: Add/update widgets on WIDGET PAGES only
- **Use Case**: Build dashboard layouts with multiple widgets
- **Parameters**: platformSlug, siteId, pageId, widgets array
- **Widget Types**: custom_widget, html, rich_text
- **Important**: Replaces ALL widgets on page, only works with widget pages
- **Returns**: Updated page object with all widgets

**Workflow:**
```typescript
// 1. Get widget UUIDs
widget-get-custom-widgets({ platformSlug, siteId })

// 2. Add widgets to page
page-add-widgets({
  platformSlug,
  siteId,
  pageId: 175255,
  widgets: [
    {
      type: "custom_widget",
      widget_definition_uuid: "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260",
      position: 0,
      column: 0,
      enabled: true
    }
  ]
})
```

### 4. Enhanced Page Creation Tool

#### `page-create` (Updated)
- **Purpose**: Create pages of all three types
- **New Parameters**:
  - `page_type`: 'default'|'home'|'content'|'entry'|'origination'
  - `content_type_id`: Required for content pages
  - `grid_type`: For widget pages only
- **Returns**: Created page object

**Examples:**

**Widget Page:**
```typescript
page-create({
  platformSlug: "fed-team",
  siteId: 4605,
  name: "Dashboard",
  path: "/dashboard",
  page_type: "default",
  grid_type: "full_three_cols_grid"
})
```

**Content Page:**
```typescript
page-create({
  platformSlug: "fed-team",
  siteId: 4605,
  name: "Blog",
  path: "/blog",
  page_type: "content",
  content_type_id: 5756  // REQUIRED
})
```

## Documentation Created

### 1. `/docs/MODYO_PAGE_TYPES.md`
**Comprehensive guide to Modyo's three page types:**
- Widget Pages (layout pages with custom widgets)
- Content Pages (connected to Content API with automatic Liquid drops)
- Origination Pages (multi-step form workflows)

**Key Sections:**
- Page type comparison table
- Detailed characteristics of each type
- Index vs Show views for content pages
- Automatic Liquid drops (`entries`, `entry`)
- Complete examples for each type
- Routing patterns
- When to use each type

### 2. `/docs/tools/RELEASE_TOOLS.md`
**Complete guide to publishing workflow:**
- Two-step publishing process explanation
- Tool parameters and return types
- Multiple examples (immediate, scheduled, batch)
- Complete workflow example
- Best practices
- Common errors and solutions
- Related tools

### 3. `/docs/tools/WIDGET_TOOLS.md`
**Guide to published widget management:**
- Widget definitions vs custom widgets
- Widget lifecycle (create → edit → publish → use)
- OID vs UUID explanation
- Tool parameters and returns
- Search and pagination examples
- Complete workflow for getting UUIDs
- Understanding widget UUIDs (OID format)
- Common errors

### 4. `/docs/tools/PAGE_WIDGET_TOOLS.md`
**Guide to adding widgets to pages:**
- **Updated with page type warnings**
- Grid layout reference
- Widget positioning (column, position)
- Three widget types (custom_widget, html, rich_text)
- Widget configuration options
- Content API connection options
- Widget variables
- Multiple complete examples
- Grid type column reference table
- Best practices
- Common errors

### 5. `/docs/tools/TOOLS_SUMMARY.md` (This Document)
**Overview of all tools and documentation**

## Complete NeoBank Implementation

### What We Built
1. ✅ 4 Banking widgets (Account Balance, Transaction List, Quick Transfer, Product Cards)
2. ✅ Product Cards widget updated to server-side Liquid rendering
3. ✅ All widgets published via releases
4. ✅ All widgets added to NeoBank homepage
5. ✅ Complete tool suite for widget management
6. ✅ Comprehensive documentation

### Live Site
**URL**: https://fed-team.modyo.cloud/neo-bank

### Widget Details
- **Account Balance** (ID: 86713, UUID: ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260)
- **Transaction List** (ID: 86714, UUID: 5b6925958f0c82370aef9fdf4b606dafcda674c3)
- **Quick Transfer** (ID: 86716, UUID: 78d06422474244b364007bfc17f45f63be11c530)
- **Product Cards** (ID: 86717, UUID: 78986a7ae2c1264e5448bb3522ee5eee87312b98)

## Important Clarifications

### Widget Pages vs Content Pages
```
✅ Widget Pages (page_type: "default" or "home")
   - Accept custom widgets
   - Use page-add-widgets tool
   - Grid-based layouts
   - No automatic Content API connection

❌ Content Pages (page_type: "content" or "entry")
   - Do NOT accept custom widgets
   - Use Liquid templates only
   - Automatic `entries` and `entry` drops
   - MUST specify content_type_id
   - Two views: index (list) and show (detail)

❌ Origination Pages
   - Do NOT accept custom widgets
   - Form workflows only
```

### UUID Format Confusion
- Modyo calls them "UUIDs" but they're actually **OIDs** (SHA-1 hashes)
- Format: 40 hexadecimal characters (e.g., `ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260`)
- NOT RFC 4122 standard UUID format
- Stable across republishing (unlike widget IDs)

### Publishing Workflow
```
1. Create/Edit widget definition → Draft state
2. Get publishable elements → Check what's ready
3. Create release → Publish selected elements
4. Get custom widgets → Retrieve UUIDs
5. Add to widget pages → Use UUIDs
```

## Tool Categories

### Publishing & Deployment
- `release-get-elements-to-publish`
- `release-create`

### Widget Management
- `widget-get-custom-widgets`
- `widget-definition-create`
- `widget-definition-update`
- `widget-definition-get`
- `widget-definitions-list`

### Page Management
- `page-create` (supports all three page types)
- `page-get`
- `page-list`
- `page-update`
- `page-delete`
- `page-add-widgets` (widget pages only!)

### Content Management
- `entry-create`
- `entry-update`
- `entry-get`
- `entry-list`
- `type-create`
- `type-get`
- `types-list`

## Best Practices Learned

1. **Always check page type** before using page-add-widgets
2. **Publish before using** - Widgets must be published to get UUIDs
3. **Use OIDs, not IDs** - Widget IDs change, OIDs are stable
4. **Specify content_type_id** for content pages
5. **Include all widgets** when updating (page-add-widgets replaces all)
6. **Check grid_type** before setting column numbers
7. **Use Liquid for content pages** - No custom widgets allowed
8. **Get elements first** before creating release
9. **Document workflows** - Complex multi-step processes need documentation

## Common Mistakes Avoided

1. ❌ Trying to add custom widgets to content pages
2. ❌ Forgetting to publish widgets before using them
3. ❌ Using widget IDs instead of UUIDs/OIDs
4. ❌ Not specifying content_type_id for content pages
5. ❌ Assuming all pages accept custom widgets
6. ❌ Using invalid column numbers for grid type
7. ❌ Creating release without checking publishable elements first

## Future Enhancements

### Potential New Tools
1. **Content page template management** - Update index/show templates
2. **Content page preview** - See how content pages render
3. **Widget variable helpers** - Manage widget configuration variables
4. **Bulk widget publishing** - Publish multiple widgets across sites
5. **Page template tools** - Manage page-specific templates

### Documentation Improvements
1. Add diagrams for page type decision tree
2. Create video walkthroughs for common workflows
3. Add troubleshooting flowcharts
4. Create quick reference cards for each tool
5. Add more real-world examples

## Quick Reference

### Publish Widgets
```typescript
// 1. Check what's publishable
release-get-elements-to-publish({ platformSlug, siteId })

// 2. Publish
release-create({
  platformSlug,
  siteId,
  data: { widgetDefinition: [{ id: 86713, selected: true }] }
})
```

### Add Widgets to Page
```typescript
// 1. Get UUIDs
widget-get-custom-widgets({ platformSlug, siteId })

// 2. Add to page (widget page only!)
page-add-widgets({
  platformSlug,
  siteId,
  pageId: 175255,
  widgets: [{
    type: "custom_widget",
    widget_definition_uuid: "uuid-here",
    position: 0,
    column: 0
  }]
})
```

### Create Content Page
```typescript
page-create({
  platformSlug,
  siteId,
  name: "Blog",
  path: "/blog",
  page_type: "content",
  content_type_id: 5756  // REQUIRED!
})
```

## Related Documentation
- [MODYO_PAGE_TYPES.md](../MODYO_PAGE_TYPES.md) - Complete page types guide
- [RELEASE_TOOLS.md](RELEASE_TOOLS.md) - Publishing workflow
- [WIDGET_TOOLS.md](WIDGET_TOOLS.md) - Widget management
- [PAGE_WIDGET_TOOLS.md](PAGE_WIDGET_TOOLS.md) - Adding widgets to pages
- [MODYO_SITE_ARCHITECTURE.md](../MODYO_SITE_ARCHITECTURE.md) - Site structure overview