kaax-mcp 0.1.0

package/dist/i18n.js

@@ -0,0 +1,98 @@
+/**
+ * Tiny i18n — user-facing strings that the agent passes through verbatim.
+ *
+ * The agent (Claude) translates fluently on its own, but messages that
+ * users tend to copy/paste (URLs, codes, file paths, "your account is
+ * locked" stubs) we localize directly so they read native instead of
+ * machine-translated.
+ *
+ * Selection:
+ *   1. `KAAX_LOCALE` env var ("es" | "en"). Defaults to "es" because the
+ *      Kaax user base is overwhelmingly Spanish-speaking.
+ *   2. Falls back to "es" for unknown locales rather than English so we
+ *      never accidentally surface English to a Spanish-speaking user.
+ */
+export function getLocale() {
+    const raw = (process.env.KAAX_LOCALE || "es").toLowerCase().trim();
+    if (raw === "en")
+        return "en";
+    return "es";
+}
+// Centralised dictionary. Add new keys here rather than scattering literal
+// strings across tools.ts.
+const dict = {
+    proRequired_title: {
+        es: "Esta acción requiere suscripción Pro",
+        en: "This action requires a Pro subscription",
+    },
+    proRequired_body: {
+        es: "Tu plan actual es Free y no incluye acceso al API de Kaax. Para listar campos, modelos, análisis o configuraciones tenés que activar Pro.",
+        en: "Your current plan is Free and does not include Kaax API access. To list fields, models, analyses or configurations you need to activate Pro.",
+    },
+    proRequired_cta: {
+        es: "Llama a `kaax_open_billing` para abrir la página de planes, o ve a {url}.",
+        en: "Call `kaax_open_billing` to open the plans page, or visit {url}.",
+    },
+    freeAvailable_header: {
+        es: "Mientras tanto, en el plan Free podés:",
+        en: "In the meantime, on the Free plan you can:",
+    },
+    freeAvailable_items: {
+        es: [
+            "Crear cuenta y activarla (kaax_start_onboarding)",
+            "Solicitar y descargar las apps de escritorio (kaax_request_download, kaax_download_kaax)",
+            "Convertir shapefiles a KML localmente (kaax_convert_shapefile_to_kml)",
+            "Recibir sugerencias de tags y configuraciones (kaax_suggest_tags_for_field, kaax_suggest_configuration)",
+            "Leer la documentación (kaax://docs/*)",
+        ],
+        en: [
+            "Create an account and activate it (kaax_start_onboarding)",
+            "Request and download the desktop apps (kaax_request_download, kaax_download_kaax)",
+            "Convert shapefiles to KML locally (kaax_convert_shapefile_to_kml)",
+            "Get tag and configuration suggestions (kaax_suggest_tags_for_field, kaax_suggest_configuration)",
+            "Read the documentation (kaax://docs/*)",
+        ],
+    },
+    needsActivation: {
+        es: "Activá tu cuenta haciendo clic en el enlace del correo que te enviamos antes de continuar.",
+        en: "Activate your account by clicking the link in the email we sent you before continuing.",
+    },
+    missingApiKey: {
+        es: "No hay KAAX_API_KEY configurado. Si no tenés cuenta, llamá a `kaax_start_onboarding`. Si ya tenés, configurá la variable en el cliente MCP y reiniciá.",
+        en: "KAAX_API_KEY is not configured. If you have no account, call `kaax_start_onboarding`. Otherwise, set the env var in your MCP client config and restart.",
+    },
+    invalidApiKey: {
+        es: "El apiKey configurado no es válido. Revisá tu config del MCP o emití uno nuevo en /dashboard/api-manage.",
+        en: "The configured apiKey is invalid. Check your MCP config or issue a new key at /dashboard/api-manage.",
+    },
+    rateLimited: {
+        es: "Demasiadas solicitudes en poco tiempo. Esperá un momento y volvé a intentar.",
+        en: "Too many requests in a short time. Wait a moment and try again.",
+    },
+    network: {
+        es: "Error de red al hablar con Kaax. Verificá tu conexión y volvé a intentar.",
+        en: "Network error talking to Kaax. Check your connection and retry.",
+    },
+};
+/** Look up a translated phrase, optionally with `{placeholder}` substitution. */
+export function t(key, vars) {
+    const locale = getLocale();
+    const entry = dict[key];
+    let value = entry[locale] ?? entry.es;
+    if (vars) {
+        for (const [k, v] of Object.entries(vars)) {
+            value = value.replace(new RegExp(`\\{${k}\\}`, "g"), v);
+        }
+    }
+    return value;
+}
+/** Array variant — for bullet lists. */
+export function tList(key) {
+    const locale = getLocale();
+    const entry = dict[key];
+    if (Array.isArray(entry.es)) {
+        return (entry[locale] ?? entry.es);
+    }
+    return [];
+}
+//# sourceMappingURL=i18n.js.map

package/dist/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,UAAU,SAAS;IACvB,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IACnE,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,IAAI,CAAC;AACd,CAAC;AAOD,2EAA2E;AAC3E,2BAA2B;AAC3B,MAAM,IAAI,GAAG;IACX,iBAAiB,EAAE;QACjB,EAAE,EAAE,sCAAsC;QAC1C,EAAE,EAAE,yCAAyC;KAC9C;IACD,gBAAgB,EAAE;QAChB,EAAE,EAAE,2IAA2I;QAC/I,EAAE,EAAE,8IAA8I;KACnJ;IACD,eAAe,EAAE;QACf,EAAE,EAAE,2EAA2E;QAC/E,EAAE,EAAE,kEAAkE;KACvE;IACD,oBAAoB,EAAE;QACpB,EAAE,EAAE,wCAAwC;QAC5C,EAAE,EAAE,4CAA4C;KACjD;IACD,mBAAmB,EAAE;QACnB,EAAE,EAAE;YACF,kDAAkD;YAClD,0FAA0F;YAC1F,uEAAuE;YACvE,yGAAyG;YACzG,uCAAuC;SACxC;QACD,EAAE,EAAE;YACF,2DAA2D;YAC3D,mFAAmF;YACnF,mEAAmE;YACnE,iGAAiG;YACjG,wCAAwC;SACzC;KACF;IACD,eAAe,EAAE;QACf,EAAE,EAAE,4FAA4F;QAChG,EAAE,EAAE,wFAAwF;KAC7F;IACD,aAAa,EAAE;QACb,EAAE,EAAE,wJAAwJ;QAC5J,EAAE,EAAE,yJAAyJ;KAC9J;IACD,aAAa,EAAE;QACb,EAAE,EAAE,0GAA0G;QAC9G,EAAE,EAAE,sGAAsG;KAC3G;IACD,WAAW,EAAE;QACX,EAAE,EAAE,8EAA8E;QAClF,EAAE,EAAE,iEAAiE;KACtE;IACD,OAAO,EAAE;QACP,EAAE,EAAE,2EAA2E;QAC/E,EAAE,EAAE,iEAAiE;KACtE;CACgE,CAAC;AAIpE,iFAAiF;AACjF,MAAM,UAAU,CAAC,CAAC,GAAY,EAAE,IAA6B;IAC3D,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAW,CAAC;IAClC,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;IACtC,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,KAAK,CAAC,GAAY;IAChC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAmC,CAAC;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAa,CAAC;IACjD,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Kaax MCP server entry point.
+ *
+ * Starts a stdio-transport MCP server that exposes the Kaax API plus a
+ * handful of agent-friendly heuristics (tag suggestions, configuration
+ * presets, peer-averaged configs, similarity search, shapefile conversion).
+ *
+ * Configuration:
+ *   • KAAX_API_KEY  (required) — issued at /dashboard/api-manage.
+ *   • KAAX_BASE_URL (optional) — defaults to https://www.kaax-agritech.com.
+ *
+ * The server logs to stderr only — the LLM never sees logs, only tool
+ * outputs.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Kaax MCP server entry point.
+ *
+ * Starts a stdio-transport MCP server that exposes the Kaax API plus a
+ * handful of agent-friendly heuristics (tag suggestions, configuration
+ * presets, peer-averaged configs, similarity search, shapefile conversion).
+ *
+ * Configuration:
+ *   • KAAX_API_KEY  (required) — issued at /dashboard/api-manage.
+ *   • KAAX_BASE_URL (optional) — defaults to https://www.kaax-agritech.com.
+ *
+ * The server logs to stderr only — the LLM never sees logs, only tool
+ * outputs.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { KaaxClient } from "./client.js";
+import { buildTools } from "./tools.js";
+import { buildResources } from "./resources.js";
+import { buildPrompts } from "./prompts.js";
+const SERVER_NAME = "kaax-mcp";
+const SERVER_VERSION = "0.1.0";
+function bail(msg) {
+    // stderr only — MCP clients pipe stdout for protocol traffic.
+    process.stderr.write(`[${SERVER_NAME}] ${msg}\n`);
+    process.exit(1);
+}
+async function main() {
+    // KAAX_API_KEY is OPTIONAL. The MCP must be able to boot without it so a
+    // brand-new user can run `kaax_start_onboarding` to provision an account
+    // and acquire a key from inside the agent conversation. Once acquired,
+    // the client late-binds via `setApiKey`.
+    const apiKey = process.env.KAAX_API_KEY?.trim() || undefined;
+    const baseUrl = process.env.KAAX_BASE_URL?.trim() || undefined;
+    const client = new KaaxClient({ apiKey, baseUrl });
+    const tools = buildTools();
+    const resources = buildResources();
+    const prompts = buildPrompts();
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+        },
+    });
+    // ── Tools ───────────────────────────────────────────────────────────────
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = tools.find((t) => t.name === req.params.name);
+        if (!tool) {
+            return {
+                content: [
+                    { type: "text", text: `Unknown tool: ${req.params.name}` },
+                ],
+                isError: true,
+            };
+        }
+        return tool.handler(req.params.arguments ?? {}, { client });
+    });
+    // ── Resources ──────────────────────────────────────────────────────────
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: resources.map((r) => r.resource),
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const match = resources.find((r) => r.resource.uri === req.params.uri);
+        if (!match) {
+            throw new Error(`Unknown resource: ${req.params.uri}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: match.resource.uri,
+                    mimeType: match.resource.mimeType ?? "text/plain",
+                    text: match.text,
+                },
+            ],
+        };
+    });
+    // ── Prompts ────────────────────────────────────────────────────────────
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: prompts.map((p) => p.prompt),
+    }));
+    server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+        const match = prompts.find((p) => p.prompt.name === req.params.name);
+        if (!match) {
+            throw new Error(`Unknown prompt: ${req.params.name}`);
+        }
+        return match.build((req.params.arguments ?? {}));
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const keyState = client.hasApiKey() ? "configured" : "missing (onboarding mode)";
+    process.stderr.write(`[${SERVER_NAME}] v${SERVER_VERSION} ready · tools=${tools.length} resources=${resources.length} prompts=${prompts.length} · apiKey=${keyState}\n`);
+}
+main().catch((err) => {
+    bail(`fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/platform.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cross-platform helpers — kept tiny and dependency-free so the MCP server
+ * stays slim. We deliberately avoid the `open` npm package to keep the
+ * dependency tree auditable.
+ */
+/**
+ * Open a URL in the user's default browser. Fire-and-forget — never throws.
+ *
+ * - Windows: spawns `cmd /c start "" <url>`. The empty title arg is required
+ *   because `start` treats the first quoted arg as the window title.
+ * - macOS:   spawns `open <url>`.
+ * - Linux:   spawns `xdg-open <url>`.
+ *
+ * Child processes are detached and unref'd so the MCP process exits cleanly
+ * even if the browser is still running.
+ */
+export declare function openBrowser(url: string): {
+    spawned: boolean;
+    platform: string;
+};
+/**
+ * Download a remote file to disk with bounded resource use:
+ *   - Connect timeout enforced via AbortController.
+ *   - Streams the response body directly to disk (no full-buffer in memory).
+ *   - Refuses to write outside the user's intended directory tree (the
+ *     parent must already exist OR we create it via mkdir -p first).
+ *   - Caller controls the destination path — we never derive a path from
+ *     a server-supplied Content-Disposition.
+ */
+export interface DownloadResult {
+    bytesWritten: number;
+    outputPath: string;
+    contentType?: string;
+}
+export declare function downloadFile(url: string, outputPath: string, opts?: {
+    timeoutMs?: number;
+}): Promise<DownloadResult>;

package/dist/platform.js

@@ -0,0 +1,72 @@
+/**
+ * Cross-platform helpers — kept tiny and dependency-free so the MCP server
+ * stays slim. We deliberately avoid the `open` npm package to keep the
+ * dependency tree auditable.
+ */
+import { spawn } from "child_process";
+import { createWriteStream } from "fs";
+import { mkdir, stat } from "fs/promises";
+import { dirname } from "path";
+import { pipeline } from "stream/promises";
+import { fetch } from "undici";
+/**
+ * Open a URL in the user's default browser. Fire-and-forget — never throws.
+ *
+ * - Windows: spawns `cmd /c start "" <url>`. The empty title arg is required
+ *   because `start` treats the first quoted arg as the window title.
+ * - macOS:   spawns `open <url>`.
+ * - Linux:   spawns `xdg-open <url>`.
+ *
+ * Child processes are detached and unref'd so the MCP process exits cleanly
+ * even if the browser is still running.
+ */
+export function openBrowser(url) {
+    const platform = process.platform;
+    try {
+        let child;
+        if (platform === "win32") {
+            child = spawn("cmd", ["/c", "start", "", url], {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true,
+            });
+        }
+        else if (platform === "darwin") {
+            child = spawn("open", [url], { detached: true, stdio: "ignore" });
+        }
+        else {
+            child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+        }
+        child.unref();
+        return { spawned: true, platform };
+    }
+    catch (err) {
+        process.stderr.write(`[kaax-mcp] openBrowser failed on ${platform}: ${err.message}\n`);
+        return { spawned: false, platform };
+    }
+}
+export async function downloadFile(url, outputPath, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5 * 60_000; // 5 min
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        // Make sure the destination directory exists.
+        await mkdir(dirname(outputPath), { recursive: true });
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok || !res.body) {
+            throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+        }
+        const sink = createWriteStream(outputPath);
+        await pipeline(res.body, sink);
+        const st = await stat(outputPath);
+        return {
+            bytesWritten: st.size,
+            outputPath,
+            contentType: res.headers.get("content-type") ?? undefined,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"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"}

package/dist/prompts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Guided prompts — pre-canned conversation starters the agent can offer the
+ * user. Each prompt expands to a short instruction block that nudges the
+ * agent through a known-good Kaax flow without re-deriving it from scratch.
+ */
+import type { Prompt, GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
+interface PromptDef {
+    prompt: Prompt;
+    build: (args: Record<string, string>) => GetPromptResult;
+}
+export declare function buildPrompts(): PromptDef[];
+export {};

package/dist/prompts.js

@@ -0,0 +1,185 @@
+/**
+ * Guided prompts — pre-canned conversation starters the agent can offer the
+ * user. Each prompt expands to a short instruction block that nudges the
+ * agent through a known-good Kaax flow without re-deriving it from scratch.
+ */
+export function buildPrompts() {
+    return [
+        {
+            prompt: {
+                name: "kaax_quickstart",
+                description: "Walk a new user through setting up Kaax from zero to first analysis.",
+                arguments: [
+                    {
+                        name: "crop",
+                        description: "Crop type (sugarcane, pineapple, banana, oil palm…)",
+                        required: false,
+                    },
+                    {
+                        name: "region",
+                        description: "Region or country — used to seed regional tags.",
+                        required: false,
+                    },
+                ],
+            },
+            build: (args) => ({
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                "I'm new to Kaax. Walk me through getting from zero to my first analysis.",
+                                args.crop ? `Crop: ${args.crop}.` : "",
+                                args.region ? `Region: ${args.region}.` : "",
+                                "",
+                                "Please:",
+                                "1. Call kaax_check_setup_status first so we know what's missing.",
+                                "2. Read kaax://docs/quickstart for the canonical walkthrough.",
+                                "3. If I have no model, point me at kaax://docs/models.",
+                                "4. Propose 3–4 tags via kaax_suggest_tags_for_field for my first parcel.",
+                                "5. Suggest the right configuration with kaax_suggest_configuration once I pick an analysis type.",
+                                "Be concise — list the next concrete action at the end.",
+                            ]
+                                .filter(Boolean)
+                                .join("\n"),
+                        },
+                    },
+                ],
+            }),
+        },
+        {
+            prompt: {
+                name: "kaax_analyze_field",
+                description: "Given a field name, queue the right analysis with a sensible config.",
+                arguments: [
+                    { name: "field", description: "Field / parcel name", required: true },
+                    {
+                        name: "analysisType",
+                        description: "replanting / counting / path",
+                        required: true,
+                    },
+                    {
+                        name: "goal",
+                        description: "balanced | high_recall | high_precision",
+                        required: false,
+                    },
+                ],
+            },
+            build: (args) => ({
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                `I want to run a ${args.analysisType} analysis on the parcel "${args.field}".`,
+                                args.goal ? `Goal: ${args.goal}.` : "",
+                                "",
+                                "Please:",
+                                `1. Call kaax_list_fields with q="${args.field}" so we know the field id.`,
+                                "2. Verify a detection model exists via kaax_list_models (skip for path analyses).",
+                                `3. Call kaax_suggest_configuration with analysisType="${args.analysisType}"${args.goal ? `, goal="${args.goal}"` : ""}.`,
+                                `4. Call kaax_peer_config_suggestions with type="${args.analysisType}" and reconcile the two.`,
+                                "5. Return a short summary: field id, model id, final config JSON, and the URL the user should open to actually trigger the run.",
+                            ]
+                                .filter(Boolean)
+                                .join("\n"),
+                        },
+                    },
+                ],
+            }),
+        },
+        {
+            prompt: {
+                name: "kaax_organize_data",
+                description: "Audit the user's tagging hygiene and propose a clean taxonomy.",
+                arguments: [],
+            },
+            build: () => ({
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                "Help me clean up my tag taxonomy.",
+                                "",
+                                "Please:",
+                                "1. Read kaax://docs/tags for the recommended 4-axis taxonomy.",
+                                "2. Call kaax_list_tags to see what I already use.",
+                                "3. Spot collisions (same meaning, different spelling) and singletons that should be merged.",
+                                "4. Propose a final shortlist organised by axis (zafra / region / cultivo / estado).",
+                                "5. For any field I name, call kaax_suggest_tags_for_field then kaax_attach_field_tags to persist.",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+            }),
+        },
+        {
+            prompt: {
+                name: "kaax_onboard_from_zero",
+                description: "Full onboarding flow for someone who has never used Kaax: signup → activate → request download → grab the binary.",
+                arguments: [],
+            },
+            build: () => ({
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                "I have never used Kaax. Walk me through everything end-to-end.",
+                                "",
+                                "Please:",
+                                "1. Call kaax_start_onboarding — this opens the signup page in my browser. Tell me to fill it in and click submit.",
+                                "2. Call kaax_complete_onboarding with the token from step 1. Show me the apiKey when it returns and remind me to save it to KAAX_API_KEY.",
+                                "3. Remind me to click the activation link in the welcome email before continuing.",
+                                "4. Once activated, call kaax_request_download with a short useCase so I get the desktop / labeling apps.",
+                                "5. Poll kaax_check_download_status until approved. Show me what's happening.",
+                                "6. When approved, call kaax_download_kaax for the product I ask for and save it to my Downloads folder.",
+                                "7. Finally call kaax_check_setup_status so I know what to do next inside the dashboard.",
+                                "Be concise — one paragraph per step, not a wall of text.",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+            }),
+        },
+        {
+            prompt: {
+                name: "kaax_import_shapefile",
+                description: "Convert a local shapefile to KML and upload it into Kaax.",
+                arguments: [
+                    {
+                        name: "shpPath",
+                        description: "Absolute path to the .shp file",
+                        required: true,
+                    },
+                ],
+            },
+            build: (args) => ({
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                `I have a shapefile at ${args.shpPath}.`,
+                                "",
+                                "Please:",
+                                "1. Read kaax://docs/shapefile-import so you know the constraints (EPSG:4326, .dbf must be present).",
+                                `2. Call kaax_convert_shapefile_to_kml with shpPath="${args.shpPath}".`,
+                                "3. Tell me the output .kml path and any per-feature warnings.",
+                                "4. Walk me through uploading it at /dashboard/manage → Tus Campos → Nuevo campo.",
+                                "5. Suggest tags for the new field via kaax_suggest_tags_for_field.",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+            }),
+        },
+    ];
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"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"}

package/dist/resources.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Static documentation resources exposed to the agent.
+ *
+ * MCP resources are read-only blobs the agent can fetch by URI. We keep them
+ * embedded in the binary instead of fetching the live web pages so the MCP
+ * server stays usable offline and snappy. The URIs map 1:1 to the references
+ * that the tools above emit (kaax://docs/quickstart, kaax://docs/tags, …) —
+ * if an agent says "see kaax://docs/X" the agent can then call
+ * `resources/read` on that URI to actually consume the doc.
+ */
+import type { Resource } from "@modelcontextprotocol/sdk/types.js";
+interface ResourceDef {
+    resource: Resource;
+    text: string;
+}
+export declare function buildResources(): ResourceDef[];
+export {};