@aveq-research/surfmeter-mcp 0.2.0

package/build/tools.js

@@ -0,0 +1,988 @@
+import { z } from "zod";
+import { errorResult, successResult } from "./result.js";
+const actionCatalogs = new WeakMap();
+const promotedActions = new Set([
+    "surfmeter_search_measurements",
+    "surfmeter_search_anomalies",
+    "surfmeter_update_client",
+]);
+function registerActive(server, options) {
+    const callback = async (args) => {
+        try {
+            return successResult(await options.handler(args));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    };
+    server.registerTool(options.name, {
+        description: options.description,
+        inputSchema: options.schema,
+        annotations: {
+            readOnlyHint: options.readOnly,
+            destructiveHint: options.destructive ?? false,
+            idempotentHint: options.readOnly,
+            openWorldHint: true,
+        },
+    }, callback);
+}
+function register(server, options) {
+    const catalog = actionCatalogs.get(server);
+    if (!catalog) {
+        throw new Error("Surfmeter action catalog was not initialized");
+    }
+    catalog.set(options.name, {
+        category: options.readOnly
+            ? "read"
+            : options.destructive
+                ? "destructive"
+                : "write",
+        description: options.description,
+        handler: options.handler,
+        name: options.name,
+        schema: options.schema,
+    });
+    if (promotedActions.has(options.name)) {
+        registerActive(server, options);
+    }
+}
+const id = z
+    .union([z.string().min(1), z.number().int().nonnegative()])
+    .describe("Rails numeric ID or UUID, where the endpoint supports UUIDs");
+const numericId = z.number().int().positive();
+const nullableString = z.string().nullable().optional();
+const role = z.enum(["org_admin", "admin", "editor", "viewer"]);
+const keyKind = z.enum(["export", "client_analytics", "client_admin"]);
+const jsonObject = z.record(z.string(), z.unknown());
+const searchBody = z
+    .union([jsonObject, z.string().min(2)])
+    .describe("Elasticsearch Query DSL object (preferred) or JSON string. Use .keyword for exact text matching.");
+const searchOptions = {
+    body: searchBody,
+    source_only: z.boolean().optional(),
+    size: z.number().int().nonnegative().optional(),
+    from: z.number().int().nonnegative().optional(),
+    search_after: z.array(z.unknown()).optional(),
+};
+const notificationConfig = z
+    .object({
+    anomaly_events: z.boolean().optional(),
+    client_offline: z.boolean().optional(),
+    anomaly_events_frequency: z.enum(["immediate", "digest"]).optional(),
+    anomaly_events_digest_hours: z.number().int().min(1).max(168).optional(),
+    anomaly_events_digest_interval_unit: z
+        .enum(["hour", "day", "week"])
+        .optional(),
+    anomaly_events_digest_interval_count: z
+        .number()
+        .int()
+        .min(1)
+        .max(168)
+        .optional(),
+    anomaly_events_digest_at_time: z
+        .string()
+        .regex(/^([01]\d|2[0-3]):[0-5]\d$/)
+        .optional(),
+    anomaly_events_digest_day_of_week: z
+        .number()
+        .int()
+        .min(1)
+        .max(7)
+        .optional(),
+})
+    .optional();
+async function data(client, request) {
+    return (await client.request(request)).data;
+}
+function apiKeyPath(kind) {
+    return `${kind}_api_keys`;
+}
+export function registerSurfmeterTools(server, client) {
+    const catalog = new Map();
+    actionCatalogs.set(server, catalog);
+    register(server, {
+        name: "surfmeter_get_version",
+        description: "Get the Surfmeter server version.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "version" }),
+    });
+    register(server, {
+        name: "surfmeter_get_measurement_options",
+        description: "Get allowed measurement types and subjects for capability configuration.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "measurement_options" }),
+    });
+    register(server, {
+        name: "surfmeter_get_license_usage",
+        description: "Get monthly license usage. Use extended=true for license units and per-subject distribution.",
+        schema: {
+            start_time: z.string().optional(),
+            end_time: z.string().optional(),
+            extended: z.boolean().optional(),
+        },
+        readOnly: true,
+        handler: (args) => data(client, { path: "license_usage", query: args }),
+    });
+    register(server, {
+        name: "surfmeter_list_clients",
+        description: "List all owned and shared Surfmeter clients visible to the current API key.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "clients" }),
+    });
+    register(server, {
+        name: "surfmeter_get_client",
+        description: "Get one Surfmeter client by numeric ID or UUID.",
+        schema: { id },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `clients/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_check_client_label",
+        description: "Check whether a client label is available. Optionally exclude the client currently being edited.",
+        schema: { label: z.string(), exclude_id: id.optional() },
+        readOnly: true,
+        handler: (args) => data(client, {
+            path: "clients/check_label_availability",
+            query: args,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_update_client",
+        description: "Update an owned client's labels, tags, or client-group assignments. Shared clients are read-only.",
+        schema: {
+            id,
+            label: nullableString,
+            extra_label: nullableString,
+            tags: z.array(z.string()).nullable().optional(),
+            client_group_ids: z.array(numericId).optional(),
+        },
+        readOnly: false,
+        handler: ({ id, ...body }) => data(client, { method: "PUT", path: `clients/${id}`, body }),
+    });
+    for (const action of ["disable", "mute", "unmute"]) {
+        register(server, {
+            name: `surfmeter_${action}_client`,
+            description: action === "disable"
+                ? "Manually disable an owned Surfmeter client. This interrupts that probe and is not automatically reversible through this API."
+                : `${action === "mute" ? "Mute" : "Unmute"} anomaly detection for an owned client.`,
+            schema: { id },
+            readOnly: false,
+            destructive: action === "disable",
+            handler: ({ id }) => data(client, { method: "POST", path: `clients/${id}/${action}` }),
+        });
+    }
+    register(server, {
+        name: "surfmeter_list_client_groups",
+        description: "List client groups and their assigned clients.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "client_groups" }),
+    });
+    register(server, {
+        name: "surfmeter_get_client_group",
+        description: "Get one client group.",
+        schema: { id: numericId },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `client_groups/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_create_client_group",
+        description: "Create a client group.",
+        schema: { name: z.string().min(1), description: nullableString },
+        readOnly: false,
+        handler: (body) => data(client, { method: "POST", path: "client_groups", body }),
+    });
+    register(server, {
+        name: "surfmeter_update_client_group",
+        description: "Update a client group's name, description, or complete client membership.",
+        schema: {
+            id: numericId,
+            name: z.string().min(1).optional(),
+            description: nullableString,
+            client_ids: z.array(numericId).optional(),
+        },
+        readOnly: false,
+        handler: ({ id, ...body }) => data(client, { method: "PUT", path: `client_groups/${id}`, body }),
+    });
+    register(server, {
+        name: "surfmeter_delete_client_group",
+        description: "Permanently delete a client group.",
+        schema: { id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ id }) => data(client, { method: "DELETE", path: `client_groups/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_list_isp_contracts",
+        description: "List ISP contracts assigned to one client.",
+        schema: { client_id: id },
+        readOnly: true,
+        handler: ({ client_id }) => data(client, { path: `clients/${client_id}/isp_contracts` }),
+    });
+    const ispContractFields = {
+        isp_id: numericId,
+        name: z.string().min(1),
+        download_speed: z.number().int().nonnegative().nullable().optional(),
+        upload_speed: z.number().int().nonnegative().nullable().optional(),
+        connection_type: nullableString,
+        monthly_price: z.number().nonnegative().nullable().optional(),
+        currency: nullableString,
+        assumed_tariff: nullableString,
+        valid_from: nullableString,
+        valid_until: nullableString,
+    };
+    register(server, {
+        name: "surfmeter_create_isp_contract",
+        description: "Create an ISP contract for a client.",
+        schema: { client_id: id, ...ispContractFields },
+        readOnly: false,
+        handler: ({ client_id, ...isp_contract }) => data(client, {
+            method: "POST",
+            path: `clients/${client_id}/isp_contracts`,
+            body: { isp_contract },
+        }),
+    });
+    register(server, {
+        name: "surfmeter_update_isp_contract",
+        description: "Replace the editable details of a client's ISP contract.",
+        schema: {
+            client_id: id,
+            id: numericId,
+            ...ispContractFields,
+        },
+        readOnly: false,
+        handler: ({ client_id, id, ...isp_contract }) => data(client, {
+            method: "PUT",
+            path: `clients/${client_id}/isp_contracts/${id}`,
+            body: { isp_contract },
+        }),
+    });
+    register(server, {
+        name: "surfmeter_delete_isp_contract",
+        description: "Permanently remove an ISP contract from a client.",
+        schema: { client_id: id, id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ client_id, id }) => data(client, {
+            method: "DELETE",
+            path: `clients/${client_id}/isp_contracts/${id}`,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_list_isps",
+        description: "List or search ISPs. Name search returns at most 20 compact results.",
+        schema: {
+            name: z.string().optional(),
+            country: z.string().length(2).optional(),
+            type: z.enum(["FixedIsp", "MobileIsp"]).optional(),
+            verified: z.boolean().optional(),
+        },
+        readOnly: true,
+        handler: (args) => data(client, { path: "isps", query: args }),
+    });
+    register(server, {
+        name: "surfmeter_get_isp",
+        description: "Get one ISP and its detailed metadata.",
+        schema: { id: numericId },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `isps/${id}` }),
+    });
+    const ispFields = {
+        name: z.string().min(1),
+        country: z.string().length(2),
+        type: z.enum(["FixedIsp", "MobileIsp"]),
+        is_vpn: z.boolean().nullable().optional(),
+    };
+    register(server, {
+        name: "surfmeter_create_isp",
+        description: "Create a verified ISP record.",
+        schema: ispFields,
+        readOnly: false,
+        handler: (isp) => data(client, { method: "POST", path: "isps", body: { isp } }),
+    });
+    register(server, {
+        name: "surfmeter_update_isp",
+        description: "Update an ISP record.",
+        schema: {
+            id: numericId,
+            name: ispFields.name.optional(),
+            country: ispFields.country.optional(),
+            type: ispFields.type.optional(),
+            is_vpn: ispFields.is_vpn,
+        },
+        readOnly: false,
+        handler: ({ id, ...isp }) => data(client, { method: "PUT", path: `isps/${id}`, body: { isp } }),
+    });
+    register(server, {
+        name: "surfmeter_merge_isp",
+        description: "Permanently merge the loser ISP into the target ISP, repoint all references, and delete the loser.",
+        schema: { id: numericId, target_id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ id, target_id }) => data(client, {
+            method: "POST",
+            path: `isps/${id}/merge_into`,
+            body: { target_id },
+        }),
+    });
+    register(server, {
+        name: "surfmeter_delete_isp",
+        description: "Permanently delete an ISP that is safe to remove.",
+        schema: { id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ id }) => data(client, { method: "DELETE", path: `isps/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_list_users",
+        description: "List visible dashboard users in the current organization. Requires org_admin.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "client_admin_users" }),
+    });
+    register(server, {
+        name: "surfmeter_get_user",
+        description: "Get a dashboard user profile. Users can read themselves; org_admin can read peers.",
+        schema: { id: numericId },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `client_admin_users/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_create_user",
+        description: "Create a dashboard user. Requires org_admin. notify_user optionally sends account email.",
+        schema: {
+            email: z.email(),
+            username: z.string().min(1),
+            role,
+            first_name: nullableString,
+            last_name: nullableString,
+            notify_user: z.boolean().optional(),
+            notification_config: notificationConfig,
+        },
+        readOnly: false,
+        handler: (body) => data(client, { method: "POST", path: "client_admin_users", body }),
+    });
+    register(server, {
+        name: "surfmeter_update_user",
+        description: "Update a dashboard user. Only org_admin can change another user's role.",
+        schema: {
+            id: numericId,
+            first_name: nullableString,
+            last_name: nullableString,
+            role: role.optional(),
+            ai_usage_accepted: z.boolean().nullable().optional(),
+            ai_custom_prompt: nullableString,
+            notification_config: notificationConfig,
+        },
+        readOnly: false,
+        handler: ({ id, ...body }) => data(client, {
+            method: "PUT",
+            path: `client_admin_users/${id}`,
+            body,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_request_user_email_change",
+        description: "Start the verified email-change flow for a dashboard user.",
+        schema: { id: numericId, email: z.email() },
+        readOnly: false,
+        handler: ({ id, email }) => data(client, {
+            method: "POST",
+            path: `client_admin_users/${id}/email_change`,
+            body: { email },
+        }),
+    });
+    register(server, {
+        name: "surfmeter_cancel_user_email_change",
+        description: "Cancel a dashboard user's pending email change.",
+        schema: { id: numericId },
+        readOnly: false,
+        handler: ({ id }) => data(client, {
+            method: "DELETE",
+            path: `client_admin_users/${id}/email_change`,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_delete_user",
+        description: "Permanently delete a dashboard user. Requires org_admin and cannot target the current user.",
+        schema: { id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ id }) => data(client, {
+            method: "DELETE",
+            path: `client_admin_users/${id}`,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_list_api_keys",
+        description: "List API keys of one kind: export, client analytics, or client admin.",
+        schema: { kind: keyKind },
+        readOnly: true,
+        handler: ({ kind }) => data(client, { path: apiKeyPath(kind) }),
+    });
+    register(server, {
+        name: "surfmeter_get_api_key",
+        description: "Get metadata for one API key. Secret key material is only returned at creation time.",
+        schema: { kind: keyKind, id: numericId },
+        readOnly: true,
+        handler: ({ kind, id }) => data(client, { path: `${apiKeyPath(kind)}/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_create_api_key",
+        description: "Create an API key. The returned secret is shown once; handle it as sensitive data. effective_role only applies to client_admin keys.",
+        schema: {
+            kind: keyKind,
+            name: z.string().min(1).optional(),
+            valid_until: z.string().optional(),
+            effective_role: role.optional(),
+        },
+        readOnly: false,
+        handler: ({ kind, ...body }) => data(client, { method: "POST", path: apiKeyPath(kind), body }),
+    });
+    register(server, {
+        name: "surfmeter_revoke_api_key",
+        description: "Permanently revoke an API key.",
+        schema: { kind: keyKind, id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ kind, id }) => data(client, {
+            method: "DELETE",
+            path: `${apiKeyPath(kind)}/${id}`,
+        }),
+    });
+    const registrationKeyFields = {
+        comment: nullableString,
+        valid_until: nullableString,
+        num_registrations_left: z.number().int().nullable().optional(),
+        capability_id: numericId.nullable().optional(),
+        usage_limit_days: z.number().int().nonnegative().nullable().optional(),
+        testing: z.boolean().nullable().optional(),
+    };
+    register(server, {
+        name: "surfmeter_list_registration_keys",
+        description: "List client registration keys and their usage.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "registration_keys" }),
+    });
+    register(server, {
+        name: "surfmeter_get_registration_key",
+        description: "Get one client registration key.",
+        schema: { id: numericId },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `registration_keys/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_create_registration_key",
+        description: "Create a client registration key. The secret registration value is returned by the API.",
+        schema: registrationKeyFields,
+        readOnly: false,
+        handler: (body) => data(client, { method: "POST", path: "registration_keys", body }),
+    });
+    register(server, {
+        name: "surfmeter_update_registration_key",
+        description: "Update a client registration key's limits and metadata.",
+        schema: { id: numericId, ...registrationKeyFields },
+        readOnly: false,
+        handler: ({ id, ...body }) => data(client, {
+            method: "PUT",
+            path: `registration_keys/${id}`,
+            body,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_delete_registration_key",
+        description: "Permanently revoke a client registration key.",
+        schema: { id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ id }) => data(client, {
+            method: "DELETE",
+            path: `registration_keys/${id}`,
+        }),
+    });
+    const capabilityFields = {
+        name: z.string().min(1),
+        comment: nullableString,
+        allowed_measurement_types: z.array(z.string()).optional(),
+        allowed_measurement_subjects: z.array(z.string()).optional(),
+        forbidden_measurement_types: z.array(z.string()).optional(),
+        forbidden_measurement_subjects: z.array(z.string()).optional(),
+    };
+    register(server, {
+        name: "surfmeter_list_capabilities",
+        description: "List capability profiles and registration-key counts.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "capabilities" }),
+    });
+    register(server, {
+        name: "surfmeter_get_capability",
+        description: "Get one capability profile and its associated registration keys.",
+        schema: { id: numericId },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `capabilities/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_create_capability",
+        description: "Create a capability profile controlling permitted measurement types and subjects.",
+        schema: capabilityFields,
+        readOnly: false,
+        handler: (body) => data(client, { method: "POST", path: "capabilities", body }),
+    });
+    register(server, {
+        name: "surfmeter_update_capability",
+        description: "Update a capability profile.",
+        schema: {
+            id: numericId,
+            name: capabilityFields.name.optional(),
+            comment: capabilityFields.comment,
+            allowed_measurement_types: capabilityFields.allowed_measurement_types,
+            allowed_measurement_subjects: capabilityFields.allowed_measurement_subjects,
+            forbidden_measurement_types: capabilityFields.forbidden_measurement_types,
+            forbidden_measurement_subjects: capabilityFields.forbidden_measurement_subjects,
+        },
+        readOnly: false,
+        handler: ({ id, ...body }) => data(client, { method: "PUT", path: `capabilities/${id}`, body }),
+    });
+    register(server, {
+        name: "surfmeter_delete_capability",
+        description: "Permanently delete a capability profile. The API rejects unsafe deletion when dependencies prevent it.",
+        schema: { id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ id }) => data(client, { method: "DELETE", path: `capabilities/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_search_measurements",
+        description: "Search and aggregate measurement documents with Elasticsearch Query DSL. Prefer filters and aggregations server-side; use .keyword for exact text fields.",
+        schema: {
+            ...searchOptions,
+            scroll: z
+                .string()
+                .regex(/^\d+[smh]$/)
+                .optional()
+                .describe("Optional Elasticsearch scroll timeout such as 1m"),
+        },
+        readOnly: true,
+        handler: (body) => data(client, { method: "POST", path: "measurements/search", body }),
+    });
+    register(server, {
+        name: "surfmeter_get_measurement",
+        description: "Get one measurement document by Elasticsearch document ID.",
+        schema: { id: z.string().min(1) },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `measurements/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_get_p1203_report",
+        description: "Get the ITU-T P.1203 input/client-report data for one video measurement.",
+        schema: { id: z.string().min(1) },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `measurements/${id}/p1203_client_report` }),
+    });
+    register(server, {
+        name: "surfmeter_get_network_performance_report",
+        description: "Get the network performance client report attached to one web measurement.",
+        schema: { id: z.string().min(1) },
+        readOnly: true,
+        handler: ({ id }) => data(client, {
+            path: `measurements/${id}/network_performance_report`,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_search_anomalies",
+        description: "Search and aggregate anomaly episode documents with Elasticsearch Query DSL. Use .keyword for exact text fields.",
+        schema: searchOptions,
+        readOnly: true,
+        handler: (body) => data(client, { method: "POST", path: "anomaly_events/search", body }),
+    });
+    register(server, {
+        name: "surfmeter_get_anomaly",
+        description: "Get one anomaly event by its public anomaly_id.",
+        schema: { anomaly_id: z.string().min(1) },
+        readOnly: true,
+        handler: ({ anomaly_id }) => data(client, {
+            path: `anomaly_events/${encodeURIComponent(anomaly_id)}`,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_resolve_anomalies",
+        description: "Resolve up to 500 anomaly episodes by Elasticsearch document ID. Already-resolved and unknown IDs are harmless no-ops.",
+        schema: { anomaly_ids: z.array(z.string().min(1)).min(1).max(500) },
+        readOnly: false,
+        handler: (body) => data(client, {
+            method: "PATCH",
+            path: "anomaly_events/resolve",
+            body,
+        }),
+    });
+    const anomalyScope = z.object({
+        subject: z.string().optional(),
+        measurement_type: z.string().optional(),
+        metric: z.string().optional(),
+        detection_pass: z
+            .enum(["spike", "shift", "inter_client", "data_quality"])
+            .optional(),
+    });
+    const anomalyLevel = z.enum([
+        "way_more",
+        "more",
+        "normal",
+        "fewer",
+        "much_fewer",
+        "off",
+    ]);
+    register(server, {
+        name: "surfmeter_list_anomaly_overrides",
+        description: "List all anomaly-detection tuning overrides.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "anomaly_detection_overrides" }),
+    });
+    register(server, {
+        name: "surfmeter_get_anomaly_override",
+        description: "Get one anomaly-detection tuning override.",
+        schema: { id: numericId },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: `anomaly_detection_overrides/${id}` }),
+    });
+    register(server, {
+        name: "surfmeter_get_anomaly_override_dimensions",
+        description: "Get valid measurement types, subjects, metrics, detection passes, and tuning levels for authoring overrides.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "anomaly_detection_overrides/dimensions" }),
+    });
+    register(server, {
+        name: "surfmeter_create_anomaly_override",
+        description: "Create a manual anomaly-detection tuning override.",
+        schema: { scope: anomalyScope, level: anomalyLevel },
+        readOnly: false,
+        handler: (body) => data(client, {
+            method: "POST",
+            path: "anomaly_detection_overrides",
+            body,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_update_anomaly_override",
+        description: "Change an anomaly override's level. Scope changes require delete and recreate.",
+        schema: { id: numericId, level: anomalyLevel },
+        readOnly: false,
+        handler: ({ id, level }) => data(client, {
+            method: "PUT",
+            path: `anomaly_detection_overrides/${id}`,
+            body: { level },
+        }),
+    });
+    register(server, {
+        name: "surfmeter_submit_anomaly_feedback",
+        description: "Apply thumbs-style feedback to an anomaly scope, stepping alert sensitivity up or down.",
+        schema: {
+            scope: anomalyScope,
+            direction: z.enum(["up", "down"]),
+            source_anomaly_id: z.string().nullable().optional(),
+        },
+        readOnly: false,
+        handler: (body) => data(client, {
+            method: "POST",
+            path: "anomaly_detection_overrides/feedback",
+            body,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_delete_anomaly_override",
+        description: "Permanently delete one anomaly-detection override.",
+        schema: { id: numericId },
+        readOnly: false,
+        destructive: true,
+        handler: ({ id }) => data(client, {
+            method: "DELETE",
+            path: `anomaly_detection_overrides/${id}`,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_delete_anomaly_overrides",
+        description: "Permanently delete selected anomaly overrides, or all overrides when ids is omitted or empty.",
+        schema: { ids: z.array(numericId).optional() },
+        readOnly: false,
+        destructive: true,
+        handler: (body) => data(client, {
+            method: "DELETE",
+            path: "anomaly_detection_overrides",
+            body,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_get_settings",
+        description: "Get organization settings such as AI system prompt and offline threshold.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "data_owner/settings" }),
+    });
+    register(server, {
+        name: "surfmeter_update_settings",
+        description: "Update organization settings. A null offline threshold clears the override and restores the server default.",
+        schema: {
+            ai_system_prompt: z.string().nullable().optional(),
+            offline_threshold_minutes: z
+                .number()
+                .int()
+                .positive()
+                .nullable()
+                .optional(),
+        },
+        readOnly: false,
+        handler: (body) => data(client, { method: "PUT", path: "data_owner/settings", body }),
+    });
+    register(server, {
+        name: "surfmeter_get_anomaly_config",
+        description: "Get organization-wide anomaly detection status and sensitivity.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "data_owner/anomaly_detection_config" }),
+    });
+    register(server, {
+        name: "surfmeter_update_anomaly_config",
+        description: "Set organization-wide anomaly sensitivity to low, medium, or high.",
+        schema: { sensitivity: z.enum(["low", "medium", "high"]) },
+        readOnly: false,
+        handler: (body) => data(client, {
+            method: "PUT",
+            path: "data_owner/anomaly_detection_config",
+            body,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_get_ai_status",
+        description: "Check whether Surfmeter's built-in AI assistant is enabled for the organization.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "ai_assistant/status" }),
+    });
+    register(server, {
+        name: "surfmeter_get_ai_usage",
+        description: "Get the organization's Surfmeter AI usage summary. Requires org_admin.",
+        schema: {},
+        readOnly: true,
+        handler: () => data(client, { path: "ai_assistant/usage" }),
+    });
+    register(server, {
+        name: "surfmeter_explain_measurement",
+        description: "Ask Surfmeter's built-in AI assistant to explain a supplied measurement. May consume AI quota; force=true bypasses cached output.",
+        schema: {
+            measurement: jsonObject,
+            force: z.boolean().optional(),
+            user_timezone: z.string().optional(),
+        },
+        readOnly: false,
+        handler: (body) => data(client, {
+            method: "POST",
+            path: "ai_assistant/explain",
+            body,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_explain_anomaly",
+        description: "Ask Surfmeter's built-in AI assistant to explain a supplied anomaly. May consume AI quota; force=true bypasses cached output.",
+        schema: {
+            anomaly: jsonObject,
+            force: z.boolean().optional(),
+            user_timezone: z.string().optional(),
+        },
+        readOnly: false,
+        handler: (body) => data(client, {
+            method: "POST",
+            path: "ai_assistant/explain_anomaly",
+            body,
+        }),
+    });
+    register(server, {
+        name: "surfmeter_ai_chat",
+        description: "Send a conversation to Surfmeter's built-in context-aware AI assistant. May consume AI quota.",
+        schema: {
+            messages: z.array(z.unknown()).min(1),
+            context: jsonObject.optional(),
+        },
+        readOnly: false,
+        handler: (body) => data(client, {
+            method: "POST",
+            path: "ai_assistant/chat",
+            body,
+        }),
+    });
+    registerCatalogTools(server, client, catalog);
+}
+function actionExecutor(category) {
+    switch (category) {
+        case "read":
+            return "surfmeter_execute_read_action";
+        case "write":
+            return "surfmeter_execute_write_action";
+        case "destructive":
+            return "surfmeter_execute_destructive_action";
+    }
+}
+function actionSchema(action) {
+    return z.toJSONSchema(z.object(action.schema));
+}
+function actionSummary(action, detailed = false) {
+    const schema = actionSchema(action);
+    const summary = {
+        id: action.name,
+        description: action.description,
+        category: action.category,
+        executor: actionExecutor(action.category),
+        parameters: Object.keys(schema.properties ?? {}),
+        required_parameters: schema.required ?? [],
+    };
+    return detailed ? { ...summary, input_schema: schema } : summary;
+}
+function searchScore(action, query) {
+    const normalizedQuery = query
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+    const stopWords = new Set([
+        "a",
+        "an",
+        "and",
+        "for",
+        "i",
+        "of",
+        "the",
+        "to",
+        "want",
+        "with",
+    ]);
+    const terms = normalizedQuery
+        .split(/\s+/)
+        .filter((term) => term.length > 1 && !stopWords.has(term));
+    const name = action.name.toLowerCase().replace(/[^a-z0-9]+/g, " ");
+    const description = action.description.toLowerCase();
+    let score = 0;
+    if (name.includes(normalizedQuery)) {
+        score += 20;
+    }
+    if (description.includes(normalizedQuery)) {
+        score += 12;
+    }
+    for (const term of terms) {
+        if (name.includes(term)) {
+            score += 5;
+        }
+        if (description.includes(term)) {
+            score += 2;
+        }
+    }
+    return score;
+}
+async function executeCatalogAction(catalog, category, actionId, params) {
+    const action = catalog.get(actionId);
+    if (!action) {
+        throw new Error(`Unknown action '${actionId}'. Call surfmeter_search_actions first.`);
+    }
+    if (action.category !== category) {
+        throw new Error(`Action '${actionId}' is ${action.category}; use ${actionExecutor(action.category)}.`);
+    }
+    const validation = await z
+        .object(action.schema)
+        .safeParseAsync(params);
+    if (!validation.success) {
+        throw new Error(`Invalid parameters for '${actionId}': ${z.prettifyError(validation.error)}`);
+    }
+    return action.handler(validation.data);
+}
+function registerCatalogTools(server, client, catalog) {
+    registerActive(server, {
+        name: "surfmeter_get_clients",
+        description: "List all visible Surfmeter clients, or get one client when id is supplied.",
+        schema: { id: id.optional() },
+        readOnly: true,
+        handler: ({ id }) => data(client, { path: id === undefined ? "clients" : `clients/${id}` }),
+    });
+    registerActive(server, {
+        name: "surfmeter_get_system_status",
+        description: "Read server version, measurement options, license usage, or Surfmeter AI status.",
+        schema: {
+            resource: z.enum([
+                "version",
+                "measurement_options",
+                "license_usage",
+                "ai_status",
+            ]),
+            start_time: z.string().optional(),
+            end_time: z.string().optional(),
+            extended: z.boolean().optional(),
+        },
+        readOnly: true,
+        handler: ({ resource, start_time, end_time, extended }) => {
+            if (resource === "license_usage") {
+                return data(client, {
+                    path: "license_usage",
+                    query: { start_time, end_time, extended },
+                });
+            }
+            return data(client, {
+                path: resource === "ai_status" ? "ai_assistant/status" : resource,
+            });
+        },
+    });
+    registerActive(server, {
+        name: "surfmeter_search_actions",
+        description: "Find less-common Surfmeter operations by intent. Returns action IDs, safety categories, executors, and parameter names. Use surfmeter_describe_action for the exact schema.",
+        schema: {
+            query: z.string().min(1),
+            category: z.enum(["read", "write", "destructive"]).optional(),
+            limit: z.number().int().min(1).max(20).default(8),
+        },
+        readOnly: true,
+        handler: ({ query, category, limit }) => {
+            const matches = [...catalog.values()]
+                .filter((action) => category === undefined || action.category === category)
+                .map((action) => ({ action, score: searchScore(action, query) }))
+                .filter(({ score }) => score > 0)
+                .sort((left, right) => right.score - left.score ||
+                left.action.name.localeCompare(right.action.name))
+                .slice(0, limit)
+                .map(({ action }) => actionSummary(action));
+            return { actions: matches };
+        },
+    });
+    registerActive(server, {
+        name: "surfmeter_describe_action",
+        description: "Get the exact schema, safety category, and required executor for one discovered Surfmeter action.",
+        schema: { action_id: z.string().min(1) },
+        readOnly: true,
+        handler: ({ action_id }) => {
+            const action = catalog.get(action_id);
+            if (!action) {
+                throw new Error(`Unknown action '${action_id}'`);
+            }
+            return actionSummary(action, true);
+        },
+    });
+    const executorSchema = {
+        action_id: z.string().min(1),
+        params: jsonObject.default({}),
+    };
+    for (const category of ["read", "write", "destructive"]) {
+        registerActive(server, {
+            name: actionExecutor(category),
+            description: category === "read"
+                ? "Execute a read-only Surfmeter action returned by surfmeter_search_actions."
+                : category === "write"
+                    ? "Execute a non-destructive Surfmeter mutation returned by surfmeter_search_actions."
+                    : "Execute a destructive Surfmeter action returned by surfmeter_search_actions. Confirm exact targets and consequences first.",
+            schema: executorSchema,
+            readOnly: category === "read",
+            destructive: category === "destructive",
+            handler: ({ action_id, params }) => executeCatalogAction(catalog, category, action_id, params),
+        });
+    }
+}
+//# sourceMappingURL=tools.js.map