@modyo/mcp 0.1.0

package/docs/tools/channels/sites/site-create.md

@@ -0,0 +1,280 @@
+# Tool Name: `site-create`
+
+**Module**: Channels > Sites  
+**Version**: 1.0.0  
+**Status**: Stable
+
+## Overview
+
+Creates a new site in the Modyo platform with custom domain support. Sites are the top-level containers for pages, widgets, and templates in the Channels module.
+
+## Use Cases
+
+- Launch new website or web application
+- Create staging environment for testing
+- Set up brand-specific site in multi-tenant setup
+- Deploy customer-facing portal with custom domain
+
+## Parameters
+
+### Required Parameters
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| platformSlug | string | Platform identifier from ~/.platforms.json | "production" |
+| site.host | string | Domain name (must be valid hostname format) | "mysite.modyo.me" |
+| site.name | string | Display name for the site | "My Website" |
+| site.theme | string | Theme ID (currently only "208" supported) | "208" |
+
+### Optional Parameters
+
+| Parameter | Type | Default | Description | Example |
+|-----------|------|---------|-------------|---------|
+| site.realm_id | number\|null | null | Realm ID for customer authentication | 5 |
+| site.description | string | "" | Site description for documentation | "Corporate website" |
+| site.team_review | boolean | false | Enable team review workflow for changes | true |
+
+## Response
+
+### Success Response
+
+```json
+{
+  "id": 123,
+  "uuid": "abc-123-def-456",
+  "name": "My Website",
+  "host": "mysite.modyo.me",
+  "status": 0,
+  "language": "en",
+  "time_zone": "UTC",
+  "created_at": "2025-01-09T10:00:00Z",
+  "updated_at": "2025-01-09T10:00:00Z",
+  "base_url": "https://mysite.modyo.me",
+  "base_admin_url": "https://account.modyo.com/admin/sites/123",
+  "team_review": false,
+  "realm_id": null,
+  "stages_enabled": false,
+  "public_css": "",
+  "public_js": "",
+  "editable_css": "",
+  "editable_js": ""
+}
+```
+
+### Error Responses
+
+**422 Validation Error**
+```json
+{
+  "error": "Validation failed",
+  "details": {
+    "host": ["has already been taken"]
+  }
+}
+```
+
+**400 Bad Request**
+```json
+{
+  "error": "Invalid host format",
+  "message": "Host must be a valid domain name"
+}
+```
+
+## Examples
+
+### Example 1: Basic Site Creation
+
+Create a simple site with minimal configuration:
+
+```json
+{
+  "platformSlug": "production",
+  "site": {
+    "host": "mysite.modyo.me",
+    "name": "My New Site",
+    "realm_id": null,
+    "theme": "208"
+  }
+}
+```
+
+**Result**: Creates site accessible at `https://mysite.modyo.me`
+
+### Example 2: Site with Authentication Realm
+
+Create a site with customer login enabled:
+
+```json
+{
+  "platformSlug": "production",
+  "site": {
+    "host": "customers.mycompany.com",
+    "name": "Customer Portal",
+    "realm_id": 5,
+    "theme": "208"
+  }
+}
+```
+
+**Result**: Creates site where users can register/login using realm authentication.
+
+### Example 3: Production Site with Team Review
+
+Create a production site with approval workflow:
+
+```json
+{
+  "platformSlug": "production",
+  "site": {
+    "host": "www.mycompany.com",
+    "name": "Corporate Website",
+    "realm_id": null,
+    "theme": "208",
+    "description": "Public-facing corporate website",
+    "team_review": true
+  }
+}
+```
+
+**Result**: Creates site where all changes require team approval before publishing.
+
+## Related Tools
+
+- `site-get` - Retrieve site details after creation to verify configuration
+- `site-list` - List all sites to confirm creation and get site ID
+- `site-update` - Modify site settings after initial creation
+- `site-delete` - Remove site when no longer needed
+- `page-create` - Add pages to the newly created site
+- `template-create` - Add templates and snippets to the site
+
+## Common Patterns
+
+### Pattern 1: Complete Site Setup Workflow
+
+```
+1. site-create → create site infrastructure
+2. site-get → verify site created and get full details
+3. template-create (type: "snippet") → add header snippet
+4. template-create (type: "snippet") → add footer snippet  
+5. template-create (type: "css") → add global styles
+6. template-create (type: "js") → add global scripts
+7. page-create (path: "/") → create home page
+8. page-create (path: "/about") → create about page
+9. site-list → verify complete setup
+```
+
+### Pattern 2: Clone Site for Different Environment
+
+```
+1. site-list (source) → get source site configuration
+2. template-list-snippets (source) → get all snippets to replicate
+3. site-create (new) → create new site with similar config
+4. [For each snippet]: template-create (new) → recreate snippets
+5. page-list (source) → get page structure
+6. [For each page]: page-create (new) → recreate pages
+```
+
+### Pattern 3: Multi-Brand Site Creation
+
+```
+1. site-create (brand-a) → create first brand site
+2. site-create (brand-b) → create second brand site
+3. site-create (brand-c) → create third brand site
+4. [For each site]: template-create → add brand-specific styles
+5. [For each site]: global-variable-create → set brand colors/config
+```
+
+## Troubleshooting
+
+### Issue: "Host has already been taken"
+
+**Cause**: Another site in the platform is already using this domain name  
+**Solution**: 
+- Choose a different unique domain name
+- Delete the existing site if it's no longer needed
+- Use `site-list` to see all existing site domains
+
+### Issue: "Invalid host format"
+
+**Cause**: Domain doesn't match hostname validation regex  
+**Solution**: Use valid hostname format:
+- Lowercase only: `mysite.modyo.me` ✅ not `MySite.Modyo.me` ❌
+- Alphanumeric with hyphens: `my-site.modyo.me` ✅
+- No spaces or special characters: `my site.com` ❌
+- Must have domain extension: `mysite` ❌ `mysite.com` ✅
+
+### Issue: "Realm not found"
+
+**Cause**: The realm_id doesn't exist in the platform  
+**Solution**: 
+- Use `realm-list` tool to get valid realm IDs
+- Set `realm_id: null` if authentication is not needed
+- Create realm first using `realm-create` if needed
+
+### Issue: "Theme not found" or "Invalid theme"
+
+**Cause**: Invalid theme ID provided  
+**Solution**: Currently only theme "208" is supported in Modyo. Always use:
+```json
+"theme": "208"
+```
+
+### Issue: Site created but not accessible via URL
+
+**Cause**: DNS not configured for custom domain  
+**Solution**: 
+- For `*.modyo.me` domains: Immediate DNS (no action needed)
+- For custom domains: Configure DNS CNAME pointing to Modyo
+- Wait for DNS propagation (can take up to 48 hours)
+
+## Best Practices
+
+1. **Use descriptive names** - Helps identify sites in admin UI and for team members
+2. **Plan domain structure early** - Consider staging/production domain strategy
+3. **Enable team_review for production** - Prevents accidental publishing of changes
+4. **Document realm associations** - Keep track of which sites use authentication
+5. **Follow naming conventions** - Use consistent naming across environments (e.g., `brand-staging`, `brand-production`)
+6. **Test in staging first** - Create staging site before production site
+7. **Use consistent theme** - Stick with theme "208" across all sites
+
+## Permissions Required
+
+- Valid Admin API access token in `~/.platforms.json`
+- Channels module enabled in the Modyo platform
+- Site creation permissions for the authenticated user
+- Realm access (if associating with realm_id)
+
+## Rate Limits
+
+- **Standard**: 10 site creations per minute per platform
+- **Platform limit**: May vary based on subscription plan
+- **Concurrent requests**: Recommended max 5 simultaneous site creates
+
+## Important Notes
+
+- Site creation is **immediate** (no async processing required)
+- Custom domains require **DNS configuration** outside of Modyo
+- Theme selection is **limited to "208"** in current API version
+- Site host **cannot be changed** after creation (requires site recreation)
+- Deleted site domains become **available after 24 hours**
+- Site creation does **not** create any default pages (use `page-create`)
+- Empty sites show **404** until at least one page is published
+
+## See Also
+
+### Documentation
+- [Channels Module Overview](../../guides/channels-overview.md)
+- [Site Management Best Practices](../../guides/site-management.md)
+- [Complete Site Setup Guide](../../guides/complete-site-setup.md)
+
+### Official Modyo Documentation
+- [Modyo Sites Official Docs](https://docs.modyo.com/en/platform/channels/sites.html)
+- [API Reference](https://api.modyo.com/swagger#/sites/post_sites)
+- [Custom Domain Configuration](https://docs.modyo.com/en/platform/channels/sites.html#custom-domains)
+
+### Related Tool Documentation
+- [site-update](./site-update.md) - Update site configuration
+- [site-delete](./site-delete.md) - Delete sites
+- [page-create](../pages/page-create.md) - Create pages in site
+- [template-create](../templates/template-create.md) - Add templates to site

package/docs/tools/channels/templates/template-list-snippets.md

@@ -0,0 +1,320 @@
+# Tool Name: `template-list-snippets`
+
+**Module**: Channels > Templates  
+**Version**: 1.0.0  
+**Status**: Stable
+
+## Overview
+
+Lists all snippets in a site. **Snippets are reusable code blocks** that can be included in pages and other templates using Liquid tags like `{% snippet 'header' %}`. They are fundamental to Modyo's code sharing and component-based architecture.
+
+## Use Cases
+
+- Discover available snippets before adding them to pages
+- Audit which snippets exist in a site
+- Verify snippet creation was successful
+- Plan template refactoring by identifying reusable components
+- Document available snippets for team reference
+
+## Parameters
+
+### Required Parameters
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| platformSlug | string | Platform identifier from ~/.platforms.json | "production" |
+| siteId | number | The ID of the site to list snippets from | 123 |
+
+### Optional Parameters
+
+None. This tool returns all snippets in the specified site.
+
+## Response
+
+### Success Response
+
+```json
+{
+  "snippets": [
+    {
+      "id": 456,
+      "uuid": "snippet-uuid-123",
+      "name": "site-header",
+      "body": "<header><nav>...</nav></header>",
+      "published": true,
+      "created_at": "2025-01-08T10:00:00Z",
+      "updated_at": "2025-01-09T15:30:00Z"
+    },
+    {
+      "id": 457,
+      "uuid": "snippet-uuid-456",
+      "name": "site-footer",
+      "body": "<footer>&copy; 2025</footer>",
+      "published": true,
+      "created_at": "2025-01-08T10:05:00Z",
+      "updated_at": "2025-01-08T10:05:00Z"
+    },
+    {
+      "id": 458,
+      "uuid": "snippet-uuid-789",
+      "name": "product-card",
+      "body": "<div class=\"product\">{{ product.name }}</div>",
+      "published": false,
+      "created_at": "2025-01-09T14:00:00Z",
+      "updated_at": "2025-01-09T14:00:00Z"
+    }
+  ]
+}
+```
+
+### Error Responses
+
+**404 Not Found - Invalid Site**
+```json
+{
+  "error": "Site not found",
+  "site_id": 999
+}
+```
+
+**Empty Response**
+```json
+{
+  "snippets": []
+}
+```
+
+## Examples
+
+### Example 1: List All Snippets
+
+Get all snippets in a site to see what's available:
+
+```json
+{
+  "platformSlug": "production",
+  "siteId": 123
+}
+```
+
+**Result**: Returns array of all snippet objects with names, bodies, and metadata.
+
+### Example 2: Verify Snippet After Creation
+
+Check that a newly created snippet appears in the list:
+
+```json
+{
+  "platformSlug": "production",
+  "siteId": 123
+}
+```
+
+Filter response to find your snippet by name.
+
+### Example 3: Audit Site Templates
+
+List snippets to document what templates exist:
+
+```json
+{
+  "platformSlug": "production",
+  "siteId": 123
+}
+```
+
+Use for creating template inventory or migration planning.
+
+## Related Tools
+
+- `template-list-custom-snippets` - List user-defined custom snippets
+- `template-create` - Create new snippets (type: "snippet")
+- `template-get` - Get full details of a specific snippet
+- `template-update` - Modify snippet metadata
+- `template-save` - Update snippet body content
+- `template-delete` - Remove snippets
+- `page-update` - Use snippets in page content
+
+## Common Patterns
+
+### Pattern 1: Snippet Discovery and Usage
+
+```
+1. template-list-snippets → see available snippets
+2. template-get (id: X) → view snippet code
+3. page-update → add snippet to page using {% snippet 'name' %}
+4. page-get → verify snippet rendering
+```
+
+### Pattern 2: Template Audit and Documentation
+
+```
+1. template-list-snippets → get all snippets
+2. template-list-custom-snippets → get custom snippets
+3. template-list-layouts → get layouts
+4. [For each snippet]: template-get → get full details
+5. Document available templates for team
+```
+
+### Pattern 3: Snippet Migration Between Sites
+
+```
+1. template-list-snippets (source site) → get all snippets
+2. [For each snippet]: template-get (source) → get body
+3. [For each snippet]: template-create (target site) → recreate
+4. template-list-snippets (target) → verify migration
+```
+
+### Pattern 4: Identifying Unused Snippets
+
+```
+1. template-list-snippets → get all snippets
+2. page-list → get all pages
+3. [For each page]: page-get → check content for snippet references
+4. Compare to find unused snippets
+5. template-delete (unused) → cleanup
+```
+
+## Understanding Snippets
+
+### What Are Snippets?
+
+Snippets are **reusable HTML/Liquid code blocks** that solve the DRY (Don't Repeat Yourself) principle:
+
+- **Before Snippets**: Copy header HTML to every page (unmaintainable)
+- **With Snippets**: `{% snippet 'header' %}` on every page (update once, reflects everywhere)
+
+### Snippet vs Custom Snippet
+
+- **Snippets**: System-level templates, managed by administrators
+- **Custom Snippets**: User-created templates, often site-specific
+
+Both work the same way in pages, just different organizational categories.
+
+### How to Use Snippets in Pages
+
+In page content (accessed via `page-update`):
+
+```liquid
+<!DOCTYPE html>
+<html>
+<head>
+  {% snippet 'head-meta' %}
+</head>
+<body>
+  {% snippet 'site-header' %}
+  
+  <main>
+    {{ content_for_layout }}
+  </main>
+  
+  {% snippet 'site-footer' %}
+  {% snippet 'analytics' %}
+</body>
+</html>
+```
+
+When the page renders, `{% snippet 'site-header' %}` is replaced with the snippet body.
+
+### Common Snippet Types
+
+| Snippet Name | Purpose | Typical Body |
+|--------------|---------|--------------|
+| site-header | Site navigation | `<header><nav>...</nav></header>` |
+| site-footer | Footer content | `<footer>&copy; year</footer>` |
+| head-meta | SEO meta tags | `<meta name="..." content="...">` |
+| product-card | Reusable component | `<div class="card">{{ product }}</div>` |
+| analytics | Tracking scripts | `<script>ga('...')</script>` |
+| breadcrumbs | Navigation path | `<nav>{% for item in path %}</nav>` |
+
+## Troubleshooting
+
+### Issue: Empty snippets array
+
+**Cause**: No snippets have been created in this site yet  
+**Solution**:
+- Use `template-create` with type: "snippet" to create snippets
+- Check if you're looking at the correct siteId
+- Verify site exists using `site-get`
+
+### Issue: Missing expected snippet
+
+**Cause**: Snippet may be a custom_snippet instead  
+**Solution**:
+- Use `template-list-custom-snippets` to check custom snippets
+- Use `template-list` with type filter to see all template types
+- Check if snippet was deleted
+
+### Issue: Snippet body truncated
+
+**Cause**: List endpoint returns metadata only, not full body  
+**Solution**:
+- Use `template-get` with specific snippet ID to get complete body
+- List operation intentionally limits body size for performance
+
+### Issue: Published vs Unpublished snippets
+
+**Cause**: Snippets can be in draft (unpublished) state  
+**Solution**:
+- Check "published": true/false in response
+- Unpublished snippets work in draft pages but not in published pages
+- Publish snippets through Modyo admin or use template-update
+
+## Best Practices
+
+1. **Standardize naming** - Use consistent patterns (e.g., `site-*`, `component-*`)
+2. **Document snippets** - Add descriptions when creating snippets
+3. **Keep snippets focused** - One snippet = one responsibility
+4. **Version control** - Export snippet bodies to git for backup
+5. **Test before use** - Create snippets in staging first
+6. **Publish wisely** - Only publish when snippets are tested and ready
+7. **Regular audits** - Periodically list snippets to identify unused ones
+
+## Performance Considerations
+
+- **Fast operation**: Listing snippets is a lightweight query
+- **No pagination**: All snippets returned in single response
+- **Large sites**: Sites with 100+ snippets return quickly
+- **Caching**: Consider caching snippet list for frequently accessed sites
+
+## Permissions Required
+
+- Valid Admin API access token
+- Channels module enabled
+- Read access to site templates
+- Site must exist and be accessible
+
+## Rate Limits
+
+- **Standard**: 100 requests per minute
+- **Recommended**: Cache results for 5-10 minutes
+- **Concurrent requests**: No special restrictions
+
+## Important Notes
+
+- Returns **metadata only** - use `template-get` for full snippet body
+- Includes **both published and unpublished** snippets
+- **Does not include custom_snippets** - use `template-list-custom-snippets` for those
+- Snippets are **site-scoped** - cannot be shared across sites directly
+- **Empty array** is valid response (means no snippets exist)
+- Order is typically by **created_at** (oldest first)
+- Snippet **IDs are unique** within platform, not just site
+
+## See Also
+
+### Documentation
+- [Snippets and Code Reusability Guide](../../guides/snippets-guide.md)
+- [Template Management Best Practices](../../guides/template-management.md)
+- [Liquid Template Language](../../guides/liquid-guide.md)
+
+### Official Modyo Documentation
+- [Modyo Snippets Docs](https://docs.modyo.com/en/platform/channels/templates.html#snippets)
+- [API Reference](https://api.modyo.com/swagger#/templates/get_sites__site_id__templates_snippets)
+- [Liquid Template Guide](https://docs.modyo.com/en/platform/channels/liquid-markup.html)
+
+### Related Tool Documentation
+- [template-create](./template-create.md) - Create new snippets
+- [template-list-custom-snippets](./template-list-custom-snippets.md) - List custom snippets
+- [template-get](./template-get.md) - Get full snippet details
+- [template-save](./template-save.md) - Update snippet code
+- [page-update](../pages/page-update.md) - Use snippets in pages