@thalovant/mcp-server 0.1.9 → 0.1.11

package/.env.example

@@ -4,7 +4,11 @@ THALOVANT_API_URL=https://api.thalovant.com
 
 # Use one control-plane auth option for private/admin tools.
 # Recommended: a scoped, revocable API token (dashboard or device flow).
-# Minimum scopes for the full tool surface: hubs:read, clients:write, memory:read, memory:write.
+# Minimum scopes for the full tool surface: hubs:read, hubs:write, clients:write,
+# memory:read, memory:write. hubs:write implies hubs:read, which implies hubs:inspect.
+# Discovery only (browse the skill catalog, never provision): hubs:read alone.
+# Hub and runtime-group provisioning also requires a PAID plan; the marketplace
+# catalog is not paid-gated, so free-tier tokens can browse but not install.
 # THALOVANT_API_TOKEN=
 # THALOVANT_ACCESS_TOKEN=
 # THALOVANT_EMAIL=
@@ -45,6 +49,27 @@ MCP_HTTP_AUTH_TOKEN=
 # THALOVANT_PRINCIPAL_CREDENTIALS_DIR=/run/secrets/thalovant-principals
 # THALOVANT_ALLOW_SHARED_CREDENTIALS=false
 
+# Destructive control-plane tools (thalovant_delete_hub, thalovant_delete_runtime_group)
+# are NOT registered unless this is explicitly enabled. Leave it unset in any
+# deployment where a model drives the tools with a long-lived token.
+# THALOVANT_ENABLE_DESTRUCTIVE_TOOLS=false
+
+# Non-catalog skill sources (e.g. thalovant_install_runtime_group_skill with
+# sourceType "git" and an arbitrary sourceRef) can pull unvetted code into a
+# production runtime. They are refused unless this is explicitly enabled. Leave
+# it unset whenever a model drives the tools with a long-lived token.
+# THALOVANT_ENABLE_GIT_SKILL_SOURCES=false
+
+# Directory that thalovant_create_client_identity may write identity files into.
+# savePath is confined to this directory; absolute paths outside it and ".."
+# traversal are rejected. Defaults to <config-dir>/thalovant/identities.
+# THALOVANT_MCP_IDENTITY_DIR=/var/lib/thalovant-mcp/identities
+
+# Read-only mode: register ONLY tools annotated readOnlyHint:true, so a model
+# cannot mutate control-plane or runtime state. Safer default for observe-only
+# agents than hand-writing a denylist.
+# THALOVANT_MCP_READONLY=false
+
 # Optional policy and audit controls.
 # MCP_TOOL_ALLOWLIST=thalovant_*
 # MCP_TOOL_DENYLIST=thalovant_delete_memory_item

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## Unreleased
+
+### Security
+
+- `thalovant_install_runtime_group_skill` now refuses non-catalog install sources by default. A `sourceType` other than `catalog` (notably `git` with an arbitrary `sourceRef`) can pull unvetted code into a production runtime, and the control-plane validator is format-only with no host allowlist, so it is rejected before any control-plane request unless the operator sets `THALOVANT_ENABLE_GIT_SKILL_SOURCES` (accepting `1`/`true`/`yes`/`on`), mirroring the `THALOVANT_ENABLE_DESTRUCTIVE_TOOLS` gate. `sourceType` is trimmed and case-folded before it is both checked and forwarded, so a variant such as `" Catalog "` or `"CATALOG"` cannot pass the local gate yet reach the control plane — which special-cases only the exact string `"catalog"` — as an unrecognized non-catalog source. The tool is now annotated `destructiveHint: true`, and `thalovant_config_status` reports `gitSkillSourcesEnabled`.
+- `thalovant_create_client_identity` now confines the optional `savePath` to a configurable identity directory (`THALOVANT_MCP_IDENTITY_DIR`, default `<config-dir>/thalovant/identities`). Absolute paths outside the directory and `..` traversal are rejected, and the destination is validated before the identity is created in the control plane, so a model can no longer drop a `0600` credential file into a git working tree or synced folder. `thalovant_config_status` reports `identityDir`.
+- `thalovant_healthcheck` output is now passed through `redactSecrets`, matching every other tool output.
+- `thalovant_get_analytics_overview` no longer advertises the `admin` and (admin-only) `ownerId` arguments to the model, so it no longer teaches an admin mode that only ever 403s for non-admin callers; only the plain overview call remains. Injected `admin`/`ownerId` values are stripped and never reach the control plane.
+- Extended output redaction to additional secret-ish keys: `device_code`, `user_code`, `psk`, `cert`, and `jwt`.
+- Added an opt-in read-only mode (`THALOVANT_MCP_READONLY`): only tools annotated `readOnlyHint: true` are registered, so an observe-only agent needs no hand-written denylist. `thalovant_config_status` reports `readOnly`.
+
+## 0.1.10
+
+- Added hub-provisioning and skill-discovery tools so an agent can discover skills and provision hubs conversationally, all delegating to `@thalovant/sdk` (now `^0.2.28`).
+- Discovery tools: `thalovant_list_marketplace_skills`, `thalovant_list_runtime_group_marketplace`, `thalovant_list_runtime_group_inventory`, `thalovant_list_runtime_groups`, `thalovant_get_runtime_group`, `thalovant_get_runtime_group_config`, `thalovant_get_hub_runtime_capabilities`.
+- Provisioning tools: `thalovant_create_hub`, `thalovant_update_hub`, `thalovant_release_hub`, `thalovant_set_hub_rating`, `thalovant_clear_hub_rating`, `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`.
+- `thalovant_delete_hub` and `thalovant_delete_runtime_group` are **disabled by default**: they are not registered at all unless the operator sets `THALOVANT_ENABLE_DESTRUCTIVE_TOOLS`, so they never appear in `tools/list`. The existing allow/deny tool policy is a call-time filter that cannot express a default-off tool, so this is a separate registration-time gate; once enabled, the delete tools remain subject to that policy. `thalovant_config_status` now reports `destructiveToolsEnabled`.
+- Mirrored the control-plane API's exact constraints in the new input schemas so invalid values fail client-side instead of as an opaque 422: hub `spec.version` required, `name` max 128, `slug` 1-191 matching `^[a-z0-9]+(?:-[a-z0-9]+)*$`, `namespace` max 128, `domain` max 255, `visibility` max 32, `capacity_profile` restricted to `standard`/`autoscaling`, hub rating 1-5, runtime group `name` max 128 and `description` max 255, runtime group `spec.replicas` 1-20, skill `skill_id` max 191, `source_ref` max 255, `version_pin` max 64, and `marketplace_skill_id` a UUID. `source_type` is intentionally left a free-form 1-32 string because the API does not constrain it to an enum.
+- `thalovant_update_hub` requires an `etag` and no longer accepts `name`, `namespace`, or `domain`, which are immutable after creation; the description directs agents to read the etag from the hub resource body, since the API sends no `ETag` response header. `thalovant_delete_hub` requires an `etag` for the same reason.
+- Control-plane failures on the new tools now carry actionable guidance that distinguishes `403 Insufficient scopes` (checked before the plan gate, so it can mask a plan problem), the `402 API access requires a paid plan.` gate, the distinct `402 This skill requires paid marketplace access for the tenant plan.` at skill install, `412 ETag mismatch`, and `409` idempotency-key reuse.
+- Documented the scope map for the new surface — `hubs:read` for the catalog, `hubs:inspect` for runtime-group and hub runtime views, `hubs:write` plus a paid plan for provisioning — and noted that catalog browsing is not paid-gated, so a free-tier token can browse the marketplace but cannot install.
+
 ## 0.1.9
 
 - Added first-class scoped API token auth for the control plane: set `THALOVANT_API_TOKEN` and the server authenticates with the token directly and never calls the login endpoint. Precedence is `THALOVANT_API_TOKEN`, then `THALOVANT_ACCESS_TOKEN`, then the `THALOVANT_EMAIL`/`THALOVANT_PASSWORD` login fallback.

package/README.md

@@ -56,12 +56,28 @@ Minimum scopes for the full control-plane tool surface:
 
 | Scope | Used by |
 |-------|---------|
-| `hubs:read` | `thalovant_list_hubs`, `thalovant_get_hub`, `thalovant_get_analytics_overview`, and the hub lookup inside `thalovant_create_client_identity` |
+| `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`, 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` |
+| `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 hub rating tools, and the opt-in delete tools |
 | `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) |
 | `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` |
 
-Grant fewer scopes for narrower deployments: a read-only assistant needs only `hubs:read` and `memory:read`. `thalovant_get_analytics_overview` with `admin: true` additionally requires an admin account with `admin:analytics`, which API tokens for regular use should not carry. Runtime hub tools (`thalovant_ask`, `thalovant_send_action`, and friends) use Thalovant client identities, not control-plane tokens.
+The hub scopes imply one another: `hubs:write` grants `hubs:read`, which grants `hubs:inspect` and `hubs:preview`. Minting a token with `hubs:read` is therefore enough for every discovery tool in the table above.
+
+Scope is not the whole story for provisioning. Every hub and runtime-group write also requires a **paid plan**, and the API checks scope *before* the plan, so the two failure modes are ordered:
+
+- A token missing the scope fails `403 Insufficient scopes`. Free-plan API tokens are capped at `hubs:read`, `clients:read`, and `clients:write`, so on the free tier provisioning fails with this 403 and never reaches the 402.
+- A correctly scoped token on a free plan fails `402 API access requires a paid plan.`
+- `thalovant_install_runtime_group_skill` can fail with a **second, distinct** 402, `This skill requires paid marketplace access for the tenant plan.`, when the plan is paid but does not include `access_tier: paid` catalog entries.
+
+Discovery is deliberately not paid-gated: **a free-tier token can browse the marketplace catalog and set hub ratings, but cannot install skills or provision hubs.** Use `thalovant_list_runtime_group_marketplace` before installing — it reports `installable`, `purchase_required`, and `access_message` per skill, which turns an opaque 402 into a decision you can make up front.
+
+Grant fewer scopes for narrower deployments: a read-only assistant needs only `hubs:read` and `memory:read`, and a discovery-only agent that browses skills but never provisions needs `hubs:read` alone. `thalovant_get_analytics_overview` with `admin: true` additionally requires an admin account with `admin:analytics`, which API tokens for regular use should not carry. Runtime hub tools (`thalovant_ask`, `thalovant_send_action`, and friends) use Thalovant client identities, not control-plane tokens.
+
+### Hub Etags
+
+`thalovant_update_hub` and `thalovant_delete_hub` use optimistic locking and require the hub's current etag, sent as `If-Match`. The etag is only available in the **body** of the hub resource — the API sends no `ETag` response header — so an agent must call `thalovant_get_hub` first and pass the `etag` field from that response. A missing or stale value fails `412 ETag mismatch` and changes nothing; re-fetch and retry. `name`, `namespace`, and `domain` are immutable after creation, so `thalovant_update_hub` does not accept them at all; send only the fields you are changing rather than round-tripping a whole hub resource. Runtime-group writes do not use etags.
 
 ### Login Fallback
 
@@ -201,6 +217,8 @@ export MCP_TOOL_DENYLIST="thalovant_delete_memory_item"
 
 Per-principal credential files may also include `allowedTools` and `deniedTools`.
 
+Both are call-time filters, and an empty allowlist means "allow everything". They cannot make a tool default-off or hide it from `tools/list`, which is why the two destructive control-plane tools are gated separately by `THALOVANT_ENABLE_DESTRUCTIVE_TOOLS`. See [Destructive Tools](#destructive-tools).
+
 Audit logs:
 
 ```bash
@@ -295,6 +313,16 @@ Read-only:
 - `thalovant_get_memory_summary`
 - `thalovant_get_memory_item`
 
+Skill and runtime-group discovery (read-only):
+
+- `thalovant_list_marketplace_skills`
+- `thalovant_list_runtime_group_marketplace`
+- `thalovant_list_runtime_group_inventory`
+- `thalovant_list_runtime_groups`
+- `thalovant_get_runtime_group`
+- `thalovant_get_runtime_group_config`
+- `thalovant_get_hub_runtime_capabilities`
+
 Writes or hub events:
 
 - `thalovant_create_client_identity`
@@ -306,7 +334,64 @@ Writes or hub events:
 - `thalovant_update_memory_item`
 - `thalovant_delete_memory_item`
 
-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`.
+Hub and runtime-group provisioning:
+
+- `thalovant_create_hub`
+- `thalovant_update_hub`
+- `thalovant_release_hub`
+- `thalovant_set_hub_rating`
+- `thalovant_clear_hub_rating`
+- `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`
+
+Destructive, **not registered unless explicitly enabled** (see [Destructive Tools](#destructive-tools)):
+
+- `thalovant_delete_hub`
+- `thalovant_delete_runtime_group`
+
+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`.
+
+## 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.
+
+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:
+
+```bash
+export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true"
+```
+
+Accepted true values are `1`, `true`, `yes`, and `on`; anything else, including unset, leaves the tools off. The flag is read when a server instance is created, so restart the server (or, in Streamable HTTP mode, start a new session) after changing it. `thalovant_config_status` reports the current state as `destructiveToolsEnabled` and lists the tools the flag controls.
+
+This is a separate mechanism from the existing tool policy, deliberately. `MCP_TOOL_ALLOWLIST` / `MCP_TOOL_DENYLIST` and the per-principal `allowedTools` / `deniedTools` are call-time filters where an empty allowlist means "allow everything"; they cannot express a tool that is off until an operator turns it on, and they cannot hide a tool from `tools/list`. Once `THALOVANT_ENABLE_DESTRUCTIVE_TOOLS` is set the delete tools are ordinary tools again and remain subject to that policy, so the two layers compose:
+
+```bash
+# Enable deletes server-wide, but deny them to everyone except trusted principals.
+export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true"
+export MCP_TOOL_DENYLIST="thalovant_delete_hub,thalovant_delete_runtime_group"
+```
+
+with the trusted principal's credential file granting them back via `allowedTools`.
+
+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.
+
+## Non-Catalog Skill Sources
+
+`thalovant_install_runtime_group_skill` installs from the vetted marketplace catalog by default. Any other source — notably `sourceType: "git"` with an arbitrary `sourceRef` repository URL — pulls code the marketplace never reviewed straight into a production runtime, and the control-plane validator is format-only with no host allowlist. Because the tools are driven by a model holding a long-lived token, non-catalog sources are refused unless an operator opts in:
+
+```bash
+export THALOVANT_ENABLE_GIT_SKILL_SOURCES="true"
+```
+
+With the flag unset, a call with any `sourceType` other than `catalog` fails before any control-plane request is made. Accepted true values are `1`, `true`, `yes`, and `on`. `thalovant_config_status` reports the state as `gitSkillSourcesEnabled`. The tool is annotated `destructiveHint: true`.
+
+## 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`.
 
 ## Development
 

package/dist/index.js

@@ -9,12 +9,13 @@ import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import { realpathSync } from "node:fs";
 import { appendFile, readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
 import { mkdir } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRemoteJWKSet, jwtVerify } from "jose";
 import { z } from "zod";
-const VERSION = "0.1.9";
+const VERSION = "0.1.10";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 300_000;
 const MAX_LIMIT = 100;
@@ -42,9 +43,16 @@ const SECRET_KEYS = [
     "privateKey",
     "refresh_token",
     "refreshToken",
+    "device_code",
+    "deviceCode",
+    "user_code",
+    "userCode",
     "authToken",
     "authorization",
     "bearer",
+    "jwt",
+    "psk",
+    "cert",
     "token",
     "secret",
 ];
@@ -106,6 +114,140 @@ const runtimeAuthSchema = {
         .describe("Load the identity from Thalovant SDK environment variables."),
     protocol: protocolSchema.default("wss").describe("Runtime transport protocol."),
 };
+/**
+ * Tools that destroy control-plane resources. They are never registered unless
+ * an operator opts in with THALOVANT_ENABLE_DESTRUCTIVE_TOOLS, so by default
+ * 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"];
+/**
+ * Destructive control-plane tools are opt-in.
+ *
+ * The per-principal tool policy in authorizeTool() is an allow/deny filter
+ * evaluated at call time: an empty allowlist means "allow everything", so it
+ * cannot express a tool that is off until an operator turns it on, and it
+ * cannot hide a tool from tools/list. A long-lived token plus an always-listed
+ * delete tool is a categorically different risk from a read or update tool, so
+ * these two are gated at registration time by this env flag instead. When the
+ * flag is on they are registered like any other tool and remain subject to the
+ * global and per-principal policy, which can still deny them.
+ */
+function destructiveToolsEnabled() {
+    return parseBool(process.env.THALOVANT_ENABLE_DESTRUCTIVE_TOOLS, false);
+}
+/**
+ * Non-catalog skill sources are opt-in.
+ *
+ * thalovant_install_runtime_group_skill can install a skill from a source other
+ * than the vetted marketplace catalog — notably `sourceType: "git"` with an
+ * arbitrary `sourceRef` repository URL. The control-plane validator is
+ * format-only with no host allowlist, so any non-catalog source is effectively
+ * an arbitrary-code-into-the-runtime primitive. Because this server hands its
+ * tools to an LLM holding a long-lived token, that primitive is refused by
+ * default and only enabled when an operator opts in with this flag, mirroring
+ * the THALOVANT_ENABLE_DESTRUCTIVE_TOOLS gate. Installing from the catalog (the
+ * default source) is always allowed.
+ */
+function gitSkillSourcesEnabled() {
+    return parseBool(process.env.THALOVANT_ENABLE_GIT_SKILL_SOURCES, false);
+}
+/** The default install source is the vetted marketplace catalog. */
+function isCatalogSource(sourceType) {
+    return !sourceType || sourceType.trim().toLowerCase() === "catalog";
+}
+/**
+ * Read-only mode.
+ *
+ * When THALOVANT_MCP_READONLY is set, only tools annotated readOnlyHint: true
+ * are registered, so an operator can run a safe agent without hand-writing a
+ * tool denylist. Non-read-only tools are never registered and so never appear
+ * in tools/list. This complements, and is independent of, the per-principal
+ * allow/deny policy in authorizeTool().
+ */
+function readOnlyModeEnabled() {
+    return parseBool(process.env.THALOVANT_MCP_READONLY, false);
+}
+const capacityProfileSchema = z
+    .enum(["standard", "autoscaling"])
+    .describe('Hub capacity profile. Only "standard" (the API default, 1 replica) and "autoscaling" (2-32 replicas) are accepted. Omit the key entirely rather than sending null — an explicit null fails 422 INVALID_HUB_CAPACITY_PROFILE. "autoscaling" is plan-gated: 403 HUB_AUTOSCALING_NOT_INCLUDED when the plan has no autoscaling, 409 AUTOSCALING_HUB_LIMIT_REACHED when its autoscaling slots are already used.');
+const hubSpecSchema = z
+    .object({ version: z.string().min(1).describe("Required. Hub spec version, e.g. \"1\".") })
+    .passthrough()
+    .describe('Hub spec object. `version` is REQUIRED and must be a non-empty string — {"version": "1"} is the minimum valid spec; omitting it fails 422 "Schema validation failed". Other keys pass through, and the API injects defaults for replicas, resources, catalog, and protocols.');
+const hubEtagSchema = z
+    .string()
+    .min(1)
+    .describe("Required. The hub's current etag, sent as If-Match for optimistic locking. Read it from the `etag` field in the hub resource BODY returned by thalovant_get_hub — the API does not send an ETag response header, so you must fetch the hub first. A missing or stale value fails with HTTP 412 and changes nothing: re-fetch the hub, take the new etag, and retry.");
+const runtimeGroupResourceLimitsSchema = z
+    .object({
+    requests: z.record(z.string()).optional(),
+    limits: z.record(z.string()).optional(),
+})
+    .optional();
+const runtimeGroupSpecSchema = z
+    .object({
+    replicas: z.number().int().min(1).max(20).optional().describe("Replica count, 1-20."),
+    resources: z
+        .object({
+        core: runtimeGroupResourceLimitsSchema,
+        messagebus: runtimeGroupResourceLimitsSchema,
+    })
+        .optional()
+        .describe("Container resource requests/limits, as string-valued maps (for example {\"cpu\": \"500m\"})."),
+})
+    .describe("Patches replicas and container resources only. Note the replica ceiling here is 20, separate from a hub's autoscaling ceiling of 32.");
+const releaseOptionsSchema = {
+    channel: z.string().min(1).optional().describe("Release channel. Falls back to the workspace release policy when omitted."),
+    mode: z.string().min(1).optional().describe('Release mode. Passing images without mode switches to "custom".'),
+    version: z.string().min(1).optional().describe("Pinned release version."),
+    images: z.record(z.string().min(1)).optional().describe("Explicit image overrides. Switches to custom mode unless mode is also set."),
+    reason: z.string().min(1).optional().describe("Audit reason recorded with the release."),
+};
+function releaseOptionsFrom(args) {
+    return { channel: args.channel, mode: args.mode, version: args.version, images: args.images, reason: args.reason };
+}
+const SCOPE_HINT_403 = 'HTTP 403 "Insufficient scopes" — the token lacks the scope this route needs: hubs:write for provisioning, hubs:read for the marketplace catalog, hubs:inspect for runtime-group and hub runtime views (hubs:write implies hubs:read, which implies hubs:inspect and hubs:preview). The API checks scope BEFORE the paid-plan gate, so a 403 can mask a plan problem and granting the scope may surface a 402 next. Free-plan API tokens are capped at hubs:read, clients:read, and clients:write, so a free-tier API token fails provisioning with this 403 and never reaches the 402. A 403 here can also mean the caller does not own the resource ("Ownership required"), or a plan restriction such as HUB_AUTOSCALING_NOT_INCLUDED or a custom hub domain the plan does not allow.';
+const PLAN_HINT_402 = 'HTTP 402 "API access requires a paid plan." — the token is valid and correctly scoped but the tenant is on the free plan. Free-tier callers can browse the catalog (thalovant_list_marketplace_skills) and set hub ratings, but cannot create, update, release, or delete hubs and runtime groups, and cannot install skills.';
+const MARKETPLACE_HINT_402 = 'HTTP 402 "This skill requires paid marketplace access for the tenant plan." — a DIFFERENT 402 from the plan gate: the plan is paid enough to provision, but this catalog entry has access_tier "paid" and the plan does not include paid marketplace skills. thalovant_list_runtime_group_marketplace reports this per skill as purchase_required, installable, and access_message; check it before installing.';
+const ETAG_HINT_412 = 'HTTP 412 "ETag mismatch" — the If-Match etag was missing or stale and nothing changed. Re-fetch the hub with thalovant_get_hub, read the `etag` field from the response BODY (there is no ETag response header), and retry with that exact value. The comparison is exact string equality, so do not rewrite or weaken the value.';
+function controlPlaneErrorHint(profile, status, body) {
+    switch (status) {
+        case 402:
+            return profile === "skillInstall" && /marketplace/i.test(body) ? MARKETPLACE_HINT_402 : PLAN_HINT_402;
+        case 403:
+            return SCOPE_HINT_403;
+        case 409:
+            if (profile === "hubWrite") {
+                return 'HTTP 409 — for a hub create this is either a duplicate ("Hub with name ... already exists for this owner" / "Hub slug ... already exists"), an autoscaling slot limit (AUTOSCALING_HUB_LIMIT_REACHED), or "Idempotency key re-used with different payload". Only hub create honors Idempotency-Key: retrying an identical create is safe and returns the original hub, but reusing a key with a changed body conflicts — use a new idempotencyKey for a genuinely different hub.';
+            }
+            return "HTTP 409 — the resource is not in a state that allows this call: a hub with no connected client cannot report runtime capabilities, a runtime group cannot be deleted while it is the workspace default or still has hubs attached, and a deactivated marketplace skill cannot be installed.";
+        case 412:
+            return ETAG_HINT_412;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Run a control-plane call and, on failure, append actionable guidance.
+ *
+ * The SDK raises ThalovantApiError with the status embedded in the message
+ * ("Thalovant API request failed with HTTP 412: ..."), so the status is
+ * recovered by parsing rather than from a structured field.
+ */
+async function callControlPlane(profile, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const status = Number(/HTTP (\d{3})/.exec(message)?.[1]);
+        const hint = Number.isFinite(status) ? controlPlaneErrorHint(profile, status, message) : undefined;
+        if (!hint)
+            throw error;
+        throw new Error(`${message}\n\n${hint}`);
+    }
+}
 class HttpError extends Error {
     status;
     constructor(status, message) {
@@ -365,6 +507,13 @@ async function auditLog(event) {
     }
 }
 function registerThalovantTool(server, name, config, handler) {
+    if (readOnlyModeEnabled()) {
+        const annotations = (config.annotations ?? {});
+        if (annotations.readOnlyHint !== true) {
+            // Read-only mode: do not register write/destructive tools at all.
+            return;
+        }
+    }
     server.registerTool(name, config, async (args, extra) => {
         const principal = principalFromExtra(extra);
         const start = Date.now();
@@ -517,8 +666,53 @@ function summarizeReply(reply) {
         failureEvent: reply.failureEvent ? redactSecrets(reply.failureEvent.asObject()) : undefined,
     };
 }
-async function saveIdentity(path, identity) {
-    const resolvedPath = resolve(path);
+/**
+ * Base directory that saved client-identity files are confined to.
+ *
+ * thalovant_create_client_identity takes an LLM-chosen savePath. The file is
+ * written 0600, but without a base directory the model controls WHERE the
+ * secret lands and could drop a credential file into a git working tree or a
+ * synced folder. Files are therefore confined to THALOVANT_MCP_IDENTITY_DIR,
+ * defaulting to an `identities` folder under the Thalovant SDK config dir
+ * ($XDG_CONFIG_HOME/thalovant, %APPDATA%/Thalovant on Windows, else
+ * ~/.config/thalovant), matching the SDK's own convention.
+ */
+function identityBaseDir() {
+    const override = process.env.THALOVANT_MCP_IDENTITY_DIR?.trim();
+    if (override)
+        return resolve(override);
+    if (process.env.XDG_CONFIG_HOME)
+        return join(process.env.XDG_CONFIG_HOME, "thalovant", "identities");
+    if (process.platform === "win32" && process.env.APPDATA)
+        return join(process.env.APPDATA, "Thalovant", "identities");
+    return join(homedir(), ".config", "thalovant", "identities");
+}
+/**
+ * Resolve an LLM-supplied savePath against the identity base directory and
+ * refuse anything that escapes it. Relative paths resolve inside the base dir;
+ * absolute paths and `..` traversal that land outside it are rejected. The base
+ * dir is realpath'd so a symlinked base still validates correctly.
+ */
+function resolveIdentityPath(savePath) {
+    const baseDir = identityBaseDir();
+    let canonicalBase = resolve(baseDir);
+    try {
+        canonicalBase = realpathSync(canonicalBase);
+    }
+    catch {
+        // Base dir does not exist yet; writeIdentityFile creates it. Use the resolved
+        // (non-canonical) path for containment — nothing is symlinked yet.
+    }
+    const candidate = resolve(canonicalBase, savePath);
+    const rel = relative(canonicalBase, candidate);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`savePath must resolve to a location inside the identity directory (${canonicalBase}). ` +
+            `Absolute paths outside it and ".." traversal are rejected; pass a plain filename such as "my-hub.json". ` +
+            `Set THALOVANT_MCP_IDENTITY_DIR to change the identity directory.`);
+    }
+    return candidate;
+}
+async function writeIdentityFile(resolvedPath, identity) {
     await mkdir(dirname(resolvedPath), { recursive: true, mode: 0o700 });
     await writeFile(resolvedPath, `${stableStringify(identity.asObject(true))}\n`, { mode: 0o600 });
     return resolvedPath;
@@ -913,7 +1107,12 @@ export function createServer() {
         profile: process.env.THALOVANT_PROFILE,
         hasRuntimeEnvIdentity: Boolean(process.env.THALOVANT_ACCESS_KEY || process.env.THALOVANT_IDENTITY),
         defaultProtocol: "wss",
-        secretHandling: "Secrets are redacted in tool output. Identity files are only written when savePath is provided.",
+        destructiveToolsEnabled: destructiveToolsEnabled(),
+        destructiveTools: destructiveToolsEnabled() ? [...DESTRUCTIVE_TOOLS] : [],
+        gitSkillSourcesEnabled: gitSkillSourcesEnabled(),
+        readOnly: readOnlyModeEnabled(),
+        identityDir: identityBaseDir(),
+        secretHandling: "Secrets are redacted in tool output. Identity files are only written when savePath is provided, and only inside identityDir.",
     }));
     registerThalovantTool(server, "thalovant_list_public_hubs", {
         title: "List Public Hubs",
@@ -1003,7 +1202,7 @@ export function createServer() {
                 .string()
                 .min(1)
                 .optional()
-                .describe("Optional local file path for the full secret identity JSON. File mode is set to 0600."),
+                .describe("Optional filename for the full secret identity JSON, written 0600 inside the server's identity directory (see identityDir in thalovant_config_status). Pass a plain filename like \"my-hub.json\"; absolute paths outside the identity directory and \"..\" traversal are rejected."),
         },
         annotations: {
             readOnlyHint: false,
@@ -1012,6 +1211,10 @@ export function createServer() {
             openWorldHint: true,
         },
     }, async ({ hubId, name, siteId, ownerId, active, preferredProtocols, idempotencyKey, spec, 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.
+        const targetIdentityPath = savePath ? resolveIdentityPath(savePath) : undefined;
         const api = await createControlPlane(auth);
         ensureAuthenticated(api);
         const result = await api.createClientIdentity(hubId, {
@@ -1024,7 +1227,7 @@ export function createServer() {
             spec,
         });
         const selectedEndpoint = api.requireRuntimeProtocol(result, preferredProtocols[0]);
-        const savedIdentityPath = savePath ? await saveIdentity(savePath, result.identity) : undefined;
+        const savedIdentityPath = targetIdentityPath ? await writeIdentityFile(targetIdentityPath, result.identity) : undefined;
         return jsonContent({
             result: redactSecrets(result.asObject({ includeSecrets: false })),
             selectedEndpoint,
@@ -1076,7 +1279,7 @@ export function createServer() {
         const client = await createRuntimeClient(runtime);
         try {
             await client.connect(clampTimeout(timeoutMs));
-            return jsonContent(client.healthcheck());
+            return jsonContent(redactSecrets(client.healthcheck()));
         }
         finally {
             await client.close();
@@ -1251,10 +1454,8 @@ export function createServer() {
         description: "Read authenticated Thalovant analytics overview data.",
         inputSchema: {
             ...controlPlaneSchema,
-            admin: z.boolean().optional(),
             range: z.string().min(1).optional(),
             bucket: z.string().min(1).optional(),
-            ownerId: z.string().min(1).optional(),
             hubId: z.string().min(1).optional(),
             clientId: z.string().min(1).optional(),
             country: z.string().min(1).optional(),
@@ -1412,6 +1613,484 @@ export function createServer() {
         await api.deleteMemoryItem(memoryId);
         return textContent("Memory item deleted.");
     });
+    registerThalovantTool(server, "thalovant_list_marketplace_skills", {
+        title: "List Marketplace Skills",
+        description: "Browse the Thalovant marketplace skill catalog. Start here when discovering what a hub could run: each entry carries the fields an install needs (skill_id, source_type, source_ref, package_name, version compatibility, config_schema, secret_schema) plus category, tags, verified, access_tier, and billing_sku. Requires the hubs:read scope and is NOT paid-gated, so a free-tier token can browse the catalog even though it cannot install from it. The response is not paginated — the whole catalog comes back at once.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            ownerId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Admin tokens only. A non-admin caller is silently scoped to their own tenant instead of being rejected, so this is a no-op for ordinary tokens."),
+            includeInactive: z
+                .boolean()
+                .optional()
+                .describe("Admin tokens only. A non-admin caller silently gets active entries only, with no error."),
+            forceRefresh: z
+                .boolean()
+                .optional()
+                .describe("Re-sync the global catalog from its source before answering. Open to all callers; noticeably slower."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ ownerId, includeInactive, forceRefresh, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("read", () => api.listMarketplaceSkills({ ownerId, includeInactive, forceRefresh }))));
+    });
+    registerThalovantTool(server, "thalovant_list_runtime_group_marketplace", {
+        title: "List Runtime Group Marketplace",
+        description: "List the marketplace catalog resolved against one runtime group. This is the view to read immediately before installing: every catalog entry comes back with the group's own state folded in — whether the skill is desired (active, version_pin, source_type), whether it was observed running (observed_source, observed_at, intent counts), operator status, and the plan verdict (purchase_required, installable, access_message). Check installable and purchase_required here to avoid a 402 at install time. Requires the hubs:inspect scope; browsing needs no paid plan. Answers 404 for an unknown group and 403 when the caller does not own it.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            refreshInventory: z
+                .boolean()
+                .optional()
+                .describe("Force a live read from the runtime operator. Without it the envelope source is runtime-group-cache (or runtime-group-cache-empty), never a live read."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ runtimeGroupId, refreshInventory, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("read", () => api.listRuntimeGroupMarketplace(runtimeGroupId, { refreshInventory }))));
+    });
+    registerThalovantTool(server, "thalovant_list_runtime_group_inventory", {
+        title: "List Runtime Group Inventory",
+        description: "List the skills a runtime group is actually observed running right now. Where thalovant_list_runtime_group_marketplace answers 'what could be installed here', this answers 'what is loaded'. Each entry carries skill_id, version, source, active, adapt_intents, padatious_intents, total_intents, and observed_at; the envelope reports source (ovos-runtime-operator, runtime-group-cache, or ovos-runtime-operator-pending), operator_phase, and operator_message. Unlike thalovant_get_hub_runtime_capabilities this never fails with 409 when nothing is reporting — it returns an empty list with a pending source. Requires the hubs:inspect scope; no paid plan needed.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            refresh: z
+                .boolean()
+                .optional()
+                .describe("Force a live operator read. The API also refreshes on its own when it holds no cached snapshot."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ runtimeGroupId, refresh, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("read", () => api.listRuntimeGroupInventory(runtimeGroupId, { refresh }))));
+    });
+    registerThalovantTool(server, "thalovant_create_hub", {
+        title: "Create Hub",
+        description: "Create a Thalovant hub. Requires the hubs:write scope AND a paid plan: a token without the scope fails 403, and because the scope is checked before the plan, granting the scope can then surface a 402 'API access requires a paid plan'. The create is idempotent — the SDK sends an Idempotency-Key, so a retried create returns the first hub rather than making a second one; reusing a key with a DIFFERENT body fails 409.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            name: z.string().min(1).max(128).describe("Hub name, 1-128 characters. Required. Immutable once created."),
+            spec: hubSpecSchema,
+            slug: z
+                .string()
+                .min(1)
+                .max(191)
+                .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Slug must be lowercase alphanumeric segments separated by single hyphens.")
+                .optional()
+                .describe("1-191 chars, lowercase alphanumeric segments separated by single hyphens. Defaults to a slug derived from name. Unlike name, slug stays mutable."),
+            namespace: z.string().min(1).max(128).optional().describe("1-128 characters. Resolved server-side when omitted. Immutable once created."),
+            domain: z
+                .string()
+                .min(1)
+                .max(255)
+                .optional()
+                .describe("Max 255 characters. Immutable once created. Plans without custom domains are rejected with 403; when omitted, a managed subdomain is generated if the plan provides one."),
+            active: z.boolean().optional().describe("Defaults to true."),
+            visibility: z
+                .string()
+                .min(1)
+                .max(32)
+                .optional()
+                .describe('1-32 characters, defaults to "private". Only "public" is special-cased by the API, and public listing is plan-gated.'),
+            ownerId: z.string().min(1).optional().describe("Defaults to the caller. Setting another owner requires admin."),
+            runtimeGroupId: z.string().min(1).optional().describe("Runtime group UUID to attach the hub to."),
+            capacityProfile: capacityProfileSchema.optional(),
+            isLocked: z.boolean().optional(),
+            idempotencyKey: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Reuse the same key to safely retry one create. Reusing it with a different body fails 409."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const { loginScope, apiUrl, idempotencyKey, ...payload } = args;
+        const api = await createControlPlane({ loginScope, apiUrl });
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("hubWrite", () => api.createHub(payload, { idempotencyKey }))));
+    });
+    registerThalovantTool(server, "thalovant_update_hub", {
+        title: "Update Hub",
+        description: "Partially update a Thalovant hub. Send ONLY the fields you are changing — do not round-trip a whole hub resource. name, namespace, and domain are immutable and are deliberately not accepted here; the API rejects a changed value with HTTP 400. This route uses optimistic locking and requires the hub's current etag, which lives in the hub resource BODY (there is no ETag response header), so call thalovant_get_hub first and pass the etag field from its response. A missing or stale etag fails 412 and changes nothing. Requires the hubs:write scope and a paid plan.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            hubId: z.string().min(1).describe("Hub UUID. This authenticated route rejects slugs."),
+            etag: hubEtagSchema,
+            active: z.boolean().optional(),
+            visibility: z
+                .string()
+                .min(1)
+                .max(32)
+                .optional()
+                .describe('1-32 characters. Switching to "public" is plan-gated and fails 403 on plans that keep hubs private.'),
+            slug: z
+                .string()
+                .min(1)
+                .max(191)
+                .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Slug must be lowercase alphanumeric segments separated by single hyphens.")
+                .optional()
+                .describe("Mutable, unlike name/namespace/domain. Fails 409 if the slug is already taken."),
+            spec: hubSpecSchema.optional(),
+            ownerId: z.string().min(1).optional(),
+            runtimeGroupId: z.string().min(1).optional(),
+            capacityProfile: capacityProfileSchema.optional(),
+            isLocked: z.boolean().optional().describe("Admin only: a non-admin gets 403, and a non-admin cannot update a locked hub at all."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const { loginScope, apiUrl, hubId, etag, ...payload } = args;
+        const api = await createControlPlane({ loginScope, apiUrl });
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("hubWrite", () => api.updateHub(hubId, payload, { etag }))));
+    });
+    registerThalovantTool(server, "thalovant_release_hub", {
+        title: "Release Hub",
+        description: "Apply a release policy to a hub and return the updated hub. Every option is optional; omitted fields fall back to the workspace release policy. Passing images switches the hub to custom mode unless mode is also set. Requires the hubs:write scope and a paid plan. No etag is needed.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            hubId: z.string().min(1).describe("Hub UUID."),
+            ...releaseOptionsSchema,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ hubId, channel, mode, version, images, reason, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("hubWrite", () => api.releaseHub(hubId, releaseOptionsFrom({ channel, mode, version, images, reason })))));
+    });
+    registerThalovantTool(server, "thalovant_set_hub_rating", {
+        title: "Set Hub Rating",
+        description: 'Rate a public Thalovant hub from 1 to 5 and return the updated hub. Requires the hubs:write scope; no paid plan is needed, so free-tier tokens can rate. Rating a non-public hub fails 400 "Only public hubs can be rated." and rating your own hub fails 400 "Hub owners cannot rate their own public hubs."',
+        inputSchema: {
+            ...controlPlaneSchema,
+            hubId: z.string().min(1).describe("Hub UUID."),
+            rating: z.number().int().min(1).max(5).describe("Rating, an integer from 1 to 5."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ hubId, rating, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("write", () => api.setHubRating(hubId, rating))));
+    });
+    registerThalovantTool(server, "thalovant_clear_hub_rating", {
+        title: "Clear Hub Rating",
+        description: "Remove the caller's own rating from a public Thalovant hub and return the hub. This clears only the caller's rating, not the hub. Requires the hubs:write scope; no paid plan is needed.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            hubId: z.string().min(1).describe("Hub UUID."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ hubId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("write", () => api.clearHubRating(hubId))));
+    });
+    registerThalovantTool(server, "thalovant_get_hub_runtime_capabilities", {
+        title: "Get Hub Runtime Capabilities",
+        description: "Read the live skill and intent inventory a hub runtime exposes. Requires the hubs:inspect scope. The API answers HTTP 409 when the hub has no connected client that can report inventory — for a group-level view that returns an empty list instead of failing, use thalovant_list_runtime_group_inventory.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            hubId: z.string().min(1).describe("Hub UUID."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ hubId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("read", () => api.getHubRuntimeCapabilities(hubId))));
+    });
+    registerThalovantTool(server, "thalovant_list_runtime_groups", {
+        title: "List Runtime Groups",
+        description: "List the Thalovant runtime groups visible to the authenticated account. Requires the hubs:read scope. The response is not paginated — every visible group is returned at once.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            ownerId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Admin tokens only. Unlike the marketplace catalog, which silently ignores this for non-admins, passing another account's id here fails 403 \"Ownership required\". Omit it to list your own groups."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ ownerId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("read", () => api.listRuntimeGroups({ ownerId }))));
+    });
+    registerThalovantTool(server, "thalovant_get_runtime_group", {
+        title: "Get Runtime Group",
+        description: "Fetch one Thalovant runtime group. Requires the hubs:read scope.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ runtimeGroupId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("read", () => api.getRuntimeGroup(runtimeGroupId))));
+    });
+    registerThalovantTool(server, "thalovant_create_runtime_group", {
+        title: "Create Runtime Group",
+        description: "Create a Thalovant runtime group — the unit that hosts hubs and holds installed skills. Requires the hubs:write scope and a paid plan. Unlike the hub write routes this one takes no etag.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            name: z.string().min(1).max(128).describe("Runtime group name, 1-128 characters. Required."),
+            description: z.string().max(255).optional().describe("Max 255 characters."),
+            environment: z.string().min(1).max(32).optional().describe("1-32 characters. Lowercased server-side; defaults from server settings."),
+            ownerId: z.string().min(1).optional().describe("Defaults to the caller. Setting another owner requires admin."),
+            cloneFromDefault: z
+                .boolean()
+                .optional()
+                .describe("Seed the new group from the workspace default group instead of starting empty."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const { loginScope, apiUrl, ...payload } = args;
+        const api = await createControlPlane({ loginScope, apiUrl });
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("write", () => api.createRuntimeGroup(payload))));
+    });
+    registerThalovantTool(server, "thalovant_update_runtime_group", {
+        title: "Update Runtime Group",
+        description: "Update a Thalovant runtime group's name, description, or spec. spec patches replicas and container resources. This route does NOT use If-Match, so no etag is required. Requires the hubs:write scope and a paid plan.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            name: z.string().min(1).max(128).optional().describe("1-128 characters."),
+            description: z.string().max(255).optional().describe("Max 255 characters."),
+            spec: runtimeGroupSpecSchema.optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        const { loginScope, apiUrl, runtimeGroupId, ...payload } = args;
+        const api = await createControlPlane({ loginScope, apiUrl });
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("write", () => api.updateRuntimeGroup(runtimeGroupId, payload))));
+    });
+    registerThalovantTool(server, "thalovant_get_runtime_group_config", {
+        title: "Get Runtime Group Config",
+        description: "Read a Thalovant runtime group's runtime configuration and personas. Requires the hubs:read scope. Read this before thalovant_update_runtime_group_config so you know what the merge will land on.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ runtimeGroupId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("read", () => api.getRuntimeGroupConfig(runtimeGroupId))));
+    });
+    registerThalovantTool(server, "thalovant_update_runtime_group_config", {
+        title: "Update Runtime Group Config",
+        description: "Merge runtime configuration into a Thalovant runtime group. The API MERGES config into the stored configuration rather than replacing it, and marks the group pending so the runtime operator reconciles the change. personas, when provided, is REPLACED wholesale rather than merged; omit it to leave stored personas untouched. Requires the hubs:write scope and a paid plan.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            config: jsonRecordSchema.describe("Configuration object merged into the stored configuration. Required."),
+            personas: jsonRecordSchema.optional().describe("Replaces the stored personas outright. Left untouched when omitted."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ runtimeGroupId, config, personas, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("write", () => api.updateRuntimeGroupConfig(runtimeGroupId, config, { personas }))));
+    });
+    registerThalovantTool(server, "thalovant_release_runtime_group", {
+        title: "Release Runtime Group",
+        description: "Apply a runtime image policy to a Thalovant runtime group and return the updated group. Options behave like thalovant_release_hub: everything is optional, omitted fields fall back to the workspace release policy, and passing images switches to custom mode unless mode is also set. Requires the hubs:write scope and a paid plan.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            ...releaseOptionsSchema,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ runtimeGroupId, channel, mode, version, images, reason, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await callControlPlane("write", () => api.releaseRuntimeGroup(runtimeGroupId, releaseOptionsFrom({ channel, mode, version, images, reason })))));
+    });
+    registerThalovantTool(server, "thalovant_install_runtime_group_skill", {
+        title: "Install Runtime Group Skill",
+        description: "Install (or re-install) a skill in a Thalovant runtime group from the marketplace catalog. Installing a skill that is already present updates the existing entry rather than failing. Discover skillId with thalovant_list_marketplace_skills, then confirm installable/purchase_required with thalovant_list_runtime_group_marketplace before calling this. Requires the hubs:write scope and a paid plan (402 'API access requires a paid plan'); a paid marketplace skill ALSO needs marketplace access on the tenant plan, which fails with a second, distinct 402 about paid marketplace access. Only catalog sources are allowed by default: installing from a non-catalog source such as sourceType \"git\" runs code the marketplace never vetted and is refused unless the operator sets THALOVANT_ENABLE_GIT_SKILL_SOURCES.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            skillId: z
+                .string()
+                .min(1)
+                .max(191)
+                .describe("Skill id from the catalog, 1-191 characters. Sent as skill_id in the request BODY on install (it is a path segment only on uninstall). For a catalog install the API persists the resolved catalog id, which may differ from what you send."),
+            marketplaceSkillId: z.string().uuid().optional().describe("Catalog entry UUID, to disambiguate when the skill id alone is ambiguous."),
+            sourceType: z
+                .string()
+                .min(1)
+                .max(32)
+                .optional()
+                .describe('Install source, 1-32 characters, defaulting to "catalog". The API accepts any string here rather than a fixed enum, but only "catalog" (requires the skill to exist in the marketplace catalog) and "git" (requires sourceRef) get special handling. The value is trimmed and lower-cased before it is both checked and forwarded, so "Catalog" and " catalog " are treated exactly as "catalog". Any value that is not "catalog" is refused unless the operator sets THALOVANT_ENABLE_GIT_SKILL_SOURCES, because a non-catalog source can pull unvetted code into the runtime.'),
+            sourceRef: z.string().min(1).max(255).optional().describe("Max 255 characters. Required for git installs — a git install without a valid repository URL fails 422. Only usable when THALOVANT_ENABLE_GIT_SKILL_SOURCES is set."),
+            versionPin: z.string().min(1).max(64).optional().describe("Pin the skill to an exact version. Max 64 characters."),
+            active: z
+                .boolean()
+                .optional()
+                .describe("Whether the skill is enabled after install. Defaults to true. Installing with false also adds the skill to the group's blacklist."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ runtimeGroupId, skillId, marketplaceSkillId, sourceType: rawSourceType, sourceRef, versionPin, active, ...auth }) => {
+        // Normalize once (trim + case-fold) and forward the SAME value the gate
+        // validates. Otherwise a whitespace/case variant such as " Catalog " or
+        // "CATALOG" passes the local catalog check while the control plane, which
+        // special-cases only the exact string "catalog", treats it as a
+        // non-catalog source — bypassing the gate for the case it exists to block.
+        // A blank/omitted value defaults to the catalog source server-side.
+        const trimmedSource = typeof rawSourceType === "string" ? rawSourceType.trim() : "";
+        const sourceType = trimmedSource ? trimmedSource.toLowerCase() : undefined;
+        if (!isCatalogSource(sourceType) && !gitSkillSourcesEnabled()) {
+            throw new Error(`Refusing to install a skill from non-catalog source "${rawSourceType}". A non-catalog source (for example sourceType "git" with an arbitrary sourceRef) can pull unvetted code into the runtime and is disabled by default. ` +
+                "Set THALOVANT_ENABLE_GIT_SKILL_SOURCES=1 to allow non-catalog skill sources, or install from the marketplace catalog by omitting sourceType (or setting it to \"catalog\").");
+        }
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        const options = { marketplaceSkillId, sourceType, sourceRef, versionPin, active };
+        return jsonContent(redactSecrets(await callControlPlane("skillInstall", () => api.installRuntimeGroupSkill(runtimeGroupId, skillId, options))));
+    });
+    registerThalovantTool(server, "thalovant_uninstall_runtime_group_skill", {
+        title: "Uninstall Runtime Group Skill",
+        description: "Remove one skill from a Thalovant runtime group. This removes only the named skill; the runtime group and its other skills are untouched. Requires the hubs:write scope and a paid plan.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            skillId: z.string().min(1).describe("Skill id to remove."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ runtimeGroupId, skillId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        await callControlPlane("write", () => api.uninstallRuntimeGroupSkill(runtimeGroupId, skillId));
+        return textContent("Runtime group skill uninstalled.");
+    });
+    if (destructiveToolsEnabled()) {
+        registerThalovantTool(server, "thalovant_delete_hub", {
+            title: "Delete Hub",
+            description: "Permanently delete a Thalovant hub along with its dependent clients and ACLs. This cannot be undone. Requires the hub's current etag, read from the `etag` field in the hub resource BODY returned by thalovant_get_hub — the API sends no ETag response header — and sent as If-Match; a missing or stale etag fails 412 and deletes nothing. Requires the hubs:write scope and a paid plan. This tool is disabled unless the operator sets THALOVANT_ENABLE_DESTRUCTIVE_TOOLS.",
+            inputSchema: {
+                ...controlPlaneSchema,
+                hubId: z.string().min(1).describe("Hub UUID. This authenticated route rejects slugs."),
+                etag: hubEtagSchema,
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        }, async ({ hubId, etag, ...auth }) => {
+            const api = await createControlPlane(auth);
+            ensureAuthenticated(api);
+            await callControlPlane("hubWrite", () => api.deleteHub(hubId, { etag }));
+            return textContent("Hub deleted.");
+        });
+        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.",
+            inputSchema: {
+                ...controlPlaneSchema,
+                runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        }, async ({ runtimeGroupId, ...auth }) => {
+            const api = await createControlPlane(auth);
+            ensureAuthenticated(api);
+            await callControlPlane("write", () => api.deleteRuntimeGroup(runtimeGroupId));
+            return textContent("Runtime group deleted.");
+        });
+    }
     return server;
 }
 export async function startHttpServer(config = getHttpConfig()) {

package/examples/principal-credentials.sample.json

@@ -18,7 +18,7 @@
         }
       },
       "allowedTools": ["thalovant_*"],
-      "deniedTools": ["thalovant_delete_memory_item"]
+      "deniedTools": ["thalovant_delete_memory_item", "thalovant_delete_hub", "thalovant_delete_runtime_group"]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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.2.21",
+    "@thalovant/sdk": "^0.2.28",
     "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.1.9",
+  "version": "0.1.10",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@thalovant/mcp-server",
-      "version": "0.1.9",
+      "version": "0.1.10",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.1.9",
+      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.1.10",
       "transport": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:3000/mcp"