@convertcom/mcp-server 0.0.1-beta.15 → 0.0.1-beta.17

package/build/mcp-server-compat.js

@@ -0,0 +1,28 @@
+const FALSY_REQUEST_ID_COMPAT = Symbol('convert.falsy-request-id-cancellation');
+/**
+ * @modelcontextprotocol/server 2.0.0 ignores cancellation for the valid
+ * falsy JSON-RPC IDs 0 and "".
+ * Keep the workaround on each Convert-owned server instance so the published
+ * npm package and Worker bundle have identical behavior without package-manager
+ * patch protocols. Remove this shim once the pinned SDK contains the fix.
+ */
+export function applyFalsyRequestIdCancellationCompat(server) {
+    const protocol = server;
+    if (protocol[FALSY_REQUEST_ID_COMPAT])
+        return;
+    if (typeof protocol._oncancel !== 'function'
+        || !(protocol._requestHandlerAbortControllers instanceof Map)) {
+        throw new Error('MCP server cancellation compatibility seam is unavailable.');
+    }
+    const original = protocol._oncancel.bind(protocol);
+    protocol._oncancel = async (notification) => {
+        const requestId = notification.params.requestId;
+        if (requestId !== 0 && requestId !== '') {
+            await original(notification);
+            return;
+        }
+        protocol._requestHandlerAbortControllers.get(requestId)?.abort(notification.params.reason);
+    };
+    protocol[FALSY_REQUEST_ID_COMPAT] = true;
+}
+//# sourceMappingURL=mcp-server-compat.js.map

package/build/mcp-server-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server-compat.js","sourceRoot":"","sources":["../src/mcp-server-compat.ts"],"names":[],"mappings":"AAaA,MAAM,uBAAuB,GAAG,MAAM,CAAC,uCAAuC,CAAC,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,qCAAqC,CAAC,MAAc;IAClE,MAAM,QAAQ,GAAG,MAAiD,CAAC;IACnE,IAAI,QAAQ,CAAC,uBAAuB,CAAC;QAAE,OAAO;IAC9C,IAAI,OAAO,QAAQ,CAAC,SAAS,KAAK,UAAU;WACvC,CAAC,CAAC,QAAQ,CAAC,+BAA+B,YAAY,GAAG,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnD,QAAQ,CAAC,SAAS,GAAG,KAAK,EAAE,YAAY,EAAE,EAAE;QAC1C,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC;QAChD,IAAI,SAAS,KAAK,CAAC,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YACxC,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,+BAA+B,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7F,CAAC,CAAC;IACF,QAAQ,CAAC,uBAAuB,CAAC,GAAG,IAAI,CAAC;AAC3C,CAAC"}

package/build/modern-runtime.d.ts

@@ -0,0 +1,13 @@
+import { Server } from '@modelcontextprotocol/server';
+import { type ConvertMcpServerIdentityOptions, type ConvertMcpRuntimeOptions } from './runtime.js';
+/**
+ * Builds the v2 protocol server while keeping catalog and dispatch behavior in
+ * the shared runtime. The HTTP entry must create one of these per request.
+ */
+export declare function createModernConvertMcpServer(options: ConvertMcpRuntimeOptions): Server;
+/**
+ * A listen request needs only identity and capabilities. Keeping this factory
+ * separate prevents a long-lived SSE handler from retaining Convert OAuth
+ * props, catalogs, docs providers, validators, or execution closures.
+ */
+export declare function createModernConvertMcpListenServer(options: ConvertMcpServerIdentityOptions, advertiseListChanged: boolean): Server;

package/build/modern-runtime.js

@@ -0,0 +1,148 @@
+import { CLIENT_INFO_META_KEY, ProtocolError, Server, } from '@modelcontextprotocol/server';
+import { McpError as LegacyMcpError, } from '@modelcontextprotocol/sdk/types.js';
+import { convertMcpServerDefinition, createConvertMcpHandlers, } from './runtime.js';
+import { applyFalsyRequestIdCancellationCompat } from './mcp-server-compat.js';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function sharedClientInfoFrom(value) {
+    if (!isRecord(value) || typeof value.name !== 'string' || typeof value.version !== 'string')
+        return undefined;
+    const clientInfo = { name: value.name, version: value.version };
+    for (const key of ['title', 'description', 'websiteUrl']) {
+        if (typeof value[key] === 'string')
+            clientInfo[key] = value[key];
+    }
+    if (Array.isArray(value.icons)) {
+        const icons = value.icons
+            .filter(isRecord)
+            .map((icon) => {
+            if (typeof icon.src !== 'string')
+                return undefined;
+            const sanitized = { src: icon.src };
+            if (typeof icon.mimeType === 'string')
+                sanitized.mimeType = icon.mimeType;
+            if (Array.isArray(icon.sizes) && icon.sizes.every((size) => typeof size === 'string')) {
+                sanitized.sizes = icon.sizes;
+            }
+            if (icon.theme === 'light' || icon.theme === 'dark')
+                sanitized.theme = icon.theme;
+            return sanitized;
+        })
+            .filter((icon) => icon !== undefined);
+        if (icons.length > 0)
+            clientInfo.icons = icons;
+    }
+    return clientInfo;
+}
+function clientInfoFromEnvelope(envelope) {
+    if (!envelope)
+        return undefined;
+    const value = envelope[CLIENT_INFO_META_KEY];
+    return sharedClientInfoFrom(value);
+}
+function translateLegacyProtocolError(error) {
+    if (error instanceof LegacyMcpError) {
+        throw new ProtocolError(error.code, error.message, error.data);
+    }
+    throw error;
+}
+async function withModernProtocolErrors(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        return translateLegacyProtocolError(error);
+    }
+}
+/**
+ * Builds the v2 protocol server while keeping catalog and dispatch behavior in
+ * the shared runtime. The HTTP entry must create one of these per request.
+ */
+export function createModernConvertMcpServer(options) {
+    const definition = convertMcpServerDefinition(options);
+    const capabilities = options.advertiseListChanged === false
+        ? {
+            tools: { listChanged: false },
+            prompts: { listChanged: false },
+            resources: { listChanged: false },
+        }
+        : definition.options.capabilities;
+    const server = new Server(definition.implementation, {
+        ...definition.options,
+        capabilities,
+    });
+    applyFalsyRequestIdCancellationCompat(server);
+    const handlers = createConvertMcpHandlers(options, (extra) => extra.clientInfo ?? sharedClientInfoFrom(server.getClientVersion()));
+    const runtimeExtra = (ctx) => {
+        const extra = {
+            signal: ctx.mcpReq.signal,
+            requestId: ctx.mcpReq.id,
+            sendNotification: (notification) => ctx.mcpReq.notify(notification),
+            clientInfo: clientInfoFromEnvelope(ctx.mcpReq.envelope),
+        };
+        return extra;
+    };
+    server.setRequestHandler('tools/list', async (_request, ctx) => {
+        return await withModernProtocolErrors(async () => {
+            return await handlers.listTools(runtimeExtra(ctx));
+        });
+    });
+    server.setRequestHandler('resources/list', async (_request, ctx) => {
+        return await withModernProtocolErrors(async () => {
+            return await handlers.listResources(runtimeExtra(ctx));
+        });
+    });
+    server.setRequestHandler('resources/templates/list', async (_request, ctx) => {
+        return await withModernProtocolErrors(async () => {
+            return await handlers.listResourceTemplates(runtimeExtra(ctx));
+        });
+    });
+    server.setRequestHandler('resources/read', async (request, ctx) => {
+        return await withModernProtocolErrors(async () => {
+            return await handlers.readResource(request, runtimeExtra(ctx));
+        });
+    });
+    server.setRequestHandler('prompts/list', async (_request, ctx) => {
+        return await withModernProtocolErrors(async () => {
+            return await handlers.listPrompts(runtimeExtra(ctx));
+        });
+    });
+    server.setRequestHandler('prompts/get', async (request, ctx) => {
+        return await withModernProtocolErrors(async () => {
+            return await handlers.getPrompt(request, runtimeExtra(ctx));
+        });
+    });
+    server.setRequestHandler('tools/call', async (request, ctx) => {
+        return await withModernProtocolErrors(async () => {
+            let outputSchema;
+            const result = await handlers.callTool(request, runtimeExtra(ctx), (tool) => {
+                outputSchema = tool?.outputSchema;
+            });
+            // Low-level v2 handlers use this public codec seam. Convert's schemas
+            // and structured results are object-rooted, so projection is identity
+            // today while retaining the SDK's required text fallback behavior.
+            return server.projectCallToolResult(result, outputSchema);
+        });
+    });
+    return server;
+}
+/**
+ * A listen request needs only identity and capabilities. Keeping this factory
+ * separate prevents a long-lived SSE handler from retaining Convert OAuth
+ * props, catalogs, docs providers, validators, or execution closures.
+ */
+export function createModernConvertMcpListenServer(options, advertiseListChanged) {
+    const definition = convertMcpServerDefinition(options);
+    return new Server(definition.implementation, {
+        ...definition.options,
+        capabilities: advertiseListChanged
+            ? definition.options.capabilities
+            : {
+                tools: { listChanged: false },
+                prompts: { listChanged: false },
+                resources: { listChanged: false },
+            },
+    });
+}
+//# sourceMappingURL=modern-runtime.js.map

package/build/modern-runtime.js.map

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

package/build/namespaced.js

@@ -1,5 +1,5 @@
 import { toolDefinitionMap } from './tools.js';
-import { executeToolByName, truncateSchemaText, validateToolArgs } from './executor.js';
+import { executeToolByName, executeValidatedToolByName, truncateSchemaText, validateToolArgs } from './executor.js';
 import { JSON_SCHEMA_DRAFT_2020_12, pathParamsFromTemplate, tryParseJsonLike } from './shared.js';
 import { toolSafetyKindForDelegate } from './tool-safety.js';
 import { MDE_FRACTION_BOUNDARY_VERSION, experienceStatsVersion, usesLegacyFixedMdeScale, } from './stats-engine-version.js';
@@ -15,6 +15,7 @@ const STATS_ENGINE_EVIDENCE_NOTE = [
     'Never mix engine vocabularies in the same interpretation.',
     'Never calculate, estimate, simulate, or label an inactive-engine result from the current report counts, including hypothetical or "what if we switched" requests. A Convert chance_to_win must come from a fresh Bayesian aggregate report; a Convert significance result must come from a fresh Frequentist aggregate report.',
     'After any stats-lens change, fetch a fresh aggregated report and never carry a conclusion across lenses.',
+    'Use settings.min_variation_conversions for the minimum conversion count. Deprecated min_conversion_value aliases the same stored count; it is not a separate revenue threshold. Settings are returned configuration, not an include/expand relation.',
 ].join(' ');
 function requiredPathParamsForDef(def) {
     const declared = (def.executionParameters || [])
@@ -320,6 +321,7 @@ export const ACTION_NOTES = {
         'Type enum: "a/b", "a/a", "mvt", "split_url", "multipage", "deploy" (standard projects), "a/b_fullstack", "feature_rollout" (fullstack projects only).',
         'Deploy semantics: type "deploy" is a rollout/deployment container, not a tracked experience. Do not expect visitor/conversion reporting for deploys.',
         'Required body fields: name, type, url. If status is omitted, MCP defaults it to "draft".',
+        'Before creation, fetch projects.get with default_goals, default_audiences, and default_locations included/expanded, inspect project stats/allocation and integrations, and resolve the intended resources by name. Discuss inherited defaults with the user; operator.get_defaults is a suggestion, not consent to attach a goal or enable MAB/integrations. Read back the draft with expanded goals, audiences, locations and variations and disclose any inherited configuration before activation. Do not promise that omitted fields mean disabled or empty.',
         'Setting status to "active" requires explicit user confirmation at tool-call level: confirmation: { "user_confirmed": true, "reason": "..." }.',
         'For hand-written JS/CSS in an A/B test, use changes[].type "customCode" with data { "js": "...", "css": "" }. Do not use "defaultCode" unless sending Visual Editor data with custom_js.',
         'Create control+treatment variations by sending body.variations with each variation name and optional changes array. Use traffic_distribution for variation traffic; MCP also accepts legacy traffic_percentage and normalizes it.',
@@ -397,7 +399,7 @@ export const ACTION_NOTES = {
         'Engine vocabularies are mutually exclusive. For Bayesian reports, use chance_to_win, done, and estimated_progress. Never describe Bayesian evidence as confidence or statistically significant; never use confidence, statistically_significant, observed_power, or other Frequentist significance fields, and do not quote or interpret the ambiguous numeric risk vector. For Frequentist reports, use confidence, statistically_significant, done, and engine-appropriate progress; never use chance_to_win, Bayesian risk, or Bayesian decision-threshold language. MCP removes inactive-engine metric fields before returning the report.',
         'Do not describe a shared settings field as active evidence merely because it is present. Resolve stats_methodology first, then discuss only settings and metric fields that belong to that engine.',
     ].join('\n'),
-    'experiences.daily_report': 'Works on tracked experience types. Returns empty data arrays for draft/inactive experiences. Deploy experiences are not tracked experiences, so daily reports are not applicable and clients must skip this request when diagnosing deploy tracking.',
+    'experiences.daily_report': 'Use body.goal (numeric goal ID), not query.goal_id or body.goal_id. Example: { "action": "daily_report", "path": { "account_id": 123, "project_id": 456, "experience_id": 789 }, "body": { "goal": 101, "report_type": "non_cumulative", "metric": "conversion_rate" } }. Date range and segments also belong in the documented body fields; resolve goal IDs from the experience before selecting a non-primary goal. Works on tracked experience types. An empty series does not prove zero traffic; check lifecycle and collection coverage. Deploy experiences are not tracked experiences, so daily reports are not applicable and clients must skip this request when diagnosing deploy tracking.',
     'experiences.get_heatmap_background': 'Requires heatmap_id in path. Optional body.device is one of "desktop", "tablet", or "mobile" and defaults to "desktop".',
     'experiences.get_heatmap_overlay': 'Requires heatmap_id in path. Optional body.device is one of "desktop", "tablet", or "mobile"; optional body.interaction is "click", "scroll", or "move". Defaults are desktop/click.',
     // ── locations ────────────────────────────────────────────
@@ -523,9 +525,11 @@ export const ACTION_NOTES = {
         'MCP accepts legacy type aliases "custom_js" -> "code_trigger" and "scrolls_to" -> "scroll_percentage".',
         'description max length is 500 characters.',
         'Use triggering_rule for URL or audience-style scoping; it accepts nested OR→AND→OR_WHEN rules.',
+        'visits_page does not use settings.url for tracking. Put page matching in triggering_rule; an echoed settings value is not proof that targeting was applied. Omit settings for an intentionally unscoped page-visit goal.',
         'clicks_element settings example: { "selector": ".cta" }. code_trigger requires no settings.',
         'clicks_link requires settings.href as a string; Convert API rejects match objects there. Use triggering_rule for page scoping, or create multiple link goals when multiple href patterns are needed.',
     ].join('\n'),
+    'goals.update': 'Use triggering_rule for page scoping, not settings.url, including partial updates that omit type. Preserve existing triggering_rule conditions when editing scope; omission preserves them, while null clears them. Do not infer a goal collection start from its creation date or compare goals as if they necessarily share a collection window.',
     // ── accounts ─────────────────────────────────────────────
     'accounts.list_sdk_keys': 'Requires "project_id" in path even though it\'s under the accounts namespace.',
     'accounts.create_sdk_key': [
@@ -1042,6 +1046,18 @@ function evaluateGoalGuardrails(action, body) {
         return null;
     if (!isNonArrayObject(body.settings))
         return null;
+    if ((typeof body.type === 'undefined' || body.type === 'visits_page')
+        && Object.prototype.hasOwnProperty.call(body.settings, 'url')) {
+        return {
+            code: 'GoalUrlRequiresTriggeringRule',
+            message: [
+                'goals.create/update: body.settings.url does not scope visits_page tracking, even when the API echoes it. No write was sent.',
+                'For partial updates that omit type, fetch goals.get to confirm the goal type before editing its tracking configuration.',
+                'Remove settings.url and express page scoping in triggering_rule, for example: { "OR": [{ "AND": [{ "OR_WHEN": [{ "rule_type": "url", "value": "https://example.com/free-trial", "matching": { "match_type": "contains" } }] }] }] }.',
+                'Preserve any existing triggering_rule conditions; do not replace them blindly. Omit settings for an intentionally unscoped visits_page goal.',
+            ].join('\n'),
+        };
+    }
     if (typeof body.type !== 'undefined' && body.type !== 'clicks_link')
         return null;
     const href = body.settings.href;
@@ -1528,6 +1544,10 @@ const AGGREGATED_REPORT_GUIDANCE = {
         interpretation: 'srm=true is an API-detected sample-ratio mismatch and blocks inferential conclusions for the affected scope. srm=false means the API did not flag SRM for this response; it is not independent proof of correct allocation when threshold, expected-allocation, or sample context is absent.',
         provenance: 'api_boolean_without_threshold_context',
     },
+    computation_provenance: {
+        state: 'unknown_without_upstream_computation_metadata',
+        interpretation: 'The API transformer may default missing srm_pvalue to 1, missing chance_to_win/confidence to 0, and missing done/srm to false. Preserve genuine numeric 0/1, boolean true/false, and explicit missing/null values; the wire value alone cannot establish whether the statistic was computed. done=false means no completion is reported, not proof that a computation ran and failed its stopping gates. Respect reported done=true and engine-specific decision gates; never manufacture completion. Do not infer a paused-experience effect, a minimum-conversion gate, or a clean allocation from default-like values. Disclose the uncertainty when it affects a conclusion.',
+    },
 };
 const DYNAMIC_MDE_GUIDANCE = {
     semantics_version: 'convert.dynamic-mde.v1',
@@ -1768,6 +1788,7 @@ export function normalizeAggregatedReportResult(result) {
         '- Deprecated conversion_data, revenue_data, and products_data blocks were removed.',
         '- Use reportData[].variations[].metrics[] as the only statistical evidence source.',
         '- Treat srm=true as an API-detected allocation mismatch. Treat srm=false only as "not flagged by this API response", not as independent proof that allocation is correct when threshold context is absent.',
+        `- ${AGGREGATED_REPORT_GUIDANCE.computation_provenance.interpretation}`,
         `- ${engineGuidance}`,
     ].join('\n');
     const content = [{
@@ -2237,12 +2258,18 @@ export async function executeNamespacedTool(toolName, args, executionContext, to
             isError: true,
         }, namespace, action, delegate);
     }
-    const executedResult = await executeToolByName(delegate, flattenedArgs, executionContext);
+    const executedResult = await executeValidatedToolByName(delegate, flattenedArgs, executionContext);
     const approvalAwareResult = normalizeApprovalRequiredError(namespace, action, path, executedResult);
     const result = normalizeProjectCreatePermissionError(namespace, action, approvalAwareResult);
     // Append action-specific guidance to error messages so agents can self-correct
     if (result.isError) {
-        const note = ACTION_NOTES[`${namespace}.${action}`];
+        const lifecycleDenied = namespace === 'experiences' && isNonArrayObject(normalizedBody)
+            && ((action === 'update' && ['active', 'paused'].includes(String(normalizedBody.status)))
+                || (action === 'create' && normalizedBody.status === 'active'))
+            && asObject(result.structuredContent)?.status === 403;
+        const note = lifecycleDenied
+            ? `Activation/pause was denied by Convert. Human confirmation records intent; it does not grant authorization. Verify the exact account/project, the credential principal's current ${action === 'create' ? 'experience.add' : 'experience.pauseplay'} permission and OAuth grant scope. Plan or approval restrictions are possibilities, not established causes unless the backend explicitly identifies them. Do not retry with different payloads, reconnect automatically, or submit an approval request unless Convert returns ApprovalRequired and the user asks to submit it. Staff impersonation remains browse-only.`
+            : ACTION_NOTES[`${namespace}.${action}`];
         if (note && result.content?.[0]?.type === 'text') {
             result.content[0].text += `\n\nHint for ${namespace}.${action}:\n${note}`;
         }