kaax-mcp 0.1.0

package/README.md

@@ -0,0 +1,274 @@
+# Kaax MCP server
+
+Connect any [MCP](https://modelcontextprotocol.io)-aware agent — Claude
+Desktop, Claude Code, Cursor, Windsurf, Zed — to your Kaax account so it can
+query your analyses, suggest tag taxonomies, recommend advanced
+configurations, find similar fields across your history, aggregate density
+statistics, and convert shapefiles to KML — all locally, with your own API
+key.
+
+## What you get
+
+**Full onboarding from inside the agent** — no Kaax account required to start:
+
+```
+kaax_start_onboarding  →  browser opens at /sign-up?onboardToken=…
+                          user fills the form (password stays in the browser)
+                          page binds the new account to the token
+
+kaax_complete_onboarding(token) →  polls server, returns apiKey ONCE
+                                   late-binds it on the in-process client
+
+kaax_request_download   →  server-side HubSpot form submission
+kaax_check_download_status →  poll for admin approval
+kaax_download_kaax       →  stream the binary to disk
+```
+
+**21 tools**, split by tier:
+
+- **Free** (no Pro subscription needed): onboarding, license check, billing
+  page opener, download flow, shapefile conversion, tag/config suggestions,
+  parameter docs.
+- **Pro** (subscription required): everything that reads or writes data on
+  your Kaax account (analyses, fields, models, tags, density stats, peer
+  configs, similarity search). Free users get a localized "necesitás Pro"
+  message + the upgrade URL instead of an error.
+
+The agent should **call `kaax_check_license` first** if it doesn't already
+know the user's plan — every Pro tool tagged its description with `[Pro]`
+so the agent can read intent from the schema.
+
+The full list:
+
+| Tool                              | Tier  | What it does                                       |
+| --------------------------------- | ----- | -------------------------------------------------- |
+| `kaax_start_onboarding`           | Free  | Open browser at signup with a single-use 15-min token |
+| `kaax_complete_onboarding`        | Free  | Poll for binding; returns the apiKey once on success  |
+| `kaax_check_license`              | Free  | Show plan, capabilities, upgrade URL                |
+| `kaax_open_billing`               | Free  | Open the plans page in the user's browser           |
+| `kaax_request_download`           | Free  | Submit the HubSpot form for desktop apps           |
+| `kaax_check_download_status`      | Free  | Poll for approval; returns binary URLs on success  |
+| `kaax_download_kaax`              | Free  | Stream a binary to disk (no buffering)             |
+| `kaax_suggest_tags_for_field`     | Free  | Heuristic tag set for a new parcel                 |
+| `kaax_suggest_configuration`      | Free  | Curated configuration preset per analysis type     |
+| `kaax_explain_advanced_config`    | Free  | Plain-language docs per parameter                  |
+| `kaax_convert_shapefile_to_kml`   | Free  | Local .shp → .kml conversion (no GDAL needed)      |
+| `kaax_check_setup_status`         | Pro   | Snapshot of fields, models, configs, analyses, tags |
+| `kaax_list_analyses`              | Pro   | Paginated, filterable list of analyses (v0)        |
+| `kaax_get_analysis`               | Pro   | Full detail for a single analysis                  |
+| `kaax_list_fields`                | Pro   | Fields — name, tags, geometry flag (v2)            |
+| `kaax_list_models`                | Pro   | Detection models you've uploaded (v2)              |
+| `kaax_list_tags`                  | Pro   | Tags in use with frequencies                       |
+| `kaax_attach_field_tags`          | Pro   | Persist tags to a field (v2)                       |
+| `kaax_peer_config_suggestions`    | Pro   | Anonymised, privacy-preserving crowd average (v2)  |
+| `kaax_find_similar_fields`        | Pro   | Cosine + geo similarity over your history          |
+| `kaax_get_density_stats`          | Pro   | Total area, detections/ha, mean rates              |
+
+**7 docs** the agent can `resources/read`:
+
+- `kaax://docs/quickstart` — 30-minute zero-to-first-analysis walkthrough
+- `kaax://docs/tags` — 4-axis taxonomy & normalisation rules
+- `kaax://docs/configurations` — parameter cheat sheet
+- `kaax://docs/shapefile-import` — .shp → .kml constraints
+- `kaax://docs/models` — when and how to upload detection models
+- `kaax://docs/density-stats` — what every metric means
+- `kaax://docs/security` — what the MCP server does (and doesn't) send
+
+**5 guided prompts** to seed common conversations:
+
+- `kaax_onboard_from_zero` — full signup → activate → download flow (no account needed)
+- `kaax_quickstart` — orient an existing user
+- `kaax_analyze_field` — queue an analysis end-to-end
+- `kaax_organize_data` — audit and clean up tags
+- `kaax_import_shapefile` — convert + upload .shp parcels
+
+## Install
+
+```bash
+git clone https://github.com/Ahau-x/Kaax-LandingPage.git
+cd Kaax-LandingPage/mcp
+npm install
+npm run build
+```
+
+The build emits a runnable `dist/index.js` you can invoke directly via
+`node dist/index.js` or — once published — `npx -y @kaax/mcp-server`.
+
+## Configure
+
+**Two paths:**
+
+1. **You already have a Kaax account** — get an API key at
+   <https://www.kaax-agritech.com/dashboard/api-manage> (Pro plan or higher)
+   and set it as `KAAX_API_KEY` in your MCP client config.
+2. **You're starting from zero** — just install the MCP without an
+   `KAAX_API_KEY` env var. Tell the agent "onboard me" and it will run
+   `kaax_start_onboarding`, which opens your browser at the signup form.
+   Once you submit, `kaax_complete_onboarding` retrieves the apiKey and
+   binds it to the session. Save the key from the tool output so you don't
+   have to onboard again next time.
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on
+macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "kaax": {
+      "command": "node",
+      "args": ["C:/path/to/Kaax-LandingPage/mcp/dist/index.js"],
+      "env": {
+        "KAAX_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Kaax tools appear in the tool picker.
+
+### Claude Code
+
+Add to `.mcp.json` at the root of any project (or `~/.claude/mcp.json` for
+all projects):
+
+```json
+{
+  "mcpServers": {
+    "kaax": {
+      "command": "node",
+      "args": ["/absolute/path/to/Kaax-LandingPage/mcp/dist/index.js"],
+      "env": { "KAAX_API_KEY": "your_api_key_here" }
+    }
+  }
+}
+```
+
+### Cursor
+
+`Settings → MCP → Add new MCP server`. Use the same `command` / `args` /
+`env` shape as above.
+
+### Windsurf
+
+`Settings → Cascade → MCP Servers → Add new`. Same payload.
+
+### Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "kaax": {
+      "command": { "path": "node", "args": ["…/mcp/dist/index.js"] },
+      "env": { "KAAX_API_KEY": "your_api_key_here" }
+    }
+  }
+}
+```
+
+## Free vs Pro tier
+
+The MCP works without a paid subscription — onboarding, downloading the
+desktop apps, converting shapefiles and getting tag/config suggestions all
+run on the Free tier. Tools that read or write account data (analyses,
+fields, models, etc.) are tagged `[Pro]` in their descriptions; calling
+one from a Free account returns a localized "necesitás Pro" message with
+the upgrade URL instead of failing with a raw 403.
+
+The agent should run `kaax_check_license` first when the user wants to do
+anything beyond onboarding — that's a single cheap call that tells it
+exactly what's available. Free-tier limits (5 fields, 1 local model,
+3 custom configs, no API access) are enforced server-side; the MCP just
+gives clearer messages than the raw 403.
+
+## Language (KAAX_LOCALE)
+
+User-facing strings default to **Spanish** because that's Kaax's primary
+market. Set `KAAX_LOCALE=en` in your MCP client env to switch to English:
+
+```json
+"env": {
+  "KAAX_API_KEY": "…",
+  "KAAX_LOCALE": "en"
+}
+```
+
+The agent (Claude) translates the rest fluently on its own, so even
+without setting `KAAX_LOCALE` you can chat in either language and the
+user-facing answers will be in your language. The env var only affects
+the small set of stub messages that the LLM tends to copy verbatim (URLs,
+error codes, "this requires Pro").
+
+## Override the base URL (private deployments only)
+
+```json
+"env": {
+  "KAAX_API_KEY": "…",
+  "KAAX_BASE_URL": "https://kaax.acme-internal.com"
+}
+```
+
+## Security
+
+Read [`kaax://docs/security`](src/resources.ts) from inside the MCP itself,
+or the short version below:
+
+- API key read from `KAAX_API_KEY` once, never logged, sent only over HTTPS.
+- Every API call is scoped to the api-key owner — the server cannot fetch
+  other users' data.
+- `kaax_peer_config_suggestions` is the only tool that touches anonymised
+  aggregate data; the server endpoint enforces a minimum sample size, excludes
+  the caller, and rounds numeric values into natural quanta so a single
+  contributor cannot be re-identified.
+- All write endpoints (`kaax_attach_field_tags`, anything creating data) are
+  rate-limited server-side (30/min/key) and audit-logged.
+- Shapefile conversion is local file I/O — your .shp never leaves your
+  machine.
+
+## Develop
+
+```bash
+npm run dev   # tsx watch on src/index.ts
+npm run build # tsc → dist/
+```
+
+Type-check only: `npx tsc --noEmit`.
+
+## Architecture
+
+```
+mcp/src/
+├── index.ts      stdio bootstrap — wires tools, resources, prompts
+├── client.ts     HTTP wrapper + standalone onboarding helpers
+├── tools.ts      19 callable tools
+├── resources.ts  7 markdown docs served as MCP resources
+├── prompts.ts    5 guided conversation starters
+├── spatial.ts    Haversine, KML centroid, cosine, density aggregation
+├── convert.ts    shapefile → KML in pure JS (no GDAL)
+├── platform.ts   openBrowser + streaming file download (no extra deps)
+└── types.ts      shared types for v0, v2 and landing shapes
+```
+
+## Performance & resource use
+
+The MCP is engineered to stay light:
+
+- **Stateless tools** — no in-process caches that could grow unbounded.
+- **HTTP only** — the MCP never opens a Mongo / Redis / S3 client. All DB
+  access stays on the Kaax server, which already pools connections at
+  `maxPoolSize: 5` per instance with the shared `dbConnect()` cache.
+- **Bounded polling** — `kaax_complete_onboarding` and
+  `kaax_check_download_status` use exponential back-off with a hard wall
+  (15 min for signup, configurable for downloads). They never spin.
+- **Streamed downloads** — `kaax_download_kaax` pipes the response body
+  directly to disk; binaries never live in memory.
+- **Detached child processes** — `openBrowser` spawns + `unref`s the
+  browser so the MCP exits cleanly even if you leave the browser open.
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 type { AccountOverview, AnalysesFilters, AnalysesPage, AnalysisType, DownloadStatusResponse, IssueOnboardingTokenResponse, OnboardingStatus, RequestDownloadResponse, V2FieldsPage, V2ModelsList, V2PeerSuggestion, V2SetupStatus, V2TagsList } from "./types.js";
+/**
+ * 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 declare function issueOnboardingToken(baseUrl?: string, source?: "mcp" | "landing-cli" | "other"): Promise<IssueOnboardingTokenResponse>;
+/**
+ * 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 declare function fetchOnboardingStatus(token: string, baseUrl?: string): Promise<OnboardingStatus>;
+/**
+ * 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 declare function pollOnboardingUntilBound(token: string, opts?: {
+    baseUrl?: string;
+    maxWaitMs?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    onTick?: (state: OnboardingStatus, attempt: number) => void;
+}): Promise<OnboardingStatus>;
+export declare class KaaxAPIError extends Error {
+    status?: number | undefined;
+    body?: string | undefined;
+    constructor(message: string, status?: number | undefined, body?: string | undefined);
+}
+export interface KaaxClientOptions {
+    /** Optional — if absent, only the onboarding helpers work. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Timeout in milliseconds. Defaults to 30s. */
+    timeoutMs?: number;
+}
+export declare class KaaxClient {
+    /** May be undefined while the user has not finished onboarding yet. */
+    private apiKey;
+    readonly baseUrl: string;
+    private readonly timeoutMs;
+    constructor(opts?: KaaxClientOptions);
+    /** True iff the client has an apiKey and can hit authenticated endpoints. */
+    hasApiKey(): boolean;
+    /**
+     * Late-bind an apiKey acquired via the onboarding flow. The new key is
+     * used for every subsequent request without restarting the MCP.
+     */
+    setApiKey(apiKey: string): void;
+    private requireKey;
+    /**
+     * `POST /api/v0/analyses` — the single public endpoint.
+     * Filters go in the JSON body; pagination as query params.
+     */
+    listAnalyses(filters?: AnalysesFilters): Promise<AnalysesPage>;
+    /**
+     * Pulls *every* analysis page (up to a safety cap) and concatenates them.
+     * Useful for aggregates / heuristics — never on hot UI paths.
+     */
+    listAllAnalyses(filters?: Omit<AnalysesFilters, "page" | "limit">, opts?: {
+        maxPages?: number;
+        pageSize?: number;
+    }): Promise<AnalysesPage>;
+    /** GET /api/v2/setup-status — snapshot of fields, models, configs, tags. */
+    setupStatus(): Promise<V2SetupStatus | null>;
+    /** GET /api/v2/fields — paginated, filterable list of the user's fields. */
+    listFields(params?: {
+        tag?: string;
+        type?: AnalysisType;
+        q?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<V2FieldsPage | null>;
+    /** GET /api/v2/models — every detection model owned by the caller. */
+    listModels(): Promise<V2ModelsList | null>;
+    /** GET /api/v2/tags — tag dictionary with usage counts. */
+    listTagsV2(): Promise<V2TagsList | null>;
+    /** POST /api/v2/tags — append a tag to the user dictionary. */
+    createTag(tag: string): Promise<{
+        tag: string;
+        created: boolean;
+    } | null>;
+    /** POST /api/v2/fields/:id/tags — attach tags to a field. */
+    attachFieldTags(fieldId: string, tags: string[]): Promise<{
+        fieldId: string;
+        tags: string[];
+    } | null>;
+    /** GET /api/v2/peer-config-suggestions?type=… — anonymised peer averages. */
+    peerSuggestions(type: AnalysisType): Promise<V2PeerSuggestion | null>;
+    /** POST /api/landing/request-download — submit the HubSpot form server-side. */
+    requestDownload(body: {
+        useCase?: string;
+        company?: string;
+        locale?: "en" | "es" | "zh";
+    }): Promise<RequestDownloadResponse>;
+    /** GET /api/landing/download-status — returns status + binary URLs on approval. */
+    downloadStatus(): Promise<DownloadStatusResponse>;
+    private overviewCache;
+    private static readonly OVERVIEW_TTL_MS;
+    /** GET /api/landing/account-overview — plan + limits + capabilities. */
+    accountOverview(force?: boolean): Promise<AccountOverview>;
+    /** Invalidate the overview cache — call after a successful upgrade. */
+    invalidateOverview(): void;
+    /** Helper — GET that returns `null` on 404 / network errors. */
+    private tryGet;
+    /** Helper — POST that returns `null` on 404. */
+    private tryPost;
+    private request;
+}