@modyo/mcp 0.1.0

package/docs/workflows/published-page-deletion.md

@@ -0,0 +1,366 @@
+# Published Page Deletion Workflow
+
+**Date**: 2025-01-18
+**Platform**: Modyo Channels
+**Status**: ✅ Verified and Working
+
+---
+
+## Overview
+
+This document describes the correct workflow for deleting a **published page** in Modyo. Published pages require a three-step process: unpublish, archive workflow, then delete.
+
+## Three-Step Workflow
+
+### Step 1: Unpublish the Page
+
+**Endpoint**: `POST /sites/{site_id}/layout_pages/{id}/unpublish`
+
+**MCP Tool**: `page-unpublish`
+
+**Request Body**:
+```json
+{
+  "layout_page": {
+    "unpublish_at": ""
+  }
+}
+```
+
+**Empty string** (`""`) means "unpublish immediately". For scheduled unpublish, use ISO 8601 datetime:
+```json
+{
+  "layout_page": {
+    "unpublish_at": "2025-12-31T23:59:59Z"
+  }
+}
+```
+
+**Example Usage**:
+```typescript
+page-unpublish({
+  platformSlug: "fed-team",
+  siteId: 4606,
+  pageId: 175396
+})
+```
+
+**What Happens**:
+- Page is removed from live site
+- Page status changes from "published" to "unpublished"
+- Page remains in Modyo admin but not visible to public
+- Workflow remains active
+
+---
+
+### Step 2: Archive the Workflow
+
+**Endpoint**: `POST /workflows/{workflow_id}/archive`
+
+**MCP Tool**: `page-archive`
+
+**Request Body**:
+```json
+{
+  "app_type": "site",
+  "app_id": 4606
+}
+```
+
+**Example Usage**:
+```typescript
+page-archive({
+  platformSlug: "fed-team",
+  siteId: 4606,
+  pageId: 175396
+})
+```
+
+**What Happens**:
+- Tool automatically gets `workflow_id` from page
+- Archives the workflow associated with the page
+- Page can now be safely deleted
+- Workflow history is preserved
+
+**Important**: The `page-archive` tool handles getting the workflow_id automatically. You don't need to find it manually.
+
+---
+
+### Step 3: Delete the Page
+
+**Endpoint**: `DELETE /sites/{site_id}/layout_pages/{id}`
+
+**MCP Tool**: `page-delete`
+
+**Request Body**: Empty (no body required)
+
+**Example Usage**:
+```typescript
+page-delete({
+  platformSlug: "fed-team",
+  siteId: 4606,
+  pageId: 175396
+})
+```
+
+**What Happens**:
+- Page is permanently deleted from Modyo
+- Page record removed from database
+- This operation cannot be undone
+
+---
+
+## Complete Workflow Example
+
+```typescript
+// Full workflow to delete a published page
+const platformSlug = "fed-team";
+const siteId = 4606;
+const pageId = 175396;
+
+// Step 1: Unpublish
+await page-unpublish({
+  platformSlug,
+  siteId,
+  pageId
+  // layout_page is optional - omit for immediate unpublish
+});
+
+// Step 2: Archive workflow
+await page-archive({
+  platformSlug,
+  siteId,
+  pageId
+});
+
+// Step 3: Delete page
+await page-delete({
+  platformSlug,
+  siteId,
+  pageId
+});
+```
+
+---
+
+## Authentication: Bearer Token vs CSRF Token
+
+### Browser Authentication (Session-Based)
+
+Browser requests include `authenticity_token` in the request body:
+
+```bash
+curl 'https://fed-team.modyo.cloud/api/admin/sites/4606/layout_pages/175396/unpublish' \
+  -H 'content-type: application/json' \
+  -b 'cloud-prod_session=...' \
+  --data-raw '{"layout_page":{"unpublish_at":""},"authenticity_token":"pGgiNhe..."}'
+```
+
+**Why**: Browsers use session cookies for authentication, requiring CSRF protection via `authenticity_token`.
+
+### API Authentication (Bearer Token)
+
+MCP tools use Bearer token in Authorization header:
+
+```bash
+curl 'https://fed-team.modyo.cloud/api/admin/sites/4606/layout_pages/175396/unpublish' \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer YOUR_API_TOKEN' \
+  --data-raw '{"layout_page":{"unpublish_at":""}}'
+```
+
+**Why**: Bearer tokens provide authentication without cookies, eliminating need for CSRF tokens.
+
+**IMPORTANT**: ✅ **CSRF tokens are NOT required for API calls with Bearer tokens**
+
+Our MCP implementations correctly:
+- ✅ Use Bearer token authentication (handled by `FetchRepositoryBase`)
+- ✅ Do NOT include `authenticity_token` in request bodies
+- ✅ Send proper request body structure matching API expectations
+
+---
+
+## Home Page Restriction
+
+**⚠️ CRITICAL**: Home pages (path `/` or empty `""`) **CANNOT** be unpublished or deleted via API.
+
+This is a **Modyo platform protection** to prevent accidentally breaking the site.
+
+**Home Page Detection**:
+- Path is `/` (root)
+- Path is `""` (empty string)
+- Page type is `home` or `homelayoutpage`
+
+**What Happens**:
+Both `page-unpublish` and `page-delete` tools will throw an error:
+```
+Cannot unpublish home page (ID: 175381, path: "/").
+Home pages are protected by Modyo platform and cannot be unpublished or deleted via API.
+If you need to change the home page:
+1. Create a new page to be the home page,
+2. Update site settings to set the new home page,
+3. Then you can unpublish the old home page.
+```
+
+**Workaround**:
+1. Create a new page to serve as the home page
+2. In Modyo Admin UI → Channels → Sites → Settings
+3. Change the home page to the new page
+4. Now the old page can be unpublished/deleted
+
+---
+
+## Page States and Allowed Operations
+
+| Page State | Can Unpublish | Can Archive | Can Delete | Notes |
+|------------|---------------|-------------|------------|-------|
+| Draft | ⚠️ No-op | ✅ Yes | ✅ Yes | Already unpublished |
+| Review | ⚠️ No-op | ✅ Yes | ✅ Yes | Already unpublished |
+| Scheduled | ✅ Yes | ✅ Yes | ⚠️ Unpublish first | Cancel scheduled publish |
+| Published | ✅ Yes | ✅ Yes | ⚠️ Unpublish first | Requires 3-step workflow |
+| Home Page | ❌ No | ❌ No | ❌ No | Protected by platform |
+
+**Legend**:
+- ✅ Yes: Operation allowed and works
+- ⚠️ Unpublish first: Requires unpublish before deletion
+- ⚠️ No-op: Operation succeeds but has no effect
+- ❌ No: Operation blocked by platform
+
+---
+
+## Error Handling
+
+### "Cannot unpublish home page"
+**Cause**: Attempting to unpublish a page with path `/` or ``
+**Solution**: Change site home page in admin UI settings first
+
+### "Page does not have an associated workflow"
+**Cause**: Attempting to archive a page without a workflow
+**Solution**: This is rare. Contact platform admin or skip archive step
+
+### "Fetch error (400): Bad Request"
+**Cause**: Invalid request body structure
+**Solution**: Verify request body matches documented format (our tools handle this correctly)
+
+### "Fetch error (404): Not Found"
+**Cause**: Page ID doesn't exist or already deleted
+**Solution**: Verify page ID is correct using `page-list` or `page-get`
+
+### "Fetch error (403): Forbidden"
+**Cause**: Insufficient permissions
+**Solution**: Verify API token has appropriate permissions for page operations
+
+---
+
+## Implementation Details
+
+### Repository Methods
+
+**PagesRepository** (`src/repositories/channels/pages/PagesRepository.ts`):
+```typescript
+async unpublishPage(
+  siteId: number,
+  pageId: number,
+  data?: Record<string, unknown>,
+): Promise<void> {
+  return this.fetchClient.post(
+    `/sites/${siteId}/layout_pages/${pageId}/unpublish`,
+    { layout_page: data ?? {} }  // Wraps in layout_page key
+  );
+}
+
+async deletePage(siteId: number, pageId: number): Promise<void> {
+  return this.fetchClient.delete(
+    `/sites/${siteId}/layout_pages/${pageId}`
+    // No body required
+  );
+}
+```
+
+**WorkflowsRepository** (`src/repositories/channels/workflows/WorkflowsRepository.ts`):
+```typescript
+async archiveWorkflow(
+  workflowId: number,
+  params: ArchiveWorkflowParams,
+): Promise<void> {
+  return this.fetchClient.post(
+    `/workflows/${workflowId}/archive`,
+    params  // { app_type: "site", app_id: siteId }
+  );
+}
+```
+
+### Tool Implementations
+
+All three tools extend `ToolBase` and use the repository pattern:
+
+1. **Unpublish Tool** (`src/tools/channels/pages/Unpublish.ts`)
+   - Validates home page protection
+   - Calls `repo.unpublishPage(siteId, pageId, layout_page)`
+   - Repository wraps data in `layout_page` key
+
+2. **Archive Tool** (`src/tools/channels/pages/Archive.ts`)
+   - Gets page to retrieve `workflow_id`
+   - Validates workflow exists
+   - Calls `workflowRepo.archiveWorkflow(workflow_id, {app_type, app_id})`
+
+3. **Delete Tool** (`src/tools/channels/pages/Delete.ts`)
+   - Validates home page protection
+   - Calls `repo.deletePage(siteId, pageId)`
+   - No request body required
+
+---
+
+## Testing
+
+All three tools have comprehensive unit tests:
+
+- `tests/unit/tools/channels/pages/Unpublish.test.ts` - 11 tests
+- `tests/unit/tools/channels/pages/Archive.test.ts` - 7 tests
+- `tests/unit/tools/channels/pages/Delete.test.ts` - Tests include home page validation
+
+**Test Coverage**:
+- ✅ Successful operations
+- ✅ Home page protection
+- ✅ Error handling
+- ✅ Different page states
+- ✅ Parameter validation
+
+Run tests:
+```bash
+npm test -- test/tools/channels/pages
+```
+
+---
+
+## Related Documentation
+
+- [PAGE_UNPUBLISH_ISSUE.md](../issues/PAGE_UNPUBLISH_ISSUE.md) - Investigation notes
+- [TESTING_UNPUBLISH.md](../issues/TESTING_UNPUBLISH.md) - Testing guide
+- [MODYO_PAGE_TYPES.md](../MODYO_PAGE_TYPES.md) - Page types reference
+- [Modyo API Documentation](https://docs.modyo.com/en/platform/channels/pages.html)
+
+---
+
+## Summary
+
+**Key Takeaways**:
+
+1. ✅ Published pages require 3 steps: unpublish → archive → delete
+2. ✅ Bearer token authentication is sufficient (no CSRF tokens needed)
+3. ✅ Home pages are protected and cannot be unpublished/deleted via API
+4. ✅ All MCP tools implement correct request body structure
+5. ✅ Workflows must be archived before page deletion
+
+**MCP Tools**:
+- `page-unpublish` - Step 1: Remove from live site
+- `page-archive` - Step 2: Archive workflow
+- `page-delete` - Step 3: Permanently delete
+
+**Validation**: All tools validate home page protection and provide helpful error messages.
+
+---
+
+**Last Updated**: 2025-01-18
+**Verified Against**: Modyo Platform (fed-team.modyo.cloud, site ID: 4606)
+**Status**: ✅ Production Ready

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@modyo/mcp",
+  "version": "0.1.0",
+  "description": "Unified Modyo MCP Server - Model Context Protocol server for Modyo platform",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "bin": {
+    "modyo-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node build/index.js",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc && tsc-alias && chmod +x build/index.js",
+    "test": "vitest",
+    "test:run": "vitest --run",
+    "test:coverage": "vitest --run --coverage",
+    "clean": "rm -rf build tsconfig.tsbuildinfo",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write ./",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "archiver": "^7.0.1",
+    "file-type": "^21.3.0",
+    "pino": "^10.1.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@types/archiver": "^6.0.3",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "pino-pretty": "^13.1.3",
+    "strtok3": "^10.3.4",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vite-tsconfig-paths": "^6.0.3",
+    "vitest": "^4.0.16",
+    "zod-to-json-schema": "^3.25.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modyo/modyo-mcp-server.git"
+  },
+  "contributors": [
+    {
+      "name": "Modyo Team",
+      "email": "info@modyo.com"
+    }
+  ],
+  "keywords": [
+    "modyo",
+    "mcp",
+    "model-context-protocol",
+    "content",
+    "channels",
+    "customers",
+    "headless-cms"
+  ],
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Modyo Team (https://modyo.com/)",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": [
+      "biome check --write"
+    ],
+    "*.{json,md}": [
+      "biome format --write"
+    ]
+  }
+}