@convertcom/mcp-server 0.0.1-beta.10

package/build/namespaced.js

@@ -0,0 +1,927 @@
+import { toolDefinitionMap } from './tools.js';
+import { executeToolByName } from './executor.js';
+import { JSON_SCHEMA_DRAFT_2020_12, pathParamsFromTemplate } from './shared.js';
+function requiredPathParamsForDef(def) {
+    const declared = (def.executionParameters || [])
+        .filter((p) => p.in === 'path')
+        .map((p) => p.name);
+    const inferred = def.pathTemplate ? pathParamsFromTemplate(def.pathTemplate) : [];
+    return [...new Set([...declared, ...inferred])];
+}
+const REGISTRY = {
+    accounts: {
+        list: 'getaccountslist',
+        get: 'getaccountdetails',
+        get_billing_portal: 'getaccountbillingportal',
+        get_live_data: 'getaccountlivedata',
+        get_history: 'getaccounthistory',
+        list_users_accesses: 'getaccountusersaccesseslist',
+        list_api_keys: 'getapikeyslist',
+        list_sdk_keys: 'getsdkkeyslist',
+        create_sdk_key: 'createsdkkey',
+    },
+    projects: {
+        list: 'getprojectslist',
+        get: 'getproject',
+        create: 'createproject',
+        update: 'updateproject',
+        get_live_data: 'getprojectlivedata',
+        get_history: 'getprojecthistory',
+    },
+    domains: {
+        list: 'getdomainslist',
+        get: 'getdomain',
+        get_by_url: 'getdomainbyurl',
+        check_code: 'checkcodedomain',
+        create: 'createdomain',
+        update: 'updatedomain',
+        delete: 'deletedomain',
+    },
+    experiences: {
+        list: 'getexperienceslist',
+        get: 'getexperience',
+        get_by_key: 'getexperiencebykey',
+        create: 'createexperience',
+        clone: 'cloneexperience',
+        update: 'updateexperience',
+        get_live_data: 'getexperiencelivedata',
+        get_history: 'getexperiencehistory',
+        aggregated_report: 'getexperienceaggregatedreport',
+        daily_report: 'getexperiencedailyreport',
+        daily_traffic_allocation: 'getexperiencedailytrafficallocation',
+        update_variation: 'updateexperiencevariation',
+        get_variation_screenshot: 'getexperiencevariationscreenshot',
+        get_heatmap_background: 'getexperienceheatmapbackground',
+        get_heatmap_overlay: 'getexperienceheatmapoverlay',
+        upload_variation_screenshot: 'uploadexperiencevariationscreenshot',
+        convert_variation: 'convertexperiencevariation',
+        get_change: 'getexperiencechange',
+        update_change: 'updateexperiencechange',
+    },
+    sections: {
+        list: 'getsections',
+        create: 'createsection',
+        update: 'updatesection',
+        update_experience_sections: 'updateexperiencesections',
+        add_version: 'addexperiencesectionversion',
+        update_version: 'updateexperiencesectionversion',
+    },
+    goals: {
+        list: 'getgoalslist',
+        get: 'getgoal',
+        get_by_key: 'getgoalbykey',
+        create: 'creategoal',
+        update: 'updategoal',
+        delete: 'deletegoal',
+        clone: 'clonegoal',
+    },
+    tags: {
+        list: 'gettagslist',
+        get: 'gettag',
+        create: 'createtag',
+        update: 'updatetag',
+        delete: 'deletetag',
+    },
+    hypotheses: {
+        list: 'gethypotheseslist',
+        get: 'gethypothesis',
+        create: 'createhypothesis',
+        update: 'updatehypothesis',
+        update_status: 'updatehypothesisstatus',
+        convert: 'converthypothesis',
+        delete: 'deletehypothesis',
+    },
+    knowledgebases: {
+        list: 'getknowledgebaseslist',
+        get: 'getknowledgebase',
+        create: 'createknowledgebase',
+        update: 'updateknowledgebase',
+        delete: 'deleteknowledgebase',
+    },
+    observations: {
+        list: 'getobservationslist',
+        get: 'getobservation',
+        create: 'createobservation',
+        update: 'updateobservation',
+        delete: 'deleteobservation',
+    },
+    locations: {
+        list: 'getlocationslist',
+        get: 'getlocation',
+        create: 'createlocation',
+        update: 'updatelocation',
+        delete: 'deletelocation',
+        presets: 'getlocationspresets',
+        clone: 'clonelocation',
+    },
+    audiences: {
+        list: 'getaudienceslist',
+        get: 'getaudience',
+        create: 'createaudience',
+        update: 'updateaudience',
+        delete: 'deleteaudience',
+        presets: 'getaudiencespresets',
+        clone: 'cloneaudience',
+    },
+    features: {
+        list: 'getfeatureslist',
+        get: 'getfeature',
+        get_by_key: 'getfeaturebykey',
+        create: 'createfeature',
+        update: 'updatefeature',
+        delete: 'deletefeature',
+    },
+};
+/** Human-readable titles for each namespace */
+const NAMESPACE_TITLES = {
+    accounts: 'Accounts',
+    projects: 'Projects',
+    domains: 'Domains',
+    experiences: 'Experiences',
+    sections: 'Sections',
+    goals: 'Goals',
+    tags: 'Tags',
+    hypotheses: 'Hypotheses',
+    knowledgebases: 'Knowledge Bases',
+    observations: 'Observations',
+    locations: 'Locations',
+    audiences: 'Audiences',
+    features: 'Features',
+};
+/** Namespace-level descriptions for agents — richer than the auto-generated "Namespace 'X'" */
+const NAMESPACE_DESCRIPTIONS = {
+    accounts: 'Manage Convert.com accounts via the live API — get account details, billing portal URLs, live visitor data, history, users, API/SDK keys.',
+    projects: 'Manage Convert.com projects via the live API — list, create, update projects, get live visitor data and change history.',
+    domains: 'Manage domains in the user\'s Convert.com account — add, verify (check_code), update, delete domains for a project.',
+    experiences: 'Manage A/B tests, MVTs, split URL tests, deploys, feature rollouts, reports, screenshots, and heatmaps in the user\'s Convert.com account. Use type "a/b" (with slash, not underscore).',
+    sections: 'Manage multi-page sections within MVT experiences via the Convert.com API. Requires experience_id in path — sections are experience-scoped.',
+    goals: 'Manage conversion goals in the user\'s Convert.com account — page visits, clicks, form submits, revenue, custom JS. Use goal_key for get_by_key.',
+    tags: 'Manage tags in the user\'s Convert.com account for organizing experiences and other resources.',
+    hypotheses: 'Manage CRO hypotheses in the user\'s Convert.com account with PIE/ICE prioritization scoring (UPPERCASE).',
+    knowledgebases: 'Manage knowledge base entries in the user\'s Convert.com account. Note: path param uses underscores — knowledge_base_id (not knowledgebase_id).',
+    observations: 'Manage observations in the user\'s Convert.com account. ⚠️ update action has a known backend bug (500).',
+    locations: 'Manage page targeting rules in the user\'s Convert.com account (URL match, JS condition, DOM element trigger). Rules use nested OR→AND→OR_WHEN structure.',
+    audiences: 'Manage visitor segmentation rules in the user\'s Convert.com account. Rules use nested OR→AND→OR_WHEN structure similar to locations.',
+    features: 'Manage feature flags in the user\'s Convert.com account — only works in fullstack project types. Returns 422 for web/standard projects.',
+};
+/**
+ * Per-action agent guidance. Appended to generated descriptions as "Agent Notes:".
+ * Keys are "namespace.action" strings matching REGISTRY entries.
+ * This map survives `yarn generate` — it's hand-curated like REGISTRY.
+ */
+export const ACTION_NOTES = {
+    // ── accounts ─────────────────────────────────────────────
+    'accounts.get_billing_portal': 'Returns an authenticated Paddle billing portal URL for subscription and invoice management. Use only when the user asks for billing, subscription, or invoice access; do not surface billing links proactively.',
+    // ── experiences ──────────────────────────────────────────
+    'experiences.create': [
+        'Type enum: "a/b", "a/a", "mvt", "split_url", "multipage", "deploy" (standard projects), "a/b_fullstack", "feature_rollout" (fullstack projects only).',
+        'Required body fields: name, type, url. If status is omitted, MCP defaults it to "draft".',
+        '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.',
+        'a/b_fullstack and feature_rollout return 422 on non-fullstack projects.',
+        'Custom-code example: { "body": { "name": "My Test", "type": "a/b", "status": "draft", "url": "https://example.com", "variations": [{ "name": "control", "changes": [{ "type": "customCode", "data": { "js": "", "css": "" } }] }, { "name": "Treatment", "changes": [{ "type": "customCode", "data": { "js": "console.log(1)", "css": "" } }] }] } }',
+    ].join('\n'),
+    'experiences.update': [
+        'Setting body.status to "active" requires explicit user confirmation at tool-call level: confirmation: { "user_confirmed": true, "reason": "..." }.',
+        'Experience-level settings belong here, not in update_variation. For split URL regex support, call experiences.update without variation_id: { "body": { "settings": { "split_url_settings": { "split_regex_support": true } } } }.',
+        'MCP accepts legacy settings arrays with one object and normalizes them to the canonical settings object.',
+    ].join('\n'),
+    'experiences.get_by_key': 'Path parameter is "experience_key" (not "key"). Pass in path: { "experience_key": "abc123" }.',
+    'experiences.daily_traffic_allocation': 'Only works when MAB (Multi-Armed Bandit) is configured on the experience. Returns 422 otherwise.',
+    'experiences.update_variation': [
+        'Body is required and must be a non-empty object. Empty/missing body is rejected at MCP layer to avoid silent no-op updates.',
+        'Requires "variation_id" in path. Get variation IDs from experiences.get with query: { "include": ["variations"], "expand": ["variations"] }.',
+        'To add CSS/JS changes, use the "changes" array in body. Each change needs "type" and "data":',
+        '  - type "customCode": data = { css: "...", js: "..." } — for custom CSS/JS code',
+        '  - type "defaultCode": data = { css: "...", js: "...", custom_js: "..." } — for Visual Editor changes',
+        '  - type "defaultRedirect": data = { original_pattern, variation_pattern, case_sensitive } — for split URL',
+        '  - type "fullStackFeature": data = { feature_id, variables_data } — for fullstack features',
+        'Do NOT send experience-level settings here. For split_url_settings such as split_regex_support, use experiences.update and omit variation_id.',
+        'Example adding custom CSS+JS: { "body": { "changes": [{ "type": "customCode", "data": { "css": "body{color:red}", "js": "console.log(1)" } }] } }',
+        'To clear all changes: { "body": { "changes": [] } }',
+        'To update an existing change, include its integer "id" from the previous response.',
+    ].join('\n'),
+    'experiences.get_variation_screenshot': 'Requires "variation_id" in path. Returns 404 ("No image found") for draft experiences or variations with no visual editor changes yet — this is normal.',
+    'experiences.upload_variation_screenshot': 'Requires "variation_id" in path and multipart body { "image": "data:image/png;base64,..." }. MCP also accepts a raw data URL string as body and normalizes it to the image field.',
+    'experiences.get_change': [
+        'Requires account_id, project_id, experience_id, and change_id in path.',
+        '⚠️ Known schema issue: path params may not be auto-validated. Pass all four IDs explicitly in path.',
+        'Get change IDs from the update_variation response or from experiences.get with include/expand variations.',
+    ].join('\n'),
+    'experiences.update_change': [
+        'Requires account_id, project_id, experience_id, and change_id in path.',
+        '⚠️ Known schema issue: path params may not be auto-validated. Pass all four IDs explicitly in path.',
+        'Body uses same structure as update_variation changes: { type, data }.',
+        'For customCode: { "type": "customCode", "data": { "css": "...", "js": "..." } }',
+        'For defaultCode: { "type": "defaultCode", "data": { "css": "...", "js": "...", "custom_js": "..." } }',
+    ].join('\n'),
+    'experiences.aggregated_report': 'Works on any experience. Returns empty data arrays for draft/inactive experiences.',
+    'experiences.daily_report': 'Works on any experience. Returns empty data arrays for draft/inactive experiences.',
+    '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 ────────────────────────────────────────────
+    'locations.create': [
+        'Required body fields: name, rules, trigger.',
+        'Rules use nested OR→AND→OR_WHEN structure.',
+        'Minimal example: { "body": { "name": "Homepage", "rules": { "OR": [{ "AND": [{ "OR_WHEN": [{ "rule_type": "url", "value": "example.com", "matching": { "match_type": "contains" } }] }] }] }, "trigger": { "type": "upon_run" } } }',
+    ].join('\n'),
+    // ── audiences ────────────────────────────────────────────
+    'audiences.create': [
+        'Required body fields: name, type, rules.',
+        'Type enum: "segmentation", "permanent", "transient". MCP accepts legacy "transient_condition" and normalizes it to "transient".',
+        'Rules use nested OR→AND→OR_WHEN structure (same as locations but more rule_type options).',
+        'For visitor_type rules, use match_type: "equals" (not "matches").',
+        'Minimal example: { "body": { "name": "Returning Visitors", "type": "segmentation", "rules": { "OR": [{ "AND": [{ "OR_WHEN": [{ "rule_type": "visitor_type", "value": "returning", "matching": { "match_type": "equals" } }] }] }] } } }',
+    ].join('\n'),
+    // ── hypotheses ───────────────────────────────────────────
+    'hypotheses.create': [
+        'Required body fields: name, status (use "draft"), prioritization_score_type, prioritization_score_attributes.',
+        'prioritization_score_type: "PIE" or "ICE" (UPPERCASE only).',
+        'For PIE: attributes are { potential, importance, ease } (values 1-5).',
+        'For ICE: attributes are { impact, confidence, ease } (values 1-5).',
+        'Minimal example: { "body": { "name": "Bigger CTA button", "status": "draft", "prioritization_score_type": "PIE", "prioritization_score_attributes": { "potential": 4, "importance": 3, "ease": 5 } } }',
+    ].join('\n'),
+    'hypotheses.convert': 'Converts hypothesis to experience. The hypothesis must have associated goals and locations first. Returns 422 if prerequisites are missing.',
+    'hypotheses.update_status': [
+        'Body is { "status": "<value>" }. Valid statuses: "draft", "applied", "completed", "archived", "proven", "disproven".',
+        'Status transitions follow a strict state machine:',
+        '  draft ↔ applied → completed → { archived, proven, disproven }',
+        'Only allowed transitions: draft→applied, applied→draft, applied→completed, completed→archived, completed→proven, completed→disproven.',
+        'Returns 422 "Status cannot be updated to the desired one" for invalid transitions.',
+    ].join('\n'),
+    // ── knowledgebases ───────────────────────────────────────
+    'knowledgebases.create': 'Required body fields: name, summary. Optional: description, url, start_date, end_date.',
+    'knowledgebases.get': 'Path parameter is "knowledge_base_id" (with underscores, not "knowledgebase_id").',
+    'knowledgebases.update': [
+        'Path parameter is "knowledge_base_id" (with underscores).',
+        'Currently only accepts "status" field in body ("active" or "archived"). Other fields like name or summary will fail schema validation.',
+    ].join('\n'),
+    'knowledgebases.delete': 'Path parameter is "knowledge_base_id" (with underscores, not "knowledgebase_id").',
+    // ── observations ─────────────────────────────────────────
+    'observations.update': '⚠️ Known backend bug — API returns 500 on update. Workaround: create a new observation + delete the old one.',
+    // ── features ─────────────────────────────────────────────
+    'features.create': [
+        'Only works in fullstack project types. Returns 422 for web/standard projects.',
+        'Required body fields: name, key, variables (array).',
+        'Variable type enum: "boolean", "string", "integer", "float", "json". default_value must match the type (e.g., true for boolean, not "true").',
+        'Minimal example: { "body": { "name": "Dark Mode", "key": "dark_mode", "variables": [{ "key": "enabled", "type": "boolean", "default_value": false }] } }',
+    ].join('\n'),
+    'features.get_by_key': 'Path parameter is "feature_key" (not "key"). Pass in path: { "feature_key": "abc123" }.',
+    // ── sections ─────────────────────────────────────────────
+    'sections.list': 'Requires "experience_id" in path — sections are experience-scoped, not project-scoped.',
+    'sections.create': [
+        'Requires "experience_id" in path — sections are experience-scoped.',
+        'Only works for MVT (multivariate) experiences. Returns 403 for A/B and other types.',
+        'Required body field: "versions" array with at least one version object.',
+        'Minimal example: { "body": { "name": "New Section", "versions": [{ "name": "Original", "url": "https://example.com" }] } }',
+    ].join('\n'),
+    'sections.update': [
+        'Requires "experience_id" and "section_id" in path — sections are experience-scoped.',
+        'Required body field: "versions" array (same format as sections.create).',
+        'Example: { "body": { "name": "Updated Section", "versions": [{ "name": "V1", "url": "https://example.com" }] } }',
+    ].join('\n'),
+    // ── goals ────────────────────────────────────────────────
+    'goals.get_by_key': 'Path parameter is "goal_key" (not "key"). Pass in path: { "goal_key": "abc123" }.',
+    'goals.create': [
+        'Type enum: "advanced", "visits_page", "revenue", "clicks_link", "submits_form", "clicks_element", "dom_interaction", "scroll_percentage", "ga_import", "code_trigger".',
+        '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.',
+        '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'),
+    // ── accounts ─────────────────────────────────────────────
+    'accounts.list_sdk_keys': 'Requires "project_id" in path even though it\'s under the accounts namespace.',
+    'accounts.create_sdk_key': 'Requires "project_id" in path even though it\'s under the accounts namespace. May return 401 if API credentials lack SDK key management permissions.',
+};
+function isNonArrayObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeLooseJson(input) {
+    return input
+        .replace(/[`]/g, '"')
+        .replace(/[\u201C\u201D]/g, '"')
+        .replace(/[\u2018\u2019]/g, "'")
+        .replace(/(\{|\,)(\s*)([A-Za-z0-9_]+)(\s*):/g, (_, start, space, key, after) => `${start}${space}"${key}"${after}:`)
+        .replace(/:\s*'([^']*)'/g, ': "$1"')
+        .replace(/,\s*([}\]])/g, '$1');
+}
+function tryParseJsonLike(value) {
+    if (!value)
+        return undefined;
+    const attempts = [value, normalizeLooseJson(value)];
+    for (const candidate of attempts) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+function coerceJsonLike(value) {
+    if (typeof value !== 'string')
+        return value;
+    const parsed = tryParseJsonLike(value);
+    return typeof parsed === 'undefined' ? value : parsed;
+}
+function asObject(value) {
+    return isNonArrayObject(value) ? value : null;
+}
+function coerceObject(value) {
+    const parsed = coerceJsonLike(value);
+    const objectValue = asObject(parsed);
+    return objectValue ? { ...objectValue } : {};
+}
+function coerceParameterValue(value, schema) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return value;
+    switch (schema?.type) {
+        case 'integer': {
+            if (!/^-?\d+$/.test(trimmed))
+                return value;
+            const parsed = Number(trimmed);
+            return Number.isSafeInteger(parsed) ? parsed : value;
+        }
+        case 'number': {
+            if (!/^-?\d+(?:\.\d+)?$/.test(trimmed))
+                return value;
+            const parsed = Number(trimmed);
+            return Number.isFinite(parsed) ? parsed : value;
+        }
+        case 'boolean':
+            if (trimmed === 'true')
+                return true;
+            if (trimmed === 'false')
+                return false;
+            return value;
+        case 'array': {
+            const parsed = tryParseJsonLike(trimmed);
+            return Array.isArray(parsed) ? parsed : value;
+        }
+        case 'object': {
+            const parsed = tryParseJsonLike(trimmed);
+            return isNonArrayObject(parsed) ? parsed : value;
+        }
+        default:
+            return value;
+    }
+}
+function normalizeNamespaceArgs(rawArgs, def) {
+    const path = coerceObject(rawArgs.path);
+    const query = coerceObject(rawArgs.query);
+    const pathParamNames = requiredPathParamsForDef(def);
+    const executionParams = def.executionParameters || [];
+    for (const name of pathParamNames) {
+        const param = executionParams.find((candidate) => candidate.in === 'path' && candidate.name === name);
+        if (typeof path[name] !== 'undefined') {
+            path[name] = coerceParameterValue(path[name], param?.schema);
+            continue;
+        }
+        if (typeof rawArgs[name] !== 'undefined') {
+            path[name] = coerceParameterValue(rawArgs[name], param?.schema);
+        }
+    }
+    for (const param of executionParams) {
+        if (param.in !== 'query' && param.in !== 'header')
+            continue;
+        if (typeof query[param.name] !== 'undefined') {
+            query[param.name] = coerceParameterValue(query[param.name], param.schema);
+            continue;
+        }
+        if (typeof rawArgs[param.name] !== 'undefined') {
+            query[param.name] = coerceParameterValue(rawArgs[param.name], param.schema);
+        }
+    }
+    defaultExpandFromInclude(query, executionParams);
+    const bodySource = typeof rawArgs.body !== 'undefined' ? rawArgs.body : rawArgs.requestBody;
+    const body = coerceJsonLike(bodySource);
+    const confirmation = coerceJsonLike(rawArgs.confirmation);
+    return {
+        action: String(rawArgs.action),
+        path,
+        query,
+        body,
+        confirmation,
+    };
+}
+function hasActivationConfirmation(confirmation) {
+    if (!isNonArrayObject(confirmation))
+        return false;
+    return confirmation.user_confirmed === true;
+}
+function normalizeBodyForAction(namespace, action, body) {
+    if (namespace === 'experiences' && action === 'upload_variation_screenshot' && typeof body === 'string') {
+        return { image: body };
+    }
+    if (!isNonArrayObject(body))
+        return body;
+    if (namespace === 'audiences')
+        return normalizeAudienceBody(body);
+    if (namespace === 'goals')
+        return normalizeGoalBody(body);
+    if (namespace !== 'experiences')
+        return body;
+    return normalizeExperienceBody(action, body);
+}
+function normalizeExperienceBody(action, body) {
+    const normalized = { ...body };
+    if ((action === 'create' || action === 'update') && Array.isArray(normalized.settings)) {
+        const [onlySettings] = normalized.settings;
+        if (normalized.settings.length === 1 && isNonArrayObject(onlySettings)) {
+            normalized.settings = { ...onlySettings };
+        }
+    }
+    if ((action === 'create' || action === 'update') && Array.isArray(normalized.variations)) {
+        normalized.variations = normalizeVariationList(normalized.variations);
+    }
+    else if (action === 'update_variation') {
+        return normalizeVariationTrafficAlias(normalized);
+    }
+    if (action !== 'create')
+        return normalized;
+    const statusRaw = body.status;
+    const isMissing = statusRaw === undefined || statusRaw === null;
+    const isEmpty = typeof statusRaw === 'string' && statusRaw.trim() === '';
+    if (isMissing || isEmpty) {
+        normalized.status = 'draft';
+    }
+    return normalized;
+}
+function normalizeAudienceBody(body) {
+    const normalized = { ...body };
+    if (normalized.type === 'transient_condition') {
+        normalized.type = 'transient';
+    }
+    return normalized;
+}
+function normalizeGoalBody(body) {
+    const normalized = { ...body };
+    if (normalized.type === 'custom_js') {
+        normalized.type = 'code_trigger';
+    }
+    else if (normalized.type === 'scrolls_to') {
+        normalized.type = 'scroll_percentage';
+    }
+    return normalized;
+}
+function defaultExpandFromInclude(query, executionParams) {
+    if (typeof query.include === 'undefined' || typeof query.expand !== 'undefined')
+        return;
+    const expandParam = executionParams.find((param) => param.in === 'query' && param.name === 'expand');
+    if (!expandParam || !Array.isArray(query.include))
+        return;
+    const includeValues = query.include.filter((value) => typeof value === 'string');
+    const allowedExpandValues = expandParam.schema?.items?.enum;
+    const expandableValues = Array.isArray(allowedExpandValues) && allowedExpandValues.length > 0
+        ? includeValues.filter((value) => allowedExpandValues.includes(value))
+        : includeValues;
+    if (expandableValues.length > 0) {
+        query.expand = expandableValues;
+    }
+}
+function normalizeVariationList(value) {
+    if (!Array.isArray(value))
+        return value;
+    return value.map((variation) => {
+        return isNonArrayObject(variation) ? normalizeVariationTrafficAlias(variation) : variation;
+    });
+}
+function normalizeVariationTrafficAlias(variation) {
+    if (!Object.prototype.hasOwnProperty.call(variation, 'traffic_percentage')) {
+        return variation;
+    }
+    const normalized = { ...variation };
+    if (!Object.prototype.hasOwnProperty.call(normalized, 'traffic_distribution')) {
+        normalized.traffic_distribution = normalized.traffic_percentage;
+    }
+    delete normalized.traffic_percentage;
+    return normalized;
+}
+function evaluateGuardrails(namespace, action, body, confirmation, path) {
+    if (namespace === 'goals') {
+        return evaluateGoalGuardrails(action, body);
+    }
+    if (namespace !== 'experiences')
+        return null;
+    if (action === 'update_variation') {
+        if (!isNonArrayObject(body) || Object.keys(body).length === 0) {
+            return {
+                code: 'BodyRequired',
+                message: 'experiences.update_variation requires a non-empty "body" object (for example {"changes":[...]} or {"status":"running"}).',
+            };
+        }
+        if (hasExperienceLevelSettings(body)) {
+            const suggestedCall = buildExperienceSettingsUpdateCall(path, body);
+            return {
+                code: 'WrongActionForExperienceSettings',
+                message: `Experience-level settings such as split_url_settings cannot be applied with experiences.update_variation. Retry with experiences.update and omit variation_id:\n${JSON.stringify(suggestedCall, null, 2)}`,
+                suggested_call: suggestedCall,
+            };
+        }
+    }
+    if ((action === 'create' || action === 'update') && isNonArrayObject(body)) {
+        if (Object.prototype.hasOwnProperty.call(body, 'site_area')) {
+            const suggestedCall = buildLocationCreateCallFromSiteArea(path, body);
+            return {
+                code: 'UnsupportedInlineSiteArea',
+                message: [
+                    'body.site_area is rejected by Convert MCP because the Convert API can return success while persisting site_area:null.',
+                    'Create or reuse a Location, then pass its ID in body.locations instead. This prevents silent targeting failures.',
+                    `Suggested locations.create call:\n${JSON.stringify(suggestedCall, null, 2)}`,
+                ].join('\n'),
+                suggested_call: suggestedCall,
+            };
+        }
+        const statusRaw = body.status;
+        const status = typeof statusRaw === 'string' ? statusRaw.trim().toLowerCase() : null;
+        if (status === 'active' && !hasActivationConfirmation(confirmation)) {
+            return {
+                code: 'ActivationConfirmationRequired',
+                message: 'Setting experience status to "active" requires explicit user confirmation. Ask the user to confirm first, then retry with confirmation: { "user_confirmed": true, "reason": "..." }.',
+            };
+        }
+    }
+    return null;
+}
+function evaluateGoalGuardrails(action, body) {
+    if ((action !== 'create' && action !== 'update') || !isNonArrayObject(body))
+        return null;
+    if (body.type !== 'clicks_link' || !isNonArrayObject(body.settings))
+        return null;
+    const href = body.settings.href;
+    if (typeof href === 'undefined' || href === null || typeof href === 'string')
+        return null;
+    return {
+        code: 'ClicksLinkHrefMustBeString',
+        message: [
+            'goals.create/update for type "clicks_link" requires body.settings.href to be a string.',
+            'Convert API rejects match objects for settings.href. Use a string href, add URL scoping in triggering_rule, or create separate link goals for separate href patterns.',
+        ].join('\n'),
+    };
+}
+function hasExperienceLevelSettings(body) {
+    if (Object.prototype.hasOwnProperty.call(body, 'settings'))
+        return true;
+    if (Object.prototype.hasOwnProperty.call(body, 'split_url_settings'))
+        return true;
+    return false;
+}
+function buildExperienceSettingsUpdateCall(path, body) {
+    const settings = normalizeSettingsForSuggestion(body);
+    return {
+        action: 'update',
+        path: {
+            account_id: path.account_id ?? '<account_id>',
+            project_id: path.project_id ?? '<project_id>',
+            experience_id: path.experience_id ?? '<experience_id>',
+        },
+        body: { settings },
+    };
+}
+function normalizeSettingsForSuggestion(body) {
+    const rawSettings = body.settings ?? (Object.prototype.hasOwnProperty.call(body, 'split_url_settings')
+        ? { split_url_settings: body.split_url_settings }
+        : {});
+    if (Array.isArray(rawSettings) && rawSettings.length === 1 && isNonArrayObject(rawSettings[0])) {
+        return rawSettings[0];
+    }
+    return rawSettings;
+}
+function buildLocationCreateCallFromSiteArea(path, body) {
+    const siteArea = isNonArrayObject(body.site_area) ? body.site_area : {};
+    const include = Array.isArray(siteArea.include) ? siteArea.include : [];
+    const rules = include.length > 0
+        ? { OR: [{ AND: [{ OR_WHEN: include }] }] }
+        : { OR: [{ AND: [{ OR_WHEN: [] }] }] };
+    const baseName = typeof body.name === 'string' && body.name.trim() ? body.name.trim() : 'Experience';
+    return {
+        namespace: 'locations',
+        action: 'create',
+        path: {
+            account_id: path.account_id ?? '<account_id>',
+            project_id: path.project_id ?? '<project_id>',
+        },
+        body: {
+            name: `${baseName} Location`,
+            rules,
+            trigger: { type: 'upon_run' },
+        },
+        retry_experience_with: {
+            locations: ['<created_location_id>'],
+        },
+    };
+}
+/**
+ * Walk a JSON Schema tree and extract all enum fields with their paths
+ * and required fields. Handles allOf/oneOf/anyOf composition.
+ * Used to surface schema constraints that LLMs can't parse from raw JSON Schema.
+ */
+function extractBodyHints(inputSchema) {
+    const rbSchema = inputSchema?.properties?.requestBody;
+    if (!rbSchema)
+        return null;
+    const visited = new WeakSet();
+    const enumMap = new Map();
+    const requiredAtLevel = new Map();
+    function walk(schema, path) {
+        if (!schema || typeof schema !== 'object')
+            return;
+        if (visited.has(schema))
+            return;
+        visited.add(schema);
+        // Collect enum values
+        if (Array.isArray(schema.enum)) {
+            const vals = schema.enum.filter((v) => typeof v === 'string' || typeof v === 'number');
+            if (vals.length > 0 && path) {
+                const existing = enumMap.get(path) || new Set();
+                vals.forEach((v) => existing.add(String(v)));
+                enumMap.set(path, existing);
+            }
+        }
+        // Collect required fields
+        if (Array.isArray(schema.required) && schema.required.length > 0) {
+            const level = path || '(root)';
+            const existing = requiredAtLevel.get(level) || new Set();
+            schema.required.forEach((r) => existing.add(r));
+            requiredAtLevel.set(level, existing);
+        }
+        // Walk properties
+        if (schema.properties && typeof schema.properties === 'object') {
+            for (const [key, value] of Object.entries(schema.properties)) {
+                const prop = value;
+                if (prop.readOnly)
+                    continue; // skip auto-generated IDs
+                walk(prop, path ? `${path}.${key}` : key);
+            }
+        }
+        // Walk array items
+        if (schema.items) {
+            walk(schema.items, `${path}[]`);
+        }
+        // Walk composition keywords
+        for (const kw of ['allOf', 'oneOf', 'anyOf']) {
+            if (Array.isArray(schema[kw])) {
+                for (const sub of schema[kw]) {
+                    walk(sub, path);
+                }
+            }
+        }
+    }
+    walk(rbSchema, '');
+    const lines = [];
+    // Show enum fields with valid values (sorted by path depth, shallow first)
+    const enumEntries = [...enumMap.entries()]
+        .sort((a, b) => a[0].split('.').length - b[0].split('.').length);
+    for (const [field, values] of enumEntries) {
+        const valArr = [...values];
+        if (valArr.length > 12) {
+            lines.push(`  ${field}: ${valArr.slice(0, 10).map(v => `"${v}"`).join(', ')}, ... (${valArr.length} values)`);
+        }
+        else {
+            lines.push(`  ${field}: ${valArr.map(v => `"${v}"`).join(', ')}`);
+        }
+    }
+    // Show required fields per level
+    for (const [level, fields] of requiredAtLevel) {
+        const fieldArr = [...fields].filter(f => f !== 'id'); // skip auto-assigned ids
+        if (fieldArr.length === 0)
+            continue;
+        if (level === '(root)') {
+            lines.push(`  Required: ${fieldArr.join(', ')}`);
+        }
+        else {
+            lines.push(`  Required in ${level}: ${fieldArr.join(', ')}`);
+        }
+    }
+    return lines.length > 0 ? lines.join('\n') : null;
+}
+function actionsForToolset(namespace, toolSet) {
+    const all = Object.entries(REGISTRY[namespace] || {});
+    if (toolSet === 'all')
+        return all.map(([a]) => a);
+    // reporting/readOnly: include only underlying tools that start with 'get'
+    return all.filter(([, tool]) => tool.startsWith('get')).map(([a]) => a);
+}
+/**
+ * Compute MCP tool annotations from the filtered action set.
+ * Annotations reflect the worst-case capability of the exposed actions:
+ * - readOnlyHint: true only when ALL actions are reads
+ * - destructiveHint: true when ANY action is a delete
+ * - idempotentHint: true only when ALL actions are reads (GETs are idempotent)
+ * - openWorldHint: false — all tools affect bounded Convert API resources
+ */
+function annotationsForNamespace(ns, actions) {
+    const hasWriteAction = actions.some((a) => {
+        const toolName = REGISTRY[ns]?.[a];
+        return toolName && !toolName.startsWith('get');
+    });
+    const hasDeleteAction = actions.includes('delete');
+    return {
+        title: NAMESPACE_TITLES[ns] ?? ns,
+        readOnlyHint: !hasWriteAction,
+        destructiveHint: hasWriteAction && hasDeleteAction,
+        idempotentHint: !hasWriteAction,
+        openWorldHint: false,
+    };
+}
+export function getNamespacedTools(toolSet) {
+    return Object.keys(REGISTRY).map((ns) => {
+        const actions = actionsForToolset(ns, toolSet);
+        // Build rich namespace description from curated map or fallback
+        const nsDesc = NAMESPACE_DESCRIPTIONS[ns] || `Manage ${ns} in the user's Convert.com account via the live API.`;
+        const description = `${nsDesc} Available actions: ${actions.join(', ')}.`;
+        // Build structured metadata for each action, merging ACTION_NOTES
+        const actionMetadata = actions.map((action) => {
+            const toolName = REGISTRY[ns][action];
+            const def = toolDefinitionMap.get(toolName);
+            if (!def)
+                return { action, description: 'No metadata available' };
+            const pathParams = requiredPathParamsForDef(def);
+            const queryParams = (def.executionParameters || [])
+                .filter((p) => p.in === 'query')
+                .map((p) => p.name);
+            const hasBody = !!def.requestBodyContentType;
+            const baseDesc = def.description || 'No description';
+            const note = ACTION_NOTES[`${ns}.${action}`];
+            const bodyHints = hasBody ? extractBodyHints(def.inputSchema) : null;
+            const parts = [baseDesc];
+            if (note)
+                parts.push(`Agent Notes:\n${note}`);
+            if (bodyHints)
+                parts.push(`Body schema:\n${bodyHints}`);
+            const fullDesc = parts.join('\n\n');
+            return {
+                action,
+                description: fullDesc,
+                method: def.method.toUpperCase(),
+                path_parameters: pathParams,
+                query_parameters: queryParams,
+                accepts_body: hasBody,
+            };
+        });
+        // Hint in action description when notes are available
+        const actionsWithNotes = actions.filter(a => ACTION_NOTES[`${ns}.${a}`]);
+        const actionDesc = actionsWithNotes.length
+            ? 'Action to perform. See _meta.available_actions for detailed per-action guidance.'
+            : 'Action to perform';
+        return {
+            name: ns,
+            title: NAMESPACE_TITLES[ns] ?? ns,
+            description,
+            inputSchema: {
+                $schema: JSON_SCHEMA_DRAFT_2020_12,
+                type: 'object',
+                properties: {
+                    action: { type: 'string', enum: actions, description: actionDesc },
+                    path: { type: 'object', additionalProperties: true, description: 'Canonical wrapper for path params such as account_id, project_id, experience_id. For compatibility, known path params may also be supplied at the top level.' },
+                    query: { type: 'object', additionalProperties: true, description: 'Canonical wrapper for query and optional header-style params (for example report_token). Known query/header params may also be supplied at the top level. Array parameters (like include, expand) must always be arrays, even for single values. IMPORTANT: When using "include" to fetch related resources, also use supported "expand" values to get complete object data instead of just numeric IDs. Some fields are includable but not expandable; namespace tools auto-fill valid expand values when possible. Example: {"include": ["goals"], "expand": ["goals"]}.' },
+                    body: { type: 'object', additionalProperties: true, description: 'Canonical request body wrapper for create/update/clone actions. The namespace tool also accepts a top-level requestBody alias for compatibility.' },
+                    confirmation: { type: 'object', additionalProperties: true, description: 'Optional explicit user confirmation metadata for sensitive actions. Example: {"user_confirmed": true, "reason": "User approved activation"}' },
+                },
+                required: ['action'],
+                _meta: {
+                    namespace: ns,
+                    available_actions: actionMetadata,
+                },
+            },
+            outputSchema: {
+                $schema: JSON_SCHEMA_DRAFT_2020_12,
+                type: 'object',
+                description: 'Standardized namespace tool result envelope.',
+                properties: {
+                    ok: { type: 'boolean', description: 'True on success, false on tool-level error.' },
+                    namespace: { type: 'string', description: 'Namespace that handled the request.' },
+                    action: { type: 'string', description: 'Namespace action requested by the model.' },
+                    delegate: { type: 'string', description: 'Underlying generated tool ID executed for this action.' },
+                    status: { type: 'number', description: 'HTTP status code from the Convert API (when available).' },
+                    data: { description: 'Raw API response payload for successful requests.' },
+                    error: { description: 'Error code/object for failed requests.' },
+                    issues: { type: 'array', items: { type: 'object' }, description: 'Validation issues, if present.' },
+                },
+                additionalProperties: true,
+            },
+            annotations: annotationsForNamespace(ns, actions),
+        };
+    });
+}
+function withNamespaceEnvelope(result, namespace, action, delegate) {
+    const base = (result.structuredContent && typeof result.structuredContent === 'object')
+        ? result.structuredContent
+        : {};
+    const envelope = {
+        ok: !result.isError,
+        namespace,
+        ...base,
+    };
+    if (action)
+        envelope.action = action;
+    if (delegate)
+        envelope.delegate = delegate;
+    if (result.isError && typeof envelope.error === 'undefined') {
+        const fallbackText = result.content?.[0]?.type === 'text' ? result.content[0].text : 'Unknown error';
+        envelope.error = fallbackText;
+    }
+    return {
+        ...result,
+        structuredContent: envelope,
+    };
+}
+export async function executeNamespacedTool(namespace, args) {
+    if (!REGISTRY[namespace]) {
+        const error = { error: 'UnknownNamespace', namespace, available_namespaces: Object.keys(REGISTRY) };
+        return withNamespaceEnvelope({
+            content: [{ type: 'text', text: `Unknown namespace: ${namespace}` }],
+            structuredContent: error,
+            isError: true,
+        }, namespace);
+    }
+    const parsedArgs = asObject(coerceJsonLike(args));
+    if (!parsedArgs) {
+        const error = { error: 'InvalidArguments', message: 'Expected object with fields: action, path, query, body/requestBody, confirmation' };
+        return withNamespaceEnvelope({
+            content: [{ type: 'text', text: `Invalid arguments. Expected object with fields: action, path, query, body/requestBody, confirmation.` }],
+            structuredContent: error,
+            isError: true,
+        }, namespace);
+    }
+    const action = parsedArgs.action;
+    if (!action || typeof action !== 'string') {
+        const error = { error: 'MissingAction', message: 'The action field is required and must be a string' };
+        return withNamespaceEnvelope({
+            content: [{ type: 'text', text: `Missing or invalid 'action'.` }],
+            structuredContent: error,
+            isError: true,
+        }, namespace);
+    }
+    const delegate = REGISTRY[namespace][action];
+    if (!delegate) {
+        const available = Object.keys(REGISTRY[namespace]);
+        const error = { error: 'UnknownAction', namespace, action, available_actions: available };
+        return withNamespaceEnvelope({
+            content: [{ type: 'text', text: `Unknown action '${action}' for namespace '${namespace}'. Available: ${available.join(', ')}` }],
+            structuredContent: error,
+            isError: true,
+        }, namespace, action);
+    }
+    const def = toolDefinitionMap.get(delegate);
+    if (!def) {
+        const error = { error: 'InternalError', message: 'Delegate tool not found', delegate };
+        return withNamespaceEnvelope({
+            content: [{ type: 'text', text: `Internal error: delegate tool not found: ${delegate}` }],
+            structuredContent: error,
+            isError: true,
+        }, namespace, action, delegate);
+    }
+    const { path, query, body, confirmation } = normalizeNamespaceArgs(parsedArgs, def);
+    // Validate required path params early for better error messages
+    const requiredPathParams = requiredPathParamsForDef(def);
+    const missing = requiredPathParams.filter((k) => !(k in path));
+    if (missing.length) {
+        const note = ACTION_NOTES[`${namespace}.${action}`];
+        const hint = note ? `\n\nHint for ${namespace}.${action}:\n${note}` : '';
+        const error = { error: 'MissingPathParameters', namespace, action, missing_parameters: missing };
+        return withNamespaceEnvelope({
+            content: [{ type: 'text', text: `Missing required path parameters: ${missing.map(k => `path.${k}`).join(', ')}${hint}` }],
+            structuredContent: error,
+            isError: true,
+        }, namespace, action, delegate);
+    }
+    const normalizedBody = normalizeBodyForAction(namespace, action, body);
+    const guardrail = evaluateGuardrails(namespace, action, normalizedBody, confirmation, path);
+    if (guardrail) {
+        return withNamespaceEnvelope({
+            content: [{ type: 'text', text: guardrail.message }],
+            structuredContent: {
+                error: guardrail.code,
+                namespace,
+                action,
+                message: guardrail.message,
+                ...(guardrail.suggested_call ? { suggested_call: guardrail.suggested_call } : {}),
+            },
+            isError: true,
+        }, namespace, action, delegate);
+    }
+    const flattenedArgs = { ...path, ...query };
+    if (def.requestBodyContentType && typeof normalizedBody !== 'undefined') {
+        flattenedArgs.requestBody = normalizedBody;
+    }
+    const result = await executeToolByName(delegate, flattenedArgs);
+    // Append action-specific guidance to error messages so agents can self-correct
+    if (result.isError) {
+        const note = ACTION_NOTES[`${namespace}.${action}`];
+        if (note && result.content?.[0]?.type === 'text') {
+            result.content[0].text += `\n\nHint for ${namespace}.${action}:\n${note}`;
+        }
+    }
+    return withNamespaceEnvelope(result, namespace, action, delegate);
+}
+export function isNamespace(name) {
+    return Object.prototype.hasOwnProperty.call(REGISTRY, name);
+}
+//# sourceMappingURL=namespaced.js.map