kaax-mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,308 @@
+/**
+ * Thin HTTP client wrapping the public Kaax v0 API.
+ *
+ * The MCP server runs locally on the user's machine and talks to Kaax over
+ * HTTPS using the API key that lives at `/dashboard/api-manage`. We use
+ * `undici.fetch` for the small footprint and Node 18+ compatibility.
+ */
+import { fetch } from "undici";
+const DEFAULT_BASE_URL = "https://www.kaax-agritech.com";
+// ─────────────────────────────────────────────────────────────────────────
+// Onboarding handoff — these endpoints do NOT require an apiKey because
+// the MCP calls them BEFORE the user has signed up. They live outside the
+// `KaaxClient` class because the class invariant is "apiKey is non-empty".
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * POST /api/landing/onboarding-token — issue a 15-minute single-use token.
+ *
+ * The MCP server uses this at the very start of the browser-handoff signup
+ * flow. Returns the opaque token + a hint URL the MCP can `openBrowser` on.
+ */
+export async function issueOnboardingToken(baseUrl = DEFAULT_BASE_URL, source = "mcp") {
+    const url = `${baseUrl.replace(/\/$/, "")}/api/landing/onboarding-token`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ source }),
+    });
+    if (!res.ok) {
+        throw new KaaxAPIError(`Token issue failed: ${res.status}`, res.status, await res.text());
+    }
+    return (await res.json());
+}
+/**
+ * GET /api/landing/onboarding-status?token=… — single poll of the binding
+ * state. Callers (e.g. `pollOnboardingUntilBound`) loop on this with their
+ * own bounded back-off.
+ */
+export async function fetchOnboardingStatus(token, baseUrl = DEFAULT_BASE_URL) {
+    const url = `${baseUrl.replace(/\/$/, "")}/api/landing/onboarding-status?token=${encodeURIComponent(token)}`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+    });
+    if (!res.ok) {
+        throw new KaaxAPIError(`Status check failed: ${res.status}`, res.status, await res.text());
+    }
+    return (await res.json());
+}
+/**
+ * Bounded polling — increasing back-off, hard ceiling on total elapsed time.
+ * Returns the first non-`pending` response. Designed so a stuck MCP can
+ * never hammer the server: cap of ~120 polls over 15 minutes.
+ */
+export async function pollOnboardingUntilBound(token, opts = {}) {
+    const baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+    const maxWaitMs = opts.maxWaitMs ?? 15 * 60_000;
+    const startedAt = Date.now();
+    let delay = opts.initialDelayMs ?? 2_000;
+    const maxDelay = opts.maxDelayMs ?? 8_000;
+    let attempt = 0;
+    while (Date.now() - startedAt < maxWaitMs) {
+        attempt += 1;
+        const state = await fetchOnboardingStatus(token, baseUrl);
+        opts.onTick?.(state, attempt);
+        if (state.status !== "pending")
+            return state;
+        await new Promise((r) => setTimeout(r, delay));
+        // Increase delay up to the ceiling — keeps polling gentle.
+        delay = Math.min(Math.round(delay * 1.4), maxDelay);
+    }
+    return { status: "expired" };
+}
+export class KaaxAPIError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "KaaxAPIError";
+    }
+}
+export class KaaxClient {
+    /** May be undefined while the user has not finished onboarding yet. */
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    constructor(opts = {}) {
+        this.apiKey = opts.apiKey?.trim() || undefined;
+        this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+    }
+    /** True iff the client has an apiKey and can hit authenticated endpoints. */
+    hasApiKey() {
+        return typeof this.apiKey === "string" && this.apiKey.length >= 16;
+    }
+    /**
+     * Late-bind an apiKey acquired via the onboarding flow. The new key is
+     * used for every subsequent request without restarting the MCP.
+     */
+    setApiKey(apiKey) {
+        if (!apiKey || apiKey.length < 16) {
+            throw new Error("Refusing to set an apiKey shorter than 16 characters");
+        }
+        this.apiKey = apiKey;
+    }
+    requireKey() {
+        if (!this.apiKey) {
+            throw new KaaxAPIError("KAAX_API_KEY is not configured. Run kaax_start_onboarding first, or set the env var and restart the MCP.", 401);
+        }
+        return this.apiKey;
+    }
+    /**
+     * `POST /api/v0/analyses` — the single public endpoint.
+     * Filters go in the JSON body; pagination as query params.
+     */
+    async listAnalyses(filters = {}) {
+        const { page, limit, ...body } = filters;
+        const url = new URL(`${this.baseUrl}/api/v0/analyses`);
+        if (page)
+            url.searchParams.set("page", String(page));
+        if (limit)
+            url.searchParams.set("limit", String(limit));
+        return this.request(url.toString(), {
+            method: "POST",
+            body: Object.keys(body).length ? JSON.stringify(body) : undefined,
+        });
+    }
+    /**
+     * Pulls *every* analysis page (up to a safety cap) and concatenates them.
+     * Useful for aggregates / heuristics — never on hot UI paths.
+     */
+    async listAllAnalyses(filters = {}, opts = {}) {
+        const pageSize = opts.pageSize ?? 100;
+        const maxPages = opts.maxPages ?? 20; // hard cap: 2 000 records
+        let page = 1;
+        let total = 0;
+        const data = [];
+        while (page <= maxPages) {
+            const resp = await this.listAnalyses({
+                ...filters,
+                page,
+                limit: pageSize,
+            });
+            total = resp.total ?? data.length;
+            data.push(...resp.data);
+            if (resp.data.length < pageSize)
+                break;
+            page += 1;
+        }
+        return { total, page: 1, limit: data.length, data };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // v2 endpoints — richer per-resource queries, all read-scoped to the
+    // caller. Each method swallows 404s (endpoint not deployed yet) and
+    // returns `null` so the MCP tool layer can degrade gracefully.
+    // ─────────────────────────────────────────────────────────────────────────
+    /** GET /api/v2/setup-status — snapshot of fields, models, configs, tags. */
+    async setupStatus() {
+        return this.tryGet(`/api/v2/setup-status`);
+    }
+    /** GET /api/v2/fields — paginated, filterable list of the user's fields. */
+    async listFields(params = {}) {
+        const url = new URL(`${this.baseUrl}/api/v2/fields`);
+        if (params.tag)
+            url.searchParams.set("tag", params.tag);
+        if (params.type)
+            url.searchParams.set("type", params.type);
+        if (params.q)
+            url.searchParams.set("q", params.q);
+        if (params.page)
+            url.searchParams.set("page", String(params.page));
+        if (params.limit)
+            url.searchParams.set("limit", String(params.limit));
+        return this.tryGet(url.pathname + url.search);
+    }
+    /** GET /api/v2/models — every detection model owned by the caller. */
+    async listModels() {
+        return this.tryGet(`/api/v2/models`);
+    }
+    /** GET /api/v2/tags — tag dictionary with usage counts. */
+    async listTagsV2() {
+        return this.tryGet(`/api/v2/tags`);
+    }
+    /** POST /api/v2/tags — append a tag to the user dictionary. */
+    async createTag(tag) {
+        return this.tryPost(`/api/v2/tags`, { tag });
+    }
+    /** POST /api/v2/fields/:id/tags — attach tags to a field. */
+    async attachFieldTags(fieldId, tags) {
+        return this.tryPost(`/api/v2/fields/${encodeURIComponent(fieldId)}/tags`, {
+            tags,
+        });
+    }
+    /** GET /api/v2/peer-config-suggestions?type=… — anonymised peer averages. */
+    async peerSuggestions(type) {
+        return this.tryGet(`/api/v2/peer-config-suggestions?type=${type}`);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Landing — download permission flow (needs the apiKey but bypasses the
+    // Pro-tier subscription gate because it's part of the onboarding funnel).
+    // ─────────────────────────────────────────────────────────────────────────
+    /** POST /api/landing/request-download — submit the HubSpot form server-side. */
+    async requestDownload(body) {
+        return this.request(`${this.baseUrl}/api/landing/request-download`, { method: "POST", body: JSON.stringify(body ?? {}) });
+    }
+    /** GET /api/landing/download-status — returns status + binary URLs on approval. */
+    async downloadStatus() {
+        return this.request(`${this.baseUrl}/api/landing/download-status`, { method: "GET" });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Account overview — the ONE endpoint a free-tier user can call. Used by
+    // the MCP to decide what tools to enable and to give a clear "you need Pro"
+    // explanation BEFORE attempting a paid call that would 403.
+    //
+    // Cached in-memory for the rest of the process lifetime with a short TTL —
+    // checking it on every paid call is fine (the MCP is single-user) but we
+    // don't want to spam the endpoint either.
+    // ─────────────────────────────────────────────────────────────────────────
+    overviewCache = null;
+    static OVERVIEW_TTL_MS = 60_000; // 1 minute
+    /** GET /api/landing/account-overview — plan + limits + capabilities. */
+    async accountOverview(force = false) {
+        const now = Date.now();
+        if (!force && this.overviewCache && now < this.overviewCache.expiresAt) {
+            return this.overviewCache.value;
+        }
+        const value = await this.request(`${this.baseUrl}/api/landing/account-overview`, { method: "GET" });
+        this.overviewCache = {
+            value,
+            expiresAt: now + KaaxClient.OVERVIEW_TTL_MS,
+        };
+        return value;
+    }
+    /** Invalidate the overview cache — call after a successful upgrade. */
+    invalidateOverview() {
+        this.overviewCache = null;
+    }
+    /** Helper — GET that returns `null` on 404 / network errors. */
+    async tryGet(pathAndQuery) {
+        try {
+            return await this.request(`${this.baseUrl}${pathAndQuery}`, {
+                method: "GET",
+            });
+        }
+        catch (err) {
+            if (err instanceof KaaxAPIError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    /** Helper — POST that returns `null` on 404. */
+    async tryPost(pathAndQuery, body) {
+        try {
+            return await this.request(`${this.baseUrl}${pathAndQuery}`, {
+                method: "POST",
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            if (err instanceof KaaxAPIError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // internals
+    // ─────────────────────────────────────────────────────────────────────────
+    async request(url, init) {
+        const apiKey = this.requireKey();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(url, {
+                method: init.method,
+                headers: {
+                    apiKey,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: init.body,
+                signal: controller.signal,
+            });
+            const text = await res.text();
+            if (!res.ok) {
+                throw new KaaxAPIError(`Kaax API ${res.status} ${res.statusText}`, res.status, text);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new KaaxAPIError("Kaax API returned non-JSON body", res.status, text);
+            }
+        }
+        catch (err) {
+            if (err instanceof KaaxAPIError)
+                throw err;
+            if (err.name === "AbortError") {
+                throw new KaaxAPIError(`Kaax API request timed out after ${this.timeoutMs}ms`);
+            }
+            throw new KaaxAPIError(err.message);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/convert.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shapefile (.shp + .dbf) → KML converter.
+ *
+ * Runs entirely in JS — no GDAL/ogr2ogr install required. The MCP process
+ * has filesystem access on the user's machine, so it can read the input
+ * shapefile bundle and write the converted KML next to it.
+ *
+ * Kaax expects KML 2.2 with Placemarks containing a single Polygon (or
+ * Polygon series for multi-features). Each Placemark gets an `<ExtendedData>`
+ * block with the original DBF attributes so nothing is lost.
+ */
+export interface ConvertResult {
+    outputPath: string;
+    featuresWritten: number;
+    warnings: string[];
+}
+/**
+ * Converts a `.shp` (plus its sibling `.dbf` / `.prj`) to a `.kml` file.
+ *
+ * @param shpPath absolute path to the `.shp` file
+ * @param outputPath optional override; defaults to `<shpPath>.kml`
+ */
+export declare function convertShapefileToKml(shpPath: string, outputPath?: string): Promise<ConvertResult>;

package/dist/convert.js

@@ -0,0 +1,192 @@
+/**
+ * Shapefile (.shp + .dbf) → KML converter.
+ *
+ * Runs entirely in JS — no GDAL/ogr2ogr install required. The MCP process
+ * has filesystem access on the user's machine, so it can read the input
+ * shapefile bundle and write the converted KML next to it.
+ *
+ * Kaax expects KML 2.2 with Placemarks containing a single Polygon (or
+ * Polygon series for multi-features). Each Placemark gets an `<ExtendedData>`
+ * block with the original DBF attributes so nothing is lost.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { open as shpOpen } from "shapefile";
+import { create } from "xmlbuilder2";
+/**
+ * Converts a `.shp` (plus its sibling `.dbf` / `.prj`) to a `.kml` file.
+ *
+ * @param shpPath absolute path to the `.shp` file
+ * @param outputPath optional override; defaults to `<shpPath>.kml`
+ */
+export async function convertShapefileToKml(shpPath, outputPath) {
+    const absolute = path.resolve(shpPath);
+    await assertExists(absolute);
+    if (path.extname(absolute).toLowerCase() !== ".shp") {
+        throw new Error(`Expected a .shp file, got: ${path.extname(absolute)}`);
+    }
+    const dbfPath = absolute.replace(/\.shp$/i, ".dbf");
+    const hasDbf = await fileExists(dbfPath);
+    const out = outputPath
+        ? path.resolve(outputPath)
+        : absolute.replace(/\.shp$/i, ".kml");
+    const warnings = [];
+    const features = [];
+    const source = await shpOpen(absolute, hasDbf ? dbfPath : undefined, {
+        encoding: "utf8",
+    });
+    while (true) {
+        const result = await source.read();
+        if (result.done)
+            break;
+        features.push(result.value);
+    }
+    if (features.length === 0) {
+        throw new Error("Shapefile contains no features.");
+    }
+    const docName = path.basename(absolute, path.extname(absolute));
+    const kml = buildKmlDocument(docName, features, warnings);
+    await fs.writeFile(out, kml, "utf8");
+    return { outputPath: out, featuresWritten: features.length, warnings };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// internals
+// ───────────────────────────────────────────────────────────────────────────
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertExists(p) {
+    if (!(await fileExists(p))) {
+        throw new Error(`File not found: ${p}`);
+    }
+}
+/** Quote a coordinate triple in KML's "lon,lat,alt" textual format. */
+function coordToKml(c) {
+    const lon = Number(c[0]);
+    const lat = Number(c[1]);
+    const alt = Number.isFinite(c[2]) ? Number(c[2]) : 0;
+    return `${lon},${lat},${alt}`;
+}
+function ringToKml(ring) {
+    return ring.map(coordToKml).join(" ");
+}
+/**
+ * Builds the KML XML document. Uses `xmlbuilder2` so escaping / encoding is
+ * handled correctly even when DBF properties contain quotes or `<` / `>`.
+ */
+function buildKmlDocument(docName, features, warnings) {
+    const root = create({ version: "1.0", encoding: "UTF-8" })
+        .ele("kml", { xmlns: "http://www.opengis.net/kml/2.2" })
+        .ele("Document")
+        .ele("name")
+        .txt(docName)
+        .up()
+        .ele("description")
+        .txt(`Converted from ${docName}.shp by @kaax/mcp-server`)
+        .up();
+    features.forEach((feature, idx) => {
+        const placemark = root.ele("Placemark");
+        const props = feature.properties ?? {};
+        const name = String(props.name ?? props.NAME ?? props.id ?? `Feature ${idx + 1}`);
+        placemark.ele("name").txt(name).up();
+        // Preserve all DBF attributes as ExtendedData/Data pairs.
+        if (props && Object.keys(props).length > 0) {
+            const ext = placemark.ele("ExtendedData");
+            for (const [k, v] of Object.entries(props)) {
+                ext
+                    .ele("Data", { name: k })
+                    .ele("value")
+                    .txt(stringify(v))
+                    .up()
+                    .up();
+            }
+            ext.up();
+        }
+        const geom = feature.geometry;
+        if (!geom) {
+            warnings.push(`Feature ${idx} has no geometry — skipped`);
+            placemark.up();
+            return;
+        }
+        switch (geom.type) {
+            case "Polygon":
+                writePolygon(placemark, geom.coordinates);
+                break;
+            case "MultiPolygon": {
+                const multi = placemark.ele("MultiGeometry");
+                geom.coordinates.forEach((poly) => writePolygon(multi, poly));
+                multi.up();
+                break;
+            }
+            case "Point":
+                placemark
+                    .ele("Point")
+                    .ele("coordinates")
+                    .txt(coordToKml(geom.coordinates))
+                    .up()
+                    .up();
+                break;
+            case "MultiPoint": {
+                const multi = placemark.ele("MultiGeometry");
+                geom.coordinates.forEach((c) => multi.ele("Point").ele("coordinates").txt(coordToKml(c)).up().up());
+                multi.up();
+                break;
+            }
+            case "LineString":
+                placemark
+                    .ele("LineString")
+                    .ele("coordinates")
+                    .txt(ringToKml(geom.coordinates))
+                    .up()
+                    .up();
+                break;
+            case "MultiLineString": {
+                const multi = placemark.ele("MultiGeometry");
+                geom.coordinates.forEach((line) => multi.ele("LineString").ele("coordinates").txt(ringToKml(line)).up().up());
+                multi.up();
+                break;
+            }
+            default:
+                warnings.push(`Feature ${idx}: unsupported geometry type "${geom.type}"`);
+        }
+        placemark.up();
+    });
+    return root.end({ prettyPrint: true });
+}
+function writePolygon(parent, rings) {
+    const polygon = parent.ele("Polygon");
+    const [outer, ...holes] = rings;
+    if (outer) {
+        polygon
+            .ele("outerBoundaryIs")
+            .ele("LinearRing")
+            .ele("coordinates")
+            .txt(ringToKml(outer))
+            .up()
+            .up()
+            .up();
+    }
+    holes.forEach((hole) => polygon
+        .ele("innerBoundaryIs")
+        .ele("LinearRing")
+        .ele("coordinates")
+        .txt(ringToKml(hole))
+        .up()
+        .up()
+        .up());
+    polygon.up();
+}
+function stringify(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "object")
+        return JSON.stringify(v);
+    return String(v);
+}
+//# sourceMappingURL=convert.js.map

package/dist/convert.js.map

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

package/dist/i18n.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 type Locale = "es" | "en";
+export declare function getLocale(): Locale;
+declare const dict: {
+    proRequired_title: {
+        es: string;
+        en: string;
+    };
+    proRequired_body: {
+        es: string;
+        en: string;
+    };
+    proRequired_cta: {
+        es: string;
+        en: string;
+    };
+    freeAvailable_header: {
+        es: string;
+        en: string;
+    };
+    freeAvailable_items: {
+        es: string[];
+        en: string[];
+    };
+    needsActivation: {
+        es: string;
+        en: string;
+    };
+    missingApiKey: {
+        es: string;
+        en: string;
+    };
+    invalidApiKey: {
+        es: string;
+        en: string;
+    };
+    rateLimited: {
+        es: string;
+        en: string;
+    };
+    network: {
+        es: string;
+        en: string;
+    };
+};
+type DictKey = keyof typeof dict;
+/** Look up a translated phrase, optionally with `{placeholder}` substitution. */
+export declare function t(key: DictKey, vars?: Record<string, string>): string;
+/** Array variant — for bullet lists. */
+export declare function tList(key: DictKey): string[];
+export {};