kaax-mcp 0.1.0

package/dist/resources.js

@@ -0,0 +1,305 @@
+/**
+ * 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.
+ */
+export function buildResources() {
+    return [
+        {
+            resource: {
+                uri: "kaax://docs/quickstart",
+                name: "Kaax — Quick start (30 min)",
+                description: "End-to-end walkthrough: account → field → model → first analysis. Use when the user is new.",
+                mimeType: "text/markdown",
+            },
+            text: `# Kaax — Quick start
+
+You can take an account from zero to a working analysis in about 30 minutes. The
+critical-path is short:
+
+1. **Activate your account** — verify your email, complete the profile, and
+   confirm your subscription tier on \`/dashboard/payment\`. Replanting,
+   counting and path analyses are all included in the Pro tier.
+2. **Upload a field** — go to \`/dashboard/manage\` → *Tus Campos* → *Nuevo
+   campo*. Drop a KML with the parcel boundary (or convert from shapefile via
+   \`kaax_convert_shapefile_to_kml\`). Name the field after the parcel; you can
+   tag it later.
+3. **Upload imagery** — drone orthomosaic or satellite tile. The dashboard
+   accepts a single GeoTIFF or a folder of tiles. Multipart upload is on by
+   default for files > 100 MB.
+4. **(For counting/replanting) Upload a model** — \`/dashboard/models\` →
+   *Subir modelo*. Without a detection model these two analysis types cannot
+   run; the path analysis works out of the box.
+5. **Configure** — pick the analysis type (replanting / counting / path), set
+   the advanced parameters (call \`kaax_suggest_configuration\` for a sensible
+   default) and run.
+6. **Inspect the report** — the analysis surfaces survival/depopulation rates,
+   total counts, total area in ha, and per-zone breakdowns.
+
+Useful follow-ups:
+- \`kaax_check_setup_status\` — what's still missing on the account.
+- \`kaax_suggest_tags_for_field\` — organise across season / region / crop.
+- \`kaax_explain_advanced_config\` — what every parameter does.
+`,
+        },
+        {
+            resource: {
+                uri: "kaax://docs/tags",
+                name: "Kaax — Tagging best practices",
+                description: "How to organise fields and analyses with tags.",
+                mimeType: "text/markdown",
+            },
+            text: `# Tagging in Kaax
+
+Tags are the only structured way to slice across fields and analyses. Use them
+as a lightweight CRM: a single field can carry several tags from different
+axes, and the dashboard lets you filter analyses by any combination.
+
+## Recommended taxonomy (4 axes)
+
+| Axis    | Example tag       | Why                          |
+| ------- | ----------------- | ---------------------------- |
+| Season  | \`zafra-2024\`    | Compare year-over-year       |
+| Region  | \`region-escuintla\` | Cluster by agronomy & climate |
+| Crop    | \`cultivo-cana\`  | Filter analyses by species   |
+| Status  | \`estado-activo\` | Hide archived parcels        |
+
+You can layer in extras — \`riego-secano\`, \`semilla-cp741714\`,
+\`zonificacion-este\` — but resist the urge to invent a tag per field; use the
+parcel name field for that.
+
+## Normalisation rules
+
+The server normalises every tag on the way in:
+
+- lowercase
+- accents stripped (NFD + diacritic removal)
+- non-alphanumeric runs collapsed to \`-\`
+- leading/trailing \`-\` trimmed
+- 50-character hard cap
+- 200-tag soft cap per user (forces curation)
+
+Sending the same tag twice is **idempotent**, so it's safe for an agent to
+retry.
+
+## Useful tools
+
+- \`kaax_list_tags\` — current taxonomy with usage counts.
+- \`kaax_suggest_tags_for_field\` — heuristic tags from a field name.
+- \`kaax_attach_field_tags\` — persist tags to a field.
+`,
+        },
+        {
+            resource: {
+                uri: "kaax://docs/configurations",
+                name: "Kaax — Advanced configuration",
+                description: "Parameter glossary and tuning recipes.",
+                mimeType: "text/markdown",
+            },
+            text: `# Advanced configuration
+
+Every analysis has a JSON configuration. The defaults are reasonable, but
+tuning is what separates a good report from a great one. Below is the cheat
+sheet — call \`kaax_explain_advanced_config\` for the per-parameter detail.
+
+## Counting
+
+\`\`\`json
+{
+  "blockSize": 2048,
+  "accuracy": 0.25,
+  "postProcessing": { "refinement": true, "radiusFactor": 0.8, "iou": 0.2 },
+  "sizeClassification": { "smallMax": 0.05, "mediumMax": 0.15, "largeMax": 0.3 }
+}
+\`\`\`
+
+If you see too many duplicates in dense areas, lower \`iou\` to 0.15. If you
+see misses on overlapping plants, raise \`radiusFactor\` to 1.0.
+
+## Replanting
+
+\`\`\`json
+{
+  "blockSize": 2048,
+  "accuracy": 0.25,
+  "lineThickness": 1.5,
+  "seedsPerMeter": 3.75,
+  "seedsPerBox": 30,
+  "postProcessing": { "refinement": true, "iou": 0.2 }
+}
+\`\`\`
+
+\`seedsPerMeter\` and \`seedsPerBox\` are agronomy-driven — set them from the
+crop's planting plan, not from the model.
+
+## Path
+
+\`\`\`json
+{ "blockSize": 2048, "accuracy": 0.3, "overlap": 0.1 }
+\`\`\`
+
+For very narrow paths, raise \`overlap\` to 0.2 to reduce seam artefacts.
+
+## Sourcing defaults
+
+- \`kaax_suggest_configuration\` — the curated preset above.
+- \`kaax_peer_config_suggestions\` — anonymised crowd average for the same
+  analysis type. Use it as a sanity check, not a replacement.
+`,
+        },
+        {
+            resource: {
+                uri: "kaax://docs/shapefile-import",
+                name: "Kaax — Importing shapefiles",
+                description: "Convert .shp → .kml for upload. No GDAL or ogr2ogr needed.",
+                mimeType: "text/markdown",
+            },
+            text: `# Importing shapefiles into Kaax
+
+Kaax accepts KML for parcel boundaries. If you only have ESRI shapefiles you
+can convert them in one tool call:
+
+\`\`\`
+kaax_convert_shapefile_to_kml({
+  shpPath: "C:/finca/parcela_a.shp",
+  outputPath: "C:/finca/parcela_a.kml" // optional
+})
+\`\`\`
+
+What the tool does:
+
+1. Opens the \`.shp\` and the sibling \`.dbf\` (must be in the same folder).
+2. Re-emits every geometry as KML 2.2 — Polygon, MultiPolygon, Point,
+   MultiPoint, LineString, MultiLineString. \`Z\` coordinates are dropped to
+   2D (Kaax does not consume elevation).
+3. Preserves DBF attributes as \`<ExtendedData><Data name="…">\` pairs so
+   you don't lose plot ids / variety names.
+4. Writes the file next to the .shp by default.
+
+What it doesn't do:
+
+- Reproject. Your .shp **must already be in WGS84 (EPSG:4326)**. If it isn't,
+  reproject first with QGIS or \`ogr2ogr -t_srs EPSG:4326\`.
+- Merge multiple .shp files. Run one tool call per shapefile.
+
+After conversion, upload the .kml at \`/dashboard/manage → Tus Campos →
+Nuevo campo\`.
+`,
+        },
+        {
+            resource: {
+                uri: "kaax://docs/models",
+                name: "Kaax — Detection models",
+                description: "Why counting & replanting need a model, and how to upload one.",
+                mimeType: "text/markdown",
+            },
+            text: `# Detection models
+
+Counting and replanting analyses depend on a detection model trained on your
+crop. Kaax does **not** ship a one-size-fits-all model — accuracy on
+sugarcane, pineapple, banana and oil palm is too dependent on resolution,
+flight height and growth stage to use a single weights file.
+
+## Uploading
+
+- Page: \`/dashboard/models\`
+- Format: PyTorch \`.pt\` checkpoint
+- Naming: include crop + version (e.g. \`cana-v3.pt\`) — the agent uses the
+  name to match models against analyses.
+
+## When you don't have a model
+
+- **Path analysis** doesn't need one — point the user there first.
+- **Pilot programmes** — the Kaax team can train one for you. Send a sample
+  orthomosaic + ground truth annotations to support.
+
+## After upload
+
+Run \`kaax_list_models\` to confirm the model is visible to the API. If it
+shows up there, it'll show up in the analysis configuration drop-down too.
+`,
+        },
+        {
+            resource: {
+                uri: "kaax://docs/density-stats",
+                name: "Kaax — Density and rate aggregates",
+                description: "How density / survival / depopulation metrics are computed.",
+                mimeType: "text/markdown",
+            },
+            text: `# Density and rate metrics
+
+Every analysis returns three families of metrics. The MCP server aggregates
+them across fields when you call \`kaax_get_density_stats\`.
+
+## Core counts
+
+- \`totalAreaHa\` — analysed area in hectares.
+- \`totalCounts\` — number of detected plants.
+- \`averageTotalCounts\` — counts per analysis tile.
+
+\`detectionsPerHa = totalCounts / totalAreaHa\` is the canonical density.
+
+## Rates (0–1)
+
+- \`survivalRate\` — fraction of expected plants that are alive.
+- \`depopulationRate\` — fraction of expected positions that are empty.
+- \`replantingRate\` — fraction of expected positions that need re-seeding.
+- \`pathRate\` — fraction of the parcel covered by path-like geometry.
+
+When you ask "which fields are underperforming", filter analyses where
+\`survivalRate < 0.85\` or \`depopulationRate > 0.15\`. Use
+\`kaax_find_similar_fields\` to find historic analyses with comparable
+profiles.
+`,
+        },
+        {
+            resource: {
+                uri: "kaax://docs/security",
+                name: "Kaax — MCP security model",
+                description: "How the MCP server protects the user's API key and respects privacy.",
+                mimeType: "text/markdown",
+            },
+            text: `# Security model
+
+The MCP server is a local process. Every guarantee below holds **on the
+user's machine** — there is no Kaax-hosted intermediary.
+
+## API key
+
+- Read once from the \`KAAX_API_KEY\` environment variable.
+- Never logged, never echoed back to the agent.
+- Sent only to the configured \`KAAX_BASE_URL\` (defaults to
+  https://www.kaax-agritech.com). Override only if you have a private
+  deployment.
+- The server uses HTTPS and a 30 s timeout per request.
+
+## Privacy
+
+- Every Kaax API call is scoped to the api-key owner. The server cannot
+  return another user's fields, models or analyses.
+- \`kaax_peer_config_suggestions\` is the **only** tool that touches other
+  users' data, and it does so through the \`/api/v2/peer-config-suggestions\`
+  endpoint, which:
+  - excludes the caller from the aggregate,
+  - requires a minimum number of distinct peers,
+  - returns only numeric averages rounded to natural quanta — no names, no
+    geometries, no user identifiers.
+- Local conversions (\`kaax_convert_shapefile_to_kml\`) never leave the
+  user's machine; they are pure file I/O.
+
+## What the agent sees
+
+The agent only sees the tool outputs above — never the raw API key, never
+HTTP details, never the user's session cookies. If you need to debug HTTP
+errors, set \`DEBUG=kaax-mcp:*\` to print to stderr; stderr is not piped to
+the LLM.
+`,
+        },
+    ];
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL;YACE,QAAQ,EAAE;gBACR,GAAG,EAAE,wBAAwB;gBAC7B,IAAI,EAAE,6BAA6B;gBACnC,WAAW,EACT,6FAA6F;gBAC/F,QAAQ,EAAE,eAAe;aAC1B;YACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BX;SACI;QAED;YACE,QAAQ,EAAE;gBACR,GAAG,EAAE,kBAAkB;gBACvB,IAAI,EAAE,+BAA+B;gBACrC,WAAW,EAAE,gDAAgD;gBAC7D,QAAQ,EAAE,eAAe;aAC1B;YACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCX;SACI;QAED;YACE,QAAQ,EAAE;gBACR,GAAG,EAAE,4BAA4B;gBACjC,IAAI,EAAE,+BAA+B;gBACrC,WAAW,EAAE,wCAAwC;gBACrD,QAAQ,EAAE,eAAe;aAC1B;YACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDX;SACI;QAED;YACE,QAAQ,EAAE;gBACR,GAAG,EAAE,8BAA8B;gBACnC,IAAI,EAAE,6BAA6B;gBACnC,WAAW,EACT,4DAA4D;gBAC9D,QAAQ,EAAE,eAAe;aAC1B;YACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BX;SACI;QAED;YACE,QAAQ,EAAE;gBACR,GAAG,EAAE,oBAAoB;gBACzB,IAAI,EAAE,yBAAyB;gBAC/B,WAAW,EACT,gEAAgE;gBAClE,QAAQ,EAAE,eAAe;aAC1B;YACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;CAwBX;SACI;QAED;YACE,QAAQ,EAAE;gBACR,GAAG,EAAE,2BAA2B;gBAChC,IAAI,EAAE,oCAAoC;gBAC1C,WAAW,EAAE,6DAA6D;gBAC1E,QAAQ,EAAE,eAAe;aAC1B;YACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;CAwBX;SACI;QAED;YACE,QAAQ,EAAE;gBACR,GAAG,EAAE,sBAAsB;gBAC3B,IAAI,EAAE,2BAA2B;gBACjC,WAAW,EACT,sEAAsE;gBACxE,QAAQ,EAAE,eAAe;aAC1B;YACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCX;SACI;KACF,CAAC;AACJ,CAAC"}

package/dist/spatial.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Lightweight spatial / similarity helpers — no external geospatial deps.
+ *
+ * Two flavours of "similar field" used by the MCP tools:
+ *
+ *  1. Metric similarity — cosine distance over the analysis numeric vector
+ *     (survival, depopulation, density, etc.). Works even when the API
+ *     does not return geometry, which is the common case today.
+ *
+ *  2. Geographic similarity — Haversine distance between centroids parsed
+ *     from the KML string in the analysis record (when present).
+ */
+import type { AnalysisRecord, Coord } from "./types.js";
+/**
+ * Great-circle distance between two coordinates in kilometres.
+ * Returns `Infinity` if either point is missing.
+ */
+export declare function haversineKm(a: Coord | undefined, b: Coord | undefined): number;
+/**
+ * Parses a KML `<coordinates>` block (loose match) and returns the centroid
+ * of the *first* polygon found, in lon/lat decimal degrees.
+ * Returns `undefined` if no coordinates are found.
+ */
+export declare function centroidFromKml(kml: string | undefined): Coord | undefined;
+/**
+ * Builds a numeric feature vector from an analysis record.
+ * Missing values become 0. The order is stable so cosine works.
+ */
+export declare function vectorize(rec: AnalysisRecord): number[];
+/** Cosine similarity between two equal-length vectors. */
+export declare function cosine(a: number[], b: number[]): number;
+/**
+ * Given a reference analysis, find the most similar records from a pool.
+ * Hybrid score: 0.7 · cosine metric similarity + 0.3 · normalised proximity
+ * (closer = higher) when geometry is available, else metric only.
+ */
+export declare function findSimilar(ref: AnalysisRecord, pool: AnalysisRecord[], topK?: number): {
+    record: AnalysisRecord;
+    score: number;
+    distanceKm?: number;
+}[];
+/** Aggregates density stats across a pool of analyses. */
+export declare function aggregateDensity(pool: AnalysisRecord[]): {
+    count: number;
+    totalAreaHa: number;
+    totalDetections: number;
+    avgDetectionsPerHa: number | null;
+    avgSurvivalRate: number | null;
+    avgDepopulationRate: number | null;
+    avgReplantingRate: number | null;
+};

package/dist/spatial.js

@@ -0,0 +1,152 @@
+/**
+ * Lightweight spatial / similarity helpers — no external geospatial deps.
+ *
+ * Two flavours of "similar field" used by the MCP tools:
+ *
+ *  1. Metric similarity — cosine distance over the analysis numeric vector
+ *     (survival, depopulation, density, etc.). Works even when the API
+ *     does not return geometry, which is the common case today.
+ *
+ *  2. Geographic similarity — Haversine distance between centroids parsed
+ *     from the KML string in the analysis record (when present).
+ */
+/** Earth radius in km. */
+const EARTH_R = 6371.0088;
+/** Convert degrees to radians. */
+function toRad(deg) {
+    return (deg * Math.PI) / 180;
+}
+/**
+ * Great-circle distance between two coordinates in kilometres.
+ * Returns `Infinity` if either point is missing.
+ */
+export function haversineKm(a, b) {
+    if (!a || !b)
+        return Infinity;
+    const dLat = toRad(b.lat - a.lat);
+    const dLon = toRad(b.lon - a.lon);
+    const lat1 = toRad(a.lat);
+    const lat2 = toRad(b.lat);
+    const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+    return 2 * EARTH_R * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+/**
+ * Parses a KML `<coordinates>` block (loose match) and returns the centroid
+ * of the *first* polygon found, in lon/lat decimal degrees.
+ * Returns `undefined` if no coordinates are found.
+ */
+export function centroidFromKml(kml) {
+    if (!kml)
+        return undefined;
+    const m = /<coordinates>([\s\S]+?)<\/coordinates>/.exec(kml);
+    if (!m)
+        return undefined;
+    const raw = m[1].trim();
+    // KML coordinates are whitespace-separated triplets: lon,lat[,alt]
+    const points = raw
+        .split(/\s+/)
+        .map((triplet) => {
+        const parts = triplet.split(",").map(Number);
+        if (parts.length < 2 || parts.some((n) => !Number.isFinite(n)))
+            return null;
+        return { lon: parts[0], lat: parts[1] };
+    })
+        .filter((p) => p !== null);
+    if (points.length === 0)
+        return undefined;
+    const sum = points.reduce((acc, p) => ({ lon: acc.lon + p.lon, lat: acc.lat + p.lat }), { lon: 0, lat: 0 });
+    return { lon: sum.lon / points.length, lat: sum.lat / points.length };
+}
+/**
+ * Builds a numeric feature vector from an analysis record.
+ * Missing values become 0. The order is stable so cosine works.
+ */
+export function vectorize(rec) {
+    const a = rec.analysis ?? {};
+    return [
+        a.totalAreaHa ?? 0,
+        a.totalCounts ?? 0,
+        a.survivalRate ?? 0,
+        a.depopulationRate ?? 0,
+        a.replantingRate ?? 0,
+        a.pathRate ?? 0,
+        a.totalPathAreaHa ?? 0,
+        a.averageTotalCounts ?? 0,
+    ];
+}
+/** Cosine similarity between two equal-length vectors. */
+export function cosine(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/**
+ * Given a reference analysis, find the most similar records from a pool.
+ * Hybrid score: 0.7 · cosine metric similarity + 0.3 · normalised proximity
+ * (closer = higher) when geometry is available, else metric only.
+ */
+export function findSimilar(ref, pool, topK = 5) {
+    const refVec = vectorize(ref);
+    const refCenter = centroidFromKml(ref.kml);
+    const scored = pool
+        .filter((r) => r._id !== ref._id)
+        .map((r) => {
+        const sim = cosine(refVec, vectorize(r));
+        const center = centroidFromKml(r.kml);
+        let geoScore = 0;
+        let distanceKm;
+        if (refCenter && center) {
+            distanceKm = haversineKm(refCenter, center);
+            // Decay over 50 km — beyond that, geographic relatedness is weak.
+            geoScore = Math.max(0, 1 - distanceKm / 50);
+        }
+        const score = refCenter ? sim * 0.7 + geoScore * 0.3 : sim;
+        return { record: r, score, distanceKm };
+    })
+        .sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+}
+/** Aggregates density stats across a pool of analyses. */
+export function aggregateDensity(pool) {
+    if (pool.length === 0) {
+        return {
+            count: 0,
+            totalAreaHa: 0,
+            totalDetections: 0,
+            avgDetectionsPerHa: null,
+            avgSurvivalRate: null,
+            avgDepopulationRate: null,
+            avgReplantingRate: null,
+        };
+    }
+    const totalAreaHa = pool.reduce((s, r) => s + (r.analysis?.totalAreaHa ?? 0), 0);
+    const totalDetections = pool.reduce((s, r) => s + (r.analysis?.totalCounts ?? 0), 0);
+    const mean = (key) => {
+        const values = pool
+            .map((r) => r.analysis?.[key])
+            .filter((v) => typeof v === "number" && Number.isFinite(v));
+        if (values.length === 0)
+            return null;
+        return values.reduce((a, b) => a + b, 0) / values.length;
+    };
+    return {
+        count: pool.length,
+        totalAreaHa,
+        totalDetections,
+        avgDetectionsPerHa: totalAreaHa > 0 ? totalDetections / totalAreaHa : null,
+        avgSurvivalRate: mean("survivalRate"),
+        avgDepopulationRate: mean("depopulationRate"),
+        avgReplantingRate: mean("replantingRate"),
+    };
+}
+//# sourceMappingURL=spatial.js.map

package/dist/spatial.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { KaaxClient } from "./client.js";
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: object;
+    handler: (args: unknown, ctx: {
+        client: KaaxClient;
+    }) => Promise<CallToolResult>;
+}
+export declare function buildTools(): ToolDef[];