@centrali-io/centrali-mcp 4.2.0 → 4.2.2

package/src/tools/pages.ts

@@ -0,0 +1,573 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import { z } from "zod";
+import axios, { AxiosInstance } from "axios";
+
+function formatError(error: unknown, context: string): string {
+  if (axios.isAxiosError(error) && error.response?.data) {
+    const body = error.response.data;
+    const status = error.response.status;
+    const message = body.message || body.error || error.message;
+    return `Error ${context}: [${status}] ${message}`;
+  }
+  if (error && typeof error === "object") {
+    const e = error as Record<string, any>;
+    if ("message" in e) {
+      let msg = `Error ${context}`;
+      if ("code" in e || "status" in e) {
+        msg += `: [${e.code ?? e.status ?? "ERROR"}] ${e.message}`;
+      } else {
+        msg += `: ${e.message}`;
+      }
+      return msg;
+    }
+  }
+  return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
+}
+
+/**
+ * Derives the pages API base URL from the CENTRALI_URL.
+ * Pattern: https://centrali.io -> https://api.centrali.io/pages
+ * Or uses CENTRALI_PAGES_URL env var if explicitly set.
+ */
+function getPagesBaseUrl(centraliUrl: string): string {
+  const override = process.env.CENTRALI_PAGES_URL;
+  if (override) return override.replace(/\/$/, "");
+
+  const url = new URL(centraliUrl);
+  const hostname = url.hostname.startsWith("api.")
+    ? url.hostname
+    : `api.${url.hostname}`;
+  return `${url.protocol}//${hostname}/pages`;
+}
+
+/**
+ * Creates an axios instance for the pages API that uses the SDK's token.
+ */
+function createPagesClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: string): {
+  client: AxiosInstance;
+  workspaceId: string;
+} {
+  const baseURL = getPagesBaseUrl(centraliUrl);
+  const client = axios.create({ baseURL });
+
+  // Attach the SDK's bearer token to every request
+  client.interceptors.request.use(async (config) => {
+    const token = (sdk as any).getToken?.() ?? (sdk as any).token;
+    if (!token) {
+      // Force the SDK to fetch a token by calling getTokenOrFetch
+      const freshToken = await (sdk as any).getTokenOrFetch?.();
+      if (freshToken) {
+        config.headers.Authorization = `Bearer ${freshToken}`;
+      }
+    } else {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  });
+
+  return { client, workspaceId };
+}
+
+export function registerPageTools(
+  server: McpServer,
+  sdk: CentraliSDK,
+  centraliUrl: string,
+  workspaceId: string
+) {
+  const { client } = createPagesClient(sdk, centraliUrl, workspaceId);
+  const basePath = `/ws/${workspaceId}/api/v1/pages`;
+
+  // ── Page CRUD ──────────────────────────────────────────────────────
+
+  server.tool(
+    "list_pages",
+    "List all pages in the workspace. Pages are pre-built UI views (lists, detail views, forms, dashboards) that surface data from structures.",
+    {
+      page: z.number().optional().describe("Page number (1-indexed, default: 1)"),
+      pageSize: z.number().optional().describe("Items per page (default: 20)"),
+      pageType: z
+        .enum(["list", "detail", "form", "dashboard"])
+        .optional()
+        .describe("Filter by page type"),
+    },
+    async ({ page, pageSize, pageType }) => {
+      try {
+        const params: Record<string, any> = {};
+        if (page !== undefined) params.page = page;
+        if (pageSize !== undefined) params.pageSize = pageSize;
+        if (pageType) params.pageType = pageType;
+
+        const resp = await client.get(basePath, { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "listing pages") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_page",
+    "Get a page by its ID. Returns the page metadata including name, slug, type, and description.",
+    {
+      pageId: z.string().describe("The page ID (UUID)"),
+    },
+    async ({ pageId }) => {
+      try {
+        const resp = await client.get(`${basePath}/${pageId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "create_page",
+    "Create a new page in the workspace. A page is a UI view backed by data from structures. Specify the page type: 'list' for data tables, 'detail' for single-record views, 'form' for data entry, 'dashboard' for metrics and charts.",
+    {
+      name: z.string().describe("Display name for the page (e.g., 'Customer List')"),
+      slug: z.string().describe("URL-safe slug (e.g., 'customer-list')"),
+      pageType: z
+        .enum(["list", "detail", "form", "dashboard"])
+        .describe("The type of page to create"),
+      description: z.string().optional().describe("Optional description of the page's purpose"),
+    },
+    async ({ name, slug, pageType, description }) => {
+      try {
+        const resp = await client.post(basePath, { name, slug, pageType, description });
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "creating page") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "update_page",
+    "Update a page's metadata (name, slug, description). Does not modify the page definition — use save_page_draft for that.",
+    {
+      pageId: z.string().describe("The page ID (UUID) to update"),
+      name: z.string().optional().describe("New display name"),
+      slug: z.string().optional().describe("New URL slug"),
+      description: z.string().optional().describe("New description"),
+      showInNavShell: z.boolean().optional().describe("Whether to show this page in the navigation shell"),
+    },
+    async ({ pageId, name, slug, description, showInNavShell }) => {
+      try {
+        const body: Record<string, any> = {};
+        if (name !== undefined) body.name = name;
+        if (slug !== undefined) body.slug = slug;
+        if (description !== undefined) body.description = description;
+        if (showInNavShell !== undefined) body.showInNavShell = showInNavShell;
+
+        const resp = await client.patch(`${basePath}/${pageId}`, body);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `updating page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "delete_page",
+    "Soft-delete a page by its ID. The page will no longer be accessible but can potentially be restored.",
+    {
+      pageId: z.string().describe("The page ID (UUID) to delete"),
+    },
+    async ({ pageId }) => {
+      try {
+        await client.delete(`${basePath}/${pageId}`);
+        return {
+          content: [{ type: "text", text: `Page '${pageId}' deleted successfully.` }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `deleting page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Drafts & Versions ─────────────────────────────────────────────
+
+  server.tool(
+    "save_page_draft",
+    "Save or update the draft definition for a page. The definition describes the page's layout: sections, blocks, data sources, actions, and presentation. This does NOT publish the page — use publish_page after saving.",
+    {
+      pageId: z.string().describe("The page ID (UUID)"),
+      definition: z
+        .record(z.string(), z.any())
+        .describe(
+          "The page definition object containing sections with blocks. Each section has: id, kind (content|metrics|exceptions|actions|hero|supporting), title, layout (single-column|two-column|metric-strip|stack), and blocks array."
+        ),
+      changeSummary: z.string().optional().describe("Summary of changes in this draft"),
+    },
+    async ({ pageId, definition, changeSummary }) => {
+      try {
+        const body: Record<string, any> = { definition };
+        if (changeSummary) body.changeSummary = changeSummary;
+
+        const resp = await client.put(`${basePath}/${pageId}/draft`, body);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `saving draft for page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_page_draft",
+    "Get the current draft version of a page, including its full definition (sections, blocks, data sources).",
+    {
+      pageId: z.string().describe("The page ID (UUID)"),
+    },
+    async ({ pageId }) => {
+      try {
+        const resp = await client.get(`${basePath}/${pageId}/draft`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting draft for page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "list_page_versions",
+    "List all versions of a page. Each version captures a snapshot of the page definition at a point in time.",
+    {
+      pageId: z.string().describe("The page ID (UUID)"),
+      page: z.number().optional().describe("Page number (1-indexed, default: 1)"),
+      pageSize: z.number().optional().describe("Items per page (default: 20)"),
+    },
+    async ({ pageId, page, pageSize }) => {
+      try {
+        const params: Record<string, any> = {};
+        if (page !== undefined) params.page = page;
+        if (pageSize !== undefined) params.pageSize = pageSize;
+
+        const resp = await client.get(`${basePath}/${pageId}/versions`, { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `listing versions for page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Publishing ────────────────────────────────────────────────────
+
+  server.tool(
+    "validate_page",
+    "Run validation checks on a page's current draft to determine if it is ready to publish. Returns a list of issues (errors and warnings) that must be resolved before publishing.",
+    {
+      pageId: z.string().describe("The page ID (UUID) to validate"),
+    },
+    async ({ pageId }) => {
+      try {
+        const resp = await client.post(`${basePath}/${pageId}/validate`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `validating page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "publish_page",
+    "Publish the current draft of a page, making it accessible at its runtime URL. Validates the draft first — if there are errors, publishing is rejected with details. Returns the publication record and the public runtime URL.",
+    {
+      pageId: z.string().describe("The page ID (UUID) to publish"),
+    },
+    async ({ pageId }) => {
+      try {
+        const resp = await client.post(`${basePath}/${pageId}/publish`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `publishing page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "unpublish_page",
+    "Unpublish a page, making it no longer accessible at its runtime URL. The page definition is preserved and can be re-published later.",
+    {
+      pageId: z.string().describe("The page ID (UUID) to unpublish"),
+    },
+    async ({ pageId }) => {
+      try {
+        const resp = await client.post(`${basePath}/${pageId}/unpublish`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `unpublishing page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Access Policy ─────────────────────────────────────────────────
+
+  server.tool(
+    "set_page_access_policy",
+    "Set the access policy for a page. Controls who can view the published page: 'public' (anyone), 'authenticated' (logged-in users), or 'role-gated' (users with specific roles).",
+    {
+      pageId: z.string().describe("The page ID (UUID)"),
+      accessMode: z
+        .enum(["public", "authenticated", "role-gated"])
+        .describe("Access control mode"),
+      requiredRoles: z
+        .array(z.string())
+        .optional()
+        .describe("Required roles (only used when accessMode is 'role-gated')"),
+    },
+    async ({ pageId, accessMode, requiredRoles }) => {
+      try {
+        const body: Record<string, any> = { accessMode };
+        if (requiredRoles) body.requiredRoles = requiredRoles;
+
+        const resp = await client.put(`${basePath}/${pageId}/access-policy`, body);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, `setting access policy for page '${pageId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Theme ─────────────────────────────────────────────────────────
+
+  server.tool(
+    "get_page_theme",
+    "Get the workspace theme configuration used by published pages. Includes primary color, accent color, optional logo URL, and font family.",
+    {},
+    async () => {
+      try {
+        const resp = await client.get(`${basePath}/theme`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "getting page theme") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "set_page_theme",
+    "Set the workspace theme for published pages. Controls the visual branding of all published pages.",
+    {
+      primaryColor: z.string().describe("Primary brand color (hex, e.g., '#1a73e8')"),
+      accentColor: z.string().describe("Accent color (hex, e.g., '#ff6d00')"),
+      logoUrl: z.string().optional().describe("URL to the workspace logo"),
+      fontFamily: z.string().optional().describe("Font family name (e.g., 'Inter', 'Roboto')"),
+    },
+    async ({ primaryColor, accentColor, logoUrl, fontFamily }) => {
+      try {
+        const config: Record<string, any> = { primaryColor, accentColor };
+        if (logoUrl !== undefined) config.logoUrl = logoUrl;
+        if (fontFamily !== undefined) config.fontFamily = fontFamily;
+
+        const resp = await client.put(`${basePath}/theme`, { config });
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "setting page theme") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Navigation ────────────────────────────────────────────────────
+
+  server.tool(
+    "get_navigation",
+    "Get the workspace navigation configuration. Controls the sidebar/nav shell that wraps published pages.",
+    {},
+    async () => {
+      try {
+        const resp = await client.get(`${basePath}/navigation`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "getting navigation config") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "set_navigation",
+    "Set the workspace navigation configuration. Defines the sidebar items, branding, and grouping for the page navigation shell.",
+    {
+      config: z
+        .record(z.string(), z.any())
+        .describe(
+          "Navigation config object with: enabled (boolean), branding ({ logoUrl, displayName }), items (array of nav items with pageId, label, icon, group)"
+        ),
+    },
+    async ({ config }) => {
+      try {
+        const resp = await client.put(`${basePath}/navigation`, { config });
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "setting navigation config") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "delete_navigation",
+    "Delete the workspace navigation configuration. Pages revert to standalone rendering without a sidebar/nav shell.",
+    {},
+    async () => {
+      try {
+        await client.delete(`${basePath}/navigation`);
+        return {
+          content: [{ type: "text", text: "Navigation config deleted. Pages will render standalone." }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "deleting navigation config") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Assembly (AI-assisted page generation) ────────────────────────
+
+  server.tool(
+    "generate_starter_pages",
+    "Generate page proposals from structure IDs. Uses guided assembly to create page definitions (list, detail, form, dashboard) tailored to the data schema. Returns proposals that can be reviewed and accepted.",
+    {
+      structureIds: z
+        .array(z.string())
+        .describe("Array of structure IDs (UUIDs) to generate pages for"),
+      goals: z
+        .array(z.string())
+        .optional()
+        .describe("Optional goals to guide page generation (e.g., 'customer management dashboard', 'order tracking')"),
+    },
+    async ({ structureIds, goals }) => {
+      try {
+        const body: Record<string, any> = { structureIds };
+        if (goals) body.goals = goals;
+
+        const resp = await client.post(`${basePath}/generate-starter-pages`, body);
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "generating starter pages") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "accept_page_proposal",
+    "Accept a generated page proposal and create the page with its initial draft definition. Use after reviewing proposals from generate_starter_pages.",
+    {
+      name: z.string().describe("Display name for the page"),
+      slug: z.string().describe("URL-safe slug for the page"),
+      pageType: z
+        .enum(["list", "detail", "form", "dashboard"])
+        .describe("Page type"),
+      definition: z
+        .record(z.string(), z.any())
+        .describe("The page definition from the proposal"),
+      generationSource: z
+        .string()
+        .describe("The source that generated this proposal (from the proposal object)"),
+    },
+    async ({ name, slug, pageType, definition, generationSource }) => {
+      try {
+        const resp = await client.post(`${basePath}/accept-proposal`, {
+          name,
+          slug,
+          pageType,
+          definition,
+          generationSource,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(resp.data, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: formatError(error, "accepting page proposal") }],
+          isError: true,
+        };
+      }
+    }
+  );
+}