betterkey-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CMLabs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# betterkey-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Model Context Protocol](https://modelcontextprotocol.io) server that lets AI agents inspect **and act on** your [BetterKey](https://betterkey.xyz)-connected vehicles.
+
+Open-source bridge. You mint the key, you keep the control. The server never calls your vehicle's API directly; every request goes to BetterKey's existing `/v1/*` HTTP API over HTTPS, authenticated with an API key you mint in the BetterKey iOS app.
+
+## Tools
+
+Six tools are exposed over stdio:
+
+| Tool | What it does | API-key scope required |
+|---|---|---|
+| `list_vehicles` | Lists your connected vehicles (id, make, model, color). | `telemetry.read` |
+| `get_vehicle_telemetry` | Returns the latest windows/odometer/fuel/battery snapshot with per-signal `oemUpdatedAt` and an `isStale` flag. | `telemetry.read` |
+| `get_vehicle_capabilities` | Identity + which signals have fresh data right now + known upstream quirks the agent should respect. | `telemetry.read` |
+| `lock_vehicle` | Lock the vehicle. **Destructive**. The agent must obtain explicit human confirmation. Returns `confirmation: "confirmed"` or `"unconfirmed"`. | `vehicle.command` |
+| `unlock_vehicle` | Unlock the vehicle. **Destructive**, with the same confirmation and confirmation-status semantics as `lock_vehicle`. | `vehicle.command` |
+| `get_vehicle_location` | Current OEM-reported location. Location-sensitive; coordinates are never logged by the server. | `vehicle.command` |
+
+## What it does not do
+
+- It does not read your Firestore directly.
+- It does not hold a vehicle-manufacturer OAuth token.
+- It does not call the vehicle manufacturer's API itself.
+- It does not expose any way to bypass BetterKey's ownership, subscription, or rate-limit checks. Those run server-side on every call.
+
+## Setup
+
+### 1. Mint a BetterKey API key
+
+Open the BetterKey app on iOS → **Settings → API Keys → Create**. Copy the `bk_...` secret immediately; it is shown only once.
+
+**Scopes.** A key minted from the iOS app today holds `telemetry.read + vehicle.command` by default, enough to drive every tool here. If you'd rather keep this bridge read-only (Homebridge-style), mint the key via a direct `POST /v1/account/api-keys` with `{"label":"...","scopes":["telemetry.read"]}`. A read-only key calling a command tool returns a tool-level `insufficient_scope` error naming the missing scope.
+
+### 2. Register with your MCP host
+
+**Claude Desktop.** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "betterkey": {
+      "command": "npx",
+      "args": ["-y", "betterkey-mcp"],
+      "env": {
+        "BETTERKEY_API_KEY": "bk_...",
+        "BETTERKEY_API_BASE": "https://api.betterkey.xyz"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The six tools should appear in the tool palette.
+
+### 3. Try it
+
+- "List my vehicles."
+- "What's the latest telemetry for \<make>?"
+- "What can BetterKey tell me about \<make> right now?"
+- "Lock \<make>." The agent should confirm with you first; a `confirmation: "unconfirmed"` result means the lock command was accepted by BetterKey but the automaker's acknowledgement is unavailable (the lock may or may not have actuated).
+- "Where is \<make>?" Returns latitude/longitude plus the OEM timestamp.
+
+## Environment
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `BETTERKEY_API_KEY` | yes | *(none)* | A `bk_...` secret from the BetterKey app. The server refuses to start without one. |
+| `BETTERKEY_API_BASE` | no | `https://api.betterkey.xyz` | Point at `https://api-staging.betterkey.xyz` for staging, or `http://localhost:8080` when developing against a local BetterKey backend. |
+
+## Revoking access
+
+Agent-host access to your vehicle data lasts only as long as the API key is valid. To revoke:
+
+1. In the BetterKey app → **Settings → API Keys** → delete the key.
+2. All subsequent tool calls from the MCP server will fail with `unauthorized`.
+
+To rotate: delete the old key, mint a new one, update `BETTERKEY_API_KEY` in your MCP host config, restart the host.
+
+## Known upstream quirks the agent sees
+
+The `get_vehicle_capabilities` tool returns a `knownQuirks` list so agents don't over-report:
+
+- `isLockedWebhookUnreliable`. The vehicle's upstream lock-state webhook is defective at the provider level; any lock state reported here is last-known, not live.
+- `statusEndpointReturns501`. There is no engine-run-state (on/off) tool for your vehicle.
+
+If a tool call returns `401 unauthorized`, the API key was revoked or regenerated. If it returns `403` with `type: "insufficient_scope"` and `requiredScope: "vehicle.command"`, the key does not have the scope the called route requires; mint a new key with that scope and retry.
+
+## Security notes
+
+- The API key lives in your MCP host's env; it is never written to tool output or error messages.
+- [Zod](https://zod.dev) validates every tool argument before it reaches the HTTP client.
+- All path segments interpolated into URLs go through `encodeURIComponent`.
+- Timeouts default to 20s with `Retry-After` honored on 429.
+- `fetch` is called with `redirect: "manual"`; redirects fail closed.
+
+## Development
+
+```sh
+git clone https://github.com/CMLabsLLC/betterkey-mcp.git
+cd betterkey-mcp
+npm install
+npm run dev        # run with tsx (no build step)
+npm run typecheck  # strict typecheck without emit
+npm test           # Node's built-in test runner
+npm run build      # emit dist/
+```
+
+Point at a local backend by setting `BETTERKEY_API_BASE=http://localhost:8080` and running `make simulator-backend` in the main BetterKey repo.
+
+## License
+
+[MIT](./LICENSE)

package/dist/http.d.ts

@@ -0,0 +1,42 @@
+export interface BetterKeyClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    userAgent?: string;
+    timeoutMs?: number;
+}
+export interface BetterKeyErrorPayload {
+    error?: string;
+    type?: string;
+    message?: string;
+    retry?: {
+        recommended?: boolean;
+        after?: string;
+        reason?: string;
+    };
+    [k: string]: unknown;
+}
+export declare class BetterKeyApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly retryAfterSeconds?: number;
+    readonly payload: BetterKeyErrorPayload;
+    constructor(status: number, type: string, message: string, payload: BetterKeyErrorPayload, retryAfterSeconds?: number);
+}
+export declare class BetterKeyClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly userAgent;
+    private readonly timeoutMs;
+    constructor(opts: BetterKeyClientOptions);
+    get<T>(path: string, query?: Record<string, string | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    postWithHeaders<T>(path: string, body?: unknown): Promise<{
+        body: T;
+        headers: Record<string, string>;
+    }>;
+    private buildUrl;
+    private request;
+    private requestWithHeaders;
+}
+export declare function httpErrorHint(type: string, requiredScope?: string): string | undefined;
+export declare function redactApiKey(input: string, apiKey: string): string;

package/dist/http.js

@@ -0,0 +1,209 @@
+export class BetterKeyApiError extends Error {
+    status;
+    type;
+    retryAfterSeconds;
+    payload;
+    constructor(status, type, message, payload, retryAfterSeconds) {
+        super(message);
+        this.name = "BetterKeyApiError";
+        this.status = status;
+        this.type = type;
+        this.payload = payload;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 20_000;
+export class BetterKeyClient {
+    apiKey;
+    baseUrl;
+    userAgent;
+    timeoutMs;
+    constructor(opts) {
+        if (!opts.apiKey || opts.apiKey.trim() === "") {
+            throw new Error("BETTERKEY_API_KEY is required");
+        }
+        if (!opts.baseUrl || opts.baseUrl.trim() === "") {
+            throw new Error("BETTERKEY_API_BASE is required");
+        }
+        this.apiKey = opts.apiKey.trim();
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.userAgent = opts.userAgent ?? "betterkey-mcp/0.1.0";
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async get(path, query) {
+        const url = this.buildUrl(path, query);
+        return this.request("GET", url);
+    }
+    async post(path, body) {
+        const url = this.buildUrl(path);
+        return this.request("POST", url, body);
+    }
+    // postWithHeaders exposes a few response headers alongside the parsed body so a tool
+    // that cares about X-Command-Confirmation ("confirmed" vs "unconfirmed") or
+    // X-Operation-Id (for idempotency debugging) can surface them without a second call.
+    async postWithHeaders(path, body) {
+        const url = this.buildUrl(path);
+        return this.requestWithHeaders("POST", url, body);
+    }
+    buildUrl(path, query) {
+        if (!path.startsWith("/")) {
+            throw new Error(`internal: path must start with /: ${path}`);
+        }
+        const url = new URL(this.baseUrl + path);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value === undefined)
+                    continue;
+                url.searchParams.set(key, String(value));
+            }
+        }
+        return url.toString();
+    }
+    async request(method, url, body) {
+        const result = await this.requestWithHeaders(method, url, body);
+        return result.body;
+    }
+    async requestWithHeaders(method, url, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": this.userAgent,
+        };
+        let serializedBody;
+        if (body !== undefined) {
+            serializedBody = JSON.stringify(body);
+            headers["Content-Type"] = "application/json";
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers,
+                body: serializedBody,
+                signal: controller.signal,
+                // Fail hard on any 3xx. WHATWG fetch would otherwise follow redirects
+                // and strip the Authorization header on cross-origin hops, surfacing
+                // as a confusing 401 somewhere downstream. The backend never redirects
+                // today, so flagging a redirect explicitly is the right failure mode.
+                redirect: "error",
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new BetterKeyApiError(0, "timeout", `Request timed out after ${this.timeoutMs}ms`, {});
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new BetterKeyApiError(0, "network", redactApiKey(msg, this.apiKey), {});
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (res.ok) {
+            const parsed = (await res.json());
+            return { body: parsed, headers: pickExposedHeaders(res.headers) };
+        }
+        const retryAfterRaw = res.headers.get("Retry-After");
+        const retryAfterSeconds = parseRetryAfter(retryAfterRaw);
+        const payload = await safeParseErrorBody(res);
+        const type = typeof payload.type === "string" && payload.type.length > 0
+            ? payload.type
+            : mapStatusToType(res.status);
+        const message = typeof payload.message === "string" && payload.message.length > 0
+            ? payload.message
+            : typeof payload.error === "string" && payload.error.length > 0
+                ? payload.error
+                : `HTTP ${res.status}`;
+        throw new BetterKeyApiError(res.status, type, redactApiKey(message, this.apiKey), payload, retryAfterSeconds);
+    }
+}
+async function safeParseErrorBody(res) {
+    try {
+        const text = await res.text();
+        if (!text)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { message: text };
+        }
+    }
+    catch {
+        return {};
+    }
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value);
+    if (Number.isFinite(n) && n >= 0)
+        return n;
+    const d = Date.parse(value);
+    if (Number.isFinite(d)) {
+        const diff = Math.max(0, Math.round((d - Date.now()) / 1000));
+        return diff;
+    }
+    return undefined;
+}
+function mapStatusToType(status) {
+    if (status === 401)
+        return "unauthorized";
+    if (status === 402)
+        return "subscription_required";
+    if (status === 403)
+        return "forbidden";
+    if (status === 404)
+        return "not_found";
+    if (status === 409)
+        return "conflict";
+    if (status === 429)
+        return "rate_limit";
+    if (status >= 500 && status < 600)
+        return "upstream";
+    return "unknown";
+}
+// httpErrorHint returns a short, agent-actionable sentence for well-known backend error
+// types. Returning undefined means "no extra guidance" — the generic message is already
+// clear enough. Centralized here so every tool error-path uses the same wording.
+export function httpErrorHint(type, requiredScope) {
+    switch (type) {
+        case "unauthorized":
+            return "The BetterKey API key was rejected. Mint a new key in the BetterKey app and update the MCP server's BETTERKEY_API_KEY environment variable.";
+        case "insufficient_scope":
+            return requiredScope
+                ? `This tool requires the ${requiredScope} scope on your BetterKey API key. Revoke the current key and mint a new one with that scope enabled.`
+                : "This tool requires a scope your current API key does not grant. Revoke the key and mint a new one with the needed scope.";
+        case "subscription_required":
+            return "An active BetterKey subscription is required for this action.";
+        case "conflict":
+            return "Another command is already in flight for this vehicle. Wait a few seconds and try again.";
+        case "rate_limit":
+            return "The backend is rate-limiting this key. Honor the retryAfterSeconds hint before trying again.";
+        default:
+            return undefined;
+    }
+}
+export function redactApiKey(input, apiKey) {
+    if (!apiKey)
+        return input;
+    const prefix = apiKey.slice(0, 4);
+    return input.split(apiKey).join(`${prefix}…[redacted]`);
+}
+// EXPOSED_HEADERS is the allowlist of response headers that tools are permitted to echo
+// back to the agent. Deliberately narrow: everything else (Set-Cookie, Server, Fly-Request-Id,
+// anything we don't recognize) stays server-side so a header rename cannot accidentally
+// become an agent-visible contract.
+const EXPOSED_HEADERS = new Set(["x-command-confirmation", "x-operation-id", "x-smartcar-upstream-status"]);
+function pickExposedHeaders(headers) {
+    const out = {};
+    headers.forEach((value, key) => {
+        if (EXPOSED_HEADERS.has(key.toLowerCase())) {
+            out[key.toLowerCase()] = value;
+        }
+    });
+    return out;
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC/B,MAAM,CAAS;IACf,IAAI,CAAS;IACb,iBAAiB,CAAU;IAC3B,OAAO,CAAwB;IAExC,YAAY,MAAc,EAAE,IAAY,EAAE,OAAe,EAAE,OAA8B,EAAE,iBAA0B;QACjH,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;IAC/C,CAAC;CACJ;AAED,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,MAAM,OAAO,eAAe;IACP,MAAM,CAAS;IACf,OAAO,CAAS;IAChB,SAAS,CAAS;IAClB,SAAS,CAAS;IAEnC,YAAY,IAA4B;QACpC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,qBAAqB,CAAC;QACzD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,IAAY,EAAE,KAAoD;QAC3E,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAc;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED,qFAAqF;IACrF,4EAA4E;IAC5E,qFAAqF;IACrF,KAAK,CAAC,eAAe,CAAI,IAAY,EAAE,IAAc;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,kBAAkB,CAAI,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACzD,CAAC;IAEO,QAAQ,CAAC,IAAY,EAAE,KAAoD;QAC/E,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,qCAAqC,IAAI,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACzC,IAAI,KAAK,EAAE,CAAC;YACR,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/C,IAAI,KAAK,KAAK,SAAS;oBAAE,SAAS;gBAClC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAC7C,CAAC;QACL,CAAC;QACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,GAAW,EAAE,IAAc;QAChE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAI,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QACnE,OAAO,MAAM,CAAC,IAAI,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,kBAAkB,CAC5B,MAAc,EACd,GAAW,EACX,IAAc;QAEd,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,MAAM,OAAO,GAA2B;YACpC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;YACtC,MAAM,EAAE,kBAAkB;YAC1B,YAAY,EAAE,IAAI,CAAC,SAAS;SAC/B,CAAC;QACF,IAAI,cAAkC,CAAC;QACvC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACtC,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QACjD,CAAC;QACD,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACD,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBACnB,MAAM;gBACN,OAAO;gBACP,IAAI,EAAE,cAAc;gBACpB,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,sEAAsE;gBACtE,qEAAqE;gBACrE,uEAAuE;gBACvE,sEAAsE;gBACtE,QAAQ,EAAE,OAAO;aACpB,CAAC,CAAC;QACP,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBACpD,MAAM,IAAI,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,2BAA2B,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC,CAAC;YACjG,CAAC;YACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,MAAM,IAAI,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QAClF,CAAC;gBAAS,CAAC;YACP,YAAY,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;QAED,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;YACT,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;YACvC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACtE,CAAC;QAED,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACrD,MAAM,iBAAiB,GAAG,eAAe,CAAC,aAAa,CAAC,CAAC;QACzD,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;YACpE,CAAC,CAAC,OAAO,CAAC,IAAI;YACd,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YAC7E,CAAC,CAAC,OAAO,CAAC,OAAO;YACjB,CAAC,CAAC,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAC3D,CAAC,CAAC,OAAO,CAAC,KAAK;gBACf,CAAC,CAAC,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,IAAI,iBAAiB,CACvB,GAAG,CAAC,MAAM,EACV,IAAI,EACJ,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAClC,OAAO,EACP,iBAAiB,CACpB,CAAC;IACN,CAAC;CACJ;AAED,KAAK,UAAU,kBAAkB,CAAC,GAAa;IAC3C,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,CAAC;QACrB,IAAI,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAA0B,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,EAAE,CAAC;IACd,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CAAC,KAAoB;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED,SAAS,eAAe,CAAC,MAAc;IACnC,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,cAAc,CAAC;IAC1C,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,uBAAuB,CAAC;IACnD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,WAAW,CAAC;IACvC,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,WAAW,CAAC;IACvC,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,UAAU,CAAC;IACtC,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,YAAY,CAAC;IACxC,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,UAAU,CAAC;IACrD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED,wFAAwF;AACxF,wFAAwF;AACxF,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,aAAsB;IAC9D,QAAQ,IAAI,EAAE,CAAC;QACX,KAAK,cAAc;YACf,OAAO,6IAA6I,CAAC;QACzJ,KAAK,oBAAoB;YACrB,OAAO,aAAa;gBAChB,CAAC,CAAC,0BAA0B,aAAa,sGAAsG;gBAC/I,CAAC,CAAC,0HAA0H,CAAC;QACrI,KAAK,uBAAuB;YACxB,OAAO,+DAA+D,CAAC;QAC3E,KAAK,UAAU;YACX,OAAO,0FAA0F,CAAC;QACtG,KAAK,YAAY;YACb,OAAO,8FAA8F,CAAC;QAC1G;YACI,OAAO,SAAS,CAAC;IACzB,CAAC;AACL,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,MAAc;IACtD,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,aAAa,CAAC,CAAC;AAC5D,CAAC;AAED,wFAAwF;AACxF,+FAA+F;AAC/F,wFAAwF;AACxF,oCAAoC;AACpC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,wBAAwB,EAAE,gBAAgB,EAAE,4BAA4B,CAAC,CAAC,CAAC;AAE5G,SAAS,kBAAkB,CAAC,OAAgB;IACxC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QAC3B,IAAI,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,GAAG,KAAK,CAAC;QACnC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { BetterKeyClient } from "./http.js";
+import { registerListVehicles } from "./tools/list_vehicles.js";
+import { registerGetVehicleTelemetry } from "./tools/get_vehicle_telemetry.js";
+import { registerGetVehicleCapabilities } from "./tools/get_vehicle_capabilities.js";
+import { registerLockVehicle } from "./tools/lock_vehicle.js";
+import { registerUnlockVehicle } from "./tools/unlock_vehicle.js";
+import { registerGetVehicleLocation } from "./tools/get_vehicle_location.js";
+const SERVER_NAME = "betterkey-mcp";
+const SERVER_VERSION = "0.1.0";
+const DEFAULT_API_BASE = "https://api.betterkey.xyz";
+async function main() {
+    const apiKey = process.env.BETTERKEY_API_KEY;
+    const apiBase = process.env.BETTERKEY_API_BASE ?? DEFAULT_API_BASE;
+    if (!apiKey || apiKey.trim() === "") {
+        process.stderr.write("betterkey-mcp: BETTERKEY_API_KEY is required. Mint one in the BetterKey app's API Keys screen and set the env var in your MCP client's configuration.\n");
+        process.exit(1);
+    }
+    const client = new BetterKeyClient({
+        apiKey,
+        baseUrl: apiBase,
+        userAgent: `${SERVER_NAME}/${SERVER_VERSION}`,
+    });
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    registerListVehicles(server, client);
+    registerGetVehicleTelemetry(server, client);
+    registerGetVehicleCapabilities(server, client);
+    registerLockVehicle(server, client);
+    registerUnlockVehicle(server, client);
+    registerGetVehicleLocation(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`betterkey-mcp: fatal: ${msg}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAE7E,MAAM,WAAW,GAAG,eAAe,CAAC;AACpC,MAAM,cAAc,GAAG,OAAO,CAAC;AAC/B,MAAM,gBAAgB,GAAG,2BAA2B,CAAC;AAErD,KAAK,UAAU,IAAI;IACf,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,gBAAgB,CAAC;IAEnE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAChB,yJAAyJ,CAC5J,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QAC/B,MAAM;QACN,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,GAAG,WAAW,IAAI,cAAc,EAAE;KAChD,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QACzB,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KAC1B,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,8BAA8B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,0BAA0B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE3C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC1B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;IACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/dist/tools/_vehicle_command.d.ts

@@ -0,0 +1,19 @@
+import type { z as ZodNamespace } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type BetterKeyClient } from "../http.js";
+export interface VehicleCommandOptions {
+    toolName: "lock_vehicle" | "unlock_vehicle";
+    title: string;
+    command: "lock" | "unlock";
+    path: (vehicleId: string) => string;
+    description: string;
+    toolErrorResult: (err: unknown) => {
+        isError: boolean;
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+    };
+    z: typeof ZodNamespace;
+}
+export declare function registerVehicleCommand(server: McpServer, client: BetterKeyClient, opts: VehicleCommandOptions): void;

package/dist/tools/_vehicle_command.js

@@ -0,0 +1,48 @@
+// registerVehicleCommand factors the shared machinery for lock_vehicle and unlock_vehicle:
+// identical input schema, destructiveHint, output shape (body + exposed headers), and
+// error handling. Each command tool is a thin shell around this so the "confirmed vs
+// unconfirmed" surfacing cannot drift between lock and unlock.
+export function registerVehicleCommand(server, client, opts) {
+    const { toolName, title, command, path, description, toolErrorResult, z } = opts;
+    server.registerTool(toolName, {
+        title,
+        description,
+        annotations: {
+            destructiveHint: true,
+            openWorldHint: true,
+            idempotentHint: false,
+        },
+        inputSchema: {
+            vehicle_id: z.string().min(1).describe("The vehicle id from list_vehicles."),
+        },
+    }, async (args) => {
+        try {
+            const vehicleId = encodeURIComponent(args.vehicle_id);
+            const result = await client.postWithHeaders(path(vehicleId));
+            // Fail-safe: when the backend returns 2xx but gives us no explicit
+            // confirmation marker (neither the x-command-confirmation header nor
+            // the body.confirmation field), surface "unconfirmed" rather than
+            // defaulting to "confirmed". The product promise is that the agent
+            // reports uncertainty honestly; defaulting to confirmed on a missing
+            // marker would silently violate that if backend contract ever drifts.
+            const confirmation = result.headers["x-command-confirmation"] ??
+                (typeof result.body.confirmation === "string" ? result.body.confirmation : "unconfirmed");
+            const output = {
+                status: result.body.status ?? "success",
+                command,
+                vehicleId: result.body.vehicleId ?? args.vehicle_id,
+                confirmation,
+                message: result.body.message,
+                operationId: result.headers["x-operation-id"],
+                upstreamStatus: result.headers["x-smartcar-upstream-status"],
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+            };
+        }
+        catch (err) {
+            return toolErrorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=_vehicle_command.js.map

package/dist/tools/_vehicle_command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_vehicle_command.js","sourceRoot":"","sources":["../../src/tools/_vehicle_command.ts"],"names":[],"mappings":"AAiBA,2FAA2F;AAC3F,sFAAsF;AACtF,qFAAqF;AACrF,+DAA+D;AAC/D,MAAM,UAAU,sBAAsB,CAClC,MAAiB,EACjB,MAAuB,EACvB,IAA2B;IAE3B,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;IAEjF,MAAM,CAAC,YAAY,CACf,QAAQ,EACR;QACI,KAAK;QACL,WAAW;QACX,WAAW,EAAE;YACT,eAAe,EAAE,IAAI;YACrB,aAAa,EAAE,IAAI;YACnB,cAAc,EAAE,KAAK;SACxB;QACD,WAAW,EAAE;YACT,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,oCAAoC,CAAC;SAC/E;KACJ,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACX,IAAI,CAAC;YACD,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACtD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,eAAe,CAAuB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;YACnF,mEAAmE;YACnE,qEAAqE;YACrE,kEAAkE;YAClE,mEAAmE;YACnE,qEAAqE;YACrE,sEAAsE;YACtE,MAAM,YAAY,GACd,MAAM,CAAC,OAAO,CAAC,wBAAwB,CAAC;gBACxC,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;YAC9F,MAAM,MAAM,GAAG;gBACX,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,SAAS;gBACvC,OAAO;gBACP,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,UAAU;gBACnD,YAAY;gBACZ,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO;gBAC5B,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC;gBAC7C,cAAc,EAAE,MAAM,CAAC,OAAO,CAAC,4BAA4B,CAAC;aAC/D,CAAC;YACF,OAAO;gBACH,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;aAC9E,CAAC;QACN,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACL,CAAC,CACJ,CAAC;AACN,CAAC"}

package/dist/tools/get_vehicle_capabilities.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type BetterKeyClient } from "../http.js";
+export declare function registerGetVehicleCapabilities(server: McpServer, client: BetterKeyClient): void;

package/dist/tools/get_vehicle_capabilities.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { toolErrorResult } from "./list_vehicles.js";
+const VehicleSummary = z.object({
+    id: z.string(),
+    displayName: z.string(),
+    make: z.string(),
+    model: z.string(),
+    color: z.string().optional().default(""),
+});
+const ListVehiclesResponse = z.object({
+    vehicles: z.array(VehicleSummary),
+});
+const TelemetryResponse = z.object({
+    vehicleId: z.string(),
+    capabilities: z.record(z.boolean()),
+});
+// Static Smartcar/BetterKey quirks the agent should know when reasoning about
+// what the car can report. Not derived from the backend; these are
+// well-documented upstream behaviors that will not become false between
+// requests. Keep this list short — only quirks that would mislead an agent if
+// omitted.
+const KNOWN_QUIRKS = [
+    {
+        id: "isLockedWebhookUnreliable",
+        description: "Smartcar's Closure.IsLocked webhook is known upstream to be unreliable. Any lock-state value in the capabilities map or on past tool calls is last-known, not live. Do not report 'currently locked' with high confidence from a telemetry read; a lock command's response is more reliable than any pushed lock state.",
+    },
+    {
+        id: "statusEndpointReturns501",
+        description: "BetterKey has no engine-run-state (on/off) tool for Smartcar vehicles; the underlying endpoint returns HTTP 501 Not Implemented for this provider. Do not promise to tell the user whether the engine is running.",
+    },
+];
+export function registerGetVehicleCapabilities(server, client) {
+    server.registerTool("get_vehicle_capabilities", {
+        title: "Get vehicle capabilities",
+        description: "Describe what BetterKey can currently report for one vehicle: identity (make/model/color), the per-signal freshCapabilities map (true when a fresh reading is available right now), and a knownQuirks list of upstream Smartcar behaviors the agent should respect when reasoning about results.",
+        inputSchema: {
+            vehicle_id: z.string().min(1).describe("The vehicle id from list_vehicles."),
+        },
+    }, async (args) => {
+        try {
+            const vehicleId = encodeURIComponent(args.vehicle_id);
+            const [listRaw, telemetryRaw] = await Promise.all([
+                client.get("/v1/vehicles"),
+                client.get(`/v1/vehicles/${vehicleId}/telemetry`),
+            ]);
+            const list = ListVehiclesResponse.parse(listRaw);
+            const telemetry = TelemetryResponse.parse(telemetryRaw);
+            const summary = list.vehicles.find((v) => v.id === args.vehicle_id);
+            const body = {
+                vehicleId: telemetry.vehicleId,
+                provider: "smartcar",
+                identity: summary
+                    ? {
+                        displayName: summary.displayName,
+                        make: summary.make,
+                        model: summary.model,
+                        color: summary.color,
+                    }
+                    : null,
+                freshCapabilities: telemetry.capabilities,
+                knownQuirks: KNOWN_QUIRKS,
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+            };
+        }
+        catch (err) {
+            return toolErrorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=get_vehicle_capabilities.js.map

package/dist/tools/get_vehicle_capabilities.js.map

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

package/dist/tools/get_vehicle_location.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type BetterKeyClient } from "../http.js";
+export declare function registerGetVehicleLocation(server: McpServer, client: BetterKeyClient): void;

package/dist/tools/get_vehicle_location.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { toolErrorResult } from "./list_vehicles.js";
+const LocationResponse = z.object({
+    location: z.object({
+        latitude: z.number(),
+        longitude: z.number(),
+        locationTimestamp: z.string().optional(),
+    }),
+});
+export function registerGetVehicleLocation(server, client) {
+    server.registerTool("get_vehicle_location", {
+        title: "Get vehicle location",
+        description: "Fetch the vehicle's current reported location (latitude, longitude, and the OEM timestamp when known). This is sensitive data — the agent host should treat the result accordingly and should not persist coordinates beyond what the user asked for. Returns 503 with a Retry-After hint when the automaker's location pipe is in-flight or temporarily unavailable; retry only when the user asks.",
+        annotations: {
+            destructiveHint: false,
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            vehicle_id: z.string().min(1).describe("The vehicle id from list_vehicles."),
+        },
+    }, async (args) => {
+        try {
+            const vehicleId = encodeURIComponent(args.vehicle_id);
+            const raw = await client.get(`/v1/vehicles/${vehicleId}/location`);
+            const parsed = LocationResponse.parse(raw);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            latitude: parsed.location.latitude,
+                            longitude: parsed.location.longitude,
+                            locationTimestamp: parsed.location.locationTimestamp,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return toolErrorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=get_vehicle_location.js.map

package/dist/tools/get_vehicle_location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_vehicle_location.js","sourceRoot":"","sources":["../../src/tools/get_vehicle_location.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC3C,CAAC;CACL,CAAC,CAAC;AAEH,MAAM,UAAU,0BAA0B,CAAC,MAAiB,EAAE,MAAuB;IACjF,MAAM,CAAC,YAAY,CACf,sBAAsB,EACtB;QACI,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EACP,sYAAsY;QAC1Y,WAAW,EAAE;YACT,eAAe,EAAE,KAAK;YACtB,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,IAAI;SACtB;QACD,WAAW,EAAE;YACT,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,oCAAoC,CAAC;SAC/E;KACJ,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACX,IAAI,CAAC;YACD,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACtD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CAAU,gBAAgB,SAAS,WAAW,CAAC,CAAC;YAC5E,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC3C,OAAO;gBACH,OAAO,EAAE;oBACL;wBACI,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAChB;4BACI,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ;4BAClC,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,SAAS;4BACpC,iBAAiB,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB;yBACvD,EACD,IAAI,EACJ,CAAC,CACJ;qBACJ;iBACJ;aACJ,CAAC;QACN,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACL,CAAC,CACJ,CAAC;AACN,CAAC"}

package/dist/tools/get_vehicle_telemetry.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type BetterKeyClient } from "../http.js";
+export declare function registerGetVehicleTelemetry(server: McpServer, client: BetterKeyClient): void;
+export declare function isStale(oemUpdatedAt: string | undefined, now: number): boolean;

package/dist/tools/get_vehicle_telemetry.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { toolErrorResult } from "./list_vehicles.js";
+const SignalEnvelope = z.object({
+    oemUpdatedAt: z.string().optional(),
+    retrievedAt: z.string().optional(),
+}).passthrough();
+const TelemetryResponse = z.object({
+    vehicleId: z.string(),
+    capabilities: z.record(z.boolean()),
+    signals: z.record(SignalEnvelope).optional(),
+});
+const STALE_THRESHOLD_MS = 15 * 60 * 1000;
+export function registerGetVehicleTelemetry(server, client) {
+    server.registerTool("get_vehicle_telemetry", {
+        title: "Get vehicle telemetry",
+        description: "Fetch the latest telemetry snapshot (windows, odometer, fuel, battery) for one vehicle. Each returned signal carries oemUpdatedAt from the automaker and an isStale flag (true when the reading is older than 15 minutes). Pass refresh=true to bypass the server's 15-minute cache; most calls should leave it false.",
+        inputSchema: {
+            vehicle_id: z.string().min(1).describe("The vehicle id from list_vehicles."),
+            refresh: z
+                .boolean()
+                .optional()
+                .describe("If true, bypass the server-side 15 min signal cache. Default false."),
+        },
+    }, async (args) => {
+        try {
+            const vehicleId = encodeURIComponent(args.vehicle_id);
+            const query = args.refresh ? { refresh: "true" } : undefined;
+            const raw = await client.get(`/v1/vehicles/${vehicleId}/telemetry`, query);
+            const parsed = TelemetryResponse.parse(raw);
+            const now = Date.now();
+            const signalsWithStaleness = {};
+            for (const [name, signal] of Object.entries(parsed.signals ?? {})) {
+                signalsWithStaleness[name] = {
+                    ...signal,
+                    isStale: isStale(signal.oemUpdatedAt, now),
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            vehicleId: parsed.vehicleId,
+                            capabilities: parsed.capabilities,
+                            signals: signalsWithStaleness,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return toolErrorResult(err);
+        }
+    });
+}
+export function isStale(oemUpdatedAt, now) {
+    if (!oemUpdatedAt)
+        return true;
+    const parsed = Date.parse(oemUpdatedAt);
+    if (!Number.isFinite(parsed))
+        return true;
+    return now - parsed > STALE_THRESHOLD_MS;
+}
+//# sourceMappingURL=get_vehicle_telemetry.js.map

package/dist/tools/get_vehicle_telemetry.js.map

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

package/dist/tools/list_vehicles.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type BetterKeyClient } from "../http.js";
+export declare function registerListVehicles(server: McpServer, client: BetterKeyClient): void;
+export declare function toolErrorResult(err: unknown): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/tools/list_vehicles.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { BetterKeyApiError, httpErrorHint } from "../http.js";
+const VehicleSummary = z.object({
+    id: z.string(),
+    displayName: z.string(),
+    make: z.string(),
+    model: z.string(),
+    color: z.string().optional().default(""),
+});
+const ListVehiclesResponse = z.object({
+    vehicles: z.array(VehicleSummary),
+});
+export function registerListVehicles(server, client) {
+    server.registerTool("list_vehicles", {
+        title: "List vehicles",
+        description: "List the user's Smartcar-connected vehicles in BetterKey. Returns id, display name, make, model, and exterior color. Use the id as the vehicle_id argument to other tools.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const raw = await client.get("/v1/vehicles");
+            const parsed = ListVehiclesResponse.parse(raw);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ vehicles: parsed.vehicles }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return toolErrorResult(err);
+        }
+    });
+}
+export function toolErrorResult(err) {
+    if (err instanceof BetterKeyApiError) {
+        const body = {
+            error: true,
+            type: err.type,
+            status: err.status,
+            message: err.message,
+        };
+        if (err.retryAfterSeconds !== undefined)
+            body.retryAfterSeconds = err.retryAfterSeconds;
+        const requiredScope = typeof err.payload["required"] === "string" ? err.payload["required"] : undefined;
+        if (requiredScope)
+            body.requiredScope = requiredScope;
+        const granted = err.payload["granted"];
+        if (Array.isArray(granted))
+            body.grantedScopes = granted;
+        const hint = httpErrorHint(err.type, requiredScope);
+        if (hint)
+            body.hint = hint;
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify({ error: true, type: "internal", message }, null, 2) }],
+    };
+}
+//# sourceMappingURL=list_vehicles.js.map

package/dist/tools/list_vehicles.js.map

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

package/dist/tools/lock_vehicle.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type BetterKeyClient } from "../http.js";
+export declare function registerLockVehicle(server: McpServer, client: BetterKeyClient): void;

package/dist/tools/lock_vehicle.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { toolErrorResult } from "./list_vehicles.js";
+import { registerVehicleCommand } from "./_vehicle_command.js";
+export function registerLockVehicle(server, client) {
+    registerVehicleCommand(server, client, {
+        toolName: "lock_vehicle",
+        title: "Lock vehicle",
+        command: "lock",
+        path: (id) => `/v1/vehicles/${id}/lock`,
+        description: "Lock the vehicle. This physically actuates the car's door locks. The agent MUST obtain explicit human confirmation before invoking this tool. The response includes a confirmation field: 'confirmed' means the automaker acknowledged the command; 'unconfirmed' means BetterKey accepted it but the automaker's acknowledgement is unavailable (the lock may or may not have actuated) — report that honestly rather than assuming success.",
+        toolErrorResult,
+        z,
+    });
+}
+//# sourceMappingURL=lock_vehicle.js.map

package/dist/tools/lock_vehicle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock_vehicle.js","sourceRoot":"","sources":["../../src/tools/lock_vehicle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,UAAU,mBAAmB,CAAC,MAAiB,EAAE,MAAuB;IAC1E,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE;QACnC,QAAQ,EAAE,cAAc;QACxB,KAAK,EAAE,cAAc;QACrB,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,gBAAgB,EAAE,OAAO;QACvC,WAAW,EACP,+aAA+a;QACnb,eAAe;QACf,CAAC;KACJ,CAAC,CAAC;AACP,CAAC"}

package/dist/tools/unlock_vehicle.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type BetterKeyClient } from "../http.js";
+export declare function registerUnlockVehicle(server: McpServer, client: BetterKeyClient): void;

package/dist/tools/unlock_vehicle.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { toolErrorResult } from "./list_vehicles.js";
+import { registerVehicleCommand } from "./_vehicle_command.js";
+export function registerUnlockVehicle(server, client) {
+    registerVehicleCommand(server, client, {
+        toolName: "unlock_vehicle",
+        title: "Unlock vehicle",
+        command: "unlock",
+        path: (id) => `/v1/vehicles/${id}/unlock`,
+        description: "Unlock the vehicle. This physically actuates the car's door locks and will leave the car unsecured until it is locked again. The agent MUST obtain explicit human confirmation before invoking this tool and should surface a clear reason to the user. The response includes a confirmation field: 'confirmed' means the automaker acknowledged the command; 'unconfirmed' means BetterKey accepted it but the automaker's acknowledgement is unavailable — report that honestly rather than assuming success.",
+        toolErrorResult,
+        z,
+    });
+}
+//# sourceMappingURL=unlock_vehicle.js.map

package/dist/tools/unlock_vehicle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlock_vehicle.js","sourceRoot":"","sources":["../../src/tools/unlock_vehicle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,UAAU,qBAAqB,CAAC,MAAiB,EAAE,MAAuB;IAC5E,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE;QACnC,QAAQ,EAAE,gBAAgB;QAC1B,KAAK,EAAE,gBAAgB;QACvB,OAAO,EAAE,QAAQ;QACjB,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,gBAAgB,EAAE,SAAS;QACzC,WAAW,EACP,ifAAif;QACrf,eAAe;QACf,CAAC;KACJ,CAAC,CAAC;AACP,CAAC"}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "betterkey-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "author": "CMLabs LLC",
+  "version": "0.1.0",
+  "description": "Model Context Protocol (MCP) server exposing BetterKey vehicle data and commands to AI agents.",
+  "type": "module",
+  "bin": {
+    "betterkey-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "node --test --import tsx $(find src -name '*.test.ts')",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CMLabsLLC/betterkey-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CMLabsLLC/betterkey-mcp/issues"
+  },
+  "homepage": "https://betterkey.xyz",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "betterkey",
+    "vehicle",
+    "smartcar",
+    "ai-agent"
+  ],
+  "license": "MIT"
+}