@modyo/mcp 0.1.0

package/docs/platform/content.md

@@ -0,0 +1,76 @@
+# Modyo Content Module
+
+Headless CMS for structured content management.
+
+## Resource Hierarchy
+
+```
+Platform
+└── Spaces (content repositories)
+    ├── Types - Content schemas
+    │   └── Fields (text, rich_text, asset, location, etc.)
+    ├── Entries - Content instances
+    │   ├── Field values per locale
+    │   ├── Meta (slug, tags, category)
+    │   └── Workflow (draft/review/published)
+    ├── Assets - Media files
+    │   └── Folders for organization
+    └── Categories - Content taxonomy
+```
+
+## Key Concepts
+
+### Spaces
+- Isolated content repositories
+- Each space has its own types, entries, assets
+- Identified by `spaceId` or `space_uid`
+
+### Types
+- Define content structure (schema)
+- Fields: text, rich_text, asset, location, checkbox, dropdown, etc.
+- Support localization per field
+
+### Entries
+- Content instances of a type
+- Multi-locale support
+- Publishing workflow: draft → review → published
+
+### Assets
+- Media files (images, videos, documents)
+- Organized in folders
+- Referenced by entries via asset fields
+
+### Segments (from Customers realm)
+- Content spaces can connect to one realm
+- Entries can be targeted to specific user segments
+
+## Localization
+
+### Main Locales
+- `es-es` - Spanish
+- `en-en` - English
+- `pt-pt` - Portuguese
+
+### Accessing Other Locales
+Use Liquid filter for other languages:
+```liquid
+{{ entry.field | by_lang: "fr" }}
+{{ entry.title | by_lang: "de" }}
+```
+
+## Content API
+
+Published entries accessible via:
+```
+GET /api/content/spaces/{space_uid}/types/{type_uid}/entries
+```
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `spaces-manage` | Space lifecycle |
+| `types-manage` | Type/schema management |
+| `entries-manage` | Entry CRUD + publishing |
+| `assets-manage` | Asset upload and management |
+| `categories-manage` | Taxonomy management |

package/docs/platform/core.md

@@ -0,0 +1,54 @@
+# Modyo Core Module
+
+Platform-level management and team access control.
+
+## Resource Hierarchy
+
+```
+Platform
+├── Team Members - Platform users
+│   ├── Organization role (required)
+│   ├── Scoped roles per module
+│   └── Group memberships
+├── Groups - Organizational units
+├── Roles - Permission sets (scoped)
+└── Settings - Platform configuration
+```
+
+## Key Concepts
+
+### Team Members
+- Platform users (not end customers)
+- Can belong to multiple groups
+- Must have one organization role
+
+### Role Scopes
+Roles are scoped by module:
+
+| Scope | Applies to |
+|-------|-----------|
+| `organization` | Platform-wide (required) |
+| `content` | Content module access |
+| `channels` | Channels module access |
+| `customers` | Customers module access |
+
+Each user has:
+1. One organization role (required)
+2. Scoped roles per module they access
+
+### Groups
+- Organizational units for team members
+- Users can belong to multiple groups
+
+### Settings
+- Platform-wide configuration
+- Locales, time zones, features
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `team-member-manage` | Team member CRUD |
+| `group-manage` | Group lifecycle |
+| `role-manage` | Role assignment |
+| `settings-manage` | Platform settings |

package/docs/platform/customers.md

@@ -0,0 +1,72 @@
+# Modyo Customers Module
+
+User identity and data collection management.
+
+## Resource Hierarchy
+
+```
+Platform
+└── Realms (identity domains)
+    ├── Users - End customers
+    │   ├── Profile data
+    │   ├── Custom fields
+    │   └── Segments
+    ├── Forms - Data collection
+    │   ├── Fields (text, select, file, etc.)
+    │   └── Validations
+    ├── Submissions - Form responses
+    │   └── Originations workflow
+    ├── Data Sets - Reference data
+    └── Segments - User groups
+        └── Dynamic rules
+```
+
+## Key Concepts
+
+### Realms
+- Identity domains for end-user authentication
+- Connected to sites (one realm per site)
+- Connected to content spaces (one realm per space)
+
+### Users
+- End customers (not platform team members)
+- Custom profile fields
+- Segment membership
+
+### Segments
+- Dynamic user groups with rule-based membership
+- Used by channels for page visibility
+- Used by content for entry targeting
+
+### Forms
+- Data collection templates
+- Field types: text, textarea, select, checkbox, file, etc.
+- Validation rules
+
+### Originations
+- Form submission workflows
+- Multi-step processes
+- Rule-based routing
+
+### Data Sets
+- Reference data for forms
+- Dropdown options, lookup tables
+
+## Authentication
+
+Realms support:
+- Modyo native auth
+- OAuth2 providers
+- SAML/SSO
+- Custom identity providers
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `realms-manage` | Realm lifecycle |
+| `realm-user-manage` | User CRUD |
+| `forms-manage` | Form builder |
+| `submissions-manage` | Submission handling |
+| `originations-manage` | Workflow management |
+| `data-sets-manage` | Reference data |

package/docs/tools/CLAUDE.md

@@ -0,0 +1,358 @@
+# Tool Development Context - docs/tools/
+
+## Purpose
+
+This directory contains comprehensive documentation for all MCP tools. When developing new tools or understanding existing ones, reference these documents for complete context.
+
+## Key Documents
+
+### Core Tool Documentation
+
+1. **[TOOLS_SUMMARY.md](./TOOLS_SUMMARY.md)** - Overview of all 73 tools organized by domain
+   - Admin tools (10): users, groups, platforms, roles, settings
+   - Content tools (21): spaces, entries, assets, types, categories
+   - Channels tools (21): sites, pages, widgets, templates, navigation
+   - Customers tools (15): realms, users, forms, submissions
+
+2. **[RELEASE_TOOLS.md](./RELEASE_TOOLS.md)** - Publishing workflow
+   - Two-step release process
+   - Get publishable elements → Create release
+   - Critical for publishing widgets, pages, templates, menus
+
+3. **[WIDGET_TOOLS.md](./WIDGET_TOOLS.md)** - Widget management
+   - Widget definitions (creation, update, variables)
+   - Publishing widgets (must be published before use)
+   - Widget UUIDs are OIDs (40-char hex), not RFC 4122 UUIDs
+
+4. **[PAGE_WIDGET_TOOLS.md](./PAGE_WIDGET_TOOLS.md)** - Widget positioning on pages
+   - Adding widgets to WIDGET PAGES only (not content/origination pages)
+   - `sync` parameter (render-blocking vs non-blocking)
+   - Column validation based on `grid_type`
+
+5. **[PAGE_PARAMETERS_EXPLAINED.md](./PAGE_PARAMETERS_EXPLAINED.md)** - Critical parameters
+   - `has_router` dual purpose:
+     - Widget pages: Client-side JS routing (SPAs)
+     - Content pages: Server-side slug routing
+   - `sync` parameter: Widget loading mode
+   - Performance implications and best practices
+
+## Architecture Context
+
+### Rendering System
+
+**Must understand before creating template/page/widget tools**:
+- Read [../MODYO_SNIPPETS_ARCHITECTURE.md](../MODYO_SNIPPETS_ARCHITECTURE.md) first
+- Layouts wrap entire page with `{{ html5 }}` and `{{ content_for_layout }}`
+- `content_for_layout` invokes grid snippet based on `page.grid_type`
+- Grid snippets organize widgets using `page_grid` object
+- Widget snippets handle sync/async rendering
+
+**Key Files**:
+- [../MODYO_SNIPPETS_ARCHITECTURE.md](../MODYO_SNIPPETS_ARCHITECTURE.md) - Complete rendering system
+- [../MODYO_SITE_ARCHITECTURE.md](../MODYO_SITE_ARCHITECTURE.md) - Site structure
+- [../MODYO_PAGE_TYPES.md](../MODYO_PAGE_TYPES.md) - Three page types
+
+### Page Types - Critical for Tool Development
+
+**Three distinct page types** (NEVER mix them up):
+
+| Type | Widgets | Content | Forms | Use Case |
+|------|---------|---------|-------|----------|
+| **Widget Pages** | ✅ Custom widgets | ❌ | ❌ | SPAs, dashboards |
+| **Content Pages** | ❌ | ✅ Liquid + Content API | ❌ | Blogs, catalogs |
+| **Origination Pages** | ❌ | ❌ | ✅ Forms | Applications |
+
+**Tool Implications**:
+- `page-add-widgets` ONLY works with Widget Pages
+- Content pages use `content_type_id` and Liquid templates
+- Origination pages use forms and submission workflows
+
+### Widget Types
+
+**Two widget types** (affects deployment):
+
+| Type | `read_only` | Editable | Deployment | Format |
+|------|------------|----------|------------|--------|
+| **Normal** | `false` | ✅ Yes | Modyo UI | HTML/CSS/JS |
+| **CLI** | `true` | ❌ No | CLI push | Bundle or Zip |
+
+**CLI Widget Formats**:
+- **Bundle** (`zip: false`): Single HTML/CSS/JS bundle
+- **Zip** (`zip: true`): Full build directory with code splitting
+
+### Publishing Workflow
+
+**Two-step process** (required for all publishable resources):
+
+```typescript
+// Step 1: Get what can be published
+release-get-elements-to-publish({ platformSlug, siteId })
+
+// Step 2: Create release with selected elements
+release-create({
+  platformSlug,
+  siteId,
+  data: {
+    widgetDefinition: [{ id: 123, selected: true }],
+    page: [{ id: 456, selected: true }],
+    template: [{ id: 789, selected: true }]
+  }
+})
+```
+
+**What needs publishing**:
+- Widget definitions (before adding to pages)
+- Pages (before going live)
+- Templates (snippets, layouts, CSS, JS)
+- Menus (navigation structures)
+
+## Tool Development Patterns
+
+### Using Class-Based Tools (Recommended)
+
+**Extend `ToolBase`** for cleaner code:
+
+```typescript
+import { ToolBase, orgValidation } from "@modyo/mcp-shared";
+import { z } from "zod/v3";
+
+class MyTool extends ToolBase {
+  protected config = {
+    name: "my-tool",
+    description: "Tool description",
+    annotations: {
+      readOnlyHint: false,
+      idempotentHint: false,
+      destructiveHint: true,
+    },
+    isPublic: false,
+  };
+
+  protected getParamsSchema() {
+    return z.object({
+      platformSlug: orgValidation,
+      siteId: z.number().min(1),
+      // ... other params
+    });
+  }
+
+  async execute(params: z.infer<ReturnType<MyTool["getParamsSchema"]>>) {
+    // getRepository is async - fetches platform config from mcp-platforms service
+    const repo = await this.getRepository(MyRepository, params.platformSlug);
+
+    const result = await repo.doSomething(params);
+
+    return this.success(result);
+  }
+}
+
+export const MyToolInstance: Tool = new MyTool();
+```
+
+See [../../src/tools/CLASS_BASED_TOOLS.md](../../src/tools/CLASS_BASED_TOOLS.md) for details.
+
+### Common Validation Patterns
+
+**Platform slug** (always required):
+```typescript
+import { orgValidation } from "@modyo/mcp-shared";
+
+platformSlug: orgValidation
+```
+
+**Slug format** (for names/identifiers):
+```typescript
+import { slugRegex } from "@modyo/mcp-shared/helpers";
+
+uid: z.string().regex(slugRegex, "Must be valid slug")
+```
+
+**Widget UUIDs** (OIDs, not standard UUIDs):
+```typescript
+// ❌ WRONG
+widget_uuid: z.string().uuid()
+
+// ✅ CORRECT
+widget_uuid: z.string() // OIDs are 40-char hex strings
+```
+
+### Repository Pattern
+
+**Always use the async repository helper** in ToolBase:
+
+```typescript
+// In any tool extending ToolBase
+const repo = await this.getRepository(MyRepository, platformSlug);
+const result = await repo.myMethod(params);
+```
+
+**Note**: Repository access is now async because platform configs are fetched from the mcp-platforms service. Always use `await` when calling `this.getRepository()`.
+
+## Common Mistakes to Avoid
+
+### ❌ Widget Tool Mistakes
+
+1. **Trying to add widgets to content/origination pages**
+   ```typescript
+   // ❌ Will fail - content pages don't accept widgets
+   page-add-widgets({ pageId: contentPageId, widgets: [...] })
+   ```
+
+2. **Using unpublished widget definitions**
+   ```typescript
+   // ❌ Widget not published yet
+   page-add-widgets({ widgets: [{ definition_uuid: "unpublished..." }] })
+
+   // ✅ Publish first
+   release-create({ data: { widgetDefinition: [{ id: 123, selected: true }] } })
+   ```
+
+3. **Wrong column for grid type**
+   ```typescript
+   // ❌ full_grid only has column 0
+   page-add-widgets({ widgets: [{ column: 1 }] })
+
+   // ✅ Use column 0
+   page-add-widgets({ widgets: [{ column: 0 }] })
+   ```
+
+### ❌ Page Tool Mistakes
+
+1. **Missing content_type_id for content pages**
+   ```typescript
+   // ❌ Content pages require content_type_id
+   page-create({ page_type: "content", path: "/blog" })
+
+   // ✅ Include content_type_id
+   page-create({ page_type: "content", content_type_id: 5756 })
+   ```
+
+2. **Forgetting has_router for content show pages**
+   ```typescript
+   // ❌ Entry pages need has_router for slug routing
+   page-create({ page_type: "entry", has_router: false })
+
+   // ✅ Enable router for slugs
+   page-create({ page_type: "entry", has_router: true })
+   ```
+
+### ❌ UUID Validation Mistakes
+
+1. **Using .uuid() for widget UUIDs**
+   ```typescript
+   // ❌ Widget UUIDs are OIDs (40-char hex)
+   definition_uuid: z.string().uuid()
+
+   // ✅ OIDs are strings, not RFC 4122 UUIDs
+   definition_uuid: z.string()
+   ```
+
+### ❌ Publishing Mistakes
+
+1. **Skipping the release step**
+   ```typescript
+   // ❌ Widget not published
+   widget-definitions-create({ name: "My Widget" })
+   page-add-widgets({ widgets: [{ definition_uuid: "..." }] })
+
+   // ✅ Publish before using
+   widget-definitions-create({ name: "My Widget" })
+   release-create({ data: { widgetDefinition: [...] } })
+   page-add-widgets({ widgets: [{ definition_uuid: "..." }] })
+   ```
+
+## Liquid Drops Reference
+
+**Available in templates/snippets/widgets** (from [../MODYO_SNIPPETS_ARCHITECTURE.md](../MODYO_SNIPPETS_ARCHITECTURE.md)):
+
+| Object | Properties | Context |
+|--------|-----------|---------|
+| `account` | url, host, google_key | All |
+| `site` | name, description, language, logo, url | All |
+| `page` | content, name, url, title, description, grid | Pages/Layouts |
+| `page_grid` | column_0/1/2, main_widgets, sidebar | Grid snippets |
+| `widget` | wid, version, sync, css, html, js, name | Widget snippets |
+| `entry` | space, category, type, tags, fields | Content pages |
+| `category` | id, slug, name, url, children | Content pages |
+| `asset` | data_file_name, description, url | All |
+
+**Special variables**:
+- `{{ csp_nonce }}` - CSP nonce for inline scripts/styles
+- `{{ content_for_layout }}` - Invokes grid snippet in layouts
+- `{{ html5.open_tag }}` / `{{ html5.close_tag }}` - HTML5 document tags
+
+## Testing Tools
+
+### Using MCP Inspector
+
+```bash
+npm run inspect
+```
+
+**Access**: http://localhost:5173
+
+**Test workflow**:
+1. Select tool from list
+2. Fill in parameters
+3. Click "Run Tool"
+4. Inspect JSON response
+
+### Testing with Claude Code
+
+**Configure** in `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "modyo-mcp": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/modyo-mcp/src/index.ts"]
+    }
+  }
+}
+```
+
+**Test in conversation**:
+```
+Claude: "List all spaces in fed-team"
+Claude: "Create a widget named 'Test Widget'"
+Claude: "Add widget to page 12345"
+```
+
+## Quick Reference Checklist
+
+**Before creating a page tool**:
+- [ ] Understand 3 page types (Widget, Content, Origination)
+- [ ] Know when to use `has_router` (dual purpose)
+- [ ] Understand `content_type_id` requirement for content pages
+
+**Before creating a widget tool**:
+- [ ] Understand widget types (Normal vs CLI)
+- [ ] Know publishing is required before use
+- [ ] Understand `sync` parameter implications
+- [ ] Validate columns match `grid_type`
+
+**Before creating a template tool**:
+- [ ] Read MODYO_SNIPPETS_ARCHITECTURE.md
+- [ ] Understand layouts vs snippets
+- [ ] Know system snippets have `deletable: false`
+- [ ] Understand snippet groups and purposes
+
+**Before creating a release tool**:
+- [ ] Understand two-step workflow
+- [ ] Know what resources need publishing
+- [ ] Understand async nature of releases
+
+## Related Documentation
+
+- [../CONTEXT_FOR_NEW_TOOLS.md](../CONTEXT_FOR_NEW_TOOLS.md) - Master tool development reference
+- [../MODYO_SNIPPETS_ARCHITECTURE.md](../MODYO_SNIPPETS_ARCHITECTURE.md) - Rendering system
+- [../MODYO_SITE_ARCHITECTURE.md](../MODYO_SITE_ARCHITECTURE.md) - Site structure
+- [../MODYO_PAGE_TYPES.md](../MODYO_PAGE_TYPES.md) - Page types
+- [../../src/tools/CLASS_BASED_TOOLS.md](../../src/tools/CLASS_BASED_TOOLS.md) - ToolBase pattern
+- [../../src/tools/ERROR_HANDLING.md](../../src/tools/ERROR_HANDLING.md) - Error strategies
+
+---
+
+**Document Version**: 2.0.0
+**Last Updated**: 2025-12-26
+**Purpose**: Provide context for tool development and usage