@affset/mcp 0.1.1 → 0.3.0

package/dist/lib/targeting.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Targeting helpers shared by the targeting tools.
+ *
+ * The serve path matches `targeting_rules.rule` with an exact, case-sensitive
+ * string compare against what Cloudflare and Bowser produce for the request
+ * (lite-adserver `campaignSelectionService`): `CF-IPCountry` is upper-case
+ * ISO-3166 alpha-2, OS/browser names are Bowser's own spellings, device type is
+ * one of three lower-case words. A rule an operator reads as obviously correct —
+ * `geo: br,mx`, `os: android` — therefore matches nothing, and a whitelist that
+ * matches nothing takes the campaign out of rotation without an error anywhere.
+ * Everything written through these tools is normalised to the serve path's
+ * spelling first, and anything unrecognised comes back as a warning rather than
+ * being silently stored.
+ */
+import type { AffsetClient } from "../client.js";
+import type { TargetingRule, TargetingRuleType } from "../types.js";
+export type TargetingMethod = "whitelist" | "blacklist";
+/**
+ * Seeded types the `/serve` path never evaluates. They accept writes through the
+ * API and then do nothing, so an hours rule reads as a working dayparting setup
+ * while the campaign keeps buying around the clock.
+ */
+export declare const UNENFORCED_TYPES: Record<string, string>;
+export declare function fetchTargetingTypes(client: AffsetClient): Promise<TargetingRuleType[]>;
+export declare function fetchTargetingRules(client: AffsetClient, campaignId: string): Promise<TargetingRule[]>;
+/**
+ * Write the campaign's full rule set. The endpoint is a sync, not an append:
+ * every rule the caller wants to keep must be echoed back with its id, or it is
+ * deleted. Callers build `rules` from a fresh read for exactly that reason.
+ */
+export declare function syncTargetingRules(client: AffsetClient, campaignId: string, rules: TargetingRule[]): Promise<TargetingRule[]>;
+/** Strip everything the sync endpoint does not accept back. */
+export declare function toSyncPayload(rules: TargetingRule[]): TargetingRule[];
+/** Resolve a caller-supplied type id or name against an already-fetched catalog. */
+export declare function resolveTargetingType(types: TargetingRuleType[], type: string | number): {
+    type: TargetingRuleType;
+} | {
+    error: string;
+};
+export type NormalizedRule = {
+    value: string;
+    notes: string[];
+};
+/**
+ * Normalise a rule value to the spelling the serve path compares against.
+ * Returns an error for values that provably cannot match, and notes for values
+ * that were rewritten or that could not be checked.
+ */
+export declare function normalizeRuleValue(typeName: string, rule: string): NormalizedRule | {
+    error: string;
+};

package/dist/lib/time.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Date-range resolution for stats queries.
+ *
+ * Every boundary here is computed in the TENANT's timezone, not the timezone of
+ * the machine running this server. The API buckets `group_by=date` by the tenant
+ * timezone, so resolving "today" against the operator's laptop clock would ask
+ * for a window that straddles two of the buckets it gets back — a single "today"
+ * arriving as two partial rows. Callers fetch the tenant timezone (see
+ * AffsetClient#getTenantTimezone) and pass it in.
+ */
+export declare const RANGE_PRESETS: readonly ["today", "yesterday", "last_7_days", "last_30_days", "this_month"];
+export type RangePreset = (typeof RANGE_PRESETS)[number];
+export interface ResolvedRange {
+    /** Inclusive lower bound, epoch ms. */
+    from: number;
+    /** Inclusive upper bound, epoch ms. */
+    to: number;
+    /** Human label for display. */
+    label: string;
+}
+/**
+ * Parse one campaign schedule boundary. Date-only values use the tenant's
+ * timezone; explicit ISO timestamps and epoch milliseconds remain exact.
+ */
+export declare function parseCampaignDateBound(value: string | number | null, role: "start" | "end", timeZone: string): number | null;
+/**
+ * Resolve a range from an optional preset and/or explicit from/to bounds.
+ * Explicit bounds win over the preset. All day boundaries are in `timeZone`
+ * (the tenant's), so the window lines up with the API's date buckets.
+ */
+export declare function resolveRange(preset: RangePreset | undefined, from: string | undefined, to: string | undefined, timeZone: string): ResolvedRange;
+/**
+ * Format an instant as `YYYY-MM-DD HH:mm` in the tenant timezone. Row timestamps
+ * have to agree with the date buckets stats are read in: a conversion at 23:30
+ * tenant-local rendered in UTC lands on the next day's row and reads as a
+ * missing conversion.
+ */
+export declare function formatInstant(ms: number, timeZone: string): string;

package/dist/lib/toolResult.d.ts

@@ -0,0 +1,7 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/** Build a successful text tool result. */
+export declare function textResult(body: string): CallToolResult;
+/** Build an error tool result (isError: true). */
+export declare function errorResult(err: unknown): CallToolResult;
+/** Build an error tool result from a plain string. */
+export declare function textError(body: string): CallToolResult;

package/dist/lib/urls.d.ts

@@ -0,0 +1,2 @@
+/** Validate http(s) URL; returns an error message or undefined when ok. */
+export declare function httpUrlError(value: string, label: string): string | undefined;

package/dist/lib/zones.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Zone lookup shared by every tool that needs a traffic source: campaign creation
+ * and both integration-URL tools all take an optional `zone_id` and auto-pick when
+ * the namespace has exactly one active zone.
+ */
+import { type AffsetClient } from "../client.js";
+import type { Zone } from "../types.js";
+export type ResolvedZone = {
+    zone: Zone;
+    inactiveWarning?: string;
+};
+export type ZoneResolution = ResolvedZone | {
+    error: string;
+};
+/**
+ * Resolve the zone to build URLs against. An explicit id is fetched directly — the
+ * paginated list must not be the arbiter of whether a zone exists.
+ */
+export declare function resolveZone(client: AffsetClient, zoneId: string | undefined): Promise<ZoneResolution>;
+/**
+ * The line every integration URL needs under it: without a postback URL on the zone,
+ * conversions never make it back to the traffic source and its optimizer stays blind.
+ */
+export declare function zonePostbackNote(zone: Zone): string;

package/dist/lib/zones.js

@@ -60,7 +60,15 @@ async function listActiveZones(client) {
     return { zones, total: res.pagination?.total ?? zones.length };
 }
 function zoneList(zones, total) {
-    const lines = zones.map((z) => `- \`${z.id}\` — ${mdCell(z.name)}${z.postback_url ? "" : " (no postback URL)"}`);
+    const lines = zones.map((z) => {
+        const source = z.traffic_source_name
+            ? ` · ${mdCell(z.traffic_source_name)}`
+            : z.traffic_source_id
+                ? ` · \`${mdCell(z.traffic_source_id)}\``
+                : "";
+        const postback = z.postback_url ? "" : " (no postback URL)";
+        return `- \`${z.id}\` — ${mdCell(z.name)}${source}${postback}`;
+    });
     if (total > zones.length) {
         lines.push(`- …and ${total - zones.length} more`);
     }

package/dist/registerTools.d.ts

@@ -0,0 +1,40 @@
+import { type Config } from "./runtimeConfig.js";
+/**
+ * Structural stand-in for the SDK's `McpServer`, so a consumer's own SDK
+ * install is accepted. `McpServer` carries private fields, which makes two
+ * copies of the class (this package's and a consumer's — e.g. the Workers
+ * gateway bundling its own `@modelcontextprotocol/sdk`) nominally
+ * incompatible even at identical versions. Method-parameter bivariance makes
+ * any real `McpServer` assignable to this shape; nothing else plausibly is.
+ *
+ * The zod schemas behind `inputSchema` stay internal to this package, so
+ * consumers never mix zod instances at the type level (they may bundle zod
+ * v4 while this package uses v3 — the MCP SDK detects the flavor per call).
+ */
+export interface AffsetToolServer {
+    registerTool(name: string, config: object, callback: (...args: never[]) => unknown): unknown;
+    registerResource(name: string, uri: string, metadata: object, callback: never): unknown;
+}
+export interface ToolCallEvent {
+    toolName: string;
+    durationMs: number;
+    status: "ok" | "error";
+}
+export interface RegisterAffsetToolsOptions {
+    /**
+     * Optional transport-owned audit hook. It receives metadata only, never tool
+     * arguments or output. Hook failures are isolated from the tool result.
+     */
+    onToolCall?: (event: ToolCallEvent) => void | Promise<void>;
+}
+/**
+ * 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 declare function registerAffsetTools(toolServer: AffsetToolServer, config: Config, options?: RegisterAffsetToolsOptions): void;

package/dist/registerTools.js

@@ -0,0 +1,437 @@
+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 { listTrafficSources, listTrafficSourcesInputSchema, LIST_TRAFFIC_SOURCES_DESCRIPTION, } from "./tools/listTrafficSources.js";
+import { createTrafficSource, createTrafficSourceInputSchema, CREATE_TRAFFIC_SOURCE_DESCRIPTION, } from "./tools/createTrafficSource.js";
+import { updateTrafficSource, updateTrafficSourceInputSchema, UPDATE_TRAFFIC_SOURCE_DESCRIPTION, } from "./tools/updateTrafficSource.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("list_traffic_sources", {
+        title: "List traffic sources",
+        description: LIST_TRAFFIC_SOURCES_DESCRIPTION,
+        inputSchema: listTrafficSourcesInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, (args) => listTrafficSources(client, args));
+    registerTool("create_traffic_source", {
+        title: "Create a traffic source",
+        description: CREATE_TRAFFIC_SOURCE_DESCRIPTION,
+        inputSchema: createTrafficSourceInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => createTrafficSource(client, args));
+    registerTool("update_traffic_source", {
+        title: "Update a traffic source",
+        description: UPDATE_TRAFFIC_SOURCE_DESCRIPTION,
+        inputSchema: updateTrafficSourceInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, (args) => updateTrafficSource(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;