Improve copy-document tool with flattened schema and clearer workflow (#30)

- Flatten tool parameter schema for better LLM usability
  - Replace nested `id` + `data` structure with top-level parameters
  - Use `idToCopy` instead of `id` for clarity
  - Move `relateToOriginal` and `includeDescendants` to top level
  - Make `parentId` optional (omit for root, provide for specific parent)
- Add comprehensive tool description with workflow examples
  - Document the empty string return value behavior
  - Provide clear copy-only vs copy-and-update workflow patterns
  - Explain search-document requirement for post-copy operations
- Update e2e test to use update-document instead of search
  - Simplify workflow: copy → update → publish → delete
  - Remove unnecessary search-document and document-type lookups
  - Update allowed tools list to match actual workflow
- Pin mcp-server-tester to version 1.4.0 for consistency
- Update copy-document unit tests to match new schema

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Phil Whittaker <[email protected]>
Co-authored-by: Claude <[email protected]>

Author: 3 people

package.json

@@ -16,10 +16,10 @@
     "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "patch-publish-alpha": "npm version prerelease --preid=alpha && npm publish --tag alpha --access public",
-    "eval-mcp:basic": "npx mcp-server-tester evals tests/e2e/basic/basic-tests.yaml --server-config tests/e2e/basic/basic-tests-config.json",
-    "eval-mcp:create-data-type": "npx mcp-server-tester evals tests/e2e/create-data-type/create-data-type.yaml --server-config tests/e2e/create-data-type/create-data-type-config.json",
-    "eval-mcp:create-document-type": "npx mcp-server-tester evals tests/e2e/create-document-type/create-document-type.yaml --server-config tests/e2e/create-document-type/create-document-type-config.json",
-    "eval-mcp:create-blog-post": "npx mcp-server-tester evals tests/e2e/create-blog-post/create-blog-post.yaml --server-config tests/e2e/create-blog-post/create-blog-post-config.json",
+    "eval-mcp:basic": "npx mcp-server-tester@1.4.0 evals tests/e2e/basic/basic-tests.yaml --server-config tests/e2e/basic/basic-tests-config.json",
+    "eval-mcp:create-data-type": "npx mcp-server-tester@1.4.0 evals tests/e2e/create-data-type/create-data-type.yaml --server-config tests/e2e/create-data-type/create-data-type-config.json",
+    "eval-mcp:create-document-type": "npx mcp-server-tester@1.4.0 evals tests/e2e/create-document-type/create-document-type.yaml --server-config tests/e2e/create-document-type/create-document-type-config.json",
+    "eval-mcp:create-blog-post": "npx mcp-server-tester@1.4.0 evals tests/e2e/create-blog-post/create-blog-post.yaml --server-config tests/e2e/create-blog-post/create-blog-post-config.json",
     "eval-mcp:all": "npm run eval-mcp:basic && npm run eval-mcp:create-data-type && npm run eval-mcp:create-document-type && npm run eval-mcp:create-blog-post"
   },
   "engines": {

src/umb-management-api/tools/document/__tests__/copy-document.test.ts

@@ -34,15 +34,12 @@ describe("copy-document", () => {
       .withRootDocumentType()
       .create();
 
-    // Copy the document to root (no target)
+    // Copy the document to root (no parentId means root)
     const result = await CopyDocumentTool().handler(
       {
-        id: docBuilder.getId(),
-        data: {
-          target: null,
-          relateToOriginal: false,
-          includeDescendants: false,
-        },
+        idToCopy: docBuilder.getId(),
+        relateToOriginal: false,
+        includeDescendants: false,
       },
       { signal: new AbortController().signal }
     );
@@ -73,12 +70,9 @@ describe("copy-document", () => {
   it("should handle non-existent document", async () => {
     const result = await CopyDocumentTool().handler(
       {
-        id: BLANK_UUID,
-        data: {
-          target: null,
-          relateToOriginal: false,
-          includeDescendants: false,
-        },
+        idToCopy: BLANK_UUID,
+        relateToOriginal: false,
+        includeDescendants: false,
       },
       { signal: new AbortController().signal }
     );

src/umb-management-api/tools/document/post/copy-document.ts

@@ -1,10 +1,16 @@
 import { UmbracoManagementClient } from "@umb-management-client";
-import { postDocumentByIdCopyBody } from "@/umb-management-api/umbracoManagementAPI.zod.js";
 import { CreateUmbracoTool } from "@/helpers/mcp/create-umbraco-tool.js";
 import { z } from "zod";
-import { CurrentUserResponseModel } from "@/umb-management-api/schemas/index.js";
+import { CopyDocumentRequestModel, CurrentUserResponseModel } from "@/umb-management-api/schemas/index.js";
 import { UmbracoDocumentPermissions } from "../constants.js";
 
+const copyDocumentSchema = z.object({
+  parentId: z.string().uuid("Must be a valid document UUID of the parent node").optional(),
+  idToCopy: z.string().uuid("Must be a valid document UUID that belongs to the parent document's children"),
+  relateToOriginal: z.boolean().describe("Relate the copy to the original document. This is usually set to false unless specified."),
+  includeDescendants: z.boolean().describe("If true, all descendant documents (children, grandchildren, etc.) will also be copied. This is usually set to false unless specified."),
+});
+
 const CopyDocumentTool = CreateUmbracoTool(
   "copy-document",
   `Copy a document to a new location. This is also the recommended way to create new documents. 
@@ -25,13 +31,19 @@ const CopyDocumentTool = CreateUmbracoTool(
     Example workflows:
     1. Copy only: copy-document (creates draft copy)
     2. Copy and update: copy-document → search-document → update-document → publish-document`,
-  {
-    id: z.string().uuid(),
-    data: z.object(postDocumentByIdCopyBody.shape),
-  },
-  async (model: { id: string; data: any }) => {
+    copyDocumentSchema.shape,
+  async (model) => {
     const client = UmbracoManagementClient.getClient();
-    const response = await client.postDocumentByIdCopy(model.id, model.data);
+
+    const payload: CopyDocumentRequestModel = {
+      target: model.parentId ? {
+        id: model.parentId,
+      } : undefined,
+      relateToOriginal: model.relateToOriginal,
+      includeDescendants: model.includeDescendants,
+    };
+
+    const response = await client.postDocumentByIdCopy(model.idToCopy, payload);
     return {
       content: [
         {

tests/e2e/create-blog-post/create-blog-post-config.json

@@ -7,7 +7,7 @@
           "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp",
           "UMBRACO_CLIENT_SECRET": "1234567890",
           "UMBRACO_BASE_URL": "http://localhost:56472",
-          "UMBRACO_INCLUDE_TOOLS": "search-document,get-document-by-id,copy-document,publish-document,delete-document,get-document-root,get-document-children,get-document-publish,get-document-type-by-id,get-all-document-types"
+          "UMBRACO_INCLUDE_TOOLS": "get-document-root,get-document-children,get-document-publish,get-document-by-id,copy-document,publish-document,delete-document,update-document"
         }
       }
     }

tests/e2e/create-blog-post/create-blog-post.yaml

@@ -9,30 +9,31 @@ evals:
     - name: "Create and manage blog post workflow"
       prompt: |
         Complete these tasks in order:
-        1. Copy an existing blog post document and create a new blog post document with the following details:
+        1. Get the root document of umbraco
+        2. Find the Blogs document under the root node
+        3. Copy an existing blog post document
+        4. Update the copied blog post document with the following details:
            - Title: "_Test Blog Post - Creating Amazing Content"
            - Content/Body: A rich text content about creating amazing content for blogs
            - Author: "Paul Seal"
-        2. Publish the blog post
-        3. Delete the blog post
-        4. When successfully completed all tasks, say 'The blog post workflow has completed successfully', nothing else
+        5. Publish the blog post
+        6. Delete the blog post
+        7. When successfully completed all tasks, say 'The blog post workflow has completed successfully', nothing else
       expected_tool_calls:
         required:
-          - "search-document"
           - "copy-document"
           - "get-document-by-id"
+          - "update-document"
           - "publish-document"
           - "delete-document"
         allowed:
-          - "search-document"
           - "get-document-root"
           - "get-document-children"
           - "get-document-by-id"
           - "copy-document"
           - "publish-document"
-          - "get-document-publish"
           - "delete-document"
-          - "get-document-type-by-id"
+          - "update-document"
       response_scorers:
         - type: 'llm-judge'
           criteria: 'Did the last assistant step say "The blog post workflow has completed successfully"'