x

apps/mcp-server/README.md

@@ -52,6 +52,8 @@ Use this workflow for every Footer menu edit:
 5. Apply the same operation with `dryRun: false` and the same version.
 6. Call `get_footer_menu` again to verify and obtain the next version.
 
+If an allowed Footer menu does not exist yet, `get_footer_menu` returns `exists: false`, `version: null`, and an empty item list. Previewing the first add returns `willCreateMenu: true`; applying that add creates the menu as active and inserts the first item atomically.
+
 Available item-level tools:
 
 - `add_footer_menu_item`

apps/mcp-server/menu-toolkit.test.ts

@@ -129,6 +129,30 @@ describe("Footer MCP proxy handlers", () => {
     });
   });
 
+  test("preserves the compact contract for an allowed menu that does not exist", async () => {
+    const { api } = createApi({
+      success: true,
+      menuName: "footer-support",
+      exists: false,
+      version: null,
+      lang: "th",
+      items: [],
+    });
+    const result = await handleMenuTool(api, "get_footer_menu", {
+      menuName: "footer-support",
+    });
+
+    expect(output(result)).toEqual({
+      success: true,
+      operation: "get_footer_menu",
+      menuName: "footer-support",
+      exists: false,
+      version: null,
+      lang: "th",
+      items: [],
+    });
+  });
+
   test("adds an item with write controls", async () => {
     const { api, calls } = createApi();
     await handleMenuTool(api, "add_footer_menu_item", {
@@ -155,6 +179,45 @@ describe("Footer MCP proxy handlers", () => {
     });
   });
 
+  test("preserves a dry-run bootstrap preview for an absent allowed menu", async () => {
+    const { api } = createApi({
+      success: true,
+      operation: "add_footer_menu_item",
+      menuName: "footer-explore",
+      dryRun: true,
+      exists: false,
+      willCreateMenu: true,
+      version: null,
+      item: {
+        label: "Shop",
+        url: "/shop",
+        order: 1,
+      },
+    });
+    const result = await handleMenuTool(api, "add_footer_menu_item", {
+      menuName: "footer-explore",
+      label: "Shop",
+      url: "/shop",
+      order: 1,
+      dryRun: true,
+    });
+
+    expect(output(result)).toEqual({
+      success: true,
+      operation: "add_footer_menu_item",
+      menuName: "footer-explore",
+      dryRun: true,
+      exists: false,
+      willCreateMenu: true,
+      version: null,
+      item: {
+        label: "Shop",
+        url: "/shop",
+        order: 1,
+      },
+    });
+  });
+
   test("partially updates an item without forwarding unrelated fields", async () => {
     const { api, calls } = createApi();
     await handleMenuTool(api, "update_footer_menu_item", {

apps/mcp-server/menu-toolkit.ts

@@ -107,7 +107,7 @@ const rootMenuNodeSchema = {
 export const MENU_TOOL_DEFINITIONS = [
   {
     name: "get_footer_menu",
-    description: "Read footer-explore or footer-support in a compact, language-specific format. Use lang=all only when every translation is required.",
+    description: "Read footer-explore or footer-support in a compact, language-specific format. An allowed menu that does not exist is returned as exists:false, version:null, items:[]. Use lang=all only when every translation is required.",
     inputSchema: {
       type: "object",
       properties: {
@@ -128,7 +128,7 @@ export const MENU_TOOL_DEFINITIONS = [
   },
   {
     name: "add_footer_menu_item",
-    description: "Add one item to footer-explore or footer-support without replacing the menu. Use dryRun first and pass the version from get_footer_menu.",
+    description: "Add one item to footer-explore or footer-support without replacing the menu. The first actual add creates an allowed footer menu when it does not exist. Use dryRun first and pass the version from get_footer_menu.",
     inputSchema: {
       type: "object",
       properties: {
@@ -435,6 +435,8 @@ function compactFooterResponse(data: any, operation: string, params: any) {
 
   for (const key of [
     "dryRun",
+    "exists",
+    "willCreateMenu",
     "version",
     "lang",
     "item",