@modyo/mcp 0.1.0

package/docs/development/mcp-overview.md

@@ -0,0 +1,269 @@
+---
+search: true
+---
+
+# MCP Server
+
+The Modyo MCP (Model Context Protocol) Server is a tool based on two fundamental principles: AI integration and platform automation, implemented through natural language commands that interact directly with Modyo platform APIs.
+
+## Benefits of the MCP Server
+
+- **67 Tools**: Smart "manage" tools that combine multiple operations with 70-90% token reduction.
+- **Secure Authentication**: Uses token-based authentication for secure access.
+- **Universal Client Support**: Works with Claude Code, VS Code, Cursor, and other MCP-compatible clients.
+
+## Modules
+
+The server includes four modules in a single package:
+
+| Module | Description |
+|--------|-------------|
+| **Content** | Headless CMS - spaces, entries, types, assets, categories |
+| **Channels** | Digital Experience - sites, pages, widgets, templates, navigation |
+| **Customers** | Identity Management - realms, users, forms, submissions |
+| **Core** | Platform Administration - team users, groups, roles, settings |
+
+## Installation
+
+### Option 1: npx (Recommended)
+
+The simplest way to use the MCP server:
+
+```bash
+npx @modyo/mcp
+```
+
+### Option 2: Global Installation
+
+```bash
+npm install -g @modyo/mcp
+modyo-mcp
+```
+
+### Option 3: From Source
+
+```bash
+git clone https://github.com/modyo/modyo-mcp-server
+cd modyo-mcp-server
+npm install
+npm run build
+npm start
+```
+
+## Environment Configuration
+
+### Required Environment Variables
+
+| Variable | Example | Description |
+|----------|---------|-------------|
+| `MODYO_URL` | `https://my-company.modyo.cloud` | Your Modyo platform URL |
+| `MODYO_TOKEN` | `eyJ...` | API token from Modyo Admin → Settings → API Access |
+
+### Optional Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MODYO_PLATFORM_NAME` | `default` | Name to identify the platform |
+| `DEBUG` | `false` | Enable debug logging |
+
+### Previous Actions
+
+- **Get a Modyo access token**: To get the token, you need to have a user or [create one](/en/platform/core/roles.html#create-user) with at least the [role](/en/platform/core/roles.html#roles) of `developer` on the sites, spaces, or realms where you'll interact. Once the user is created, you can [configure an access token](/en/platform/core/api.html#authentication) for them.
+
+- **Identify your platform URL**: Get the base URL of your Modyo organization (e.g., `https://my-company.modyo.com`).
+
+## Client Configuration
+
+### Claude Code
+
+```bash
+claude mcp add modyo -- npx @modyo/mcp \
+  --env MODYO_URL=https://my-company.modyo.cloud \
+  --env MODYO_TOKEN=your_api_token
+```
+
+Or if you installed from source:
+
+```bash
+claude mcp add modyo -- node /path/to/modyo-mcp-server/build/index.js \
+  --env MODYO_URL=https://my-company.modyo.cloud \
+  --env MODYO_TOKEN=your_api_token
+```
+
+### Claude Desktop
+
+1. **Locate the configuration file**:
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+   - **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+2. **Add the configuration**:
+
+```json
+{
+  "mcpServers": {
+    "modyo": {
+      "command": "npx",
+      "args": ["@modyo/mcp"],
+      "env": {
+        "MODYO_URL": "https://my-company.modyo.cloud",
+        "MODYO_TOKEN": "your_api_token"
+      }
+    }
+  }
+}
+```
+
+3. **Restart Claude Desktop**
+
+### VS Code / Cursor
+
+Add to your `.vscode/mcp.json` file:
+
+```json
+{
+  "servers": {
+    "modyo": {
+      "command": "npx",
+      "args": ["@modyo/mcp"],
+      "env": {
+        "MODYO_URL": "https://my-company.modyo.cloud",
+        "MODYO_TOKEN": "your_api_token"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to your `~/.gemini/settings.json` file:
+
+```json
+{
+  "mcpServers": {
+    "modyo": {
+      "command": "npx",
+      "args": ["@modyo/mcp"],
+      "env": {
+        "MODYO_URL": "https://my-company.modyo.cloud",
+        "MODYO_TOKEN": "your_api_token"
+      }
+    }
+  }
+}
+```
+
+## Tools Reference
+
+The following tools are available. These are smart "manage" tools that combine multiple operations into efficient workflows with 70-90% token reduction.
+
+:::tip Best Practice
+Most LLM clients allow you to enable or disable individual tools. Keep only the tools you need enabled to maintain a clean context and help the AI focus on what matters.
+:::
+
+### Content Module
+
+| Tool | Description |
+|------|-------------|
+| `content-spaces-manage` | Complete space lifecycle |
+| `content-spaces-copy` | Clone spaces |
+| `content-types-manage` | Content type schema management |
+| `content-types-upsert` | Idempotent type management by UID |
+| `content-types-copy` | Copy content types |
+| `content-entries-manage` | Entry lifecycle including publish/unpublish |
+| `content-entries-upsert` | Idempotent entry management by slug |
+| `content-entries-bulk` | Bulk operations with preview |
+| `content-assets-manage` | Asset management |
+| `content-assets-bulk` | Bulk asset upload |
+| `content-categories-manage` | Category hierarchy management |
+
+### Channels Module
+
+| Tool | Description |
+|------|-------------|
+| `channels-sites-manage` | Complete site lifecycle |
+| `channels-sites-overview` | Get complete site overview |
+| `channels-pages-manage` | Page management |
+| `channels-pages-widget` | Widget pages with positioning |
+| `channels-pages-content` | Content pages with Liquid templates |
+| `channels-pages-copy` | Copy pages |
+| `channels-widgets-manage` | Complete widget lifecycle |
+| `channels-widgets-upsert` | Idempotent widget management |
+| `channels-widgets-copy` | Copy widgets |
+| `channels-templates-manage` | Complete template lifecycle |
+| `channels-templates-upsert` | Idempotent template management |
+| `channels-templates-copy` | Copy templates |
+| `channels-menus-manage` | Navigation menu management |
+| `channels-menu-items-manage` | Menu item management |
+| `channels-menus-copy` | Copy menus |
+| `channels-variables-manage` | Global variables |
+| `channels-publish` | Smart publishing workflow |
+
+### Customers Module
+
+| Tool | Description |
+|------|-------------|
+| `customers-realms-manage` | Complete realm lifecycle |
+| `customers-users-manage` | User management by email |
+| `customers-users-bulk` | Bulk user operations |
+| `customers-forms-manage` | Complete form lifecycle |
+| `customers-forms-copy` | Copy forms |
+| `customers-datasets-manage` | Data set management |
+| `customers-datasets-copy` | Copy data sets |
+| `customers-originations-manage` | Origination lifecycle |
+| `customers-submissions-manage` | Submission management |
+| `customers-submissions-bulk` | Bulk submission operations |
+
+### Core Module
+
+| Tool | Description |
+|------|-------------|
+| `core-users-manage` | Team user lifecycle |
+| `core-users-upsert` | Idempotent operations by email |
+| `core-users-bulk` | Bulk activate/deactivate |
+| `core-groups-manage` | Group lifecycle |
+| `core-groups-upsert` | Idempotent operations by name |
+| `core-team-manage` | Assign users/groups to resources |
+| `core-roles-list` | List available roles |
+| `core-settings-manage` | Platform settings |
+
+## Usage Examples
+
+Once configured, you can interact with Modyo using natural language:
+
+```
+"List all spaces in my platform"
+
+"Create a content type called 'Products' with fields: name (text), price (number)"
+
+"Create an entry in the blog space with title 'Hello World'"
+
+"Show all published widgets for site ID 5"
+
+"Publish all pending pages and widgets for site 4605"
+
+"Assign user john@example.com to the marketing site with editor role"
+```
+
+## Troubleshooting
+
+### "Platform not configured" errors
+
+- Verify that `MODYO_URL` and `MODYO_TOKEN` environment variables are set
+- Ensure the token has the correct permissions
+
+### Tools not visible
+
+1. Verify the server is running
+2. Restart your MCP client
+3. Check MCP client logs for errors
+
+### Authentication errors
+
+- Verify API tokens have correct permissions
+- Ensure API endpoints are correct
+
+:::warning Attention
+The token owner user must have appropriate permissions for the operations you want to perform.
+:::

package/docs/development/test-utilities.md

@@ -0,0 +1,85 @@
+# Test Utilities
+
+Shared test patterns from `@modyo/mcp-shared`.
+
+## Quick Start
+
+```typescript
+import {
+  test,
+  expect, describe, it,
+  setupToolTest,
+  parseResultJSON,
+  STANDARD_PAGINATION_CASES,
+} from "@modyo/mcp-shared";
+```
+
+## Test Fixtures
+
+Use `test` for automatic fixture injection:
+
+```typescript
+test("should register tool", async ({ server, organizations, logger }) => {
+  MyTool.registerTool(server, organizations, logger);
+  expect(server.registerTool).toHaveBeenCalled();
+});
+
+test("should handle request", async ({ testSetup }) => {
+  const handler = testSetup.extractHandler();
+  const result = await handler({ action: "list" });
+  expect(result).toBeDefined();
+});
+```
+
+## Mock Creators
+
+| Function | Purpose |
+|----------|---------|
+| `createMockServer()` | Mock MCP server |
+| `createMockOrganizations(orgs?)` | Mock platform map |
+| `createMockLogger()` | Mock logger |
+| `setupToolTest()` | Complete setup |
+
+## Parametrized Cases
+
+```typescript
+import { STANDARD_PAGINATION_CASES } from "@modyo/mcp-shared";
+
+it.each(STANDARD_PAGINATION_CASES)(
+  "should handle $description",
+  async ({ params }) => {
+    await handler({ ...params });
+  }
+);
+```
+
+Available constants:
+- `STANDARD_PAGINATION_CASES`
+- `STANDARD_ID_CASES`
+- `STANDARD_QUERY_CASES`
+- `STANDARD_LIST_CASES`
+
+## Result Helpers
+
+| Function | Purpose |
+|----------|---------|
+| `parseResultJSON<T>(result)` | Parse JSON from result |
+| `extractResultText(result)` | Extract text content |
+| `isCallToolResult(result)` | Type guard |
+
+## Coverage Thresholds
+
+| Metric | Threshold |
+|--------|-----------|
+| Lines | 80% |
+| Statements | 80% |
+| Functions | 80% |
+| Branches | 75% |
+
+## Running Tests
+
+```bash
+npm run test:run                # All tests
+npm run test:coverage           # With coverage
+npm test -- --run src/file      # Single file
+```

package/docs/development/tool-patterns.md

@@ -0,0 +1,102 @@
+# Tool Implementation Patterns
+
+Standard patterns for MCP tool development.
+
+## Tool Description Format
+
+```
+Tool summary.
+
+**Actions**: action1, action2
+**Params**: param1 (required), param2
+**Response**: {format}
+**Note**: important notes
+
+📚 modyo://mcp-{module}/tools/{tool-name}
+```
+
+## Action Patterns
+
+### CRUD Actions
+| Action | Purpose |
+|--------|---------|
+| `manage` | Get/create/update (default) |
+| `list` | List with pagination |
+| `delete` | Delete resource |
+
+### Lifecycle Actions
+| Action | Purpose |
+|--------|---------|
+| `publish` | Publish draft |
+| `unpublish` | Remove from published |
+| `archive` | Archive resource |
+| `restore` | Restore archived |
+
+## Parameter Patterns
+
+### Smart Identifier
+```typescript
+identifier: z.union([z.string(), z.number()])
+```
+- **Number** → Direct ID lookup
+- **String** → Search by name/slug
+
+### Pagination
+```typescript
+page: z.number().min(1).default(1)
+per_page: z.number().min(1).max(100).default(30)
+```
+
+### Verification
+```typescript
+verify: z.boolean().default(false)
+```
+Returns before/after comparison.
+
+## Validation
+
+### Use Zod Refinements
+```typescript
+const schema = z.object({...})
+  .refine(
+    (data) => condition,
+    { message: "Error message", path: ["field"] }
+  );
+```
+
+Prefer refinements over `throw` in execute.
+
+## Response Patterns
+
+### Single Resource
+```json
+{ "id": 123, "name": "...", "action": "created|updated|deleted" }
+```
+
+### List Response
+```json
+{ "items": [...], "total": 100, "page": 1, "per_page": 30 }
+```
+
+### Verification Response
+```json
+{
+  "before": {...},
+  "after": {...},
+  "changes": ["field1", "field2"],
+  "verified": true
+}
+```
+
+## File Structure
+
+```
+src/tools/{category}/
+├── Manage.ts           # Main CRUD tool
+├── Copy.ts             # Cross-site copy
+├── UpdateOrCreate.ts   # Idempotent operations
+└── handlers/           # Action handlers (optional)
+    ├── index.ts
+    ├── listHandler.ts
+    └── manageHandler.ts
+```

package/docs/platform/api-quirks.md

@@ -0,0 +1,87 @@
+# Common API Quirks
+
+Documented API behaviors and workarounds.
+
+## ID vs UUID
+
+| Field | Behavior |
+|-------|----------|
+| `id` | Changes after publishing (new version) |
+| `uuid` | Stable across versions |
+
+Always use UUID for stable references.
+
+## Publishing Behavior
+
+### Widget/Template IDs
+- IDs change when published
+- Refetch lists after publishing
+- Use UUID for widget page references
+
+### Widget Publishing Order
+1. Create widget definition
+2. **Publish widget** (required)
+3. Add to page using `definition_uuid`
+
+## Field Formats
+
+### Content Groups (Nested Children)
+```json
+{
+  "children": [
+    { "parent_id": "temp_1", "name": "New Child" },
+    { "parent_id": 123, "name": "Existing Child" }
+  ]
+}
+```
+- `parent_id: "temp_N"` for new items
+- `parent_id: number` for existing items
+
+### Asset Sources
+Accept multiple formats:
+- Manager URL: `/api/files/{id}`
+- External URL: `https://...`
+- Local path: `/path/to/file`
+
+### Widget UUIDs
+- 40-character hex OIDs
+- NOT RFC 4122 UUIDs
+- Example: `507f1f77bcf86cd799439011`
+
+## Page Paths
+
+### Home Page
+- Path is `''` (empty string)
+- NOT `/home` or `home`
+- Cannot be deleted/unpublished
+
+### Path Format
+- No leading slash: `blog` not `/blog`
+- Nested: `products/category`
+
+## List vs Detail Responses
+
+Some fields differ between list and detail:
+
+### Pages
+- List: `full_path`
+- Detail: `path`
+
+### Widgets
+- List: `status: "published"` (string)
+- Detail: `published: true` (boolean)
+
+## Pagination Limits
+
+| Default | Max |
+|---------|-----|
+| 30 | 100 |
+
+## Template Names
+
+Allowed characters:
+- Lowercase letters (a-z)
+- Numbers (0-9)
+- Underscores (_)
+
+**Invalid**: uppercase, hyphens, spaces

package/docs/platform/architecture.md

@@ -0,0 +1,70 @@
+# Modyo Platform Architecture
+
+## Overview
+
+Modyo is a Digital Experience Platform (DXP) with four main modules:
+
+```
+Platform (Organization)
+├── Content - Headless CMS
+├── Channels - Website Builder
+├── Customers - Identity & Forms
+└── Core - Platform Management
+```
+
+## Core Concepts
+
+### Platform/Organization
+- Top-level container for all resources
+- Configured via environment variables (MODYO_URL, MODYO_TOKEN)
+
+### Publishing Workflow
+All content follows a draft → publish workflow:
+1. **Draft** - Initial creation, editable
+2. **Review** - Pending approval (optional)
+3. **Published** - Live, accessible via API/website
+4. **Scheduled** - Future publish date
+
+### ID vs UUID
+- **IDs** change after publishing (new version created)
+- **UUIDs** remain stable across versions
+- Always use UUIDs for stable references
+
+## API Authentication
+
+All APIs use token-based auth:
+```
+Authorization: Bearer {api_token}
+```
+
+Token configured via MODYO_TOKEN environment variable.
+
+## Resource URIs
+
+Tool documentation accessed via:
+```
+modyo://mcp-{module}/tools/{tool-name}
+```
+
+## Common Patterns
+
+### Smart Identifier Resolution
+Most tools accept flexible identifiers:
+- **Number** → Direct ID lookup
+- **String** → Search by name/slug/host
+
+### Verification Workflow
+Add `verify: true` to get before/after comparison:
+```json
+{
+  "before": {...},
+  "after": {...},
+  "changes": ["field1", "field2"],
+  "verified": true
+}
+```
+
+### Pagination
+Standard pagination params:
+- `page` - Page number (default: 1)
+- `per_page` - Results per page (default: 30, max: 100)

package/docs/platform/channels.md

@@ -0,0 +1,93 @@
+# Modyo Channels Module
+
+Website builder for digital experiences.
+
+## Resource Hierarchy
+
+```
+Platform
+└── Sites (websites)
+    ├── Pages (3 types)
+    │   ├── Widget Pages - Micro frontends
+    │   ├── Content Pages - Liquid + Content API
+    │   └── Origination Pages - Form workflows
+    ├── Widget Definitions - Reusable components
+    ├── Templates - Layouts, snippets, CSS, JS
+    ├── Navigation Menus - Site navigation
+    └── Global Variables - Site-wide config
+```
+
+## Key Concepts
+
+### Sites
+- Individual websites
+- Support stages (like git branches)
+- **Clone**: Independent copy
+- **Stage**: Linked branch with `original_stage` reference
+
+### Localization
+Sites only support three locales:
+- `es-es` - Spanish
+- `en-en` - English
+- `pt-pt` - Portuguese
+
+**Important**: Site locale must match content locale. For other languages, use Liquid filter:
+```liquid
+{{ entry.title | by_lang: "fr" }}
+```
+
+### Pages
+Three types:
+1. **Widget Pages** - Embed micro frontends (Vue/React apps)
+2. **Content Pages** - Liquid templates + Content API
+3. **Origination Pages** - Form submission workflows
+
+### Widget Definitions
+- Reusable micro frontend components
+- HTML + CSS + JS code
+- Must be published before use in pages
+
+### Templates
+| Category | Description | CDN-Cached |
+|----------|-------------|------------|
+| `layout` | Page wrapper (requires `{{ content_for_layout }}`) | No |
+| `custom_snippet` | Reusable Liquid components | No |
+| `stylesheet` | CSS templates | Yes |
+| `javascript` | JS templates | Yes |
+
+### Navigation
+- Hierarchical menu structure
+- Menu items with labels, URLs, parent relationships
+
+### Segments (from Customers realm)
+- Pages can be restricted to specific user segments
+- Access user segments via Liquid:
+```liquid
+{% if user.segments contains "premium" %}
+  <!-- Premium content -->
+{% endif %}
+```
+
+## Important Notes
+
+### Home Page
+- Path is `''` (empty string), NOT `/home`
+- Cannot be deleted, unpublished, or archived
+
+### Publishing
+- Widget/template IDs change after publishing
+- UUIDs remain stable
+- Use `smart-publish` for one-step publishing
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `sites-manage` | Site lifecycle + stages |
+| `page-manage` | Page properties |
+| `page-widget-manage` | Widget page creation |
+| `page-content-manage` | Content page creation |
+| `widget-definition-manage` | Widget CRUD |
+| `template-manage` | Template CRUD |
+| `navigation-menu-manage` | Menu management |
+| `smart-publish` | One-step publishing |