@kywi-software/mcp 0.6.7 → 0.7.0

package/AGENT-PATTERNS.md

@@ -260,8 +260,8 @@ everywhere.
 | `name` | Purpose |
 |---|---|
 | `breadcrumbs` | Trail of ancestor links |
-| `navMenu` | A named menu (`menuSlug`) rendered to a depth |
-| `navigation` | Site navigation with a style variant and depth |
+| `navMenu` | A named menu (`menuSlug`) in a `variant`: horizontal / mega / vertical / footer |
+| `navigation` | Site navigation in the same four variants, to a depth |
 | `siteMap` | Nested list of the site tree |
 | `searchBox` | Compact search input posting to a results URL |
 | `search` | Full search form (method, label, results URL) |
@@ -328,6 +328,62 @@ page", "Case study" — so new pages start from a consistent skeleton. Hand-writ
 JSX stays fine for genuinely fixed chrome (a bespoke 404, legal boilerplate) —
 but if marketing will ever want to swap a headline, it's a layout page.
 
+### Navigation: menus vs. the site tree
+
+Two sources feed every nav module, and both resolve to the exact same
+render-ready shape — `navMenu`/`navigation` never know which one produced it:
+
+- **Menus** (Menus admin) — an owner-managed, named list of items. Each item
+  either links a content node (its href resolves live off that page — publish,
+  rename, or move the page and the menu link follows) or carries an external
+  URL, plus a label, an optional description (used by `mega` panels) and an
+  open-in-new-window flag. Reference one from a `navMenu` module's `menuSlug`
+  prop.
+- **The site tree** — every page with `isNav` checked (Site Tree admin), in
+  `sortOrder`. A page's nav label is its `menuTitle` when the editor set one,
+  else its `title` — so a long page title ("Plans and Pricing for Teams") can
+  show a short nav label ("Pricing") without a second, independently-maintained
+  copy of the link. `navigation` and `siteMap` modules render this tree, to
+  `depth` levels.
+
+**NEVER hardcode the site nav in chrome.** A hand-typed `<nav>` with pasted
+hrefs is exactly the failure mode this exists to close: a prior marketing
+build's hardcoded header had 7 of its 13 links quietly 404ing, because nothing
+checked them against the pages that actually existed. A menu item's href is
+derived from its linked page, so it cannot drift the way a pasted URL can; a
+site-tree nav module can't drift either, because it IS the tree. Build the
+header/footer from a `navMenu`/`navigation` module (or, in a scaffolded app's
+own chrome, from `scope.menus`/`scope.nav` directly — see below) and never from
+a list of `<a>` tags an agent typed out.
+
+`navMenu`'s `menuSlug` resolves server-side against a real, owner-managed menu.
+Both `navMenu` and `navigation` still accept hand-authored `items` JSON — as
+the fallback when a `menuSlug` names a menu that doesn't (yet) exist, or as a
+deliberate one-off override — but a named menu or the site tree is how a
+*maintained* nav gets built, not hand-typed JSON.
+
+**Variants** (`variant` prop, shared by `navMenu` and `navigation`):
+`horizontal` (dropdown panels — a top bar), `mega` (full-width multi-column
+panels with descriptions — reach for this when a top-level item has several
+children worth previewing), `vertical` (nested fly-outs — a sidebar), `footer`
+(grouped columns of links, no interactivity). Every variant is JS-off safe:
+links always render server-side, and below the mobile breakpoint the bar
+collapses behind a native `<details>` hamburger. The interactive variants carry
+`data-kywi-nav` + `data-kywi-nav-variant`; `@kywi-software/js` auto-boots
+hover-intent, keyboard and outside-click handling on any element with
+`data-kywi-nav` — nothing to wire up beyond loading `/kywi.js`.
+
+**A scaffolded app's own header/footer follow the same rule.**
+`app/(site)/layout.tsx` renders the `'main'` menu when the site has one,
+falling back to the `isNav` site tree — so a fresh install has a working header
+with zero manual wiring, and an owner who later builds a `'main'` menu in the
+admin overrides it with no code change. The footer renders a `'footer'` menu
+only when one exists (no tree fallback there — an unbuilt footer menu should be
+empty, not suddenly cluttered with the whole site tree). Both render through
+the same shared nav renderer as the `navigation` module, never hand-rolled
+markup, so the header and footer get the identical CSS and
+`@kywi-software/js` enhancement as any nav module placed in the page body.
+
 ## 6. Forms: always the Forms builder
 
 Never hand-code a `<form>`. Build forms in the Forms admin (fields, multi-step,

package/dist/site/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAWjD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CA6BpE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAYjD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CA8BpE"}

package/dist/site/server.js

@@ -7,6 +7,7 @@ import { registerModuleTypesTool } from '../module-types.js';
 import { registerContentTools } from './tools/content.js';
 import { registerLayoutTools } from './tools/layout.js';
 import { registerFeedTools } from './tools/feeds.js';
+import { registerMenuTools } from './tools/menus.js';
 import { registerSearchTools } from './tools/search.js';
 import { registerMediaTools } from './tools/media.js';
 import { registerUserTools } from './tools/users.js';
@@ -68,6 +69,7 @@ export function createSiteMcpServer(config) {
     registerContentTools(server, sdk, config.baseUrl, config.apiKey);
     registerLayoutTools(server, sdk);
     registerFeedTools(server, sdk);
+    registerMenuTools(server, sdk);
     registerSearchTools(server, sdk);
     registerMediaTools(server, sdk);
     registerUserTools(server, sdk);

package/dist/site/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGlE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAiB,EACjB,GAAiB,EACjB,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;QAC5C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAIpB,uBAAuB,CAAC,CAAA;QAE9B,IAAI,OAAO,IAAK,GAA+B;YAAE,OAAO,CAAC,CAAA;QAEzD,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAiC,EAAE,CAAA;YACrD,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;gBAC9B,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,QAAQ;oBACvC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;oBAClC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YACjD,CAAC;YAED,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE;gBACvC,WAAW,EAAE,gBAAgB,EAAE,CAAC,KAAK,EAAE;gBACvC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;aACpC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBAChB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAA+B,CAAC,CAAA;gBAC/E,OAAO,UAAU,CAAC,IAAI,CAAC,CAAA;YACzB,CAAC,CAAC,CAAA;YAEF,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;gBACrC,WAAW,EAAE,QAAQ,EAAE,CAAC,KAAK,UAAU;gBACvC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;oBACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;oBACjC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;oBAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;iBAC9B,CAAC;aACH,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBAChB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;gBAC/D,OAAO,UAAU,CAAC,MAAM,CAAC,CAAA;YAC3B,CAAC,CAAC,CAAA;YAEF,KAAK,IAAI,CAAC,CAAA;QACZ,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAA;IACV,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACvD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,OAAO,EAAE,EACrD,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAA;IAED,MAAM,GAAG,GAAG,aAAa,CAAC;QACxB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CAAA;IAEF,wEAAwE;IACxE,oBAAoB,CAAC,MAAM,CAAC,CAAA;IAC5B,yEAAyE;IACzE,iEAAiE;IACjE,uBAAuB,CAAC,MAAM,CAAC,CAAA;IAC/B,oBAAoB,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IAChE,mBAAmB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAChC,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,mBAAmB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAChC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC/B,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE9B,uFAAuF;IACvF,mCAAmC;IACnC,+CAA+C;IAC/C,iEAAiE;IAEjE,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGlE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAiB,EACjB,GAAiB,EACjB,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;QAC5C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAIpB,uBAAuB,CAAC,CAAA;QAE9B,IAAI,OAAO,IAAK,GAA+B;YAAE,OAAO,CAAC,CAAA;QAEzD,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAiC,EAAE,CAAA;YACrD,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;gBAC9B,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,QAAQ;oBACvC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;oBAClC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YACjD,CAAC;YAED,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE;gBACvC,WAAW,EAAE,gBAAgB,EAAE,CAAC,KAAK,EAAE;gBACvC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;aACpC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBAChB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAA+B,CAAC,CAAA;gBAC/E,OAAO,UAAU,CAAC,IAAI,CAAC,CAAA;YACzB,CAAC,CAAC,CAAA;YAEF,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;gBACrC,WAAW,EAAE,QAAQ,EAAE,CAAC,KAAK,UAAU;gBACvC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;oBACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;oBACjC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;oBAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;iBAC9B,CAAC;aACH,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBAChB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;gBAC/D,OAAO,UAAU,CAAC,MAAM,CAAC,CAAA;YAC3B,CAAC,CAAC,CAAA;YAEF,KAAK,IAAI,CAAC,CAAA;QACZ,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAA;IACV,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACvD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,OAAO,EAAE,EACrD,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAA;IAED,MAAM,GAAG,GAAG,aAAa,CAAC;QACxB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CAAA;IAEF,wEAAwE;IACxE,oBAAoB,CAAC,MAAM,CAAC,CAAA;IAC5B,yEAAyE;IACzE,iEAAiE;IACjE,uBAAuB,CAAC,MAAM,CAAC,CAAA;IAC/B,oBAAoB,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IAChE,mBAAmB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAChC,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,mBAAmB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAChC,kBAAkB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC/B,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE9B,uFAAuF;IACvF,mCAAmC;IACnC,+CAA+C;IAC/C,iEAAiE;IAEjE,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/site/tools/menus.d.ts

@@ -0,0 +1,67 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { KywiSdkScope } from '@kywi-software/sdk';
+/**
+ * Menu item as an agent writes it. Narrower than the SDK's `MenuItemInput`:
+ * tools link by `contentSlug` (stable across page moves) or `externalUrl`,
+ * never by raw content id.
+ */
+export interface MenuItemInputArg {
+    label: string;
+    contentSlug?: string | undefined;
+    externalUrl?: string | undefined;
+    description?: string | undefined;
+    openInNewWindow?: boolean | undefined;
+    children?: MenuItemInputArg[] | undefined;
+}
+/**
+ * Returns a message describing the first item that does not set exactly one of
+ * contentSlug / externalUrl, or null when the whole tree is valid. The API
+ * enforces this too; failing here names the offending item so an agent can fix
+ * it without decoding a 400.
+ */
+export declare function findLinkTargetError(items: MenuItemInputArg[], ancestors?: string[]): string | null;
+export declare function handleListMenus(sdk: KywiSdkScope, args: {
+    siteId?: string | undefined;
+}): Promise<{
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    isError?: undefined;
+}>;
+export declare function handleGetMenu(sdk: KywiSdkScope, args: {
+    slug: string;
+    siteId?: string | undefined;
+}): Promise<{
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    isError?: undefined;
+} | {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    isError: true;
+}>;
+export declare function handleUpsertMenu(sdk: KywiSdkScope, args: {
+    slug: string;
+    name: string;
+    siteId?: string | undefined;
+    items: MenuItemInputArg[];
+}): Promise<{
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    isError?: undefined;
+} | {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    isError: true;
+}>;
+export declare function registerMenuTools(server: McpServer, sdk: KywiSdkScope): void;
+//# sourceMappingURL=menus.d.ts.map

package/dist/site/tools/menus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menus.d.ts","sourceRoot":"","sources":["../../../src/site/tools/menus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGtD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAA;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,gBAAgB,EAAE,EACzB,SAAS,GAAE,MAAM,EAAO,GACvB,MAAM,GAAG,IAAI,CAiBf;AAID,wBAAsB,eAAe,CACnC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE;;;;;;GAItC;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE;;;;;;;;;;;;GAOpD;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,gBAAgB,EAAE,CAAA;CAAE;;;;;;;;;;;;GAY7F;AAaD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAyB5E"}

package/dist/site/tools/menus.js

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { textResult, errorResult } from '../../shared.js';
+/**
+ * Returns a message describing the first item that does not set exactly one of
+ * contentSlug / externalUrl, or null when the whole tree is valid. The API
+ * enforces this too; failing here names the offending item so an agent can fix
+ * it without decoding a 400.
+ */
+export function findLinkTargetError(items, ancestors = []) {
+    for (const item of items) {
+        const path = [...ancestors, item.label].join(' > ');
+        const hasSlug = item.contentSlug !== undefined && item.contentSlug !== '';
+        const hasUrl = item.externalUrl !== undefined && item.externalUrl !== '';
+        if (hasSlug && hasUrl) {
+            return `Menu item "${path}" sets both contentSlug and externalUrl — set exactly one.`;
+        }
+        if (!hasSlug && !hasUrl) {
+            return `Menu item "${path}" sets neither contentSlug nor externalUrl — set exactly one.`;
+        }
+        if (item.children?.length) {
+            const childError = findLinkTargetError(item.children, [...ancestors, item.label]);
+            if (childError)
+                return childError;
+        }
+    }
+    return null;
+}
+// ─── Exported handler functions (testable without server) ───────────────────
+export async function handleListMenus(sdk, args) {
+    const menus = await sdk.menus.list({ siteId: args.siteId });
+    return textResult({ menus, total: menus.length });
+}
+export async function handleGetMenu(sdk, args) {
+    const menu = await sdk.menus.get(args.slug, { siteId: args.siteId });
+    if (!menu) {
+        return errorResult(`Menu '${args.slug}' not found`);
+    }
+    return textResult(menu);
+}
+export async function handleUpsertMenu(sdk, args) {
+    const linkError = findLinkTargetError(args.items);
+    if (linkError)
+        return errorResult(linkError);
+    const menu = await sdk.menus.upsert({
+        slug: args.slug,
+        name: args.name,
+        items: args.items,
+        ...(args.siteId ? { siteId: args.siteId } : {}),
+    });
+    return textResult(menu);
+}
+// ─── Registration ───────────────────────────────────────────────────────────
+const menuItemSchema = z.lazy(() => z.object({
+    label: z.string().describe('Visible link text (always required — it wins over the page title)'),
+    contentSlug: z.string().optional().describe('Slug of a page in this site to link to; href resolves live from the page path'),
+    externalUrl: z.string().optional().describe('Absolute off-site URL, e.g. https://github.com/…'),
+    description: z.string().optional().describe('Supporting copy shown in mega-menu panels'),
+    openInNewWindow: z.boolean().optional().describe('Open the link in a new tab'),
+    children: z.array(menuItemSchema).optional().describe('Nested sub-items (dropdown / mega-panel column)'),
+}));
+export function registerMenuTools(server, sdk) {
+    server.registerTool('list_menus', {
+        description: "List the site's named navigation menus (slug + name). Use this to discover which menus exist before editing one.",
+        inputSchema: {
+            siteId: z.string().optional().describe('Site ID (uses default if omitted)'),
+        },
+    }, async (args) => handleListMenus(sdk, args));
+    server.registerTool('get_menu', {
+        description: 'Get one menu by slug with its full nested item tree, including items whose linked content is unpublished or deleted (flagged `resolvable: false` / `contentMissing: true`) so broken nav links are visible.',
+        inputSchema: {
+            slug: z.string().describe('Menu slug, e.g. "main" or "footer"'),
+            siteId: z.string().optional().describe('Site ID (uses default if omitted)'),
+        },
+    }, async (args) => handleGetMenu(sdk, args));
+    server.registerTool('upsert_menu', {
+        description: 'Create or update a navigation menu and replace its entire item tree in one idempotent call. Items are nested; each item links to a page via `contentSlug` (preferred — the href stays correct when the page moves) OR to an off-site address via `externalUrl`. Exactly one of the two is required per item. Re-running with the same input is a no-op.',
+        inputSchema: {
+            slug: z.string().describe('Menu slug, e.g. "main" or "footer"'),
+            name: z.string().describe('Human-readable menu name shown in the admin'),
+            siteId: z.string().optional().describe('Site ID (uses default if omitted)'),
+            items: z.array(menuItemSchema).describe('The menu\'s complete nested item tree — this replaces all existing items'),
+        },
+    }, async (args) => handleUpsertMenu(sdk, args));
+}
+//# sourceMappingURL=menus.js.map

package/dist/site/tools/menus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"menus.js","sourceRoot":"","sources":["../../../src/site/tools/menus.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kywi-software/mcp",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "Model Context Protocol servers for Kywi CMS — a site server (content/nav/media over the REST API) and a developer server (kywi.config.ts scaffolding and mutation).",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -47,8 +47,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.25.0",
-    "@kywi-software/core": "0.6.7",
-    "@kywi-software/sdk": "0.6.7"
+    "@kywi-software/core": "0.7.0",
+    "@kywi-software/sdk": "0.7.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",