@revfleet/hscli 0.8.7 → 0.8.10

package/dist/mcp/hubspot-modules.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MCP tools for HubSpot's drag-and-drop module library.
+ *
+ * Three tools:
+ *   - `hubspot_module_list`       — inventory of `@hubspot/*` modules
+ *                                   accessible on the caller's portal.
+ *   - `hubspot_module_describe`   — fetch + return a module's
+ *                                   `fields.json` schema: field names,
+ *                                   types, defaults, nested children,
+ *                                   choices. This is what a HubSpot
+ *                                   drag-and-drop user sees when they
+ *                                   select the module in the editor.
+ *   - `hubspot_module_compose`    — given a module path and a field
+ *                                   value map, return a widget body
+ *                                   shaped for inclusion in a marketing
+ *                                   email or CMS page's `widgets` dict
+ *                                   under `flexAreas`/`layoutSections`.
+ *                                   Rejects unknown fields + type
+ *                                   mismatches *before* the widget is
+ *                                   posted back to HubSpot.
+ *
+ * Design rationale: auto-generating 55 per-module MCP tools would bloat
+ * the tool listing and force eager fetches of every schema at startup.
+ * A single dynamic tool accepting the module path mirrors how a UI user
+ * actually works — browse the palette, select a module, fill the fields.
+ * Agents get full schema awareness on demand without paying for it up
+ * front.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerHubspotModuleTools(server: McpServer): void;

package/dist/mcp/hubspot-modules.js

@@ -0,0 +1,305 @@
+/**
+ * MCP tools for HubSpot's drag-and-drop module library.
+ *
+ * Three tools:
+ *   - `hubspot_module_list`       — inventory of `@hubspot/*` modules
+ *                                   accessible on the caller's portal.
+ *   - `hubspot_module_describe`   — fetch + return a module's
+ *                                   `fields.json` schema: field names,
+ *                                   types, defaults, nested children,
+ *                                   choices. This is what a HubSpot
+ *                                   drag-and-drop user sees when they
+ *                                   select the module in the editor.
+ *   - `hubspot_module_compose`    — given a module path and a field
+ *                                   value map, return a widget body
+ *                                   shaped for inclusion in a marketing
+ *                                   email or CMS page's `widgets` dict
+ *                                   under `flexAreas`/`layoutSections`.
+ *                                   Rejects unknown fields + type
+ *                                   mismatches *before* the widget is
+ *                                   posted back to HubSpot.
+ *
+ * Design rationale: auto-generating 55 per-module MCP tools would bloat
+ * the tool listing and force eager fetches of every schema at startup.
+ * A single dynamic tool accepting the module path mirrors how a UI user
+ * actually works — browse the palette, select a module, fill the fields.
+ * Agents get full schema awareness on demand without paying for it up
+ * front.
+ */
+import { z } from "zod";
+import { createClient } from "../core/http.js";
+import { resolveProfile, registerMcpTool, baseArgsSchema } from "./server.js";
+/**
+ * The wordlist is the same as `hscli cms source-code list-modules` uses.
+ * Drawn from HubSpot's developer docs + the email/web modules split
+ * changelog + live verification on a Content Hub portal (2026-04-23:
+ * 55 of 68 probed names respond on this portal).
+ */
+const KNOWN_HUBSPOT_MODULES = [
+    // Universal + web
+    "rich_text", "text", "header", "section_header", "button", "cta",
+    "divider", "horizontal_spacer", "form", "icon", "linked_image",
+    "image_grid", "gallery", "image_slider_gallery", "logo", "logo_grid",
+    "video", "menu", "simple_menu", "language_switcher", "social_sharing",
+    "social_follow", "page_footer", "meetings", "payments", "product",
+    "whatsapp_link",
+    // Blog
+    "blog_content", "blog_subscribe", "blog_comments", "post_filter",
+    "post_listing", "rss_listing", "blog_posts",
+    // System
+    "search_input", "search_results", "password_prompt",
+    "membership_social_logins",
+    // Email-specific
+    "email_header", "email_footer", "email_cta", "email_text",
+    "email_section_header", "email_linked_image", "email_logo",
+    "email_post_filter", "email_post_listing", "email_social_sharing",
+    "email_subscriptions", "email_subscriptions_confirmation",
+    "email_simple_subscription", "email_body", "raw_html_email",
+    "email_can_spam", "image_email", "video_email", "one_line_of_text",
+    "view_as_web_page", "whitespace", "spacer", "follow_me",
+    "rss_email", "product_markdown",
+    // Legacy quotes
+    "quote_download", "quote_payment", "quote_signature", "line_items",
+];
+const MODULE_IDS = {
+    // Hard-coded well-known module_ids that HubSpot's widget renderer
+    // requires for legacy modules. These aren't exposed by fields.json;
+    // discovered via inspection of existing portal emails.
+    rich_text: 1155639,
+    email_footer: 2869621,
+};
+function cmsModulePath(modulePath) {
+    // `@hubspot/button` → `@hubspot/button.module/fields.json`
+    const stripped = modulePath.replace(/^@hubspot\//, "");
+    return `@hubspot/${stripped}.module/fields.json`;
+}
+async function fetchModuleSchema(profile, modulePath, environment = "published") {
+    const client = createClient(profile);
+    const encoded = cmsModulePath(modulePath)
+        .split("/")
+        .map((p) => encodeURIComponent(p))
+        .join("/");
+    const res = (await client.request(`/cms/v3/source-code/${encodeURIComponent(environment)}/content/${encoded}`));
+    if (Array.isArray(res))
+        return res;
+    // Some responses wrap the JSON in a `message` string.
+    if (typeof res === "object" && res !== null && "message" in res) {
+        const body = res.message;
+        if (typeof body === "string") {
+            try {
+                return JSON.parse(body);
+            }
+            catch {
+                return [];
+            }
+        }
+    }
+    return [];
+}
+/**
+ * Walk a schema and a value map in lock-step. Checks required fields,
+ * enum membership, and primitive types. Throws on the first violation
+ * with a human-readable message. Returns a shallow-cloned value map
+ * with defaults filled in for missing-but-not-required fields.
+ */
+function validateAgainstSchema(fields, values, pathPrefix = "") {
+    const out = {};
+    const known = new Set();
+    for (const field of fields) {
+        if (!field.name)
+            continue;
+        known.add(field.name);
+        const key = field.name;
+        const fullPath = pathPrefix ? `${pathPrefix}.${key}` : key;
+        const value = values[key];
+        if (value === undefined || value === null) {
+            if (field.required) {
+                throw new Error(`Missing required field: ${fullPath} (type: ${field.type ?? "unknown"})`);
+            }
+            if (field.default !== undefined) {
+                out[key] = field.default;
+            }
+            continue;
+        }
+        // Type check for simple primitives.
+        if (field.type === "boolean" && typeof value !== "boolean") {
+            throw new Error(`Field ${fullPath} must be boolean, got ${typeof value}`);
+        }
+        if (field.type === "number" && typeof value !== "number") {
+            throw new Error(`Field ${fullPath} must be number, got ${typeof value}`);
+        }
+        if ((field.type === "text" || field.type === "richtext") && typeof value !== "string") {
+            throw new Error(`Field ${fullPath} must be string, got ${typeof value}`);
+        }
+        if (field.type === "choice" && Array.isArray(field.choices)) {
+            const allowed = field.choices.map((c) => c[0]);
+            if (!allowed.includes(String(value))) {
+                throw new Error(`Field ${fullPath} must be one of [${allowed.join(", ")}], got ${String(value)}`);
+            }
+        }
+        if (field.type === "group" && field.children && typeof value === "object" && value !== null) {
+            out[key] = validateAgainstSchema(field.children, value, fullPath);
+            continue;
+        }
+        out[key] = value;
+    }
+    for (const extra of Object.keys(values)) {
+        if (!known.has(extra)) {
+            throw new Error(`Unknown field: ${pathPrefix ? `${pathPrefix}.` : ""}${extra}. ` +
+                `Call \`hubspot_module_describe\` to see the full schema.`);
+        }
+    }
+    return out;
+}
+/**
+ * Build the widget payload HubSpot's email/CMS renderer expects.
+ * Returns a widget body ready to drop into
+ * `content.widgets[widgetId] = <this>` plus a `flexAreas` section
+ * referencing the same `widgetId`.
+ */
+function buildWidget(widgetId, modulePath, order, body) {
+    const shortName = modulePath.replace(/^@hubspot\//, "");
+    return {
+        type: "module",
+        name: widgetId,
+        id: widgetId,
+        module_id: MODULE_IDS[shortName] ?? 0,
+        order,
+        label: null,
+        css: {},
+        child_css: {},
+        smart_type: null,
+        styles: { breakpointStyles: { default: {}, mobile: {} } },
+        body: {
+            css_class: "dnd-module",
+            path: modulePath,
+            schema_version: 2,
+            lineNumber: 32,
+            startPosition: 19,
+            parent_widget_container: null,
+            ...body,
+        },
+    };
+}
+export function registerHubspotModuleTools(server) {
+    registerMcpTool(server, "hubspot_module_list", {
+        description: "Enumerate @hubspot/* built-in drag-and-drop modules available on the " +
+            "caller's portal. Each entry reports whether fields.json resolves (i.e. " +
+            "whether the module can be used in widgets). Useful for discovery — call " +
+            "hubspot_module_describe on any available entry to see its field schema.",
+        inputSchema: {
+            ...baseArgsSchema,
+            environment: z
+                .enum(["draft", "published"])
+                .optional()
+                .describe("CMS source-code environment (default: published)"),
+            schemas: z
+                .boolean()
+                .optional()
+                .describe("Include full field schema for each module in the output"),
+        },
+    }, async (args) => {
+        const profile = resolveProfile(args.profile);
+        const environment = args.environment ?? "published";
+        const results = [];
+        for (const name of KNOWN_HUBSPOT_MODULES) {
+            try {
+                const fields = await fetchModuleSchema(profile, `@hubspot/${name}`, environment);
+                results.push({
+                    modulePath: `@hubspot/${name}`,
+                    available: true,
+                    fieldCount: fields.length,
+                    ...(args.schemas ? { fields } : {}),
+                });
+            }
+            catch {
+                results.push({ modulePath: `@hubspot/${name}`, available: false });
+            }
+        }
+        const available = results.filter((r) => r.available).length;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        total: results.length,
+                        available,
+                        missing: results.length - available,
+                        modules: results,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    registerMcpTool(server, "hubspot_module_describe", {
+        description: "Return the full field schema for a HubSpot drag-and-drop module (the same " +
+            "schema a user sees when clicking a module in the editor). Fields include name, " +
+            "label, type (text, richtext, number, boolean, color, choice, group, image, " +
+            "link, ...), required flag, default, choices, and nested children for groups. " +
+            "Call this before hubspot_module_compose to know what fields to pass.",
+        inputSchema: {
+            ...baseArgsSchema,
+            modulePath: z
+                .string()
+                .regex(/^@hubspot\//, "modulePath must start with @hubspot/")
+                .describe("Module path, e.g. @hubspot/button or @hubspot/rich_text"),
+            environment: z.enum(["draft", "published"]).optional(),
+        },
+    }, async (args) => {
+        const profile = resolveProfile(args.profile);
+        const fields = await fetchModuleSchema(profile, args.modulePath, args.environment ?? "published");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ modulePath: args.modulePath, fieldCount: fields.length, fields }, null, 2),
+                },
+            ],
+        };
+    });
+    registerMcpTool(server, "hubspot_module_compose", {
+        description: "Compose a widget body for a HubSpot drag-and-drop module using given field " +
+            "values. Validates the values against the module's fields.json schema before " +
+            "returning — rejects unknown fields and type mismatches. The returned widget " +
+            "is ready to drop into an email or CMS page's content.widgets[widgetId], with " +
+            "the schema + metadata HubSpot's renderer expects. Use this instead of " +
+            "hand-shaping widget bodies.",
+        inputSchema: {
+            ...baseArgsSchema,
+            modulePath: z
+                .string()
+                .regex(/^@hubspot\//, "modulePath must start with @hubspot/")
+                .describe("Module path, e.g. @hubspot/rich_text"),
+            widgetId: z
+                .string()
+                .min(1)
+                .describe("Widget key under content.widgets[] (e.g. module-0-0-0)"),
+            order: z.number().int().optional().describe("Display order (default: 1)"),
+            fields: z
+                .record(z.string(), z.unknown())
+                .describe("Field values keyed by field name. Call hubspot_module_describe " +
+                "first to see the full schema."),
+            environment: z.enum(["draft", "published"]).optional(),
+        },
+    }, async (args) => {
+        const profile = resolveProfile(args.profile);
+        const schema = await fetchModuleSchema(profile, args.modulePath, args.environment ?? "published");
+        const validatedBody = validateAgainstSchema(schema, args.fields ?? {});
+        const widget = buildWidget(args.widgetId, args.modulePath, args.order ?? 1, validatedBody);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        widgetId: args.widgetId,
+                        modulePath: args.modulePath,
+                        widget,
+                        hint: "Insert `widget` under `content.widgets[widgetId]` and reference " +
+                            "widgetId from a flexAreas section's columns[].widgets[] array.",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=hubspot-modules.js.map

package/dist/mcp/hubspot-modules.js.map

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

package/dist/mcp/server.d.ts

@@ -6,11 +6,13 @@ export interface McpBaseArgs {
     profile?: string;
     force?: boolean;
     dryRun?: boolean;
+    changeTicket?: string;
 }
 export declare const baseArgsSchema: {
     profile: z.ZodOptional<z.ZodString>;
     force: z.ZodOptional<z.ZodBoolean>;
     dryRun: z.ZodOptional<z.ZodBoolean>;
+    changeTicket: z.ZodOptional<z.ZodString>;
 };
 export declare function resolveProfile(requested?: string): string;
 export declare function executeTool(args: McpBaseArgs, fn: (ctx: CliContext, client: HubSpotClient) => Promise<unknown>): Promise<{

package/dist/mcp/server.js

@@ -1,17 +1,23 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { getToken, getApiBaseUrl } from "../core/auth.js";
-import { HubSpotClient } from "../core/http.js";
+import { createClient } from "../core/http.js";
+import { runWithTelemetryContext, withTelemetryContext } from "../core/telemetry-context.js";
 import { CliError, redactSensitive } from "../core/output.js";
 import { ENGAGEMENT_OBJECT_TYPES, OBJECT_COMMAND_TYPES, PIPELINE_OBJECT_TYPES, PROPERTY_OBJECT_TYPES, appendOptional, encodePathSegment, maybeWrite, parseBooleanFlag, parseNumberFlag, parseSupportedObjectType, } from "../commands/crm/shared.js";
 import { resolvePortalContext, enrichListResponse, enrichRecordUrl, enrichCustomListResponse, enrichCustomRecordUrl, } from "../core/urls.js";
 import { registerHubspotCompatTools } from "./compat-hubspot.js";
 import { registerExtensionTools } from "./ext-tools.js";
+import { registerHubspotModuleTools } from "./hubspot-modules.js";
 export const baseArgsSchema = {
     profile: z.string().min(1).optional(),
     force: z.boolean().optional(),
     dryRun: z.boolean().optional(),
+    changeTicket: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Change ticket / ops ID. Required by policies with requireChangeTicket=true; also threaded into trace/audit events."),
 };
 export function resolveProfile(requested) {
     // Priority order:
@@ -41,11 +47,17 @@ export function resolveProfile(requested) {
 function mcpContext(args) {
     const force = Boolean(args.force);
     const dryRun = args.dryRun ?? !force;
+    const changeTicket = args.changeTicket?.trim()
+        || process.env.HSCLI_CHANGE_TICKET?.trim()
+        || undefined;
+    const policyFile = process.env.HSCLI_POLICY_FILE?.trim() || undefined;
     return {
         profile: resolveProfile(args.profile),
         json: true,
         dryRun,
         force,
+        ...(changeTicket ? { changeTicket } : {}),
+        ...(policyFile ? { policyFile } : {}),
     };
 }
 function asStructuredContent(value) {
@@ -64,12 +76,13 @@ function textResult(data) {
 export async function executeTool(args, fn) {
     try {
         const ctx = mcpContext(args);
-        const client = new HubSpotClient(getToken(ctx.profile), {
-            profile: ctx.profile,
+        const client = createClient(ctx.profile, {
             strictCapabilities: isEnvTrue(process.env.HSCLI_MCP_STRICT_CAPABILITIES),
-            apiBaseUrl: getApiBaseUrl(ctx.profile),
         });
-        const result = await fn(ctx, client);
+        // Extend the outer tool-name ALS scope with the changeTicket parsed
+        // from args so emitTelemetry() tags every HTTP event triggered by
+        // this MCP call with both toolName + changeTicket.
+        const result = await withTelemetryContext(ctx.changeTicket ? { changeTicket: ctx.changeTicket } : {}, () => fn(ctx, client));
         return textResult(result);
     }
     catch (error) {
@@ -101,26 +114,10 @@ export async function executeTool(args, fn) {
 export function registerMcpTool(server, name, config, handler) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const wrapped = (...handlerArgs) => {
-        const previous = process.env.HSCLI_MCP_TOOL_NAME;
-        process.env.HSCLI_MCP_TOOL_NAME = name;
-        const restore = () => {
-            if (previous === undefined)
-                delete process.env.HSCLI_MCP_TOOL_NAME;
-            else
-                process.env.HSCLI_MCP_TOOL_NAME = previous;
-        };
-        try {
-            const result = handler(...handlerArgs);
-            if (result && typeof result.then === "function") {
-                return Promise.resolve(result).finally(restore);
-            }
-            restore();
-            return result;
-        }
-        catch (err) {
-            restore();
-            throw err;
-        }
+        // AsyncLocalStorage scopes toolName to this invocation's async chain.
+        // Using process.env here was race-prone: two concurrent MCP calls
+        // would clobber each other's tool name and mis-attribute trace events.
+        return runWithTelemetryContext({ toolName: name }, () => handler(...handlerArgs));
     };
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     server.registerTool(name, config, wrapped);
@@ -257,6 +254,13 @@ export function registerHubSpotTools(server) {
     // expose (workflows, files, forms, webhooks, marketing-emails, CMS writes,
     // conversations).
     registerExtensionTools(server);
+    // HubSpot drag-and-drop module library — exposes every @hubspot/*
+    // module's field schema as a typed MCP surface. Agents can discover
+    // modules (`hubspot_module_list`), inspect their fields
+    // (`hubspot_module_describe`), and compose validated widget bodies
+    // (`hubspot_module_compose`) before writing to marketing/emails or
+    // CMS pages.
+    registerHubspotModuleTools(server);
     registerMcpTool(server, "crm_properties_list", {
         description: "List properties for an object type",
         inputSchema: { ...baseArgsSchema, objectType: z.enum(PROPERTY_OBJECT_TYPES) },