@affset/mcp 0.1.0 → 0.2.0

package/dist/registerTools.js

@@ -0,0 +1,401 @@
+import { normalizeRuntimeConfig } from "./runtimeConfig.js";
+import { AffsetClient } from "./client.js";
+import { DOCS_FEEDS, fetchDocsFeed } from "./docs.js";
+import { getStats, getStatsInputSchema, GET_STATS_DESCRIPTION } from "./tools/getStats.js";
+import { cutZones, cutZonesInputSchema, CUT_ZONES_DESCRIPTION } from "./tools/cutZones.js";
+import { createCampaign, createCampaignInputSchema, CREATE_CAMPAIGN_DESCRIPTION, } from "./tools/createCampaign.js";
+import { listCampaigns, listCampaignsInputSchema, LIST_CAMPAIGNS_DESCRIPTION, } from "./tools/listCampaigns.js";
+import { getCampaign, getCampaignInputSchema, GET_CAMPAIGN_DESCRIPTION, } from "./tools/getCampaign.js";
+import { listZones, listZonesInputSchema, LIST_ZONES_DESCRIPTION } from "./tools/listZones.js";
+import { listTeam, listTeamInputSchema, LIST_TEAM_DESCRIPTION } from "./tools/listTeam.js";
+import { createTeamMember, createTeamMemberInputSchema, CREATE_TEAM_MEMBER_DESCRIPTION, } from "./tools/createTeamMember.js";
+import { createZone, createZoneInputSchema, CREATE_ZONE_DESCRIPTION } from "./tools/createZone.js";
+import { getZoneUrl, getZoneUrlInputSchema, GET_ZONE_URL_DESCRIPTION } from "./tools/getZoneUrl.js";
+import { getTrackingLink, getTrackingLinkInputSchema, GET_TRACKING_LINK_DESCRIPTION, } from "./tools/getTrackingLink.js";
+import { updateZone, updateZoneInputSchema, UPDATE_ZONE_DESCRIPTION } from "./tools/updateZone.js";
+import { updateCampaign, updateCampaignInputSchema, UPDATE_CAMPAIGN_DESCRIPTION, } from "./tools/updateCampaign.js";
+import { setCampaignStatus, setCampaignStatusInputSchema, SET_CAMPAIGN_STATUS_DESCRIPTION, } from "./tools/setCampaignStatus.js";
+import { listPayoutRules, listPayoutRulesInputSchema, LIST_PAYOUT_RULES_DESCRIPTION, } from "./tools/listPayoutRules.js";
+import { setPayoutRule, setPayoutRuleInputSchema, SET_PAYOUT_RULE_DESCRIPTION, } from "./tools/setPayoutRule.js";
+import { deletePayoutRule, deletePayoutRuleInputSchema, DELETE_PAYOUT_RULE_DESCRIPTION, } from "./tools/deletePayoutRule.js";
+import { setPayoutGoal, setPayoutGoalInputSchema, SET_PAYOUT_GOAL_DESCRIPTION, } from "./tools/setPayoutGoal.js";
+import { listTargetingTypes, listTargetingTypesInputSchema, LIST_TARGETING_TYPES_DESCRIPTION, } from "./tools/listTargetingTypes.js";
+import { listTargetingRules, listTargetingRulesInputSchema, LIST_TARGETING_RULES_DESCRIPTION, } from "./tools/listTargetingRules.js";
+import { setTargetingRule, setTargetingRuleInputSchema, SET_TARGETING_RULE_DESCRIPTION, } from "./tools/setTargetingRule.js";
+import { removeTargetingRule, removeTargetingRuleInputSchema, REMOVE_TARGETING_RULE_DESCRIPTION, } from "./tools/removeTargetingRule.js";
+import { listSubLabels, listSubLabelsInputSchema, LIST_SUB_LABELS_DESCRIPTION, } from "./tools/listSubLabels.js";
+import { setSubLabels, setSubLabelsInputSchema, SET_SUB_LABELS_DESCRIPTION, } from "./tools/setSubLabels.js";
+import { listConversions, listConversionsInputSchema, LIST_CONVERSIONS_DESCRIPTION, } from "./tools/listConversions.js";
+import { whoami, whoamiInputSchema, WHOAMI_DESCRIPTION } from "./tools/whoami.js";
+function resultIsError(result) {
+    return (typeof result === "object" && result !== null && "isError" in result && result.isError === true);
+}
+function instrumentToolCallback(name, callback, onToolCall) {
+    const instrumented = async (...args) => {
+        const startedAt = Date.now();
+        let status = "ok";
+        try {
+            const result = await callback(...args);
+            if (resultIsError(result))
+                status = "error";
+            return result;
+        }
+        catch (error) {
+            status = "error";
+            throw error;
+        }
+        finally {
+            try {
+                await onToolCall({
+                    toolName: name,
+                    durationMs: Math.max(0, Date.now() - startedAt),
+                    status,
+                });
+            }
+            catch {
+                // Audit/telemetry must never alter the MCP tool's result.
+            }
+        }
+    };
+    return instrumented;
+}
+/**
+ * Register the full affset tool roster and docs resources against `config`.
+ * The single source of truth for the roster: the stdio entrypoint
+ * (`createServer`) and the remote gateway's `McpAgent` both call exactly this,
+ * so the two transports cannot drift (REMOTE-MCP-PRD.md §5.6).
+ *
+ * When `config.readOnly` is set, every tool that is not `readOnlyHint: true`
+ * is skipped — identical semantics to AFFSET_READ_ONLY on stdio and to a
+ * `read`-scoped OAuth grant on the gateway.
+ */
+export function registerAffsetTools(toolServer, config, options = {}) {
+    const runtimeConfig = normalizeRuntimeConfig(config);
+    const client = new AffsetClient(runtimeConfig);
+    // One cast at the boundary; everything below is the SDK's real surface.
+    const server = toolServer;
+    // Skip mutating tools entirely when read-only is set — they never appear in
+    // tools/list and cannot be called. Skipping is fail-closed: we do not depend
+    // on the SDK's remove() to unlist a tool that was already registered. See
+    // AFFSET_READ_ONLY in the README for why this exists (untrusted third-party
+    // data can reach model context via list_conversions/get_stats, so mutation
+    // tools are an injection blast-radius control, not just a UI nicety).
+    const registerTool = (name, toolConfig, cb) => {
+        if (runtimeConfig.readOnly && toolConfig.annotations?.readOnlyHint !== true) {
+            return {
+                enabled: false,
+                enable() { },
+                disable() { },
+                remove() { },
+            };
+        }
+        const callback = options.onToolCall ? instrumentToolCallback(name, cb, options.onToolCall) : cb;
+        return server.registerTool(name, toolConfig, callback);
+    };
+    registerTool("whoami", {
+        title: "Show the tenant this MCP is bound to",
+        description: WHOAMI_DESCRIPTION,
+        inputSchema: whoamiInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, () => whoami(client, runtimeConfig));
+    registerTool("get_stats", {
+        title: "Get affset stats",
+        description: GET_STATS_DESCRIPTION,
+        inputSchema: getStatsInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => getStats(client, args));
+    registerTool("list_campaigns", {
+        title: "List campaigns",
+        description: LIST_CAMPAIGNS_DESCRIPTION,
+        inputSchema: listCampaignsInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => listCampaigns(client, args));
+    registerTool("get_campaign", {
+        title: "Get a campaign's full record",
+        description: GET_CAMPAIGN_DESCRIPTION,
+        inputSchema: getCampaignInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => getCampaign(client, args));
+    registerTool("list_zones", {
+        title: "List zones",
+        description: LIST_ZONES_DESCRIPTION,
+        inputSchema: listZonesInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => listZones(client, args));
+    registerTool("list_team", {
+        title: "List team members",
+        description: LIST_TEAM_DESCRIPTION,
+        inputSchema: listTeamInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => listTeam(client, args));
+    registerTool("create_team_member", {
+        title: "Invite a team member",
+        description: CREATE_TEAM_MEMBER_DESCRIPTION,
+        inputSchema: createTeamMemberInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => createTeamMember(client, args));
+    registerTool("get_zone_url", {
+        title: "Get the zone URL for a traffic source",
+        description: GET_ZONE_URL_DESCRIPTION,
+        inputSchema: getZoneUrlInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => getZoneUrl(client, runtimeConfig, args));
+    registerTool("get_tracking_link", {
+        title: "Get a campaign's tracking link",
+        description: GET_TRACKING_LINK_DESCRIPTION,
+        inputSchema: getTrackingLinkInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => getTrackingLink(client, runtimeConfig, args));
+    registerTool("create_campaign", {
+        title: "Create a campaign",
+        description: CREATE_CAMPAIGN_DESCRIPTION,
+        inputSchema: createCampaignInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => createCampaign(client, runtimeConfig, args));
+    registerTool("update_campaign", {
+        title: "Update a campaign",
+        description: UPDATE_CAMPAIGN_DESCRIPTION,
+        inputSchema: updateCampaignInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => updateCampaign(client, args));
+    registerTool("set_campaign_status", {
+        title: "Run or pause a campaign",
+        description: SET_CAMPAIGN_STATUS_DESCRIPTION,
+        inputSchema: setCampaignStatusInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => setCampaignStatus(client, args));
+    registerTool("create_zone", {
+        title: "Create a zone",
+        description: CREATE_ZONE_DESCRIPTION,
+        inputSchema: createZoneInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => createZone(client, args));
+    registerTool("update_zone", {
+        title: "Update a zone",
+        description: UPDATE_ZONE_DESCRIPTION,
+        inputSchema: updateZoneInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => updateZone(client, args));
+    registerTool("cut_zones", {
+        title: "Cut underperforming zones",
+        description: CUT_ZONES_DESCRIPTION,
+        inputSchema: cutZonesInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => cutZones(client, args));
+    registerTool("list_payout_rules", {
+        title: "List payout rules",
+        description: LIST_PAYOUT_RULES_DESCRIPTION,
+        inputSchema: listPayoutRulesInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => listPayoutRules(client, args));
+    registerTool("set_payout_rule", {
+        title: "Set a payout rule",
+        description: SET_PAYOUT_RULE_DESCRIPTION,
+        inputSchema: setPayoutRuleInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => setPayoutRule(client, args));
+    registerTool("delete_payout_rule", {
+        title: "Delete a payout rule",
+        description: DELETE_PAYOUT_RULE_DESCRIPTION,
+        inputSchema: deletePayoutRuleInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => deletePayoutRule(client, args));
+    registerTool("set_payout_goal", {
+        title: "Set payout goal type",
+        description: SET_PAYOUT_GOAL_DESCRIPTION,
+        inputSchema: setPayoutGoalInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => setPayoutGoal(client, args));
+    registerTool("list_targeting_types", {
+        title: "List targeting rule types",
+        description: LIST_TARGETING_TYPES_DESCRIPTION,
+        inputSchema: listTargetingTypesInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, () => listTargetingTypes(client));
+    registerTool("list_targeting_rules", {
+        title: "List campaign targeting rules",
+        description: LIST_TARGETING_RULES_DESCRIPTION,
+        inputSchema: listTargetingRulesInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => listTargetingRules(client, args));
+    registerTool("set_targeting_rule", {
+        title: "Set a targeting rule",
+        description: SET_TARGETING_RULE_DESCRIPTION,
+        inputSchema: setTargetingRuleInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => setTargetingRule(client, args));
+    registerTool("remove_targeting_rule", {
+        title: "Remove a targeting rule",
+        description: REMOVE_TARGETING_RULE_DESCRIPTION,
+        inputSchema: removeTargetingRuleInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => removeTargetingRule(client, args));
+    registerTool("list_sub_labels", {
+        title: "List sub labels",
+        description: LIST_SUB_LABELS_DESCRIPTION,
+        inputSchema: listSubLabelsInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, () => listSubLabels(client));
+    registerTool("set_sub_labels", {
+        title: "Set sub labels",
+        description: SET_SUB_LABELS_DESCRIPTION,
+        inputSchema: setSubLabelsInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => setSubLabels(client, args));
+    registerTool("list_conversions", {
+        title: "List conversions",
+        description: LIST_CONVERSIONS_DESCRIPTION,
+        inputSchema: listConversionsInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => listConversions(client, args));
+    // Documentation resources. The affset API reference (the same content as the
+    // /docs page) is exposed so an assistant can answer "how does X work / how do
+    // I call Y" from the docs themselves, not just from the tool schemas above.
+    // Fetched from config.docsBaseUrl at read time, so it always reflects the
+    // currently published docs. Always registered — read-only by nature, so
+    // AFFSET_READ_ONLY doesn't gate them.
+    const registerDocsResource = (name, uri, description, feed) => {
+        server.registerResource(name, uri, { title: name, description, mimeType: feed.mimeType }, async (resourceUri) => ({
+            contents: [
+                {
+                    uri: resourceUri.href,
+                    mimeType: feed.mimeType,
+                    text: await fetchDocsFeed(runtimeConfig, feed),
+                },
+            ],
+        }));
+    };
+    registerDocsResource("affset-api-reference", "affset://docs/api-reference", "The affset HTTP API reference (endpoints, auth, roles, examples) as Markdown — the same content as the /docs page.", DOCS_FEEDS.markdown);
+    registerDocsResource("affset-api-reference-json", "affset://docs/api-reference.json", "The affset HTTP API reference as structured JSON, for programmatic use.", DOCS_FEEDS.json);
+}
+//# sourceMappingURL=registerTools.js.map

package/dist/runtimeConfig.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Runtime configuration shared by the stdio entrypoint and library consumers.
+ *
+ * Keep this module free of Node-specific globals and types: it is part of the
+ * public `@affset/mcp/core` declaration graph and is consumed by Workers.
+ */
+export interface Config {
+    /** Base URL of the affset API. Normalized to a bare origin. */
+    baseUrl: string;
+    /** Public origin that serves the documentation feeds. */
+    docsBaseUrl: string;
+    /** Tenant API key sent as `Authorization: Bearer <key>`. */
+    apiKey: string;
+    /** Tenant namespace sent as `X-Namespace`. */
+    namespace: string;
+    /** Per-request timeout in milliseconds. */
+    requestTimeoutMs: number;
+    /** When true, only tools annotated as read-only are registered. */
+    readOnly: boolean;
+}
+export declare const MIN_REQUEST_TIMEOUT_MS = 1000;
+export declare const MAX_REQUEST_TIMEOUT_MS = 300000;
+/** Parse and normalize an HTTP(S) origin, refusing cleartext remote hosts. */
+export declare function parseOriginUrl(raw: string, name: string, carriesApiKey?: boolean): URL;
+/** Validate a namespace using the same rules as tenant signup. */
+export declare function validateNamespace(namespace: string, name: string): void;
+/** Reject empty keys and CR/LF so a value cannot split HTTP headers. */
+export declare function validateApiKey(value: unknown, name: string): string;
+/**
+ * Validate and normalize config supplied through the public library API.
+ *
+ * TypeScript types are not a runtime security boundary. Hosted transports can
+ * source these values from deployment config or grant records, so fail before
+ * registering tools if a malformed value could leak a bearer key or silently
+ * disable the read-only boundary.
+ */
+export declare function normalizeRuntimeConfig(config: Config): Config;

package/dist/runtimeConfig.js

@@ -0,0 +1,93 @@
+export const MIN_REQUEST_TIMEOUT_MS = 1_000;
+export const MAX_REQUEST_TIMEOUT_MS = 300_000;
+const NAMESPACE_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+function isLoopbackHost(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "::1" ||
+        hostname.endsWith(".localhost"));
+}
+/** Parse and normalize an HTTP(S) origin, refusing cleartext remote hosts. */
+export function parseOriginUrl(raw, name, carriesApiKey = false) {
+    const normalized = raw.replace(/\/+$/, "");
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        throw new Error(`${name} is not a valid URL: ${raw}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`${name} must be http(s), got ${parsed.protocol}`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error(`${name} must not contain embedded credentials.`);
+    }
+    if ((parsed.pathname !== "/" && parsed.pathname !== "") || parsed.search || parsed.hash) {
+        throw new Error(`${name} must be an origin only (scheme, host, and optional port; no path, query, or fragment).`);
+    }
+    if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
+        const cleartextHint = carriesApiKey ? " — plain http would send the API key in cleartext" : "";
+        throw new Error(`${name} must be https for a non-local host (got http://${parsed.hostname})${cleartextHint}.`);
+    }
+    return parsed;
+}
+/** Validate a namespace using the same rules as tenant signup. */
+export function validateNamespace(namespace, name) {
+    if (namespace.length < 3 || namespace.length > 63) {
+        throw new Error(`${name} must be 3–63 characters.`);
+    }
+    if (!NAMESPACE_RE.test(namespace) || namespace.includes("--")) {
+        throw new Error(`${name} must be lowercase letters, numbers, and hyphens only ` +
+            "(no leading/trailing or consecutive hyphens).");
+    }
+}
+function requiredString(value, name) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${name} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+/** Reject empty keys and CR/LF so a value cannot split HTTP headers. */
+export function validateApiKey(value, name) {
+    const apiKey = requiredString(value, name);
+    if (/\r|\n/.test(apiKey)) {
+        throw new Error(`${name} must not contain line breaks.`);
+    }
+    return apiKey;
+}
+/**
+ * Validate and normalize config supplied through the public library API.
+ *
+ * TypeScript types are not a runtime security boundary. Hosted transports can
+ * source these values from deployment config or grant records, so fail before
+ * registering tools if a malformed value could leak a bearer key or silently
+ * disable the read-only boundary.
+ */
+export function normalizeRuntimeConfig(config) {
+    if (config === null || typeof config !== "object") {
+        throw new Error("config must be an object.");
+    }
+    const baseUrl = parseOriginUrl(requiredString(config.baseUrl, "config.baseUrl"), "config.baseUrl", true).origin;
+    const docsBaseUrl = parseOriginUrl(requiredString(config.docsBaseUrl, "config.docsBaseUrl"), "config.docsBaseUrl").origin;
+    const apiKey = validateApiKey(config.apiKey, "config.apiKey");
+    const namespace = requiredString(config.namespace, "config.namespace");
+    validateNamespace(namespace, "config.namespace");
+    if (!Number.isSafeInteger(config.requestTimeoutMs) ||
+        config.requestTimeoutMs < MIN_REQUEST_TIMEOUT_MS ||
+        config.requestTimeoutMs > MAX_REQUEST_TIMEOUT_MS) {
+        throw new Error(`config.requestTimeoutMs must be an integer between ${MIN_REQUEST_TIMEOUT_MS} and ${MAX_REQUEST_TIMEOUT_MS}.`);
+    }
+    if (typeof config.readOnly !== "boolean") {
+        throw new Error("config.readOnly must be a boolean.");
+    }
+    return {
+        baseUrl,
+        docsBaseUrl,
+        apiKey,
+        namespace,
+        requestTimeoutMs: config.requestTimeoutMs,
+        readOnly: config.readOnly,
+    };
+}
+//# sourceMappingURL=runtimeConfig.js.map

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Config } from "./runtimeConfig.js";
+/** Build the MCP server with the affset tools registered against `config`. */
+export declare function createServer(config: Config): McpServer;