@modyo/mcp 0.1.0

package/docs/tools/WIDGET_TOOLS.md

@@ -0,0 +1,374 @@
+# Widget Tools Documentation
+
+## Overview
+
+Widget tools manage published widgets in Modyo Channels. After widgets are published through releases, they become available as "custom widgets" that can be added to pages.
+
+**⚠️ Important**: For detailed instructions on editing widgets that are already published and used on pages, see [Editing Published Widgets](../../docs/EDITING_PUBLISHED_WIDGETS.md).
+
+## Key Concepts
+
+**Widget Definitions vs Custom Widgets:**
+- **Widget Definitions**: Draft/editable versions managed through `widget-definition-*` tools (accessed via `/widget_definitions` endpoint)
+- **Custom Widgets**: Published versions accessible through `widget-get-custom-widgets` (accessed via `/custom_widgets` endpoint - **deprecated name**, they ARE editable through widget definitions)
+- Only custom widgets (published) can be added to pages
+- Each has a unique `definition_uuid` (OID/SHA hash) for identification
+- **Widget IDs change after publishing**, but UUIDs remain stable
+
+**Widget Lifecycle:**
+1. Create widget definition (`widget-definitions-create`)
+2. Edit HTML/CSS/JS (`widget-definition-update`)
+3. Publish via release (`release-create`)
+4. Widget appears in custom widgets list
+5. Add to pages using `definition_uuid`
+
+## Tools
+
+### widget-get-custom-widgets
+
+Lists all published custom widgets for a site, returning their definition UUIDs needed for adding widgets to pages.
+
+**Use Cases:**
+- Get definition UUIDs for adding widgets to pages
+- Verify which widgets are published and available
+- Search for specific widgets by name or tags
+- Audit published widget inventory
+- Find widgets for page layouts
+
+**Parameters:**
+- `platformSlug` (required): Platform identifier from platforms.json
+- `siteId` (required): Numeric ID of the site
+- `query` (optional): Search keywords to filter by label/name
+- `sort_by` (optional): Field to sort by
+  - `"type"` - Widget type
+  - `"widget_class_name"` - Class name
+  - `"label"` - Widget label/name
+  - `"tags"` - Widget tags
+  - `"multiple_instances"` - Instance limit
+  - `"preferred_position"` - Position preference
+  - `"definition_uuid"` - UUID
+  - `"updated_at"` - Last update timestamp (default)
+- `order` (optional): `"asc"` or `"desc"` (default: desc)
+- `page` (optional): Page number for pagination (default: 1)
+- `per_page` (optional): Results per page (default: 10)
+
+**Returns:**
+```typescript
+{
+  custom_widgets: Array<{
+    type: "custom_widget";
+    widget_class_name: string;  // Usually "CustomWidget"
+    label: string;  // Widget display name
+    id: number;  // Widget definition ID
+    tags: string;  // Comma-separated tags
+    multiple_instances: number;  // 0=unlimited, 1=single per page
+    preferred_position: number;  // Suggested position
+    widget_definition_uuid: string;  // OID (deprecated field)
+    definition_uuid: string;  // OID - USE THIS for adding to pages
+    variables: Array<{
+      slug: string;
+      value: string;
+      selected?: boolean;
+    }>;
+    sync: boolean;
+    published: boolean;
+  }>;
+  meta: {
+    total_entries: number;
+    per_page: number;
+    current_page: number;
+    total_pages: number;
+  };
+}
+```
+
+**Important Notes:**
+- **Only shows published widgets** - Use release tools to publish first
+- `definition_uuid` is an OID (SHA hash), not a standard UUID format
+- This is the identifier needed for `page-add-widgets` tool
+- `widget_definition_uuid` is deprecated; use `definition_uuid` instead
+- Empty result means no widgets are published yet
+- `multiple_instances: 0` allows unlimited instances per page
+- `multiple_instances: 1` restricts to single instance per page
+
+**Examples:**
+
+**Get all published widgets:**
+```typescript
+{
+  platformSlug: "fed-team",
+  siteId: 4605
+}
+
+// Response:
+{
+  custom_widgets: [
+    {
+      type: "custom_widget",
+      label: "Account Balance",
+      id: 86713,
+      definition_uuid: "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260",
+      tags: "banking,account,balance,dashboard",
+      multiple_instances: 1,
+      variables: [],
+      published: true
+    },
+    {
+      label: "Quick Transfer",
+      id: 86716,
+      definition_uuid: "78d06422474244b364007bfc17f45f63be11c530",
+      tags: "banking,transfer,payments,dashboard",
+      ...
+    }
+  ],
+  meta: { total_entries: 4, ... }
+}
+```
+
+**Search for banking widgets:**
+```typescript
+{
+  platformSlug: "fed-team",
+  siteId: 4605,
+  query: "banking",
+  sort_by: "label",
+  order: "asc"
+}
+```
+
+**Get first page of widgets:**
+```typescript
+{
+  platformSlug: "fed-team",
+  siteId: 4605,
+  per_page: 10,
+  page: 1
+}
+```
+
+## Complete Workflow Example
+
+### Getting Widget UUIDs for Page Layout
+
+**Scenario:** After publishing 4 banking widgets, you need their UUIDs to add them to the homepage.
+
+**Step 1: Get published widgets**
+```typescript
+widget-get-custom-widgets({
+  platformSlug: "fed-team",
+  siteId: 4605
+})
+```
+
+**Step 2: Extract definition_uuid values**
+```json
+{
+  "custom_widgets": [
+    {
+      "label": "Account Balance",
+      "definition_uuid": "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260"
+    },
+    {
+      "label": "Quick Transfer",
+      "definition_uuid": "78d06422474244b364007bfc17f45f63be11c530"
+    },
+    {
+      "label": "Transaction List",
+      "definition_uuid": "5b6925958f0c82370aef9fdf4b606dafcda674c3"
+    },
+    {
+      "label": "Product Cards",
+      "definition_uuid": "78986a7ae2c1264e5448bb3522ee5eee87312b98"
+    }
+  ]
+}
+```
+
+**Step 3: Use UUIDs with page-add-widgets**
+```typescript
+page-add-widgets({
+  platformSlug: "fed-team",
+  siteId: 4605,
+  pageId: 175255,
+  widgets: [
+    {
+      type: "custom_widget",
+      widget_definition_uuid: "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260",
+      position: 0,
+      column: 0,
+      enabled: true,
+      label: "Account Balance"
+    },
+    // ... more widgets
+  ]
+})
+```
+
+## Best Practices
+
+1. **Always check published state** - This tool only shows published widgets
+2. **Use definition_uuid** - It's the current field; `widget_definition_uuid` is deprecated
+3. **Store UUIDs** - OIDs remain stable across republishing (unlike widget IDs)
+4. **Filter with tags** - Use consistent tagging strategy for easier discovery
+5. **Respect multiple_instances** - Check this before adding multiple copies to a page
+6. **Search before creating** - Use `query` parameter to avoid duplicate widgets
+7. **Paginate large lists** - Use `per_page` and `page` for sites with many widgets
+
+## Understanding Widget UUIDs and Versioning
+
+### UUID vs OID
+
+**Format:**
+- 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 (no hyphens)
+- Stable across republishing (unlike widget IDs which may change)
+
+### Critical: Widget ID Changes After Publishing
+
+**IMPORTANT**: When a widget is published in Modyo:
+
+1. **ID Changes**: The widget `id` field changes because Modyo creates a new version
+2. **UUID/OID Stable**: The `definition_uuid` (OID) remains constant across all versions
+3. **Old Version Stored**: Previous version is archived for rollback/history
+4. **Rollback Available**: Can revert to previous versions via Modyo UI
+
+**Why This Matters:**
+```typescript
+// ❌ WRONG - Don't store or reference widgets by ID
+const widgetId = 86713;
+widget-definition-update({ widgetId, ... });  // May fail after publish
+
+// ✅ CORRECT - Always use definition_uuid (OID) for references
+const widgetUuid = "ac2fe2d381f5436e52b1cea8a37e0a8a2faf5260";
+// Use UUID to identify widget across all versions
+```
+
+**Versioning Workflow:**
+```
+1. Create widget definition (id: 100, definition_uuid: "abc123...")
+2. Edit widget (still id: 100, definition_uuid: "abc123...")
+3. Publish via release → Creates version
+   - Old version archived (id: 100, version: 1)
+   - New published version (id: 101, definition_uuid: "abc123...")
+4. Edit again (id: 101, definition_uuid: "abc123...")
+5. Publish again → Creates another version
+   - Version 1 archived (id: 100)
+   - Version 2 archived (id: 101)
+   - New published version (id: 102, definition_uuid: "abc123...")
+```
+
+**Rollback Behavior:**
+- Can revert to version 1 (id: 100) or version 2 (id: 101) via Modyo UI
+- After rollback, a new version is created with new ID
+- `definition_uuid` always remains "abc123..." throughout all versions
+
+**Why OIDs Matter:**
+- ✅ Widget IDs change after every publish - don't rely on them
+- ✅ OIDs (definition_uuid) remain constant - always use these
+- ✅ Stable references across versions and republishing
+- ✅ Used for syncing widgets across sites
+- ✅ Required parameter for adding widgets to pages
+
+**Best Practices:**
+- ✅ Use `definition_uuid` for stable references across versions
+- ✅ Fetch current widget info by UUID before operations
+- ✅ Store UUIDs/OIDs in external systems, not IDs
+- ❌ Don't hardcode widget IDs
+- ❌ Don't assume IDs remain constant after publishing
+- ❌ Don't use ID-based lookups in automated workflows
+
+## Common Errors
+
+**Empty custom_widgets array**
+- No widgets have been published yet
+- Solution: Use `release-create` to publish widget definitions
+
+**"Widget definition uuid can't be blank"**
+- Attempting to add widget without providing UUID
+- Solution: Get UUID from this tool first
+
+**Widget not appearing in list**
+- Widget definition exists but not published
+- Solution: Check `release-get-elements-to-publish` and create release
+
+## Related Tools
+
+- `release-create` - Publish widget definitions to make them available
+- `release-get-elements-to-publish` - Check which widgets need publishing
+- `page-add-widgets` - Add published widgets to pages using UUIDs
+- `widget-definition-get` - View widget definition details (draft version)
+- `widget-definitions-list` - List all widget definitions (draft and published)
+
+## Editing Published Widgets
+
+**Quick Reference**: To edit a widget that's already published and used on pages:
+
+### 1. Find Widget UUID from Page
+
+```typescript
+const page = await page-get({ platformSlug, siteId, pageId });
+const widget = page.widgets.find(w => w.label === "Widget Name");
+const uuid = widget.definition_uuid;  // e.g., "bee3ee40972ffa9d8b44cabac65aaa618549e356"
+```
+
+### 2. Get Widget Definition ID (Not Custom Widget ID!)
+
+**❌ WRONG** - Don't use `widget-get-custom-widgets`:
+```typescript
+// This returns custom widgets (published), but IDs won't work for editing
+const customWidgets = await widget-get-custom-widgets({ platformSlug, siteId });
+```
+
+**✅ CORRECT** - Use `widget-definitions-list`:
+```typescript
+// This returns editable widget definitions with correct IDs
+const definitions = await widget-definitions-list({ platformSlug, siteId, query: "" });
+const widget = definitions.widget_definitions.find(w => w.uuid === uuid);
+const widgetId = widget.id;  // This is the ID to use for editing!
+```
+
+### 3. Get and Update Widget
+
+```typescript
+// Get current code
+const widget = await widget-definition-get({ platformSlug, siteId, widgetId });
+
+// Update with new code
+await widget-definition-update({
+  platformSlug,
+  siteId,
+  widgetId,
+  html: "<div>New HTML...</div>",
+  css: ".new-styles { }",
+  js: "console.log('Updated');"
+});
+```
+
+### 4. Publish Changes
+
+```typescript
+// Get publishable elements
+const elements = await release-get-elements-to-publish({ platformSlug, siteId });
+
+// Find widget by UUID (NOT ID - ID may have changed!)
+const widgetToPublish = elements.widgetDefinition.find(w => w.oid === uuid);
+
+// Publish
+await release-create({
+  platformSlug,
+  siteId,
+  data: {
+    widgetDefinition: [{ id: widgetToPublish.id, selected: true }]
+  }
+});
+```
+
+**📖 Full Guide**: See [Editing Published Widgets](../../docs/EDITING_PUBLISHED_WIDGETS.md) for complete documentation with troubleshooting and best practices.
+
+## API References
+
+- Admin API Widget Definitions: `/sites/{site_id}/widget_definitions` (GET) - **Use this for editing**
+- Admin API Custom Widgets: `/sites/{site_id}/custom_widgets` (GET) - For published list only
+- Query parameters: `query`, `sort_by`, `order`, `page`, `per_page`
+- Documentation: https://docs.modyo.com/en/platform/channels/widgets.html

package/docs/tools/channels/pages/page-create.md

@@ -0,0 +1,328 @@
+# Tool Name: `page-create`
+
+**Module**: Channels > Pages  
+**Version**: 1.0.0  
+**Status**: Stable
+
+## Overview
+
+Creates a new layout page within a site. Pages define the routes/paths that visitors can access on the site domain (e.g., /home, /about, /products). Each page represents a URL endpoint in your site structure.
+
+## Use Cases
+
+- Create home page (/) for site entry point
+- Add content pages (about, contact, services)
+- Build product catalog pages (/products)
+- Set up nested page hierarchies (/products/category/item)
+- Create dynamic content pages linked to Content entries
+
+## Parameters
+
+### Required Parameters
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| platformSlug | string | Platform identifier from ~/.platforms.json | "production" |
+| siteId | number | The ID of the site where page will be created | 123 |
+| name | string | Display name of the page (shown in admin) | "Home Page" |
+| path | string | URL path for the page (must start with /) | "/" or "/about" |
+
+### Optional Parameters
+
+| Parameter | Type | Default | Description | Example |
+|-----------|------|---------|-------------|---------|
+| parent_uuid | string\|null | null | UUID of parent page for nested structure | "abc-123-def" |
+| page_type | string | "default" | Type of page template to use | "home", "default" |
+| grid_type | string\|null | null | Grid layout type for the page | "standard" |
+| private | boolean | false | Whether the page requires authentication | true |
+| has_router | boolean | false | Enable routing functionality for dynamic paths | true |
+| restriction_enabled | boolean | false | Enable access restrictions based on user roles | true |
+| excerpt | string\|null | null | Short description for SEO and listings | "Welcome page" |
+| content_type_id | number\|null | null | Link to Content type for dynamic content | 45 |
+| origination_uuid | string\|null | null | UUID of original page if this is a clone | "xyz-789" |
+
+## Response
+
+### Success Response
+
+```json
+{
+  "id": 456,
+  "uuid": "page-uuid-123",
+  "name": "Home Page",
+  "path": "/",
+  "page_type": "home",
+  "grid_type": null,
+  "private": false,
+  "has_router": false,
+  "restriction_enabled": false,
+  "excerpt": "Welcome to our site",
+  "content_type_id": null,
+  "parent_uuid": null,
+  "origination_uuid": null,
+  "created_at": "2025-01-09T10:00:00Z",
+  "updated_at": "2025-01-09T10:00:00Z",
+  "status": "draft",
+  "workflow_id": 789,
+  "site_id": 123
+}
+```
+
+### Error Responses
+
+**422 Validation Error - Duplicate Path**
+```json
+{
+  "error": "Validation failed",
+  "details": {
+    "path": ["has already been taken"]
+  }
+}
+```
+
+**404 Not Found - Invalid Site**
+```json
+{
+  "error": "Site not found",
+  "site_id": 999
+}
+```
+
+## Examples
+
+### Example 1: Create Home Page
+
+Create the main entry point for your site:
+
+```json
+{
+  "platformSlug": "production",
+  "siteId": 123,
+  "name": "Home",
+  "path": "/",
+  "page_type": "home",
+  "excerpt": "Welcome to our website"
+}
+```
+
+**Result**: Creates home page accessible at site root URL.
+
+### Example 2: Create About Page
+
+Add a standard content page:
+
+```json
+{
+  "platformSlug": "production",
+  "siteId": 123,
+  "name": "About Us",
+  "path": "/about",
+  "page_type": "default",
+  "excerpt": "Learn more about our company"
+}
+```
+
+**Result**: Page accessible at `https://yoursite.com/about`
+
+### Example 3: Create Nested Product Detail Page
+
+Build hierarchical page structure:
+
+```json
+{
+  "platformSlug": "production",
+  "siteId": 123,
+  "name": "Product Details",
+  "path": "/products/details",
+  "parent_uuid": "products-page-uuid",
+  "page_type": "default"
+}
+```
+
+**Result**: Nested page at `https://yoursite.com/products/details`
+
+### Example 4: Create Private Customer Portal Page
+
+Page requiring authentication:
+
+```json
+{
+  "platformSlug": "production",
+  "siteId": 123,
+  "name": "My Account",
+  "path": "/account",
+  "page_type": "default",
+  "private": true,
+  "restriction_enabled": true
+}
+```
+
+**Result**: Page only accessible to logged-in users.
+
+### Example 5: Dynamic Content Page
+
+Page connected to Content entries:
+
+```json
+{
+  "platformSlug": "production",
+  "siteId": 123,
+  "name": "Blog Post",
+  "path": "/blog/:slug",
+  "page_type": "entry",
+  "has_router": true,
+  "content_type_id": 45
+}
+```
+
+**Result**: Dynamic page that displays Content entries from type 45.
+
+## Related Tools
+
+- `page-list` - List all pages in site to verify creation
+- `page-get` - Retrieve page details including content
+- `page-update` - Modify page properties and content after creation
+- `page-delete` - Remove pages when no longer needed
+- `site-get` - Get site details to verify siteId
+- `template-create` - Create snippets to use in page content
+
+## Common Patterns
+
+### Pattern 1: Basic Site Structure Setup
+
+```
+1. page-create (path: "/") → home page
+2. page-create (path: "/about") → about page  
+3. page-create (path: "/services") → services page
+4. page-create (path: "/contact") → contact page
+5. page-list → verify all pages created
+```
+
+### Pattern 2: E-Commerce Page Structure
+
+```
+1. page-create (path: "/") → home
+2. page-create (path: "/products") → product catalog
+3. page-create (path: "/products/:slug", has_router: true) → product details
+4. page-create (path: "/cart") → shopping cart
+5. page-create (path: "/checkout", private: true) → checkout
+6. page-update → add content with product snippets
+```
+
+### Pattern 3: Blog Structure with Dynamic Content
+
+```
+1. page-create (path: "/") → home
+2. page-create (path: "/blog") → blog list
+3. page-create (path: "/blog/:slug", has_router: true, content_type_id: X) → blog post
+4. page-create (path: "/blog/category/:category") → category pages
+5. template-create (type: "snippet") → blog post card snippet
+6. page-update → add blog post cards to list page
+```
+
+### Pattern 4: Multi-Language Site
+
+```
+1. page-create (path: "/en") → English home
+2. page-create (path: "/es") → Spanish home
+3. page-create (path: "/en/about") → English about
+4. page-create (path: "/es/acerca") → Spanish about
+5. global-variable-create (scope: "site") → language switcher config
+```
+
+## Troubleshooting
+
+### Issue: "Path has already been taken"
+
+**Cause**: Another page in the same site uses this exact path  
+**Solution**:
+- Use `page-list` to see all existing paths
+- Choose a different unique path
+- Delete the existing page if it's no longer needed
+- Check for case-sensitivity (paths are case-sensitive)
+
+### Issue: "Parent UUID not found"
+
+**Cause**: The parent_uuid doesn't exist or belongs to different site  
+**Solution**:
+- Use `page-list` to get valid parent page UUIDs
+- Set parent_uuid to null for top-level pages
+- Ensure parent page exists before creating child
+
+### Issue: "Invalid path format"
+
+**Cause**: Path doesn't start with "/" or contains invalid characters  
+**Solution**:
+- Always start paths with "/" : `/about` ✅ not `about` ❌
+- Use lowercase and hyphens: `/my-page` ✅
+- Avoid spaces and special chars: `/my page` ❌
+- Use URL-safe characters only
+
+### Issue: "Content type not found"
+
+**Cause**: content_type_id doesn't exist in the platform  
+**Solution**:
+- Use `type-list` to get valid content type IDs
+- Set content_type_id to null if not using dynamic content
+- Create content type first using `type-create` if needed
+
+### Issue: Page created but shows 404
+
+**Cause**: Page is in draft status and not published  
+**Solution**:
+- Pages are created as drafts by default
+- Must be published through Modyo admin UI or API
+- Check page status with `page-get`
+
+## Best Practices
+
+1. **Plan URL structure** - Map out all pages before creating
+2. **Use semantic paths** - `/products/shoes` is better than `/p1`
+3. **Start with home page** - Create "/" path first as site entry point
+4. **Hierarchical organization** - Use parent_uuid for logical structure
+5. **Consistent naming** - Match page name to path (`"About Us"` → `/about-us`)
+6. **Add excerpts** - Improves SEO and content organization
+7. **Test paths** - Verify no conflicts before creating many pages
+
+## Permissions Required
+
+- Valid Admin API access token
+- Channels module enabled
+- Page creation permissions for the site
+- Site must exist and be accessible
+
+## Rate Limits
+
+- **Standard**: 50 page creations per minute per site
+- **Recommended**: Create pages in batches of 10-20
+- **Large sites**: Consider pagination when creating 100+ pages
+
+## Important Notes
+
+- Page creation sets status to **"draft"** (not published)
+- Pages require **publishing** through Modyo admin or API to be public
+- **Paths are case-sensitive**: `/About` and `/about` are different
+- **Paths must be unique** within a site
+- Path cannot be changed after creation (requires page recreation)
+- Router pages (has_router: true) enable **dynamic URL parameters** like `:slug`
+- Private pages require site to have **realm authentication** enabled
+- Parent-child relationships create **breadcrumb navigation**
+- Empty pages (no content) will display **blank** until content added
+
+## See Also
+
+### Documentation
+- [Pages Management Guide](../../guides/pages-management.md)
+- [Page Content Best Practices](../../guides/page-content.md)
+- [Dynamic Pages and Routing](../../guides/dynamic-pages.md)
+
+### Official Modyo Documentation
+- [Modyo Pages Docs](https://docs.modyo.com/en/platform/channels/pages.html)
+- [API Reference](https://api.modyo.com/swagger#/layout_pages/post_sites__site_id__layout_pages)
+- [Page Templates](https://docs.modyo.com/en/platform/channels/templates.html)
+
+### Related Tool Documentation
+- [page-update](./page-update.md) - Add content and update pages
+- [page-list](./page-list.md) - List and find pages
+- [site-create](../sites/site-create.md) - Create site first
+- [template-create](../templates/template-create.md) - Create reusable snippets