kaax-mcp 0.1.0

package/dist/tools.js

@@ -0,0 +1,926 @@
+/**
+ * Tool registry — every callable function exposed to the LLM agent.
+ *
+ * Each entry pairs a JSON-Schema input definition (what the agent must send)
+ * with an async handler that returns text-form results suitable for the
+ * agent to reason over. Outputs are kept compact and **explicit about next
+ * steps** so the agent never has to guess what to do next.
+ */
+import { z } from "zod";
+import { issueOnboardingToken, pollOnboardingUntilBound, } from "./client.js";
+import { aggregateDensity, findSimilar, } from "./spatial.js";
+import { convertShapefileToKml } from "./convert.js";
+import { downloadFile, openBrowser } from "./platform.js";
+import { homedir } from "os";
+import { join } from "path";
+import { getLocale, t, tList } from "./i18n.js";
+import { KaaxAPIError } from "./client.js";
+// ─────────────────────────────────────────────────────────────────────────
+// Helpers shared by every tool
+// ─────────────────────────────────────────────────────────────────────────
+function text(...parts) {
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+}
+function errorText(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `❌ ${msg}` }], isError: true };
+}
+/**
+ * Pretty-print a paid-tier refusal. Used both proactively (tier guard
+ * before the call) and reactively (when the server returns 403). The two
+ * paths must produce the SAME text so the agent doesn't see two different
+ * UX flows for the same condition.
+ */
+function proRequiredText(upgradeUrl) {
+    const lines = [
+        `🔒 ${t("proRequired_title")}`,
+        "",
+        t("proRequired_body"),
+        "",
+        t("proRequired_cta", { url: upgradeUrl }),
+        "",
+        t("freeAvailable_header"),
+        ...tList("freeAvailable_items").map((s) => `  • ${s}`),
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+}
+/**
+ * Translate a thrown error into a localized, actionable tool result. Detects
+ * the canonical Kaax v2 error codes (carried as JSON in the body of a
+ * KaaxAPIError) and routes them through the dictionary. Falls back to the
+ * raw message for anything we don't recognise.
+ */
+function apiErrorText(err, ctx) {
+    if (err instanceof KaaxAPIError) {
+        let parsed = null;
+        if (err.body) {
+            try {
+                parsed = JSON.parse(err.body);
+            }
+            catch {
+                /* not JSON — fall through */
+            }
+        }
+        const code = parsed?.error ?? "";
+        if (code === "API_ACCESS_DENIED" || err.status === 403) {
+            return proRequiredText(ctx?.upgradeUrl ??
+                "https://www.kaax-agritech.com/es/dashboard/payment");
+        }
+        if (code === "MISSING_API_KEY") {
+            return { content: [{ type: "text", text: `❌ ${t("missingApiKey")}` }], isError: true };
+        }
+        if (code === "INVALID_API_KEY") {
+            return { content: [{ type: "text", text: `❌ ${t("invalidApiKey")}` }], isError: true };
+        }
+        if (code === "RATE_LIMITED" || err.status === 429) {
+            return { content: [{ type: "text", text: `⌛ ${t("rateLimited")}` }] };
+        }
+        if (!err.status) {
+            return { content: [{ type: "text", text: `❌ ${t("network")}` }], isError: true };
+        }
+    }
+    return errorText(err);
+}
+/**
+ * Tier guard — runs BEFORE a paid call. Fetches the (cached) account
+ * overview, and if the user is on the Free tier we short-circuit with the
+ * Pro-required message instead of letting the server return 403. Saves a
+ * round-trip and keeps the UX consistent.
+ */
+async function withPaidTier(client, fn) {
+    if (!client.hasApiKey()) {
+        return {
+            content: [{ type: "text", text: `❌ ${t("missingApiKey")}` }],
+            isError: true,
+        };
+    }
+    let overview;
+    try {
+        overview = await client.accountOverview();
+    }
+    catch (err) {
+        // If the overview call itself fails (network, invalid key, server down)
+        // surface that as-is. Don't pretend Pro is required when we don't know.
+        return apiErrorText(err);
+    }
+    if (!overview.user.active) {
+        return {
+            content: [{ type: "text", text: `⚠️ ${t("needsActivation")}` }],
+        };
+    }
+    if (!overview.limits.apiAccess) {
+        const locale = getLocale();
+        return proRequiredText(locale === "en" ? overview.upgradeUrlEn : overview.upgradeUrl);
+    }
+    try {
+        return await fn(overview);
+    }
+    catch (err) {
+        const locale = getLocale();
+        return apiErrorText(err, {
+            upgradeUrl: locale === "en" ? overview.upgradeUrlEn : overview.upgradeUrl,
+        });
+    }
+}
+function compactAnalysis(r) {
+    return {
+        id: r._id,
+        imageSetId: r.imageSetId,
+        name: r.name,
+        tags: r.tag,
+        analysisType: r.analysisType,
+        createdAt: r.createdAt,
+        metrics: {
+            areaHa: r.analysis?.totalAreaHa,
+            detections: r.analysis?.totalCounts,
+            survivalRate: r.analysis?.survivalRate,
+            depopulationRate: r.analysis?.depopulationRate,
+            replantingRate: r.analysis?.replantingRate,
+            pathRate: r.analysis?.pathRate,
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Schemas
+// ─────────────────────────────────────────────────────────────────────────
+const AnalysisTypeSchema = z.enum(["replanting", "counting", "path"]);
+const ListAnalysesArgs = z.object({
+    name: z.string().optional().describe("Filter by field name (substring match server-side)"),
+    start: z.union([z.string(), z.number()]).optional().describe("Start date — ISO 8601 string or unix millis"),
+    end: z.union([z.string(), z.number()]).optional().describe("End date — ISO 8601 string or unix millis"),
+    tag: z.string().optional().describe("Filter by a single tag"),
+    type: AnalysisTypeSchema.optional().describe("Analysis type: replanting / counting / path"),
+    page: z.number().int().min(1).optional().describe("Page number (default: 1)"),
+    limit: z.number().int().min(1).max(100).optional().describe("Page size (default: 20, max: 100)"),
+});
+const GetAnalysisArgs = z.object({
+    id: z.string().describe("The analysis _id to inspect"),
+});
+const SuggestTagsArgs = z.object({
+    fieldName: z.string().describe("Field/parcel name as the user calls it"),
+    crop: z.string().optional().describe("Crop type if known (sugarcane, pineapple…)"),
+    region: z.string().optional().describe("Region / country / farm name"),
+});
+const SuggestConfigArgs = z.object({
+    analysisType: AnalysisTypeSchema.describe("Which analysis you're configuring"),
+    crop: z.string().optional().describe("Crop type — affects defaults"),
+    goal: z
+        .enum(["balanced", "high_recall", "high_precision"])
+        .optional()
+        .describe("What you optimise for. Default: balanced."),
+});
+const ExplainParameterArgs = z.object({
+    parameter: z.enum([
+        "blockSize",
+        "accuracy",
+        "iou",
+        "radiusFactor",
+        "overlap",
+        "smallMax",
+        "mediumMax",
+        "largeMax",
+        "seedsPerMeter",
+        "seedsPerBox",
+    ]),
+});
+const FindSimilarArgs = z.object({
+    analysisId: z.string().describe("Reference analysis _id"),
+    topK: z.number().int().min(1).max(20).optional().describe("How many neighbours to return (default 5)"),
+});
+const DensityStatsArgs = z.object({
+    tag: z.string().optional(),
+    type: AnalysisTypeSchema.optional(),
+    start: z.union([z.string(), z.number()]).optional(),
+    end: z.union([z.string(), z.number()]).optional(),
+});
+const ConvertShpArgs = z.object({
+    shpPath: z.string().describe("Absolute path to the .shp file on the user's machine"),
+    outputPath: z.string().optional().describe("Optional .kml output path. Defaults next to the .shp file."),
+});
+const PeerSuggestionsArgs = z.object({
+    type: AnalysisTypeSchema.describe("Analysis type whose peer average to fetch"),
+});
+const AttachTagsArgs = z.object({
+    fieldId: z.string().describe("Field (imageSet) id to tag"),
+    tags: z
+        .array(z.string().min(1).max(50))
+        .min(1)
+        .max(30)
+        .describe("Tags to attach. Server normalises them."),
+});
+const StartOnboardingArgs = z.object({});
+const CompleteOnboardingArgs = z.object({
+    token: z.string().min(16).max(64).describe("The onboarding token returned by kaax_start_onboarding"),
+    maxWaitMinutes: z
+        .number()
+        .int()
+        .min(1)
+        .max(15)
+        .optional()
+        .describe("How long to keep polling. Default 10 minutes. Hard cap 15."),
+});
+const RequestDownloadArgs = z.object({
+    useCase: z
+        .string()
+        .max(500)
+        .optional()
+        .describe("Short description of what the user wants to do with Kaax Labeling / Desktop"),
+    company: z.string().max(120).optional(),
+    locale: z.enum(["en", "es", "zh"]).optional(),
+});
+const DownloadKaaxArgs = z.object({
+    product: z
+        .enum(["kaaxLabeling", "kaaxDesktop"])
+        .describe("Which binary to fetch"),
+    outputDir: z
+        .string()
+        .optional()
+        .describe("Directory to save the binary. Defaults to the user's home Downloads folder."),
+});
+export function buildTools() {
+    return [
+        // ── Onboarding (browser handoff) ────────────────────────────────────
+        {
+            name: "kaax_start_onboarding",
+            description: "Start a brand-new Kaax account. Issues a single-use 15-minute token and opens the user's default browser at the Kaax signup page with the token attached. The user fills the form (email/password) in the browser; once they submit, the page binds their new account to the token so kaax_complete_onboarding can pick up the apiKey. Use when the agent has no KAAX_API_KEY configured and the user wants to onboard from scratch.",
+            inputSchema: zodToJsonSchema(StartOnboardingArgs),
+            async handler(_args, { client }) {
+                try {
+                    const issued = await issueOnboardingToken(client.baseUrl, "mcp");
+                    const signupUrl = `${client.baseUrl}${issued.signupUrlHint}`;
+                    const opened = openBrowser(signupUrl);
+                    return text("🚀 Onboarding started.", "", opened.spawned
+                        ? `Opened your default browser at: ${signupUrl}`
+                        : `Could not open the browser automatically (platform=${opened.platform}). Open this URL manually: ${signupUrl}`, "", `Token: ${issued.token}`, `Expires in: ${Math.floor(issued.ttlSeconds / 60)} minutes`, "", "Next step: complete the signup form in the browser. Then call kaax_complete_onboarding with the token above to fetch your apiKey.");
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_complete_onboarding",
+            description: "Polls the Kaax server until the onboarding token has been bound to a freshly-created user (i.e. they finished the signup form in the browser). Returns the apiKey **once** — set it via KAAX_API_KEY on next MCP run, or use it immediately within this session. Times out after 10 minutes by default.",
+            inputSchema: zodToJsonSchema(CompleteOnboardingArgs),
+            async handler(args, { client }) {
+                try {
+                    const { token, maxWaitMinutes } = CompleteOnboardingArgs.parse(args);
+                    const result = await pollOnboardingUntilBound(token, {
+                        baseUrl: client.baseUrl,
+                        maxWaitMs: (maxWaitMinutes ?? 10) * 60_000,
+                    });
+                    if (result.status === "bound") {
+                        // Late-bind the apiKey on the in-process client so subsequent
+                        // tool calls in this session don't need a restart.
+                        client.setApiKey(result.apiKey);
+                        return text("✅ Account ready. ApiKey acquired and configured for this session.", "", `apiKey: ${result.apiKey}`, "", "⚠️ This key is shown ONLY ONCE. Save it permanently by setting the `KAAX_API_KEY` environment variable in your MCP client config — otherwise you'll need to retrieve it from /dashboard/api-manage next time.", "", "Next: activate your account via the email we sent before requesting downloads or running paid analyses.");
+                    }
+                    if (result.status === "pending") {
+                        return text("⌛ Still pending after the timeout. Re-run kaax_complete_onboarding with the same token to keep waiting (token is valid for 15 minutes total).");
+                    }
+                    if (result.status === "expired") {
+                        return text("⏰ Token expired. Call kaax_start_onboarding again to issue a fresh one.");
+                    }
+                    // already_consumed
+                    return text("🔒 This token was already consumed by another caller. Issue a new one with kaax_start_onboarding.");
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        // ── License & billing (free-tier friendly) ──────────────────────────
+        {
+            name: "kaax_check_license",
+            description: "Show the active plan, what's enabled for the current account (API access, fields/models/configs limits, download permission) and the upgrade URL. ALWAYS call this BEFORE any analysis/field/model/tag tool so you can warn the user upfront if they're on the Free tier — analyses require a Pro subscription.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            async handler(_args, { client }) {
+                try {
+                    if (!client.hasApiKey()) {
+                        return {
+                            content: [{ type: "text", text: `ℹ️ ${t("missingApiKey")}` }],
+                        };
+                    }
+                    const o = await client.accountOverview(true /* force refresh */);
+                    const locale = getLocale();
+                    const upgrade = locale === "en" ? o.upgradeUrlEn : o.upgradeUrl;
+                    const lines = [];
+                    lines.push(locale === "en"
+                        ? `📋 Account: ${o.user.email}`
+                        : `📋 Cuenta: ${o.user.email}`);
+                    lines.push(locale === "en"
+                        ? `   Plan: ${o.plan.name}${o.plan.isPaid ? "" : " (Free)"}`
+                        : `   Plan: ${o.plan.name}${o.plan.isPaid ? "" : " (Gratis)"}`);
+                    lines.push(locale === "en"
+                        ? `   Activated: ${o.user.active ? "yes" : "no — check your email"}`
+                        : `   Activado: ${o.user.active ? "sí" : "no — revisá tu correo"}`);
+                    lines.push("");
+                    lines.push(locale === "en" ? "Enabled in this plan:" : "Disponible en este plan:");
+                    const ok = "✅";
+                    const no = "❌";
+                    lines.push(`  ${o.capabilities.onboarding ? ok : no} ${locale === "en" ? "Onboarding" : "Onboarding"}`);
+                    lines.push(`  ${o.capabilities.localUtilities ? ok : no} ${locale === "en"
+                        ? "Local utilities (shapefile → KML, tag/config suggestions)"
+                        : "Utilidades locales (shapefile → KML, sugerencias de tags/config)"}`);
+                    lines.push(`  ${o.capabilities.downloadRequest ? ok : no} ${locale === "en" ? "Desktop app download" : "Descarga de apps de escritorio"}${o.download.permission ? (locale === "en" ? " (approved)" : " (aprobado)") : ""}`);
+                    lines.push(`  ${o.capabilities.analysesRead ? ok : no} ${locale === "en" ? "Analyses & fields API (Pro)" : "API de análisis y campos (Pro)"}`);
+                    lines.push("");
+                    lines.push(locale === "en" ? "Limits:" : "Límites:");
+                    lines.push(`  ${locale === "en" ? "Fields" : "Campos"}: ${o.limits.fields}`);
+                    lines.push(`  ${locale === "en" ? "Local models" : "Modelos locales"}: ${o.limits.localModels}`);
+                    lines.push(`  ${locale === "en" ? "Custom configurations" : "Configuraciones personalizadas"}: ${o.limits.customConfigurations}`);
+                    if (!o.plan.isPaid) {
+                        lines.push("");
+                        lines.push(locale === "en"
+                            ? `💎 Upgrade to Pro: ${upgrade}`
+                            : `💎 Upgrade a Pro: ${upgrade}`);
+                        lines.push(locale === "en"
+                            ? "Call `kaax_open_billing` to open it in your browser."
+                            : "Llamá a `kaax_open_billing` para abrirlo en el navegador.");
+                    }
+                    return { content: [{ type: "text", text: lines.join("\n") }] };
+                }
+                catch (err) {
+                    return apiErrorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_open_billing",
+            description: "Open the Kaax billing / plans page in the user's default browser. Use after kaax_check_license shows Free tier and the user wants to upgrade. Honors KAAX_LOCALE for the URL.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            async handler(_args, { client }) {
+                try {
+                    const locale = getLocale();
+                    let url;
+                    if (client.hasApiKey()) {
+                        try {
+                            const o = await client.accountOverview();
+                            url = locale === "en" ? o.upgradeUrlEn : o.upgradeUrl;
+                        }
+                        catch {
+                            url = `${client.baseUrl}/${locale}/dashboard/payment`;
+                        }
+                    }
+                    else {
+                        url = `${client.baseUrl}/${locale}/dashboard/payment`;
+                    }
+                    const opened = openBrowser(url);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: opened.spawned
+                                    ? locale === "en"
+                                        ? `🌐 Opened the billing page: ${url}`
+                                        : `🌐 Abrí la página de planes: ${url}`
+                                    : locale === "en"
+                                        ? `Could not open the browser (platform=${opened.platform}). Open this URL manually: ${url}`
+                                        : `No pude abrir el navegador (plataforma=${opened.platform}). Abrí manualmente: ${url}`,
+                            },
+                        ],
+                    };
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        // ── Querying the API ─────────────────────────────────────────────────
+        {
+            name: "kaax_list_analyses",
+            description: "[Pro] List your Kaax analyses. Supports filtering by name, date range, tag and analysis type, plus pagination. REQUIRES a Pro subscription — the tool returns an upgrade message for Free users. Use this whenever the user asks about their fields, recent runs, density, survival, replanting rates, etc.",
+            inputSchema: zodToJsonSchema(ListAnalysesArgs),
+            async handler(args, { client }) {
+                return withPaidTier(client, async () => {
+                    const filters = ListAnalysesArgs.parse(args);
+                    const page = await client.listAnalyses(filters);
+                    if (page.data.length === 0) {
+                        return text("No analyses match those filters.", "", "If the user just signed up, suggest they upload their first field and watch the official tutorial:", "• kaax://docs/quickstart", "• kaax://docs/tutorial");
+                    }
+                    const compact = page.data.map(compactAnalysis);
+                    return text(`Found ${page.total} analyses · returning ${page.data.length} on page ${page.page} (limit ${page.limit}).`, "", JSON.stringify(compact, null, 2));
+                });
+            },
+        },
+        {
+            name: "kaax_get_analysis",
+            description: "[Pro] Get a single analysis in full detail by its _id. REQUIRES a Pro subscription. Returns every metric plus the report URLs. Use after kaax_list_analyses when the user wants a deeper look.",
+            inputSchema: zodToJsonSchema(GetAnalysisArgs),
+            async handler(args, { client }) {
+                return withPaidTier(client, async () => {
+                    const { id } = GetAnalysisArgs.parse(args);
+                    const page = await client.listAnalyses({ limit: 100 });
+                    const match = page.data.find((r) => r._id === id);
+                    if (!match) {
+                        return text(`No analysis with _id ${id} in the first page. Try a tighter filter (date / tag / name) and re-run kaax_list_analyses.`);
+                    }
+                    return text(JSON.stringify(match, null, 2));
+                });
+            },
+        },
+        // ── Setup & guidance ────────────────────────────────────────────────
+        {
+            name: "kaax_check_setup_status",
+            description: "[Pro] Reports what the user has in their Kaax account (fields, models, custom configs, analyses by type, tags) and what they're missing. REQUIRES a Pro subscription. Call this **first** when the user says they're new or things 'aren't working' AFTER you've confirmed they're on Pro via kaax_check_license.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            async handler(_args, { client }) {
+                return withPaidTier(client, async () => {
+                    // Preferred path — v2 endpoint already computes everything server-side
+                    // (cheaper, accurate, never leaks other users' data).
+                    const v2 = await client.setupStatus();
+                    if (v2) {
+                        const lines = [];
+                        lines.push("📊 Account snapshot");
+                        lines.push(`  • Fields: ${v2.counts.fields}`);
+                        lines.push(`  • Detection models: ${v2.counts.models}`);
+                        lines.push(`  • Custom configurations: ${v2.counts.customConfigurations}`);
+                        lines.push(`  • Tags: ${v2.counts.tags}`);
+                        lines.push(`  • Analyses run: ${v2.counts.analyses}`);
+                        const types = Object.entries(v2.analysesByType);
+                        if (types.length) {
+                            lines.push("  • Fields by analysis type:");
+                            for (const [t, n] of types)
+                                lines.push(`      ${t}: ${n}`);
+                        }
+                        if (v2.topTags.length) {
+                            lines.push("  • Top tags: " +
+                                v2.topTags
+                                    .slice(0, 10)
+                                    .map((t) => `${t.tag} (${t.count})`)
+                                    .join(", "));
+                        }
+                        if (v2.nextSteps.length) {
+                            lines.push("");
+                            lines.push("🧭 Next-step suggestions:");
+                            for (const s of v2.nextSteps) {
+                                const sev = s.severity === "critical" ? "🔴" : s.severity === "warning" ? "🟡" : "ℹ️";
+                                lines.push(`  ${sev} ${s.title}`);
+                                if (s.description)
+                                    lines.push(`      ${s.description}`);
+                                if (s.resource)
+                                    lines.push(`      Resource: ${s.resource}`);
+                                if (s.href)
+                                    lines.push(`      Link: ${s.href}`);
+                            }
+                        }
+                        return text(...lines);
+                    }
+                    // Fallback — v0 aggregation, less accurate but always works.
+                    const all = await client.listAllAnalyses({}, { pageSize: 100, maxPages: 5 });
+                    const byType = groupBy(all.data, (r) => r.analysisType ?? "unknown");
+                    const fields = new Set(all.data.map((r) => r.imageSetId)).size;
+                    const tags = uniqueTags(all.data);
+                    const lines = [];
+                    lines.push(`📊 Account snapshot (sampled ${all.data.length} most-recent analyses)`);
+                    lines.push(`  • Unique fields (imageSets): ${fields}`);
+                    lines.push(`  • Tags in use: ${tags.length}${tags.length ? " — " + tags.slice(0, 10).join(", ") : ""}`);
+                    lines.push(`  • By analysis type:`);
+                    for (const t of ["replanting", "counting", "path", "unknown"]) {
+                        lines.push(`      ${t}: ${(byType[t] ?? []).length}`);
+                    }
+                    lines.push("");
+                    lines.push("🧭 Next-step suggestions:");
+                    if (all.data.length === 0) {
+                        lines.push("  • Zero analyses — point the user to the 30-min tutorial.");
+                        lines.push("  • Resource: kaax://docs/quickstart");
+                    }
+                    if (fields > 0 && tags.length === 0) {
+                        lines.push("  • Fields without tags. Suggest a tag taxonomy with kaax_suggest_tags_for_field.");
+                    }
+                    if ((byType.replanting?.length ?? 0) === 0 && (byType.counting?.length ?? 0) === 0) {
+                        lines.push("  • No replanting/counting runs. The user probably needs to upload a model first — kaax://docs/models.");
+                    }
+                    if (tags.length > 0 && tags.length < 3) {
+                        lines.push("  • Few tags — encourage organising by season + region + crop. See kaax://docs/tags.");
+                    }
+                    return text(...lines);
+                });
+            },
+        },
+        // ── Tags & organisation ────────────────────────────────────────────
+        {
+            name: "kaax_list_tags",
+            description: "[Pro] Returns every tag currently in use across the user's analyses, with usage counts. REQUIRES a Pro subscription. Useful to understand how their data is already organised before suggesting more tags.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            async handler(_args, { client }) {
+                return withPaidTier(client, async () => {
+                    const all = await client.listAllAnalyses({}, { pageSize: 100, maxPages: 5 });
+                    const counts = new Map();
+                    for (const r of all.data) {
+                        for (const tagValue of r.tag ?? [])
+                            counts.set(tagValue, (counts.get(tagValue) ?? 0) + 1);
+                    }
+                    if (counts.size === 0) {
+                        return text("No tags found across the recent analyses.", "", "Suggest creating a basic taxonomy:", "  • season — e.g. zafra-2024", "  • region — e.g. escuintla", "  • crop   — e.g. cana, pina", "", "Call kaax_suggest_tags_for_field with the user's field name for tailored suggestions.");
+                    }
+                    const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+                    return text("Tags in use (descending frequency):", ...sorted.map(([tagValue, n]) => `  • ${tagValue} — ${n}`), "", "If two tags carry the same meaning, suggest the user merge them in /dashboard/manage.");
+                });
+            },
+        },
+        {
+            name: "kaax_suggest_tags_for_field",
+            description: "[Free] Given a field name, crop and/or region, returns a concise list of recommended tags following Kaax's best practices (season + region + crop + lifecycle). Pure heuristic, no API call — works on the Free tier.",
+            inputSchema: zodToJsonSchema(SuggestTagsArgs),
+            async handler(args) {
+                try {
+                    const { fieldName, crop, region } = SuggestTagsArgs.parse(args);
+                    const year = new Date().getFullYear();
+                    const slug = (s) => s
+                        .toLowerCase()
+                        .normalize("NFD")
+                        .replace(/[̀-ͯ]/g, "")
+                        .replace(/[^a-z0-9]+/g, "-")
+                        .replace(/^-|-$/g, "");
+                    const suggestions = [
+                        `zafra-${year}`,
+                        crop ? `cultivo-${slug(crop)}` : "cultivo-cana",
+                        region ? `region-${slug(region)}` : undefined,
+                        `parcela-${slug(fieldName)}`,
+                        "estado-activo",
+                    ].filter(Boolean);
+                    return text("Suggested tags for this field (apply 2–4 of these):", ...suggestions.map((t) => `  • ${t}`), "", "Naming rules:", "  • lowercase, no accents, hyphenated", "  • prefix by axis (zafra-, region-, cultivo-, estado-)", "  • combine tags in filters to slice across axes", "", "Apply them at /dashboard/manage → Etiquetas. See also kaax://docs/tags.");
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        // ── Configuration suggestions ──────────────────────────────────────
+        {
+            name: "kaax_suggest_configuration",
+            description: "[Free] Returns a recommended advanced-configuration preset for a given analysis type. Pure heuristic, no API call — works on the Free tier. The preset reflects the defaults that most Kaax users converge on after iteration. Use it as a starting point — never as final values.",
+            inputSchema: zodToJsonSchema(SuggestConfigArgs),
+            async handler(args) {
+                try {
+                    const { analysisType, crop, goal = "balanced" } = SuggestConfigArgs.parse(args);
+                    const presets = {
+                        counting: {
+                            blockSize: 2048,
+                            accuracy: 0.25,
+                            postProcessing: {
+                                refinement: true,
+                                radiusFactor: 0.8,
+                                iou: 0.2,
+                            },
+                            sizeClassification: {
+                                smallMax: 0.05,
+                                mediumMax: 0.15,
+                                largeMax: 0.3,
+                            },
+                        },
+                        replanting: {
+                            blockSize: 2048,
+                            accuracy: 0.25,
+                            lineThickness: 1.5,
+                            seedsPerMeter: 3.75,
+                            seedsPerBox: 30,
+                            postProcessing: { refinement: true, iou: 0.2 },
+                        },
+                        path: {
+                            blockSize: 2048,
+                            accuracy: 0.3,
+                            overlap: 0.1,
+                        },
+                    };
+                    const config = JSON.parse(JSON.stringify(presets[analysisType]));
+                    // Goal tweaks — affect recall/precision trade-off knobs.
+                    if (goal === "high_recall") {
+                        config.accuracy = 0.18;
+                        if (config.postProcessing)
+                            config.postProcessing.iou = 0.15;
+                    }
+                    else if (goal === "high_precision") {
+                        config.accuracy = 0.35;
+                        if (config.postProcessing)
+                            config.postProcessing.iou = 0.3;
+                    }
+                    return text(`Recommended ${analysisType} configuration (goal: ${goal}${crop ? `, crop: ${crop}` : ""}):`, "", JSON.stringify(config, null, 2), "", "Apply at /dashboard/manage → Configuración Avanzada.", "If results undershoot, increase recall (lower accuracy + lower IoU). Overshoot → opposite.", "Use kaax_explain_advanced_config for any parameter you're not sure about.");
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_explain_advanced_config",
+            description: "[Free] Plain-language explanation of one advanced-configuration parameter. Static docs, no API call — works on the Free tier.",
+            inputSchema: zodToJsonSchema(ExplainParameterArgs),
+            async handler(args) {
+                try {
+                    const { parameter } = ExplainParameterArgs.parse(args);
+                    const guide = {
+                        blockSize: "Side length (px) of the tile fed to the model. Larger = more context but slower and more memory. Default 2048 works for drone orthomosaics; raise to 4096 only on very high-res inputs.",
+                        accuracy: "Confidence threshold at which a detection is kept. Lower = more recall (fewer misses, more false positives). Higher = more precision. Safe range 0.18–0.4; default 0.25.",
+                        iou: "Intersection-over-Union threshold for deduplication. Two detections overlapping above IoU are merged. Lower = remove more duplicates (risk under-counting). Higher = keep more (risk double-counting). Default 0.2.",
+                        radiusFactor: "Radius multiplier (× plant size) used to search for duplicate neighbours. Smaller misses overlaps; larger over-merges. Default 0.8.",
+                        overlap: "Fractional overlap between processing tiles. Higher overlap reduces seam artefacts on object boundaries but costs more compute. Default 0.1.",
+                        smallMax: "Upper bound (m²) for the 'very small' size bucket in counting size-classification. Anything ≤ this is counted as very small.",
+                        mediumMax: "Upper bound (m²) for the 'medium' size bucket. Adjust together with smallMax/largeMax so buckets cover the expected plant-area distribution.",
+                        largeMax: "Upper bound (m²) for the 'large' size bucket. Anything above is unclassified.",
+                        seedsPerMeter: "Replanting calculation: how many seeds are sown per linear meter of furrow. Defaults to your crop's agronomic guide.",
+                        seedsPerBox: "Replanting calculation: seeds per packaging unit. Used to translate seed counts back into purchase orders.",
+                    };
+                    const note = guide[parameter] || "No description available.";
+                    return text(`Parameter: ${parameter}`, "", note);
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        // ── Spatial intelligence ───────────────────────────────────────────
+        {
+            name: "kaax_find_similar_fields",
+            description: "[Pro] Given an analysis _id, returns the most similar analyses from the user's history. REQUIRES a Pro subscription. Uses metric cosine similarity, weighted by geographic proximity when KML centroids are available. Surface this when the user asks 'which of my fields look like this one' or 'where else have I seen this pattern'.",
+            inputSchema: zodToJsonSchema(FindSimilarArgs),
+            async handler(args, { client }) {
+                return withPaidTier(client, async () => {
+                    const { analysisId, topK = 5 } = FindSimilarArgs.parse(args);
+                    const all = await client.listAllAnalyses({}, { pageSize: 100, maxPages: 5 });
+                    const ref = all.data.find((r) => r._id === analysisId);
+                    if (!ref) {
+                        return text(`Analysis ${analysisId} not found in the most recent 500 records. Ask the user to widen the search or filter by tag.`);
+                    }
+                    const neighbours = findSimilar(ref, all.data, topK);
+                    if (neighbours.length === 0) {
+                        return text("No similar analyses found — pool is too small.");
+                    }
+                    return text(`Reference: ${ref.name ?? ref._id} (${ref.analysisType})`, "", "Top similar analyses:", ...neighbours.map((n, i) => `  ${i + 1}. ${n.record.name ?? n.record._id} · score ${n.score.toFixed(3)}${n.distanceKm !== undefined ? ` · ${n.distanceKm.toFixed(2)} km` : ""}`), "", "Use kaax_get_analysis with any of these IDs to dig into the metrics.");
+                });
+            },
+        },
+        {
+            name: "kaax_get_density_stats",
+            description: "[Pro] Aggregates density and rate stats across the user's analyses. REQUIRES a Pro subscription. Returns total area, total detections, detections/ha, and average survival/depopulation/replanting rates.",
+            inputSchema: zodToJsonSchema(DensityStatsArgs),
+            async handler(args, { client }) {
+                return withPaidTier(client, async () => {
+                    const filters = DensityStatsArgs.parse(args);
+                    const all = await client.listAllAnalyses(filters, { pageSize: 100, maxPages: 10 });
+                    const stats = aggregateDensity(all.data);
+                    return text(`Density stats across ${stats.count} analyses${filters.tag ? ` · tag=${filters.tag}` : ""}${filters.type ? ` · type=${filters.type}` : ""}`, "", JSON.stringify(stats, null, 2));
+                });
+            },
+        },
+        // ── v2 fields / tags / models ─────────────────────────────────────
+        {
+            name: "kaax_list_fields",
+            description: "[Pro] List the user's fields (imageSets) with their tags, analysis type and whether they already have geometry attached. REQUIRES a Pro subscription. Use this when the user asks 'which fields do I have' — it's cheaper than listing analyses because it skips report data.",
+            inputSchema: zodToJsonSchema(z.object({
+                tag: z.string().optional(),
+                type: AnalysisTypeSchema.optional(),
+                q: z.string().optional().describe("Substring match on field name"),
+                page: z.number().int().min(1).optional(),
+                limit: z.number().int().min(1).max(100).optional(),
+            })),
+            async handler(args, { client }) {
+                return withPaidTier(client, async () => {
+                    const parsed = z
+                        .object({
+                        tag: z.string().optional(),
+                        type: AnalysisTypeSchema.optional(),
+                        q: z.string().optional(),
+                        page: z.number().int().min(1).optional(),
+                        limit: z.number().int().min(1).max(100).optional(),
+                    })
+                        .parse(args);
+                    const page = await client.listFields(parsed);
+                    if (!page) {
+                        return text("The v2 /fields endpoint is not available on this Kaax deployment. Fall back to kaax_list_analyses.");
+                    }
+                    if (page.data.length === 0) {
+                        return text("No fields match those filters. If the user has not uploaded any yet, point them at kaax://docs/quickstart.");
+                    }
+                    return text(`Found ${page.total} fields · returning ${page.data.length} on page ${page.page}.`, "", JSON.stringify(page.data, null, 2));
+                });
+            },
+        },
+        {
+            name: "kaax_list_models",
+            description: "[Pro] Returns every detection model the user has uploaded. REQUIRES a Pro subscription. Models are required for replanting & counting analyses — call this whenever the user reports 'I can't analyse' or 'why is the run failing'.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            async handler(_args, { client }) {
+                return withPaidTier(client, async () => {
+                    const models = await client.listModels();
+                    if (!models) {
+                        return text("The v2 /models endpoint is not available on this Kaax deployment. Ask the user to check their /dashboard/models page directly.");
+                    }
+                    if (models.total === 0) {
+                        return text("No detection models uploaded yet — counting & replanting analyses will fail until at least one is present.", "", "Send the user to the tutorial: kaax://docs/models");
+                    }
+                    return text(`Detection models (${models.total}):`, "", ...models.data.map((m) => `  • ${m.name} · type=${m.type ?? "unknown"} · id=${m.id}`));
+                });
+            },
+        },
+        {
+            name: "kaax_attach_field_tags",
+            description: "[Pro] Attach one or more tags to a field. REQUIRES a Pro subscription. Server normalises (lowercase, deburred, hyphenated) and dedups. Use after kaax_suggest_tags_for_field to actually persist the suggestion.",
+            inputSchema: zodToJsonSchema(AttachTagsArgs),
+            async handler(args, { client }) {
+                return withPaidTier(client, async () => {
+                    const { fieldId, tags } = AttachTagsArgs.parse(args);
+                    const result = await client.attachFieldTags(fieldId, tags);
+                    if (!result) {
+                        return text("Write endpoint not available on this Kaax deployment. The user can apply tags manually at /dashboard/manage → Etiquetas.");
+                    }
+                    return text(`✅ Field ${result.fieldId} now has ${result.tags.length} tag(s):`, "  " + result.tags.join(", "));
+                });
+            },
+        },
+        {
+            name: "kaax_peer_config_suggestions",
+            description: "[Pro] Returns an anonymised average of advanced-configuration parameters used by other Kaax users for the requested analysis type. REQUIRES a Pro subscription. Privacy-preserving (excludes the caller, requires a minimum number of distinct peers, bucketed values). Use this **alongside** kaax_suggest_configuration so the user gets both the curated preset and the crowd-sourced reference.",
+            inputSchema: zodToJsonSchema(PeerSuggestionsArgs),
+            async handler(args, { client }) {
+                return withPaidTier(client, async () => {
+                    const { type } = PeerSuggestionsArgs.parse(args);
+                    const result = await client.peerSuggestions(type);
+                    if (!result) {
+                        return text("The peer-suggestions endpoint is not available on this Kaax deployment. Use kaax_suggest_configuration to get the curated preset instead.");
+                    }
+                    if (!result.suggestion) {
+                        return text(`Not enough anonymised samples yet (have ${result.samples}, need ${result.minRequired ?? "more"}).`, "", "Fall back to kaax_suggest_configuration for the curated preset.");
+                    }
+                    return text(`Peer reference for ${type} (n=${result.samples} anonymised users):`, "", JSON.stringify(result.suggestion, null, 2), "", result.notice ?? "Use this as a starting point, then tune to your crop and region.");
+                });
+            },
+        },
+        // ── Download permission (HubSpot-gated) ──────────────────────────────
+        {
+            name: "kaax_request_download",
+            description: "Request permission to download the Kaax Labeling / Desktop binaries. Submits a HubSpot form server-side using the authenticated user's info. Idempotent: calling twice within 24 hours returns the existing pending request. Use this when the user wants the local labeling / desktop apps.",
+            inputSchema: zodToJsonSchema(RequestDownloadArgs),
+            async handler(args, { client }) {
+                try {
+                    const parsed = RequestDownloadArgs.parse(args);
+                    const result = await client.requestDownload(parsed);
+                    if (result.status === "approved") {
+                        return text("✅ Permission is already granted on this account.", "Call kaax_check_download_status to get the binary URLs.");
+                    }
+                    return text(`⌛ Request submitted${result.idempotent ? " (existing pending request)" : ""}.`, "", result.requestId ? `Request ID: ${result.requestId}` : "", "", result.message ?? "We will notify you by email when an admin approves it.", "", "Poll kaax_check_download_status every minute or so to detect approval.");
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_check_download_status",
+            description: "Check the status of the user's download-permission request. Returns `pending`, `approved`, `rejected`, `not_requested`, or `needs_activation`. When approved, the response includes the latest stable binary URLs.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            async handler(_args, { client }) {
+                try {
+                    const result = await client.downloadStatus();
+                    if (result.status === "approved") {
+                        const labeling = result.binaries.kaaxLabeling;
+                        const desktop = result.binaries.kaaxDesktop;
+                        return text("✅ Download permission granted.", "", labeling
+                            ? `Kaax Labeling · v${labeling.version ?? "?"} · ${labeling.fileName}\n  ${labeling.url}`
+                            : "Kaax Labeling · no stable build available", "", desktop
+                            ? `Kaax Desktop · v${desktop.version ?? "?"} · ${desktop.fileName}\n  ${desktop.url}`
+                            : "Kaax Desktop · no stable build available", "", "Use kaax_download_kaax to fetch a binary directly to disk.");
+                    }
+                    if (result.status === "needs_activation") {
+                        return text("⚠️ Activate your account via the email we sent before downloads can be granted.");
+                    }
+                    if (result.status === "rejected") {
+                        return text(`❌ Request rejected${result.rejectedReason ? `: ${result.rejectedReason}` : "."}`, "Reach out to support if you think this is a mistake.");
+                    }
+                    if (result.status === "not_requested") {
+                        return text("ℹ️ No download request on file. Call kaax_request_download first.");
+                    }
+                    return text("⌛ Request still pending. Try again in a minute or two.", result.requestId ? `Request ID: ${result.requestId}` : "");
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_download_kaax",
+            description: "Download a Kaax binary (kaaxLabeling or kaaxDesktop) directly to disk. Requires that the user has been approved for downloads. Defaults to the user's home Downloads folder unless an outputDir is provided. Streams the file — never buffers it in memory.",
+            inputSchema: zodToJsonSchema(DownloadKaaxArgs),
+            async handler(args, { client }) {
+                try {
+                    const { product, outputDir } = DownloadKaaxArgs.parse(args);
+                    const status = await client.downloadStatus();
+                    if (status.status !== "approved") {
+                        return text(`❌ Cannot download: status is "${status.status}". Run kaax_request_download → kaax_check_download_status first.`);
+                    }
+                    const info = status.binaries[product];
+                    if (!info) {
+                        return text(`❌ No stable build is currently published for ${product}. Try again later or pick the other product.`);
+                    }
+                    const destDir = outputDir || join(homedir(), "Downloads");
+                    const destPath = join(destDir, info.fileName);
+                    const result = await downloadFile(info.url, destPath);
+                    return text(`✅ Downloaded ${product} → ${result.outputPath}`, `Size: ${(result.bytesWritten / 1024 / 1024).toFixed(1)} MB`, info.version ? `Version: ${info.version}` : "", "", "On Windows, you may need to right-click → Properties → Unblock the .exe before running it.");
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        // ── Data conversion ────────────────────────────────────────────────
+        {
+            name: "kaax_convert_shapefile_to_kml",
+            description: "[Free] Converts a local Shapefile (.shp + .dbf) into a Kaax-compatible KML 2.2 file. Runs entirely on the user's machine — no API call, no Pro subscription needed. Returns the output path and any per-feature warnings. Call this when the user mentions shapefiles, .shp, ESRI files, or asks 'how do I import a shp into Kaax'.",
+            inputSchema: zodToJsonSchema(ConvertShpArgs),
+            async handler(args) {
+                try {
+                    const { shpPath, outputPath } = ConvertShpArgs.parse(args);
+                    const result = await convertShapefileToKml(shpPath, outputPath);
+                    const lines = [
+                        `✅ Wrote ${result.featuresWritten} features to ${result.outputPath}`,
+                    ];
+                    if (result.warnings.length) {
+                        lines.push("", "Warnings:");
+                        for (const w of result.warnings)
+                            lines.push(`  • ${w}`);
+                    }
+                    lines.push("", "Next: upload the .kml at /dashboard/manage → Tus Campos → Nuevo campo.");
+                    return text(...lines);
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+    ];
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Tiny zod-to-json-schema (we only use the shapes the MCP needs).
+// Keeps us off a heavier dep.
+// ─────────────────────────────────────────────────────────────────────────
+function zodToJsonSchema(schema) {
+    if (schema instanceof z.ZodObject) {
+        const shape = schema.shape;
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            properties[key] = zodToJsonSchema(value);
+            if (!value.isOptional())
+                required.push(key);
+        }
+        return {
+            type: "object",
+            properties,
+            ...(required.length ? { required } : {}),
+            additionalProperties: false,
+        };
+    }
+    if (schema instanceof z.ZodString) {
+        const out = { type: "string" };
+        if (schema.description)
+            out.description = schema.description;
+        return out;
+    }
+    if (schema instanceof z.ZodNumber) {
+        const out = { type: "number" };
+        if (schema.description)
+            out.description = schema.description;
+        return out;
+    }
+    if (schema instanceof z.ZodBoolean) {
+        return { type: "boolean" };
+    }
+    if (schema instanceof z.ZodEnum) {
+        const out = {
+            type: "string",
+            enum: schema.options,
+        };
+        if (schema.description)
+            out.description = schema.description;
+        return out;
+    }
+    if (schema instanceof z.ZodOptional) {
+        return zodToJsonSchema(schema.unwrap());
+    }
+    if (schema instanceof z.ZodUnion) {
+        return {
+            oneOf: schema.options.map(zodToJsonSchema),
+            ...(schema.description ? { description: schema.description } : {}),
+        };
+    }
+    return {}; // permissive fallback
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────
+function groupBy(items, key) {
+    return items.reduce((acc, item) => {
+        const k = key(item);
+        (acc[k] ||= []).push(item);
+        return acc;
+    }, {});
+}
+function uniqueTags(records) {
+    const set = new Set();
+    for (const r of records)
+        for (const t of r.tag ?? [])
+            set.add(t);
+    return [...set];
+}
+//# sourceMappingURL=tools.js.map