@modyo/mcp 0.1.0

package/docs/tools/RELEASE_TOOLS.md

@@ -0,0 +1,263 @@
+# Release Tools Documentation
+
+## Overview
+
+Release tools manage the publishing workflow for Modyo Channels elements (templates, pages, widget definitions, and menus). In Modyo, changes to these elements are not immediately visible to end users - they must be published through a release.
+
+## Publishing Workflow
+
+Modyo uses a two-step publishing process:
+
+1. **Get publishable elements** - Retrieve list of draft elements ready to be published
+2. **Create release** - Publish selected elements making them live
+
+## Tools
+
+### release-get-elements-to-publish
+
+Retrieves all elements that are ready to be published in a site.
+
+**Use Cases:**
+- Check what changes are pending publication
+- See all unpublished widgets, templates, pages, and menus
+- Prepare data for creating a release
+- Audit draft content before publishing
+
+**Parameters:**
+- `platformSlug` (required): Platform identifier from platforms.json
+- `siteId` (required): Numeric ID of the site
+
+**Returns:**
+```typescript
+{
+  template?: Array<{
+    id: number;
+    title: string;
+    oid: string;
+    type: "template";
+    is_new: boolean;
+    selected: boolean;
+    publish_at?: string;
+    unpublish_at?: string;
+  }>;
+  page?: Array<{...}>;  // Same structure
+  widgetDefinition?: Array<{...}>;  // Same structure
+  menu?: Array<{...}>;  // Same structure
+}
+```
+
+**Notes:**
+- For sites with team review enabled, only shows approved elements
+- `is_new: true` indicates element has never been published
+- `oid` is the element's unique identifier (OID/SHA hash, not UUID)
+- Empty arrays mean no elements of that type are pending publication
+
+**Example:**
+```typescript
+// Get all publishable elements for NeoBank site
+{
+  platformSlug: "fed-team",
+  siteId: 4605
+}
+
+// Response shows 4 unpublished widgets:
+{
+  widgetDefinition: [
+    { id: 86713, title: "Account Balance", is_new: true, ... },
+    { id: 86714, title: "Transaction List", is_new: true, ... },
+    { id: 86716, title: "Quick Transfer", is_new: true, ... },
+    { id: 86717, title: "Product Cards", is_new: true, ... }
+  ],
+  template: [],
+  page: [],
+  menu: []
+}
+```
+
+---
+
+### release-create
+
+Creates and immediately publishes a release with selected elements.
+
+**Use Cases:**
+- Publish multiple widgets at once
+- Deploy template changes to production
+- Update multiple pages simultaneously
+- Schedule future publications
+- Coordinate releases across element types
+
+**Parameters:**
+- `platformSlug` (required): Platform identifier from platforms.json
+- `siteId` (required): Numeric ID of the site
+- `data` (required): Object containing arrays of elements to publish:
+  - `template?`: Array of `{id: number, selected: boolean}`
+  - `page?`: Array of `{id: number, selected: boolean}`
+  - `widgetDefinition?`: Array of `{id: number, selected: boolean}`
+  - `menu?`: Array of `{id: number, selected: boolean}`
+- `scheduled` (optional): Boolean, default false - whether this is a scheduled release
+- `publish_at` (optional): ISO datetime string - schedule publication for future
+- `unpublish_at` (optional): ISO datetime string - schedule automatic unpublication
+
+**Returns:**
+```typescript
+{
+  message: string;  // "All selected elements were successfully published"
+}
+```
+
+**Important Notes:**
+- Only elements with `selected: true` will be published
+- Use element IDs from `release-get-elements-to-publish` response
+- Publishing is immediate unless `scheduled: true` or `publish_at` is set
+- Once published, widgets become available via `custom_widgets` endpoint
+- Scheduled releases require both `scheduled: true` and `publish_at`
+- `unpublish_at` must be after `publish_at`
+
+**Examples:**
+
+**Publish all widgets immediately:**
+```typescript
+{
+  platformSlug: "fed-team",
+  siteId: 4605,
+  data: {
+    widgetDefinition: [
+      { id: 86713, selected: true },
+      { id: 86714, selected: true },
+      { id: 86716, selected: true },
+      { id: 86717, selected: true }
+    ]
+  }
+}
+```
+
+**Publish specific widgets and templates:**
+```typescript
+{
+  platformSlug: "fed-team",
+  siteId: 4605,
+  data: {
+    widgetDefinition: [
+      { id: 86713, selected: true },
+      { id: 86714, selected: false }  // Won't be published
+    ],
+    template: [
+      { id: 12345, selected: true }
+    ]
+  }
+}
+```
+
+**Schedule future publication:**
+```typescript
+{
+  platformSlug: "fed-team",
+  siteId: 4605,
+  scheduled: true,
+  publish_at: "2025-12-25T00:00:00.000Z",  // Christmas launch
+  data: {
+    widgetDefinition: [
+      { id: 86717, selected: true }
+    ]
+  }
+}
+```
+
+**Publish with automatic unpublication:**
+```typescript
+{
+  platformSlug: "fed-team",
+  siteId: 4605,
+  publish_at: "2025-01-01T00:00:00.000Z",
+  unpublish_at: "2025-01-31T23:59:59.999Z",  // Campaign runs for January only
+  data: {
+    page: [
+      { id: 175255, selected: true }
+    ]
+  }
+}
+```
+
+## Complete Workflow Example
+
+### Publishing New Widgets to a Site
+
+**Scenario:** You've created 4 banking widgets and want to publish them all.
+
+**Step 1: Get publishable elements**
+```typescript
+release-get-elements-to-publish({
+  platformSlug: "fed-team",
+  siteId: 4605
+})
+```
+
+**Step 2: Review response and note widget IDs**
+```json
+{
+  "widgetDefinition": [
+    {"id": 86713, "title": "Account Balance", "is_new": true},
+    {"id": 86714, "title": "Transaction List", "is_new": true},
+    {"id": 86716, "title": "Quick Transfer", "is_new": true},
+    {"id": 86717, "title": "Product Cards", "is_new": true}
+  ]
+}
+```
+
+**Step 3: Publish all widgets**
+```typescript
+release-create({
+  platformSlug: "fed-team",
+  siteId: 4605,
+  data: {
+    widgetDefinition: [
+      { id: 86713, selected: true },
+      { id: 86714, selected: true },
+      { id: 86716, selected: true },
+      { id: 86717, selected: true }
+    ]
+  }
+})
+```
+
+**Step 4: Verify publication**
+Use `widget-get-custom-widgets` to confirm widgets are now published and available for use.
+
+## Best Practices
+
+1. **Always get elements first** - Use `release-get-elements-to-publish` before creating release
+2. **Review before publishing** - Check titles and `is_new` flag to verify you're publishing the right elements
+3. **Use selective publishing** - Set `selected: false` for elements you want to keep as draft
+4. **Schedule important releases** - Use `publish_at` for coordinated launches
+5. **Batch related changes** - Publish widgets, templates, and pages together when they depend on each other
+6. **Test in staging** - Use separate platformSlug for staging environment before production
+7. **Track IDs carefully** - Widget IDs may change after publishing; use OIDs/UUIDs for stable references
+
+## Common Errors
+
+**"Widget definition uuid can't be blank"**
+- Attempting to add widget to page before publishing it
+- Solution: Use release tools to publish widget first
+
+**"No elements to publish"**
+- All elements are already published or archived
+- Solution: Make changes to elements or create new ones
+
+**"Column must be included in [0]"**
+- Trying to use invalid column number for page's grid type
+- Solution: Check page's `grid_type` and use valid column numbers
+
+## Related Tools
+
+- `widget-get-custom-widgets` - List published widgets (use after creating release)
+- `page-add-widgets` - Add published widgets to pages
+- `widget-definition-update` - Modify widget content (creates draft, needs republishing)
+- `template-save` - Modify templates (creates draft, needs republishing)
+- `page-update` - Modify pages (creates draft, needs republishing)
+
+## API References
+
+- Admin API: `/sites/{site_id}/releases/elements_to_publish` (GET)
+- Admin API: `/sites/{site_id}/releases` (POST)
+- Documentation: https://docs.modyo.com/en/platform/channels/publishing.html

package/docs/tools/TOOLS_SUMMARY.md

@@ -0,0 +1,368 @@
+# 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