@thalovant/mcp-server 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.6.0 — 2026-09-28
+
+Link Home Assistant, or any home controller, to a hub from an agent: sign in on the device, create a connection of the `home_assistant` kind, and wait for the hub to admit it. Existing tool schemas are unchanged; every addition is optional.
+
+- **Device sign-in as two tools.** `thalovant_begin_device_login` answers the code and URL to show a person with an opaque `loginId` (an empty `scopes` list is accepted and left out, so the API's default applies); `thalovant_poll_device_login` asks once and answers `pending` (with the interval, lengthened for good after a `slow_down`), `approved`, `expired` or `denied`. The device code and the minted token stay on the server, bound to the principal that began the sign-in, and never reach the model. With no credential configured, every control-plane tool for that principal then uses the token. `thalovant_revoke_device_login` signs out; a token already revoked counts as revoked, and signing out again answers `alreadyRevoked` without asking the API. A sign-in reaches only the configured API origin, because its verification URL is shown to a person.
+- **Connections of a kind.** `thalovant_create_client_identity` takes `connectionType`; the API must answer with the same kind, and a connection it made without it is deleted again before the call fails. The result carries `clientId`, `connectionType` and `operationId`. A refusal adds guidance by kind after the API's own text: a kind the API does not know yet, a plan that does not allow it, a hub already linked (naming the connection that holds the link), or a token to sign in again.
+- **Admission.** `thalovant_wait_for_admission` (read-only) follows the create's operation for the ninety seconds a hub takes and answers `admitted`; `failed`, with the operation's `errorCode` for a failure on the platform or the API's `status`, `code` and `detail` when it refused the wait itself; or `timeout` as an outcome to wait on again. A 429 is ridden out for the time the API names (its body, else `Retry-After`, else `RateLimit-Reset`), and one asking for longer than is left is a timeout at once. A token the API refuses and an API out of reach are tool errors of their own, each with a hint. It honours MCP cancellation and never follows a link to another origin than the API's.
+- **`thalovant_delete_client`**, opt-in with the other destructive tools: `If-Match`, reading the etag first when none is given, one retry on `412`, and a connection already gone counts as deleted.
+- The catalog has 50 default tools (24 in read-only mode, 53 with destructive tools enabled). `thalovant_config_status` reports `deviceLoginSignedIn`.
+- Takes `@thalovant/sdk` ^0.9.0, which carries the device sign-in, the connection kinds and admission; the lock resolves 0.9.0.
+- The parity contract declares `device-login`, `connection-kinds` and `connection-admission` as required and `home-link` as not applicable: a tool call holds a hub connection only for its own length, and nothing could answer a hub's request. The three vector files run through the SDK that resolves here, recorded before asserting, and through the tools over stdio, recorded under the same names; all 46 cases digest as the reference's (reference `2460eb90bd56`). Each worker of the recorder now writes only a shard of its own, and a Vitest global setup (`vitest.config.ts`) merges the shards once after every worker has finished: merging inside the workers let two of them stage the same file and rename each other's away, and a merge that scanned early could land after a complete one.
+- The Dockerfile's version label had stayed at 0.4.0; it now says 0.6.0 like the rest.
+
 ## 0.5.3 — 2026-09-26
 
 - A tool error says what the API said, not only the SDK's one-line message. That line is cut at 160 characters, and a `platform_image_required` refusal names every image each refused key may be instead -- longer than that -- so the list a model needed to retry was the part cut off, and `refused_images`, `allowed_images` and `allowed_repositories` never reached it at all. The error text now goes on with `code:`, `detail:` (the whole sentence, when the first line had to shorten it) and `fields:`, every other member of the body as compact, redacted JSON. A value a validation error echoes back from the request is redacted there and never reaches the first line.

package/README.md

@@ -43,6 +43,17 @@ The server selects control-plane auth in this order:
 
 When a token is set, the server never calls the login endpoint. `thalovant_config_status` reports the active mode as `controlPlaneAuthMode` without revealing token values.
 
+With none of these configured, a person can sign the server in through the browser instead: see [Device Sign-In](#device-sign-in). The token that sign-in mints is used only when nothing above is configured.
+
+### Device Sign-In
+
+A tool call cannot wait for a person, so the device flow (RFC 8628) is two tools:
+
+1. `thalovant_begin_device_login` with optional `scopes` (an empty list, like none, asks for the API's default) and `clientName` answers `loginId`, `userCode`, `verificationUri`, `verificationUriComplete`, `interval` and `expiresIn`. Show the person the URL and the code.
+2. `thalovant_poll_device_login` with that `loginId` asks once. `outcome` is `pending` (poll again after `interval` seconds, already five seconds longer for good if the API asked to slow down), `approved` (with `tokenId`, `scopes` and `expiresAt`), `expired` or `denied`.
+
+The device code and the token never reach the model: the server keeps both, bound to the principal that began the sign-in, for the life of the process. Once approved, every control-plane tool for that principal uses the token when no credential is configured. `thalovant_revoke_device_login` signs out: it revokes that token (a token may always revoke itself, and one already revoked counts as revoked) and forgets it; signing out again answers `alreadyRevoked` without a request, and configured tokens are never touched. A sign-in reaches only the configured API origin (`THALOVANT_API_URL`, or the default), since the verification URL it answers with is shown to a person. A Home Assistant link asks for `hubs:read`, `clients:read` and `clients:write`, which is also all a Free plan can approve.
+
 ### API Tokens (Recommended For AI Agents And CI)
 
 Scoped API tokens are the right credential for AI and automation use: they are minted from the Thalovant dashboard (or through the device flow), carry only the scopes you grant, can be revoked individually, and never involve your account password or MFA. Tokens start with `tvpat_`.
@@ -61,7 +72,7 @@ Minimum scopes for the full control-plane tool surface:
 | `hubs:read` | `thalovant_list_hubs`, `thalovant_get_hub`, `thalovant_get_analytics_overview`, `thalovant_list_marketplace_skills`, `thalovant_list_runtime_groups`, `thalovant_get_runtime_group`, `thalovant_get_runtime_group_config`, the guarded merge read in `thalovant_update_runtime_group_config`, and the hub lookup inside `thalovant_create_client_identity` |
 | `hubs:inspect` | `thalovant_get_hub_runtime_capabilities`, `thalovant_list_runtime_group_marketplace`, `thalovant_list_runtime_group_inventory`, `thalovant_list_hub_skills`, `thalovant_list_hub_skill_history` |
 | `hubs:write` | All hub and runtime-group provisioning: `thalovant_create_hub`, `thalovant_update_hub`, `thalovant_release_hub`, `thalovant_create_runtime_group`, `thalovant_update_runtime_group`, `thalovant_update_runtime_group_config`, `thalovant_release_runtime_group`, `thalovant_install_runtime_group_skill`, `thalovant_uninstall_runtime_group_skill`, the per-hub `thalovant_install_hub_skill`, `thalovant_update_hub_skill`, `thalovant_remove_hub_skill`, the hub rating tools, and the opt-in delete tools |
-| `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) |
+| `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) and the opt-in `thalovant_delete_client` |
 | `memory:read` | `thalovant_list_memory_items`, `thalovant_get_memory_summary`, `thalovant_get_memory_item` |
 | `memory:write` | `thalovant_create_memory_item`, `thalovant_update_memory_item`, `thalovant_delete_memory_item` |
 
@@ -112,6 +123,18 @@ URL spellings and paths on the same origin are allowed; custom origins must be
 configured alongside their credentials. Anonymous public discovery may still
 select a custom API URL.
 
+## Link Home Assistant
+
+A home controller such as Home Assistant links to a hub with a connection of its own kind:
+
+1. Sign in, when no token is configured: [Device Sign-In](#device-sign-in).
+2. `thalovant_create_client_identity` with `connectionType: "home_assistant"`. The API must answer with the same kind; one that made an ordinary connection instead has it deleted again and the call fails. The result carries `clientId`, `connectionType` and `operationId`.
+3. `thalovant_wait_for_admission` with that `operationId`. A hub admits a new connection in about ninety seconds and refuses it until then. `outcome` is `admitted`, `failed` or `timeout`. A failure on the platform carries the operation's `errorCode` (and `status` null); the API refusing the wait itself carries its `status`, `code` and `detail`. A `timeout` means the connection may still be admitted: call the tool again rather than creating another connection. A 429 is waited out for the time the API names (in its body, else `Retry-After`, else `RateLimit-Reset`); one asking for longer than is left is a `timeout` at once. A token the API refuses (401, 403) and an API out of reach are tool errors of their own, each with a hint, never a failed admission. It reads only, honours cancellation, and never follows a `links.self` to another origin than the API's.
+
+Each refusal of step 2 names what to do next after the API's own text (see [Tool Errors](#tool-errors)): a kind the API does not know yet, a plan that does not allow the connection, a hub that already holds its one Home Assistant link (with the `client_id` holding it), or a token the API refused (sign in again). `thalovant_delete_client` removes a connection (`If-Match`, reading the etag first when none is given, retrying once on `412`, and counting a connection already gone as deleted); it is a destructive tool the operator enables.
+
+Answering the hub's requests afterwards is the integration's own long-lived job, on the data plane; an MCP tool call holds a hub connection only for its own length, so that part of the link is not a tool.
+
 ## Local Stdio
 
 The server speaks MCP over stdio and does not write logs to stdout.
@@ -325,6 +348,7 @@ Read-only:
 - `thalovant_list_hubs`
 - `thalovant_get_hub`
 - `thalovant_get_operation`
+- `thalovant_wait_for_admission`
 - `thalovant_identity_status`
 - `thalovant_healthcheck`
 - `thalovant_intent_inventory`
@@ -344,6 +368,12 @@ Skill and runtime-group discovery (read-only):
 - `thalovant_get_runtime_group_config`
 - `thalovant_get_hub_runtime_capabilities`
 
+Sign-in (see [Device Sign-In](#device-sign-in)):
+
+- `thalovant_begin_device_login`
+- `thalovant_poll_device_login`
+- `thalovant_revoke_device_login`
+
 Writes or hub events:
 
 - `thalovant_create_client_identity`
@@ -382,6 +412,7 @@ Destructive, **not registered unless explicitly enabled** (see [Destructive Tool
 
 - `thalovant_delete_hub`
 - `thalovant_delete_runtime_group`
+- `thalovant_delete_client`
 
 Tool outputs redact credential-shaped fields. `thalovant_create_client_identity` does not return secret identity material; pass `savePath` when you want the full identity written to a local file with mode `0600`. `savePath` is confined to the server's identity directory (`THALOVANT_MCP_IDENTITY_DIR`, default `<config-dir>/thalovant/identities`): pass a plain filename, since absolute paths outside that directory and `..` traversal are rejected, so a model cannot drop a credential file into a git working tree or synced folder. `thalovant_config_status` reports the active `identityDir`.
 
@@ -457,9 +488,9 @@ or use an SDK that preserves large JSON integers.
 
 ## Destructive Tools
 
-`thalovant_delete_hub` and `thalovant_delete_runtime_group` are **disabled by default**. They are not merely blocked when called — they are never registered, so they do not appear in `tools/list` and a model cannot see or attempt them.
+`thalovant_delete_hub`, `thalovant_delete_runtime_group` and `thalovant_delete_client` are **disabled by default**. They are not merely blocked when called — they are never registered, so they do not appear in `tools/list` and a model cannot see or attempt them.
 
-A long-lived control-plane token combined with an always-available delete tool is a categorically different risk from a read or update tool: deleting a hub also deletes its dependent clients and ACLs, and none of it is reversible. So these two are opt-in:
+A long-lived control-plane token combined with an always-available delete tool is a categorically different risk from a read or update tool: deleting a hub also deletes its dependent clients and ACLs, and none of it is reversible. So these are opt-in:
 
 ```bash
 export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true"
@@ -477,7 +508,7 @@ export MCP_TOOL_DENYLIST="thalovant_delete_hub,thalovant_delete_runtime_group"
 
 The global deny applies to every principal and cannot be overridden by a principal's `allowedTools`. To restrict only selected principals, leave these tools out of the global denylist and use those principals' `deniedTools` instead.
 
-Deleting a hub still requires a current etag (`412` otherwise), and deleting a runtime group fails with `409` while it is the workspace default or still has hubs attached.
+Deleting a hub still requires a current etag (`412` otherwise), and deleting a runtime group fails with `409` while it is the workspace default or still has hubs attached. Deleting a client cuts off the device or link using it; its etag is read first when none is given.
 
 ## Non-Catalog Skill Sources
 
@@ -491,7 +522,7 @@ With the flag unset, a call with any `sourceType` other than `catalog` fails bef
 
 ## Read-Only Mode
 
-Set `THALOVANT_MCP_READONLY=1` to register only tools annotated `readOnlyHint: true`. Write and destructive tools are then never registered and never appear in `tools/list`, so an operator can run an observe-only agent without hand-writing a denylist. Like the other registration-time gates it is read when a server instance is created; `thalovant_config_status` reports the state as `readOnly`.
+Set `THALOVANT_MCP_READONLY=1` to register only tools annotated `readOnlyHint: true` (the sign-in tools are not among them; `thalovant_wait_for_admission` is). Write and destructive tools are then never registered and never appear in `tools/list`, so an operator can run an observe-only agent without hand-writing a denylist. Like the other registration-time gates it is read when a server instance is created; `thalovant_config_status` reports the state as `readOnly`.
 
 ## HiveMind Runtime Compatibility
 
@@ -499,7 +530,7 @@ Runtime calls sharing the same hub client identity run sequentially within one
 MCP process. Use a distinct client identity for each independently running MCP
 server so the hub can keep their sessions separate.
 
-Version 0.5.1 requires `@thalovant/sdk` `^0.7.1` (0.7.1 through versions below 0.8.0). This release enforces
+Version 0.6.0 requires `@thalovant/sdk` `^0.9.0` (0.9.0 through versions below 0.10.0). Since 0.5.1 the server enforces
 secure effective MQTT URLs and carries a single connection deadline through
 MQTT setup and HTTP failure cleanup. Runtime tools support
 HiveMind v3 Noise over WSS, HTTPS and MQTT over TLS. `thalovant_healthcheck`
@@ -577,7 +608,7 @@ one tool for every SDK conversation or event-listener method.
 
 ### Shared-runtime skill management
 
-The catalog has 46 default tools, 23 in read-only mode, and 48 with destructive tools enabled.
+The catalog has 50 default tools, 24 in read-only mode, and 53 with destructive tools enabled.
 
 Hub-addressed skill methods select the runtime group attached to the hub UUID.
 Every hub sharing that group sees the same skill changes and history. The API

package/dist/device-login.d.ts

@@ -0,0 +1,57 @@
+import type { DeviceAuthorization, ThalovantControlPlane } from "@thalovant/sdk";
+/**
+ * Device sign-ins, held by the server between the tool calls that run them.
+ *
+ * A tool call cannot wait for a person to approve a sign-in in a browser, so
+ * the device flow is two tools: one starts it and one polls it. What sits
+ * between them stays here, in this process, and never reaches the model: the
+ * device code (the secret half of the grant) behind an opaque login id, and
+ * the token an approved sign-in minted. Both belong to the principal that
+ * started the sign-in; another principal can neither poll it nor use its token.
+ */
+/** A sign-in started and not finished. */
+interface PendingLogin {
+    readonly principal: string;
+    readonly api: ThalovantControlPlane;
+    readonly authorization: DeviceAuthorization;
+    readonly expiresAt: number;
+}
+/** The token an approved sign-in minted, on the control plane that holds it. */
+export interface SignedIn {
+    readonly api: ThalovantControlPlane;
+    readonly origin: string;
+}
+export declare class DeviceLogins {
+    private readonly now;
+    private readonly pending;
+    private readonly signedIn;
+    /** The id of the token each principal last revoked, until it signs in again. */
+    private readonly revoked;
+    constructor(now?: () => number);
+    /**
+     * Keep a started sign-in for `principal`; returns the id its polls name it by.
+     *
+     * A principal holds at most a few at once, and starting another drops only
+     * its own oldest. Throws when the server as a whole holds as many as it will.
+     */
+    start(principal: string, api: ThalovantControlPlane, authorization: DeviceAuthorization): string;
+    /** The pending sign-in `loginId` names, if `principal` started it and it has not expired. */
+    find(loginId: string, principal: string): PendingLogin | undefined;
+    /** Forget a sign-in that ended: approved, expired or denied. */
+    finish(loginId: string): void;
+    /** Keep the token an approved sign-in minted, as `principal`'s. */
+    approve(principal: string, api: ThalovantControlPlane): void;
+    /** The token `principal` signed in with on `origin`, if there is one. */
+    signedInOn(principal: string, origin: string): SignedIn | undefined;
+    /** The token `principal` signed in with, wherever. */
+    signedInAs(principal: string): SignedIn | undefined;
+    /** Forget `principal`'s token, remembering its id as revoked. */
+    signOut(principal: string, tokenId?: string | null): void;
+    /**
+     * The id of the token `principal` signed out of, when it has signed out and
+     * not signed in since; undefined when it never signed out.
+     */
+    revokedOf(principal: string): string | null | undefined;
+    private prune;
+}
+export {};

package/dist/device-login.js

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+/** Sign-ins one principal may have pending at once; its own oldest is dropped first. */
+const MAX_PENDING_PER_PRINCIPAL = 4;
+/**
+ * Sign-ins pending at once across every principal. Past it a new sign-in is
+ * refused rather than evicting somebody else's: dropping another principal's
+ * sign-in would let one caller keep everyone else from ever signing in.
+ */
+const MAX_PENDING_LOGINS = 256;
+export class DeviceLogins {
+    now;
+    pending = new Map();
+    signedIn = new Map();
+    /** The id of the token each principal last revoked, until it signs in again. */
+    revoked = new Map();
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    /**
+     * Keep a started sign-in for `principal`; returns the id its polls name it by.
+     *
+     * A principal holds at most a few at once, and starting another drops only
+     * its own oldest. Throws when the server as a whole holds as many as it will.
+     */
+    start(principal, api, authorization) {
+        this.prune();
+        const own = [...this.pending].filter(([, login]) => login.principal === principal);
+        for (const [loginId] of own.slice(0, Math.max(0, own.length - MAX_PENDING_PER_PRINCIPAL + 1))) {
+            this.pending.delete(loginId);
+        }
+        if (this.pending.size >= MAX_PENDING_LOGINS) {
+            throw new Error("Too many device sign-ins are in progress on this server. Try again once some have finished or expired.");
+        }
+        const loginId = randomUUID();
+        this.pending.set(loginId, {
+            principal,
+            api,
+            authorization,
+            expiresAt: this.now() + authorization.expiresIn * 1000,
+        });
+        return loginId;
+    }
+    /** The pending sign-in `loginId` names, if `principal` started it and it has not expired. */
+    find(loginId, principal) {
+        this.prune();
+        const login = this.pending.get(loginId);
+        return login && login.principal === principal ? login : undefined;
+    }
+    /** Forget a sign-in that ended: approved, expired or denied. */
+    finish(loginId) {
+        this.pending.delete(loginId);
+    }
+    /** Keep the token an approved sign-in minted, as `principal`'s. */
+    approve(principal, api) {
+        this.signedIn.set(principal, { api, origin: new URL(api.apiUrl).origin });
+        this.revoked.delete(principal);
+    }
+    /** The token `principal` signed in with on `origin`, if there is one. */
+    signedInOn(principal, origin) {
+        const signedIn = this.signedIn.get(principal);
+        return signedIn && signedIn.origin === origin && signedIn.api.accessToken ? signedIn : undefined;
+    }
+    /** The token `principal` signed in with, wherever. */
+    signedInAs(principal) {
+        const signedIn = this.signedIn.get(principal);
+        return signedIn?.api.accessToken ? signedIn : undefined;
+    }
+    /** Forget `principal`'s token, remembering its id as revoked. */
+    signOut(principal, tokenId = null) {
+        this.signedIn.delete(principal);
+        this.revoked.set(principal, tokenId);
+    }
+    /**
+     * The id of the token `principal` signed out of, when it has signed out and
+     * not signed in since; undefined when it never signed out.
+     */
+    revokedOf(principal) {
+        return this.revoked.has(principal) ? this.revoked.get(principal) : undefined;
+    }
+    prune() {
+        const now = this.now();
+        for (const [loginId, login] of this.pending) {
+            if (login.expiresAt <= now)
+                this.pending.delete(loginId);
+        }
+    }
+}

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { apiErrorText } from "./api-error-output.js";
+import { DeviceLogins } from "./device-login.js";
 import { inventoryPresentation } from "./inventory-output.js";
 import { runtimeReplyContent } from "./reply-output.js";
 import { throwIfRuntimeCancelled, withRuntimeLease } from "./runtime-lease.js";
@@ -7,7 +8,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { DEFAULT_CONTROL_API_URL, ThalovantApiError, ThalovantClient, ThalovantControlPlane, ThalovantIdentity, buildClientContext, buildLocation, } from "@thalovant/sdk";
+import { CONNECTION_TYPE_HOME_ASSISTANT, DEFAULT_CONTROL_API_URL, HOME_ASSISTANT_SCOPES, ThalovantAdmissionFailedError, ThalovantAdmissionTimeoutError, ThalovantAlreadyLinkedError, ThalovantApiError, ThalovantApiUnreachableError, ThalovantAuthError, ThalovantClient, ThalovantControlPlane, ThalovantDeviceLoginDeniedError, ThalovantDeviceLoginExpiredError, ThalovantDeviceLoginPendingError, ThalovantIdentity, ThalovantPlanError, ThalovantUnsupportedConnectionTypeError, buildClientContext, buildLocation, } from "@thalovant/sdk";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
@@ -61,6 +62,10 @@ const SECRET_KEYS = [
     "secret",
 ];
 const protocolSchema = z.enum(["wss", "https", "mqtt"]);
+const connectionTypeSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9_]{0,63}$/)
+    .describe(`The kind of connection, sent as spec.connection_type: voice_satellite, web_chat, developer, embedded, or ${CONNECTION_TYPE_HOME_ASSISTANT} for a Home Assistant link (one per hub). The kind decides what the connection may send and receive.`);
 const limitSchema = z.number().int().min(1).max(MAX_LIMIT).default(25).describe("Page size, 1-100.");
 const publicHubsLimitSchema = z
     .number()
@@ -124,7 +129,14 @@ const runtimeAuthSchema = {
  * they are absent from tools/list entirely rather than merely failing when
  * called. See destructiveToolsEnabled().
  */
-const DESTRUCTIVE_TOOLS = ["thalovant_delete_hub", "thalovant_delete_runtime_group"];
+const DESTRUCTIVE_TOOLS = ["thalovant_delete_hub", "thalovant_delete_runtime_group", "thalovant_delete_client"];
+/**
+ * Device sign-ins in progress, and the tokens approved ones minted, per
+ * principal, for the life of this process. See device-login.ts.
+ */
+const deviceLogins = new DeviceLogins();
+/** How long thalovant_wait_for_admission waits by default: a hub admits a new connection in about ninety seconds. */
+const ADMISSION_DEFAULT_TIMEOUT_MS = 120_000;
 /**
  * Destructive control-plane tools are opt-in.
  *
@@ -247,6 +259,40 @@ function controlPlaneErrorHint(profile, status, body, code) {
             return undefined;
     }
 }
+/**
+ * Guidance for a refused connection create or delete, by the SDK's class for
+ * the refusal. Undefined when the class says nothing a hint could add to.
+ */
+function connectionErrorHint(error, connectionType) {
+    if (error instanceof ThalovantUnsupportedConnectionTypeError) {
+        return error.statusCode === undefined
+            ? `The API made an ordinary connection instead of a ${JSON.stringify(connectionType)} one, so the server deleted it again (the message says if that failed). This API does not support the kind yet; retrying will not change that.`
+            : `The API does not know the connection type ${JSON.stringify(connectionType)} yet (HTTP 422). Retrying will not change that; omit connectionType for an ordinary connection.`;
+    }
+    if (error instanceof ThalovantAlreadyLinkedError) {
+        return `A hub takes one Home Assistant connection, and this one already has it${error.clientId ? `: client ${error.clientId}` : ""}. Use that connection, or delete it with thalovant_delete_client (a destructive tool the operator enables) and create the link again.`;
+    }
+    if (error instanceof ThalovantPlanError) {
+        return error.code === "plan_limit"
+            ? "The plan's connections are used up (see resource, used and limit in the fields above). Delete one with thalovant_delete_client, or move the workspace to a larger plan; granting a scope will not help."
+            : "The plan does not allow this connection (HTTP 402). Move the workspace to a paid plan; granting a scope will not help.";
+    }
+    if (error instanceof ThalovantAuthError) {
+        return "The API refused the token itself: it is unknown, expired or revoked (401), the account is locked (423), or it lacks clients:write (403 Insufficient scopes). Sign in again with thalovant_begin_device_login, or configure a token that carries clients:read and clients:write.";
+    }
+    if (error instanceof ThalovantApiUnreachableError) {
+        return "The Thalovant API could not be reached, which says nothing about the connection: it may be admitted, or created, all the same. Try again once the API answers; do not create another connection before checking.";
+    }
+    return undefined;
+}
+/** Rethrow a refused connection call with its guidance, when it has any. */
+function withConnectionHint(error, connectionType) {
+    const hint = connectionErrorHint(error, connectionType);
+    if (!hint)
+        throw error;
+    const said = apiErrorText(error, redactSecrets) ?? (error instanceof Error ? error.message : String(error));
+    throw new Error(`${said}\n\n${hint}`, { cause: error });
+}
 /**
  * Run a control-plane call and, on failure, append actionable guidance.
  *
@@ -627,17 +673,38 @@ function redactSecrets(value) {
     }
     return output;
 }
+/** The control-plane URL this principal's credentials belong to. */
+async function configuredControlApiUrl(principal = currentPrincipal()) {
+    const credential = await credentialForPrincipal(principal);
+    const canUseShared = allowSharedThalovantCredentials(principal);
+    return credential?.control?.apiUrl ?? (canUseShared ? process.env.THALOVANT_API_URL : undefined) ?? DEFAULT_CONTROL_API_URL;
+}
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Keep server-managed credentials on their configured control-plane origin. */
 async function createControlPlane(options) {
     const principal = currentPrincipal();
     const credential = await credentialForPrincipal(principal);
     const canUseShared = allowSharedThalovantCredentials(principal);
-    const configuredApiUrl = credential?.control?.apiUrl ?? (canUseShared ? process.env.THALOVANT_API_URL : undefined) ?? DEFAULT_CONTROL_API_URL;
+    const configuredApiUrl = await configuredControlApiUrl(principal);
     const apiUrl = options.apiUrl ?? configuredApiUrl;
-    const accessToken = credential?.control?.accessToken ??
-        (canUseShared ? process.env.THALOVANT_API_TOKEN ?? process.env.THALOVANT_ACCESS_TOKEN : undefined);
     const email = canUseShared ? process.env.THALOVANT_EMAIL : undefined;
     const password = canUseShared ? process.env.THALOVANT_PASSWORD : undefined;
+    const configuredToken = credential?.control?.accessToken ??
+        (canUseShared ? process.env.THALOVANT_API_TOKEN ?? process.env.THALOVANT_ACCESS_TOKEN : undefined);
+    // With nothing configured, the token this principal signed in with through
+    // thalovant_begin_device_login / thalovant_poll_device_login, which exists
+    // only for the configured origin.
+    const signedIn = configuredToken || (email && password)
+        ? undefined
+        : deviceLogins.signedInOn(principal.id, originOf(configuredApiUrl) ?? "");
+    const accessToken = configuredToken ?? signedIn?.api.accessToken;
     if (accessToken || (email && password)) {
         let endpoint;
         let configuredEndpoint;
@@ -672,6 +739,24 @@ function ensureAuthenticated(api) {
         throw new Error("This tool requires Thalovant API auth. Configure THALOVANT_API_TOKEN (recommended: a scoped, revocable API token), THALOVANT_ACCESS_TOKEN, THALOVANT_EMAIL/THALOVANT_PASSWORD, or per-principal Thalovant credentials for this MCP principal.");
     }
 }
+/**
+ * A control plane for a device sign-in, on the configured API origin only.
+ *
+ * It carries no credential: the sign-in is what mints one. The origin is fixed
+ * because the verification URL the API answers with is shown to a person, and
+ * the token it mints is kept here for later calls; a tool argument must not
+ * send either somewhere else.
+ */
+async function deviceLoginControlPlane(apiUrl) {
+    const configuredApiUrl = await configuredControlApiUrl();
+    const configured = originOf(configuredApiUrl);
+    if (!configured)
+        throw new Error("The configured control-plane API URL is invalid.");
+    if (apiUrl !== undefined && originOf(apiUrl) !== configured) {
+        throw new Error("apiUrl must use the configured Thalovant API origin for a device sign-in.");
+    }
+    return new ThalovantControlPlane(apiUrl ?? configuredApiUrl, { userAgent: `thalovant-mcp/${VERSION}` });
+}
 function controlPlaneAuthModeFromEnv() {
     if (process.env.THALOVANT_API_TOKEN)
         return "api-token";
@@ -1172,6 +1257,7 @@ export function createServer() {
     }, async () => jsonContent({
         apiUrl: process.env.THALOVANT_API_URL ?? DEFAULT_CONTROL_API_URL,
         controlPlaneAuthMode: controlPlaneAuthModeFromEnv(),
+        deviceLoginSignedIn: Boolean(deviceLogins.signedInAs(currentPrincipal().id)),
         hasApiToken: Boolean(process.env.THALOVANT_API_TOKEN),
         hasAccessToken: Boolean(process.env.THALOVANT_ACCESS_TOKEN),
         hasEmailPassword: Boolean(process.env.THALOVANT_EMAIL && process.env.THALOVANT_PASSWORD),
@@ -1265,7 +1351,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_create_client_identity", {
         title: "Create Client Identity",
-        description: "Create a Thalovant client identity for a hub. The identity is secret; output is redacted unless savePath is used.",
+        description: "Create a Thalovant client identity (a hub connection) for a hub. The identity is secret; output is redacted unless savePath is used. Pass connectionType (for example home_assistant) for a connection of that kind: the API must answer with the same kind, or the connection it made instead is deleted and the call fails. A new connection is admitted by its hub in about ninety seconds; follow operationId with thalovant_wait_for_admission before connecting.",
         inputSchema: {
             ...controlPlaneSchema,
             hubId: z
@@ -1279,6 +1365,7 @@ export function createServer() {
             preferredProtocols: z.array(protocolSchema).min(1).default(["wss", "https"]),
             idempotencyKey: z.string().min(1).optional(),
             spec: jsonRecordSchema.optional(),
+            connectionType: connectionTypeSchema.optional(),
             savePath: z
                 .string()
                 .min(1)
@@ -1291,7 +1378,7 @@ export function createServer() {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ hubId, name, siteId, ownerId, active, preferredProtocols, idempotencyKey, spec, savePath, ...auth }) => {
+    }, async ({ hubId, name, siteId, ownerId, active, preferredProtocols, idempotencyKey, spec, connectionType, savePath, ...auth }) => {
         // Validate the destination BEFORE creating a cloud identity, so a path
         // that escapes the identity directory is refused without leaving an
         // orphaned credential behind in the control plane.
@@ -1306,19 +1393,180 @@ export function createServer() {
             preferredProtocols,
             idempotencyKey,
             spec,
-        });
+            connectionType,
+        }).catch((error) => withConnectionHint(error, connectionType));
         const selectedEndpoint = api.requireRuntimeProtocol(result, preferredProtocols[0]);
         const savedIdentityPath = targetIdentityPath ? await writeIdentityFile(targetIdentityPath, result.identity) : undefined;
         return jsonContent({
             result: redactSecrets(result.asObject({ includeSecrets: false })),
+            clientId: result.clientId ?? null,
+            connectionType: result.connectionType ?? null,
+            operationId: result.operation?.id ?? null,
             selectedEndpoint,
             enabledProtocols: result.identity.enabledProtocols(),
             savedIdentityPath,
             secretNotice: savedIdentityPath
                 ? "Full identity was written to the requested local path with mode 0600."
                 : "Secret identity fields were not returned. Pass savePath to write a protected local identity file.",
+            next: result.operation
+                ? "The hub admits a new connection in about ninety seconds and refuses it until then. Call thalovant_wait_for_admission with this operationId before connecting."
+                : "The API returned no admission operation, so there is nothing to wait for.",
+        });
+    });
+    registerThalovantTool(server, "thalovant_wait_for_admission", {
+        title: "Wait For Connection Admission",
+        description: "Wait until a hub admits a connection made with thalovant_create_client_identity: about ninety seconds after the create. Follows the operation the create returned (operationId), reading it every pollIntervalMs; a 429 is waited out for the time the API names. outcome is admitted (ready, or an operation the API no longer tracks), failed -- the platform could not admit it (errorCode says why, status is null) or the API refused the wait itself (status, code and detail say what it answered) -- or timeout: timeoutMs passed first and the connection may still be admitted, so call this tool again rather than creating another connection. A token the API refuses (401, 403) or an API out of reach is a tool error of its own, not a failed admission. Omit operationId when the create returned none. Reads only.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            operationId: z
+                .string()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("operationId from thalovant_create_client_identity: the operation's id or its links.self path. An absolute URL must be on the API's own origin."),
+            timeoutMs: z.number().int().min(1_000).max(MAX_TIMEOUT_MS).default(ADMISSION_DEFAULT_TIMEOUT_MS),
+            pollIntervalMs: z.number().int().min(500).max(10_000).default(2_000).describe("Milliseconds between two reads of the operation."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ operationId, timeoutMs, pollIntervalMs, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        const signal = requestContext.getStore()?.signal;
+        throwIfRuntimeCancelled(signal);
+        try {
+            await api.waitForAdmission(operationId ?? null, { timeoutMs: clampTimeout(timeoutMs), pollIntervalMs, signal });
+            return jsonContent({ outcome: "admitted" });
+        }
+        catch (error) {
+            if (error instanceof ThalovantAdmissionTimeoutError) {
+                return jsonContent({
+                    outcome: "timeout",
+                    next: "The hub has not admitted the connection yet and may still. Call thalovant_wait_for_admission again with the same operationId; do not create another connection.",
+                });
+            }
+            if (error instanceof ThalovantAdmissionFailedError) {
+                // The API's own words when it refused the wait; null for a failure on the platform.
+                return jsonContent(redactSecrets({
+                    outcome: "failed",
+                    errorCode: error.errorCode ?? null,
+                    status: error.statusCode ?? null,
+                    code: error.code ?? null,
+                    detail: error.detail ?? null,
+                    message: error.message,
+                }));
+            }
+            throwIfRuntimeCancelled(signal);
+            withConnectionHint(error);
+        }
+    });
+    registerThalovantTool(server, "thalovant_begin_device_login", {
+        title: "Begin Device Sign-In",
+        description: "Start a device sign-in (RFC 8628) when no API token is configured: a person approves it in a browser. Show the person verificationUri and userCode (or verificationUriComplete, which carries the code), then call thalovant_poll_device_login with loginId every `interval` seconds. The device code stays on this server. Once approved, control-plane tools for this principal use the token it minted. A Home Assistant link asks for hubs:read, clients:read and clients:write, which is also all a Free plan can approve.",
+        inputSchema: {
+            apiUrl: controlPlaneSchema.apiUrl,
+            scopes: z
+                .array(z.string().min(1).max(64))
+                .max(32)
+                .optional()
+                .describe(`Scopes the token will carry. The API applies its default when omitted or empty (an empty list is left out of the request). A Home Assistant link asks for ${HOME_ASSISTANT_SCOPES.join(", ")}.`),
+            clientName: z.string().min(1).max(128).optional().describe("The name the approval page and the dashboard's token list show."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ apiUrl, scopes, clientName }) => {
+        const api = await deviceLoginControlPlane(apiUrl);
+        const grant = await api.beginDeviceLogin({ scopes, clientName });
+        const loginId = deviceLogins.start(currentPrincipal().id, api, grant);
+        return jsonContent({
+            loginId,
+            userCode: grant.userCode,
+            verificationUri: grant.verificationUri,
+            verificationUriComplete: grant.verificationUriComplete,
+            interval: grant.interval,
+            expiresIn: grant.expiresIn,
+            next: `Ask the person to open ${grant.verificationUri} and enter ${grant.userCode}, then call thalovant_poll_device_login with this loginId every ${grant.interval} seconds until the outcome is no longer pending. The code expires in ${grant.expiresIn} seconds.`,
         });
     });
+    registerThalovantTool(server, "thalovant_poll_device_login", {
+        title: "Poll Device Sign-In",
+        description: "Ask once whether the person approved a device sign-in started with thalovant_begin_device_login. outcome is pending (poll again after `interval` seconds, already lengthened if the API asked to slow down), approved (control-plane tools for this principal now use the token; tokenId, scopes and expiresAt describe it), expired or denied (begin a new sign-in). The token itself is never returned.",
+        inputSchema: {
+            loginId: z.string().min(1).max(64).describe("loginId from thalovant_begin_device_login."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ loginId }) => {
+        const principal = currentPrincipal().id;
+        const login = deviceLogins.find(loginId, principal);
+        if (!login) {
+            throw new Error("No device sign-in in progress has this loginId: it expired, already ended, or was started by another principal. Begin a new one with thalovant_begin_device_login.");
+        }
+        try {
+            const token = await login.api.pollDeviceLogin(login.authorization);
+            deviceLogins.finish(loginId);
+            deviceLogins.approve(principal, login.api);
+            return jsonContent({
+                outcome: "approved",
+                tokenType: token.tokenType,
+                scopes: [...token.scopes],
+                expiresAt: token.expiresAt,
+                tokenId: token.tokenId,
+                next: "Signed in. Control-plane tools for this principal now use this token until thalovant_revoke_device_login or a server restart.",
+            });
+        }
+        catch (error) {
+            if (error instanceof ThalovantDeviceLoginPendingError) {
+                return jsonContent({ outcome: "pending", interval: error.interval });
+            }
+            if (error instanceof ThalovantDeviceLoginExpiredError) {
+                deviceLogins.finish(loginId);
+                return jsonContent({ outcome: "expired", status: error.statusCode ?? null, next: "The code expired before anybody approved it. Begin a new sign-in." });
+            }
+            if (error instanceof ThalovantDeviceLoginDeniedError) {
+                deviceLogins.finish(loginId);
+                return jsonContent({ outcome: "denied", status: error.statusCode ?? null, next: "The person declined the sign-in in the browser." });
+            }
+            throw error;
+        }
+    });
+    registerThalovantTool(server, "thalovant_revoke_device_login", {
+        title: "Revoke Device Sign-In",
+        description: "Sign out: revoke the API token this principal signed in with through thalovant_poll_device_login, and stop using it. A token may always revoke itself, and one already revoked counts as revoked; signing out again answers alreadyRevoked without a request. Tokens configured on the server are never touched.",
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async () => {
+        const principal = currentPrincipal().id;
+        const signedIn = deviceLogins.signedInAs(principal);
+        if (!signedIn) {
+            // Signing out twice is signing out once: the token is already gone.
+            const earlier = deviceLogins.revokedOf(principal);
+            if (earlier !== undefined)
+                return jsonContent({ revoked: true, tokenId: earlier, alreadyRevoked: true });
+            throw new Error("This principal has not signed in with a device sign-in, so there is no token of its own to revoke.");
+        }
+        const tokenId = signedIn.api.tokenId ?? null;
+        // A token the API no longer accepts (401 on its own revoke) is already
+        // revoked; the SDK counts that as done.
+        await signedIn.api.revokeApiToken();
+        deviceLogins.signOut(principal, tokenId);
+        return jsonContent({ revoked: true, tokenId });
+    });
     registerThalovantTool(server, "thalovant_identity_status", {
         title: "Identity Status",
         description: "Load a Thalovant identity and return redacted protocol and endpoint status.",
@@ -2294,6 +2542,26 @@ export function createServer() {
             await callControlPlane("hubWrite", () => api.deleteHub(hubId, { etag }));
             return textContent("Hub deleted.");
         });
+        registerThalovantTool(server, "thalovant_delete_client", {
+            title: "Delete Client",
+            description: "Permanently delete a client (a hub connection): the device or link using it loses access to the hub. This cannot be undone. etag is the client's current etag, sent as If-Match; when omitted the server reads it first. A client changed underneath (412) is read again and the delete retried once, and a client already gone counts as deleted. Requires the clients:write scope. This tool is disabled unless the operator sets THALOVANT_ENABLE_DESTRUCTIVE_TOOLS.",
+            inputSchema: {
+                ...controlPlaneSchema,
+                clientId: z.string().min(1).max(128).describe("Client UUID, for example the clientId a create returned or the client_id of an already-linked refusal."),
+                etag: z.string().min(1).optional().describe("The client's current etag. Read first when omitted."),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async ({ clientId, etag, ...auth }) => {
+            const api = await createControlPlane(auth);
+            ensureAuthenticated(api);
+            await api.deleteClient(clientId, { etag }).catch((error) => withConnectionHint(error));
+            return jsonContent({ deleted: true, clientId });
+        });
         registerThalovantTool(server, "thalovant_delete_runtime_group", {
             title: "Delete Runtime Group",
             description: "Permanently delete a Thalovant runtime group. This cannot be undone. The API answers HTTP 409 for the workspace default group and for a group that still has hubs attached — move or delete those hubs first. This route takes no etag. Requires the hubs:write scope and a paid plan. This tool is disabled unless the operator sets THALOVANT_ENABLE_DESTRUCTIVE_TOOLS.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Stdio and Streamable HTTP MCP server for Thalovant control-plane and hub runtime APIs.",
   "license": "MIT",
   "type": "module",
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@thalovant/sdk": "^0.8.7",
+    "@thalovant/sdk": "^0.9.0",
     "jose": "^6.2.8",
     "zod": "^3.25.76"
   },

package/server.json

@@ -7,19 +7,19 @@
     "url": "https://github.com/thalovant/thalovant-mcp",
     "source": "github"
   },
-  "version": "0.5.3",
+  "version": "0.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@thalovant/mcp-server",
-      "version": "0.5.3",
+      "version": "0.6.0",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.5.3",
+      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.6.0",
       "transport": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:3000/mcp"