@thalovant/mcp-server 0.6.6 → 0.7.0

package/CHANGELOG.md

@@ -1,8 +1,24 @@
-Last Edit: Codex (exact runtime model identifier unavailable) - 2026-10-25 - Motive: Document the scoped dependency security patch.
+Last Edit: Claude Opus 5.5 - 2026-11-03 - Motive: 0.7.0 chat apps tools; date the published 0.6.6.
 
 # Changelog
 
-## 0.6.6 - Unreleased
+## 0.7.0 - Unreleased
+
+A hub can answer in a chat network through a chat app: Telegram and Discord, and Matrix, Mattermost and Twitch as beta once the API lists them. These tools let an agent read and look after the bridges a person connected in the console. Existing tool schemas are unchanged.
+
+- **Reads:** `thalovant_list_chat_app_connectors` (status, setup steps in `en` or `fr`, the secrets the console asks for by name, the settings form, chat id format, helpers), `thalovant_get_bridge_networks` (networks offered and the plan's allowance, with a `summary`; Free plans get 0), `thalovant_list_bridges`, `thalovant_get_bridge` and `thalovant_list_bridge_chats`. All five change nothing. The first four need `hubs:read` and stay in `THALOVANT_MCP_READONLY` mode. `thalovant_list_bridge_chats` asks the chat network on the bot's behalf, so the API serves it only to `hubs:write`, the hub's owner or a manager, and a paid plan; read-only mode leaves it out.
+- **Status in plain words.** Each bridge's `status` keeps the API's `reason`, `phase`, `ready` and `applied`, and adds `summary`: what `Setup`, `Starting`, `Connected`, `Paused`, `Unavailable`, `TokenMissing` or `TokenRejected` means and what to do, a `plan_limit` or `account_suspended` hold and since when, and whether the latest change has reached the bridge. A reason this server does not know yet is kept and named. The platform's own diagnostic message (`status.message`, `status.operator_reason`) is never included, even for an administrator's token.
+- **Writes:** `thalovant_pause_bridge` and `thalovant_resume_bridge` (`PATCH paused`), `thalovant_update_bridge` (`allowed`, which replaces the whole list, `requireMention`, `sessionScope` and non-secret `settings`) and `thalovant_send_bridge_test_message`. Each takes an optional `etag`, sent as `If-Match` only when given.
+- **Tokens and secrets stay in the console.** No tool takes a credential as an argument, so creating a bridge and replacing its token or secrets have no tool; descriptions and outputs say where to go (Connections > Add connection > Chat apps, or the hub's Chat apps tab, and **Replace token**). `thalovant_update_bridge` refuses a setting whose name looks like a token or secret, at any depth, before any request, naming it by its dotted path without its value.
+- **`thalovant_delete_bridge`**, opt-in with the other destructive tools (`THALOVANT_ENABLE_DESTRUCTIVE_TOOLS`): it removes the bridge and its stored token, which only the console can put back.
+- **Outputs are allowlisted.** Bridges, connectors, chats and the allowance are built from the members the API documents, not passed through; the owner's `settings` and a queued `operation` go through the usual redaction. Redacting whole bridges by key name would have hidden `secrets_set` and `secrets` (names) and `token_updated_at` (a time).
+- **Hints by code** after a refused chat app call: the settings a `bridge_settings_invalid` or `bridge_url_*` refusal names (from the SDK's new `ThalovantApiError.fields`, names only), Telegram's pause-to-list rule (`bridge_running`), the plan's allowance after `402` or `403 plan_limit`, the wait after a `429`, a stale `etag` (`412`), a bridge the token cannot see (`404`), and the console for every token or secret code.
+- The catalog has 59 default tools (28 in read-only mode, 63 with destructive tools enabled).
+- Takes `@thalovant/sdk` ^0.10.0, which carries the chat app methods and `ThalovantApiError.fields`.
+- The parity contract declares `chat-apps` as required and refreshes the evidence hashes of `src/index.ts`, `test/http.test.ts` and `test/provisioning.test.ts`.
+- `package.json`, `package-lock.json`, `server.json`, the OCI label, the README and this file move to 0.7.0 together.
+
+## 0.6.6 - 2026-10-26
 
 - Update body-parser to 2.4.0 (CVE-2026-111181), Zod to 4.6.7 (patched bounds checks from 4.6.6), and the existing fast-uri override to 3.1.9. No audit suppression is added.
 - Migrate five records to Zod 4's explicit string-key signature. Bounded arrays reject oversized input before parsing elements. UUIDs now enforce standard version/variant bits (plus nil/max UUIDs); memory-list offsets reject unsafe integers.

package/README.md

@@ -1,4 +1,4 @@
-Last Edit: Codex (exact runtime model identifier unavailable) - 2026-10-25 - Motive: Record security dependency compatibility and the next patch version.
+Last Edit: Claude Opus 5.5 - 2026-11-03 - Motive: Chat apps tools (connectors, bridges, pause/resume, chats, test message, allowance) for 0.7.0.
 
 # Thalovant MCP Server
 
@@ -16,6 +16,7 @@ It uses the official Thalovant Node.js SDK and the production MCP TypeScript SDK
 - Static bearer tokens for simple/private deployments.
 - JWT/JWKS and OAuth token introspection for production remote deployments.
 - Per-principal Thalovant credentials and tool policy.
+- Chat app tools: connectors, bridges and their status in words, pause and resume, chats, test messages and the plan's allowance. Bot tokens stay in the console.
 - Host/origin validation, CORS, rate limiting, body limits, secure headers, and session binding.
 - Optional resumability event storage and JSONL audit logs.
 - Docker, Compose, Kubernetes, CI, npm package metadata, and MCP registry `server.json`.
@@ -73,9 +74,9 @@ Minimum scopes for the full control-plane tool surface:
 
 | Scope | Used by |
 |-------|---------|
-| `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: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`, the hub lookup inside `thalovant_create_client_identity`, and the chat app reads (`thalovant_list_chat_app_connectors`, `thalovant_get_bridge_networks`, `thalovant_list_bridges`, `thalovant_get_bridge`) |
 | `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 |
+| `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, the chat app writes (`thalovant_pause_bridge`, `thalovant_resume_bridge`, `thalovant_update_bridge`, `thalovant_send_bridge_test_message`), `thalovant_list_bridge_chats` (it changes nothing but asks the chat network, so the API serves it only to `hubs:write` and a paid plan), and the opt-in delete tools |
 | `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` |
@@ -139,6 +140,37 @@ Each refusal of step 2 names what to do next after the API's own text (see [Tool
 
 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.
 
+## Chat Apps
+
+A hub can answer in a chat network through a **chat app**: Telegram and Discord are offered, and Matrix, Mattermost and Twitch appear as beta when the API lists them. Each connection of a hub to a chat network is a *bridge* (`/v1/bridges`). The person makes the bot in the chat network, then connects it to a hub in the Thalovant console.
+
+**Tokens and secrets stay in the console.** Creating a bridge and replacing its token or secrets need the bot's credential, and no tool of this server takes a credential as an argument (see [Control-Plane Auth](#control-plane-auth)), so there is no tool for them. The descriptions and outputs say where to go instead: Connections > Add connection > Chat apps, or the hub's Chat apps tab, and **Replace token** on the bot. `thalovant_update_bridge` refuses a setting whose name looks like a token or secret, at any depth, before any request, naming it by its dotted path and never its value.
+
+| Tool | What it does | Kind |
+|------|--------------|------|
+| `thalovant_list_chat_app_connectors` | The chat apps (`GET /v1/bridges/connectors`) in `en` or `fr`: status (`offered`, `beta`), whether a bridge can be created now, description and setup steps, the secrets the console asks for (by key and label, never a value), the settings form, what a chat id looks like (`targets`), the mention rule, session scopes and helpers | read-only |
+| `thalovant_get_bridge_networks` | Networks offered and the plan's allowance (`GET /v1/bridges/networks`): `limit`, `used`, `remaining`, `paid_plan`, `can_create`, and a `summary` in words. Free plans get 0. With `hubId`, the hub owner's allowance | read-only |
+| `thalovant_list_bridges` | Bridges of one hub (`hubId`) or every bridge the token may see (`ownerId` narrows it; `limit` 1-500) | read-only |
+| `thalovant_get_bridge` | One bridge, with its status in plain words | read-only |
+| `thalovant_list_bridge_chats` | The chats, channels or rooms the bot can see, to choose from; `manual_entry: true` when the ids are typed instead. Changes nothing, but needs `hubs:write` and a paid plan (it asks the network) | read-only, write scope |
+| `thalovant_pause_bridge` | `PATCH paused: true`: stops answering everywhere, keeps chats, settings and token. Always allowed | write |
+| `thalovant_resume_bridge` | `PATCH paused: false`. Needs a paid plan with room in its allowance | write |
+| `thalovant_update_bridge` | The chats it answers in (`allowed`, which replaces the whole list), `requireMention`, `sessionScope`, and non-secret `settings` | write |
+| `thalovant_send_bridge_test_message` | Posts a short "Connected to <hub>." line in one allowed chat | write |
+| `thalovant_delete_bridge` | Deletes the bridge and its stored token; opt-in like the other [destructive tools](#destructive-tools) | destructive |
+
+Each bridge comes back with the API's own members (`network`, `connector`, `state`, `allowed`, `require_mention`, `session_scope`, `paused`, `hold`, `bot`, `invite_links`, `secrets_set` by name, `etag`, timestamps, and `operation` when the change queued one) and `status`:
+
+- `reason` is the API's customer-safe status, and `summary` says it in words: `Setup` (no chats chosen yet), `Starting`, `Connected`, `Paused`, `Unavailable`, `TokenMissing` and `TokenRejected` (both send the person to **Replace token** in the console). A reason this server does not know yet is kept and named.
+- `phase`, `ready`, and `applied`: `true` once the bridge carries the latest change, `false` while it is on its way, `null` in setup.
+- `hold` says why the platform paused a bridge: `plan_limit` (the plan allows fewer running chat apps, after a downgrade; it resumes on its own once there is room) or `account_suspended`. It is `null` for the owner's own pause.
+
+The platform's own diagnostic sentence and condition (`status.message`, `status.operator_reason`, sent to administrators' tokens) are never included. Outputs are built from the members the API documents rather than passed through, so a member added later does not reach the model unreviewed; `settings` and `operation` go through the usual secret redaction.
+
+The write tools take an optional `etag` (the bridge's `etag` field; there is no ETag header), sent as `If-Match`: a stale one fails `412` and changes nothing. Telegram lists chats only while its bridge is paused (`409 bridge_running`), so the flow is pause, send `/start@<bot>` in the new group, list, update `allowed`, resume. A refusal keeps the API's code, sentence and fields (see [Tool Errors](#tool-errors)) and adds a hint by code: the settings a `bridge_settings_invalid` or `bridge_url_*` refusal names (names only), the plan's allowance after `402` or `403 plan_limit`, the wait after `429`, and the console for anything about a token.
+
+Reads need `hubs:read`, except `thalovant_list_bridge_chats`: it changes nothing, but it asks the chat network on the bot's behalf, so it needs `hubs:write`, the hub's owner or a workspace manager, and a paid plan, like the writes. Writes need the same, except pausing and deleting, which always work on any plan. `THALOVANT_MCP_READONLY` keeps the four reads a `hubs:read` token can call and leaves `thalovant_list_bridge_chats` out.
+
 ## Local Stdio
 
 The server speaks MCP over stdio and does not write logs to stdout.
@@ -412,11 +444,24 @@ Hub skills, acting on the hub’s shared runtime (see [Hub Skills](#hub-skills);
 - `thalovant_update_hub_skill`
 - `thalovant_remove_hub_skill`
 
+Chat apps (see [Chat Apps](#chat-apps); the first five are read-only, and `thalovant_list_bridge_chats` needs `hubs:write`):
+
+- `thalovant_list_chat_app_connectors`
+- `thalovant_get_bridge_networks`
+- `thalovant_list_bridges`
+- `thalovant_get_bridge`
+- `thalovant_list_bridge_chats`
+- `thalovant_pause_bridge`
+- `thalovant_resume_bridge`
+- `thalovant_update_bridge`
+- `thalovant_send_bridge_test_message`
+
 Destructive, **not registered unless explicitly enabled** (see [Destructive Tools](#destructive-tools)):
 
 - `thalovant_delete_hub`
 - `thalovant_delete_runtime_group`
 - `thalovant_delete_client`
+- `thalovant_delete_bridge`
 
 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`.
 
@@ -467,6 +512,8 @@ fields: {"allowed_images":{"bus":[...],"core":[...]},"allowed_repositories":{"co
   echoes back from the request -- each entry's `input` in a `detail` or
   `errors` list, whatever its key or shape -- is replaced with `"[omitted]"`
   there and never reaches the first line. A plan refusal carries `resource`, `limit`, `used` and `plan` here.
+  A chat app refusal about settings or secrets carries the API's own `fields`
+  list here: their names, never their values. Its hint repeats the names.
 
 A hint may follow for statuses that need one. A `platform_image_required` or
 `plan_limit` 403 gets its own hint rather than the general scope hint.
@@ -500,7 +547,7 @@ or use an SDK that preserves large JSON integers.
 
 ## Destructive Tools
 
-`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.
+`thalovant_delete_hub`, `thalovant_delete_runtime_group`, `thalovant_delete_client` and `thalovant_delete_bridge` 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 are opt-in:
 
@@ -520,7 +567,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 client cuts off the device or link using it; its etag is read first when none is given.
+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. Deleting a chat app bridge removes its stored token, so connecting the bot again means pasting the token in the console; to stop a bridge for now, pause it instead.
 
 ## Non-Catalog Skill Sources
 
@@ -534,7 +581,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` (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`.
+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), less those the API serves only to a write scope: `thalovant_list_bridge_chats` changes nothing but needs `hubs:write`, which an observe-only agent's token does not carry. 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
 
@@ -542,7 +589,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.6.6 requires `@thalovant/sdk` `^0.9.9` (0.9.9 through versions below 0.10.0). Since 0.5.1 the server enforces
+Version 0.7.0 requires `@thalovant/sdk` `^0.10.0` (0.10.0 through versions below 0.11.0), which carries the chat app methods and `ThalovantApiError.fields`. 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`
@@ -622,7 +669,7 @@ one tool for every SDK conversation or event-listener method.
 
 ### Shared-runtime skill management
 
-The catalog has 50 default tools, 24 in read-only mode, and 53 with destructive tools enabled.
+The catalog has 59 default tools, 28 in read-only mode, and 63 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/chat-apps-output.d.ts

@@ -0,0 +1,46 @@
+import type { Bridge, BridgeChatList, BridgeNetworks, ChatAppConnector } from "@thalovant/sdk";
+/**
+ * What a model reads about chat apps: connectors, bridges, the allowance and
+ * the hints after a refusal.
+ *
+ * A bridge's token and secrets never reach this server: the API never sends
+ * them, and no tool takes them. Each view below is still built from a list of
+ * the members the API documents, never by passing the body through, so a
+ * member the API adds later (or the platform-only `status.message` and
+ * `status.operator_reason`, which an administrator's token is sent) does not
+ * reach the model unreviewed. The owner's free-form values -- `settings` and a
+ * queued `operation` -- go through the server's secret redaction. Redacting
+ * the whole view by key name would hide `secrets_set` and `secrets`, which are
+ * names, and `token_updated_at`, which is a time, so it is not done.
+ */
+export type ChatAppLanguage = "en" | "fr";
+type Redact = (value: unknown) => unknown;
+/** Where a person creates a bridge or pastes its token and secrets. */
+export declare const CONSOLE_CHAT_APPS = "the Thalovant console (Connections > Add connection > Chat apps, or the hub's Chat apps tab)";
+/** Where a person replaces a bridge's token or secrets. */
+export declare const CONSOLE_REPLACE_TOKEN = "the Thalovant console: open the bot from Connections or the hub's Chat apps tab and use Replace token";
+/** One connector as a model reads it, in one language. */
+export declare function connectorView(connector: ChatAppConnector, language: ChatAppLanguage, redact: Redact): Record<string, unknown>;
+export declare function connectorsOutput(connectors: readonly ChatAppConnector[], language: ChatAppLanguage, redact: Redact): Record<string, unknown>;
+/**
+ * A bridge's status in words, from the API's customer-safe `status.reason`,
+ * its `hold` and `status.applied`. Never the platform's own message.
+ */
+export declare function bridgeStatusSummary(bridge: Pick<Bridge, "status" | "hold" | "paused">): string;
+/** One bridge as a model reads it: the API's members, without the platform-only status fields. */
+export declare function bridgeView(bridge: Bridge, redact: Redact): Record<string, unknown>;
+export declare function networksOutput(networks: BridgeNetworks, redact: Redact): Record<string, unknown>;
+export declare function chatsOutput(list: BridgeChatList, redact: Redact): Record<string, unknown>;
+/**
+ * Setting names a tool refuses to send because they look like a token or
+ * secret, at any depth, as dotted paths (`server.auth.token`, `hosts.0.token`).
+ * Only names are returned, never values.
+ */
+export declare function secretLookingSettings(settings: Record<string, unknown> | undefined, isSecretKey: (key: string) => boolean): string[];
+export declare function secretSettingsRefusal(names: readonly string[]): string;
+/**
+ * Guidance after a refused chat app call, by the API's code first and then
+ * its status. Undefined when there is nothing a hint could add.
+ */
+export declare function bridgeErrorHint(error: unknown): string | undefined;
+export {};

package/dist/chat-apps-output.js

@@ -0,0 +1,346 @@
+import { ThalovantApiError, ThalovantApiUnreachableError } from "@thalovant/sdk";
+/** Where a person creates a bridge or pastes its token and secrets. */
+export const CONSOLE_CHAT_APPS = "the Thalovant console (Connections > Add connection > Chat apps, or the hub's Chat apps tab)";
+/** Where a person replaces a bridge's token or secrets. */
+export const CONSOLE_REPLACE_TOKEN = "the Thalovant console: open the bot from Connections or the hub's Chat apps tab and use Replace token";
+const NO_SECRETS_HERE = "This server never takes a token or secret.";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value, language) {
+    if (!value)
+        return null;
+    return language === "fr" && value.fr ? value.fr : value.en;
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+/** The settings form a connector's JSON Schema describes, one entry per setting. */
+function settingFields(schema, language) {
+    if (!isRecord(schema) || !isRecord(schema.properties))
+        return [];
+    const required = new Set(strings(schema.required));
+    return Object.entries(schema.properties).map(([key, raw]) => {
+        const property = isRecord(raw) ? raw : {};
+        const french = language === "fr" && typeof property["x-title-fr"] === "string" ? property["x-title-fr"] : undefined;
+        const field = {
+            key,
+            title: french ?? (typeof property.title === "string" ? property.title : key),
+            required: required.has(key),
+        };
+        for (const name of ["type", "format", "description", "pattern", "enum", "default", "minLength", "maxLength"]) {
+            if (property[name] !== undefined)
+                field[name] = property[name];
+        }
+        return field;
+    });
+}
+/** One connector as a model reads it, in one language. */
+export function connectorView(connector, language, redact) {
+    return {
+        id: connector.id,
+        name: connector.name,
+        status: connector.status,
+        offered: connector.offered,
+        version: connector.version?.version ?? null,
+        description: text(connector.description, language),
+        setup_steps: text(connector.setup_steps, language),
+        // What the console asks the person for: names and labels, never a value.
+        secrets: (connector.secrets ?? []).map((secret) => ({
+            key: secret.key,
+            label: text(secret.label, language),
+            description: text(secret.description, language),
+            required: secret.required,
+        })),
+        settings: redact(settingFields(connector.config_schema, language)),
+        targets: connector.targets
+            ? {
+                label: text(connector.targets.label, language),
+                pattern: connector.targets.pattern,
+                max: connector.targets.max,
+                lowercase: connector.targets.lowercase,
+                strip_prefix: connector.targets.strip_prefix,
+            }
+            : null,
+        require_mention_fixed: connector.options?.require_mention_fixed ?? false,
+        session_scopes: [...(connector.options?.session_scopes ?? [])],
+        helpers: [...(connector.helpers ?? [])],
+    };
+}
+export function connectorsOutput(connectors, language, redact) {
+    return {
+        language,
+        data: connectors.map((connector) => connectorView(connector, language, redact)),
+        next: `Create a bridge, and paste or replace its token or secrets, in ${CONSOLE_CHAT_APPS}. ${NO_SECRETS_HERE} Once it exists, thalovant_list_bridges finds it and the other chat app tools manage it.`,
+    };
+}
+function holdSentence(hold) {
+    switch (hold.reason) {
+        case "plan_limit":
+            return `The platform paused it on ${hold.since} because the plan allows fewer running chat apps than the account has (after a downgrade). It resumes on its own, oldest first, once the plan has room; thalovant_resume_bridge resumes it sooner when thalovant_get_bridge_networks shows room.`;
+        case "account_suspended":
+            return `The platform paused it on ${hold.since} because the account was deactivated; it resumes when the account is reactivated.`;
+        default:
+            return `The platform paused it on ${hold.since} (${hold.reason}).`;
+    }
+}
+/**
+ * A bridge's status in words, from the API's customer-safe `status.reason`,
+ * its `hold` and `status.applied`. Never the platform's own message.
+ */
+export function bridgeStatusSummary(bridge) {
+    const status = bridge.status;
+    const reason = status?.reason;
+    const hold = bridge.hold ?? null;
+    const parts = [];
+    switch (reason) {
+        case "Setup":
+            parts.push("Setting up: no chats are chosen yet, so it does not run. Choose where it answers with thalovant_update_bridge (allowed); thalovant_list_bridge_chats lists the chats it can see.");
+            break;
+        case "Starting":
+            parts.push("Starting: the bridge is on its way or has not reported yet, usually for a minute or two.");
+            break;
+        case "Connected":
+            parts.push("Connected: the bridge is running and answers in its allowed chats.");
+            break;
+        case "Paused":
+            parts.push(hold ? "Paused." : "Paused by its owner: it answers nowhere until thalovant_resume_bridge.");
+            break;
+        case "Unavailable":
+            parts.push("Unavailable: the bridge is deployed but not running, or the platform hit an error. Nothing on the owner's side needs to change; check again later.");
+            break;
+        case "TokenMissing":
+            parts.push(`Token missing: the bridge's token has not reached it. If this lasts more than a few minutes, paste the token again in ${CONSOLE_REPLACE_TOKEN}.`);
+            break;
+        case "TokenRejected":
+            parts.push(`Token rejected: the chat network refused the bridge's credentials. Paste new ones in ${CONSOLE_REPLACE_TOKEN}. ${NO_SECRETS_HERE}`);
+            break;
+        default:
+            parts.push(`${reason ?? "Unknown"}: a status this server does not know yet (phase ${status?.phase ?? "unknown"}).`);
+    }
+    if (hold)
+        parts.push(holdSentence(hold));
+    else if (bridge.paused && reason === "Setup")
+        parts.push("It is paused too, so choosing chats will not start it until thalovant_resume_bridge.");
+    else if (bridge.paused && reason !== "Paused")
+        parts.push("It is paused; stopping it may still be on its way.");
+    else if (bridge.paused === false && reason === "Paused")
+        parts.push("It is no longer paused; starting again may still be on its way.");
+    if (status?.applied === true)
+        parts.push("Every change is applied.");
+    else if (status?.applied === false)
+        parts.push("A change is still on its way to the bridge.");
+    return parts.join(" ");
+}
+/** One bridge as a model reads it: the API's members, without the platform-only status fields. */
+export function bridgeView(bridge, redact) {
+    const status = bridge.status;
+    return {
+        id: bridge.id,
+        hub_id: bridge.hub_id,
+        owner_id: bridge.owner_id,
+        network: bridge.network,
+        connector: bridge.connector
+            ? { id: bridge.connector.id, name: bridge.connector.name, version: bridge.connector.version }
+            : null,
+        state: bridge.state,
+        paused: bridge.paused,
+        hold: bridge.hold ? { reason: bridge.hold.reason, since: bridge.hold.since } : null,
+        status: {
+            reason: status?.reason ?? null,
+            phase: status?.phase ?? null,
+            ready: status?.ready ?? false,
+            applied: status?.applied ?? null,
+            summary: bridgeStatusSummary(bridge),
+        },
+        allowed: (bridge.allowed ?? []).map((chat) => ({
+            id: chat.id,
+            title: chat.title,
+            kind: chat.kind,
+            guild_id: chat.guild_id,
+            guild_name: chat.guild_name,
+        })),
+        require_mention: bridge.require_mention,
+        session_scope: bridge.session_scope,
+        settings: redact(bridge.settings ?? {}),
+        // Which secrets are stored, by name; their values are never sent.
+        secrets_set: strings(bridge.secrets_set),
+        bot: bridge.bot
+            ? {
+                user_id: bridge.bot.user_id,
+                username: bridge.bot.username,
+                display_name: bridge.bot.display_name,
+                application_id: bridge.bot.application_id,
+                avatar_url: bridge.bot.avatar_url,
+            }
+            : null,
+        invite_links: bridge.invite_links
+            ? { add_to_group: bridge.invite_links.add_to_group, direct_chat: bridge.invite_links.direct_chat }
+            : null,
+        etag: bridge.etag,
+        token_updated_at: bridge.token_updated_at,
+        activated_at: bridge.activated_at,
+        created_at: bridge.created_at,
+        updated_at: bridge.updated_at,
+        operation: bridge.operation ? redact(bridge.operation) : null,
+    };
+}
+function allowanceSummary(allowance) {
+    if (!allowance.paid_plan) {
+        return `The ${allowance.plan} plan is not a paid plan, and chat apps need one: Free plans get 0, and creating one answers 402. Pausing and deleting a bridge always work.`;
+    }
+    if (allowance.limit === 0) {
+        return `The ${allowance.plan} plan includes no chat apps.`;
+    }
+    const room = allowance.can_create
+        ? `A new one would pass the plan checks (create it in ${CONSOLE_CHAT_APPS}).`
+        : "A new one would not pass the plan checks now.";
+    return `The ${allowance.plan} plan: ${allowance.used} of ${allowance.limit} chat apps used (set up or running), ${allowance.remaining} left. ${room}`;
+}
+export function networksOutput(networks, redact) {
+    return {
+        networks: (networks.networks ?? []).map((offer) => ({
+            network: offer.network,
+            name: offer.name,
+            status: offer.status,
+            offered: offer.offered,
+        })),
+        allowance: redact({ ...networks.allowance }),
+        summary: allowanceSummary(networks.allowance),
+    };
+}
+export function chatsOutput(list, redact) {
+    return {
+        ...redact({
+            network: list.network,
+            manual_entry: list.manual_entry,
+            note: list.note,
+            data: (list.data ?? []).map((chat) => ({
+                id: chat.id,
+                title: chat.title,
+                kind: chat.kind,
+                guild_id: chat.guild_id,
+                guild_name: chat.guild_name,
+                guild_icon_url: chat.guild_icon_url,
+                allowed: chat.allowed,
+                encrypted: chat.encrypted,
+                selectable: chat.selectable,
+            })),
+        }),
+        next: list.manual_entry
+            ? "This chat app cannot list its chats: type each id yourself, matching targets.pattern from thalovant_list_chat_app_connectors, in allowed for thalovant_update_bridge."
+            : "Pass the chosen rows (id, title, kind, guild_id, guild_name) as allowed to thalovant_update_bridge. allowed replaces the whole list, so keep the chats the bridge already answers in (allowed: true). A row with selectable false cannot be chosen.",
+    };
+}
+/**
+ * Setting names a tool refuses to send because they look like a token or
+ * secret, at any depth, as dotted paths (`server.auth.token`, `hosts.0.token`).
+ * Only names are returned, never values.
+ */
+export function secretLookingSettings(settings, isSecretKey) {
+    const found = [];
+    const visit = (value, path) => {
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => visit(item, `${path}.${index}`));
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        for (const [key, nested] of Object.entries(value)) {
+            const here = path ? `${path}.${key}` : key;
+            if (isSecretKey(key))
+                found.push(here);
+            else
+                visit(nested, here);
+        }
+    };
+    visit(settings, "");
+    return found;
+}
+export function secretSettingsRefusal(names) {
+    return `Nothing was sent: settings never carry a token or secret, and these setting names look like one: ${names.join(", ")}. Paste tokens and secrets in ${CONSOLE_REPLACE_TOKEN}. ${NO_SECRETS_HERE}`;
+}
+function named(error, what) {
+    const names = error.fields ?? [];
+    return names.length ? ` The API named the ${what}: ${names.join(", ")} (values are never repeated).` : "";
+}
+/**
+ * Guidance after a refused chat app call, by the API's code first and then
+ * its status. Undefined when there is nothing a hint could add.
+ */
+export function bridgeErrorHint(error) {
+    if (error instanceof ThalovantApiUnreachableError) {
+        return "The Thalovant API could not be reached, which says nothing about the bridge: a change may have been made all the same. Read the bridge with thalovant_get_bridge before trying again.";
+    }
+    if (!(error instanceof ThalovantApiError))
+        return undefined;
+    const wait = error.retryAfterSeconds !== undefined ? ` Wait ${error.retryAfterSeconds} seconds before trying again.` : " Wait before trying again.";
+    switch (error.code) {
+        case "bridge_running":
+            return "Telegram lists chats only while the bridge is paused, because the running bridge reads the bot's messages itself. Pause it with thalovant_pause_bridge, send /start@<bot username> in the new group, list the chats, choose them with thalovant_update_bridge, then resume it with thalovant_resume_bridge. A chat id you already know can be set without listing.";
+        case "bridge_telegram_updates_busy":
+            return "Telegram itself refused the listing: another program or a webhook is reading this bot's messages. Stop it, or type the chat id.";
+        case "bridge_helper_unavailable":
+            return "This chat app has no test message. Mention the bot in one of its allowed chats instead.";
+        case "bridge_token_missing":
+        case "bridge_token_malformed":
+        case "bridge_token_invalid":
+        case "bridge_token_not_a_bot":
+        case "bridge_token_other_bot":
+        case "bridge_bot_in_use":
+        case "bridge_secrets_invalid":
+            return `This is about the bridge's token or secrets, which only ${CONSOLE_CHAT_APPS} takes. ${NO_SECRETS_HERE}${named(error, "secrets")}`;
+        case "bridge_network_refused":
+            return "The chat network refused the request, for example because the bot was removed from that chat; detail gives its reason. Add the bot back, or choose another chat.";
+        case "bridge_allowed_required":
+            return "allowed cannot be empty. To stop the bridge answering, pause it with thalovant_pause_bridge.";
+        case "bridge_chat_id_invalid":
+            return "A chat id does not match this chat app's format: see targets.pattern in thalovant_list_chat_app_connectors, or pick ids from thalovant_list_bridge_chats.";
+        case "bridge_chat_not_allowed":
+            return "A test message goes only to a chat in the bridge's allowed list. Pick one from thalovant_get_bridge, or add the chat with thalovant_update_bridge first (allowed replaces the whole list).";
+        case "bridge_settings_invalid":
+            return `A setting is unknown, missing or outside the chat app's settings form (settings in thalovant_list_chat_app_connectors).${named(error, "settings")} Tokens and secrets are never settings: they go in ${CONSOLE_CHAT_APPS}.`;
+        case "bridge_url_invalid":
+        case "bridge_url_port_not_allowed":
+        case "bridge_url_not_public":
+        case "bridge_url_unresolvable":
+            return `An address setting must be https on port 443, with a public host name (no IP address, no local or internal name, no user name, query or fragment) that resolves to public addresses only.${named(error, "settings")}`;
+        case "bridge_too_many_targets":
+            return "More chats than this chat app allows: see targets.max in thalovant_list_chat_app_connectors.";
+        case "bridge_mention_required":
+            return "A Discord bridge answers only messages that mention it or reply to it, so requireMention cannot be false.";
+        case "bridge_rate_limited":
+            return `Too many test messages or chat listings for this bridge.${wait}`;
+        case "bridge_network_rate_limited":
+            return `The chat network is limiting this bot.${wait}`;
+        case "bridge_network_unavailable":
+        case "bridge_network_timeout":
+            return "The chat network could not be reached or did not answer in time. Try again later.";
+        case "bridge_network_not_offered":
+            return "This chat app is not offered on this API right now; thalovant_get_bridge_networks says which are.";
+        case "bridge_secret_store_failed":
+        case "bridge_secret_store_unavailable":
+            return "The platform could not reach the store that keeps bridge tokens. Try again later.";
+        case "plan_limit":
+            return "The plan's chat-app allowance is used (resource, limit and used are in the fields above). Resuming needs room in it: pause or delete another bridge, or move to a larger plan; thalovant_get_bridge_networks shows the allowance. Pausing is always allowed, and granting a scope will not help.";
+        default:
+            break;
+    }
+    switch (error.statusCode) {
+        case 401:
+        case 423:
+            return "The API refused the token itself: it is unknown, expired or revoked (401), or the account is locked (423). Sign in again with thalovant_begin_device_login, or configure a valid token.";
+        case 402:
+            return "The hub's owner is on a plan without chat apps (Free plans get 0). Pausing and deleting a bridge always work; anything else needs a paid plan, and granting a scope will not help.";
+        case 403:
+            return "Reading chat apps needs the hubs:read scope, and changing them hubs:write. Listing a bridge's chats (thalovant_list_bridge_chats) also needs hubs:write and a paid plan, because it asks the chat network. A 403 can also mean the token's account does not manage this bridge (only the hub's owner or a workspace manager may change it or list its chats), or that the owner's account is deactivated.";
+        case 404:
+            return "No bridge with this id is visible to this token: a bridge is visible to its hub's owner, the workspace's members above basic, and platform administrators. thalovant_list_bridges lists the visible ones. An API without chat apps answers 404 on every bridge route.";
+        case 412:
+            return "ETag mismatch: the bridge changed after its etag was read, and nothing changed now. Read it again with thalovant_get_bridge and retry with its new etag field, or leave etag out to change the bridge as it is now.";
+        case 429:
+            return `Too many requests.${wait}`;
+        default:
+            return undefined;
+    }
+}

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { apiErrorText } from "./api-error-output.js";
+import { bridgeErrorHint, bridgeView, chatsOutput, connectorsOutput, CONSOLE_CHAT_APPS, CONSOLE_REPLACE_TOKEN, networksOutput, secretLookingSettings, secretSettingsRefusal, } from "./chat-apps-output.js";
 import { DeviceLogins } from "./device-login.js";
 import { inventoryPresentation } from "./inventory-output.js";
 import { runtimeReplyContent } from "./reply-output.js";
@@ -129,7 +130,12 @@ 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", "thalovant_delete_client"];
+const DESTRUCTIVE_TOOLS = [
+    "thalovant_delete_hub",
+    "thalovant_delete_runtime_group",
+    "thalovant_delete_client",
+    "thalovant_delete_bridge",
+];
 /**
  * Device sign-ins in progress, and the tokens approved ones minted, per
  * principal, for the life of this process. See device-login.ts.
@@ -184,6 +190,15 @@ function isCatalogSource(sourceType) {
 function readOnlyModeEnabled() {
     return parseBool(process.env.THALOVANT_MCP_READONLY, false);
 }
+/**
+ * Tools that change nothing (readOnlyHint: true) but that the API serves only
+ * to a write scope, so read-only mode leaves them out as well: an observe-only
+ * agent runs on a read-only token, which the API would refuse with 403.
+ * thalovant_list_bridge_chats asks the chat network on the bot's behalf, and
+ * the API answers it only for hubs:write, the hub's owner or a manager, and a
+ * paid plan.
+ */
+const WRITE_SCOPE_READ_TOOLS = new Set(["thalovant_list_bridge_chats"]);
 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.');
@@ -195,6 +210,24 @@ 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 bridgeIdSchema = z.string().uuid().describe("Bridge UUID: the id from thalovant_list_bridges.");
+const bridgeEtagSchema = z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Optional. The bridge's etag, read from the `etag` field of thalovant_get_bridge (the API sends no ETag header), sent as If-Match: a bridge changed since fails with HTTP 412 and nothing changes. Leave it out to change the bridge as it is now.");
+/** A chat, channel or room id as the API accepts one; each chat app's targets.pattern narrows it. */
+const bridgeChatIdSchema = z.string().regex(/^[^\s,]{1,255}$/, "A chat id is 1-255 characters with no spaces or commas.");
+// The display members are nullable because a bridge's own allowed entries,
+// which a model is told to keep, carry null where the API has nothing.
+const bridgeAllowedChatSchema = z.object({
+    id: bridgeChatIdSchema.describe("The chat, channel or room id: a row's id from thalovant_list_bridge_chats, or typed to match the chat app's targets.pattern."),
+    title: z.string().max(200).nullable().optional().describe("The chat's name, for display only."),
+    kind: z.string().max(32).nullable().optional().describe("The row's kind, for display only."),
+    guild_id: z.string().regex(/^[0-9]{1,20}$/).nullable().optional().describe("Discord: the server the channel belongs to."),
+    guild_name: z.string().max(100).nullable().optional().describe("Discord: the server's name."),
+});
 const runtimeGroupResourceLimitsSchema = z
     .object({
     requests: z.record(z.string(), z.string()).optional(),
@@ -293,6 +326,14 @@ function withConnectionHint(error, connectionType) {
     const said = apiErrorText(error, redactSecrets) ?? (error instanceof Error ? error.message : String(error));
     throw new Error(`${said}\n\n${hint}`, { cause: error });
 }
+/** Rethrow a refused chat app call with its guidance (see chat-apps-output.ts), when it has any. */
+function withBridgeHint(error) {
+    const hint = bridgeErrorHint(error);
+    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.
  *
@@ -610,8 +651,9 @@ 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.
+        if (annotations.readOnlyHint !== true || WRITE_SCOPE_READ_TOOLS.has(name)) {
+            // Read-only mode: do not register write/destructive tools at all, nor
+            // the reads only a write scope may call.
             return;
         }
     }
@@ -658,6 +700,11 @@ function clampTimeout(timeoutMs) {
         return DEFAULT_TIMEOUT_MS;
     return Math.min(Math.max(timeoutMs, 1_000), MAX_TIMEOUT_MS);
 }
+/** Whether a member name looks like it holds a credential (see SECRET_KEYS). */
+function isSecretKeyName(key) {
+    const normalized = key.toLowerCase();
+    return SECRET_KEYS.some((secretKey) => normalized.includes(secretKey.toLowerCase()));
+}
 function redactSecrets(value) {
     if (Array.isArray(value)) {
         return value.map((item) => redactSecrets(item));
@@ -667,9 +714,7 @@ function redactSecrets(value) {
     }
     const output = {};
     for (const [key, nestedValue] of Object.entries(value)) {
-        const normalized = key.toLowerCase();
-        const isSecret = SECRET_KEYS.some((secretKey) => normalized.includes(secretKey.toLowerCase()));
-        output[key] = isSecret ? "[redacted]" : redactSecrets(nestedValue);
+        output[key] = isSecretKeyName(key) ? "[redacted]" : redactSecrets(nestedValue);
     }
     return output;
 }
@@ -2531,7 +2576,150 @@ export function createServer() {
         const result = await callControlPlane("write", () => api.removeHubSkill(hubId, skill, options));
         return jsonContent(redactSecrets({ ...result, operation: result.operation ?? null }));
     });
+    // Chat apps (/v1/bridges): a hub answering in Telegram, Discord and the
+    // other chat networks. Creating a bridge and replacing its token or secrets
+    // take a credential, which no tool of this server accepts, so those stay in
+    // the console; see chat-apps-output.ts for what each output shows.
+    registerThalovantTool(server, "thalovant_list_chat_app_connectors", {
+        title: "List Chat App Connectors",
+        description: `List the chat apps a hub can answer in (GET /v1/bridges/connectors): Telegram and Discord, and Matrix, Mattermost or Twitch when they are listed. Each has status (offered, or beta), offered (whether a bridge can be created for it now), its description and setup steps in the language asked (English where there is no French), the secrets the console asks for (key, label, required: names only, never a value), the settings form, what a chat id looks like (targets: label, pattern, max, lowercase, strip_prefix), require_mention_fixed, the session scopes, and its helpers: with discover, thalovant_list_bridge_chats lists the chats (otherwise ids are typed); with test_message, thalovant_send_bridge_test_message works. Creating a bridge, and pasting or replacing its token or secrets, happen only in ${CONSOLE_CHAT_APPS}: no tool takes a token or secret. Requires the hubs:read scope. Reads only.`,
+        inputSchema: {
+            ...controlPlaneSchema,
+            language: z.enum(["en", "fr"]).default("en").describe("Language for descriptions, setup steps and labels: en or fr. French falls back to English where a text has no French."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ language, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        const connectors = await api.listChatAppConnectors().catch(withBridgeHint);
+        return jsonContent(connectorsOutput(connectors, language, redactSecrets));
+    });
+    registerThalovantTool(server, "thalovant_get_bridge_networks", {
+        title: "Get Chat App Allowance",
+        description: "Show which chat networks are offered and the plan's chat-app allowance (GET /v1/bridges/networks): networks (network, name, status offered or beta, offered) and allowance (plan, paid_plan, limit, used: bridges set up or running, remaining, can_create: whether a new bridge would pass the plan checks, saying nothing about a token). Free plans get 0. With hubId the allowance is the hub owner's, since bridges count against the owner; otherwise the caller's. summary says it in words. Read it before suggesting a new chat app or resuming one the plan paused. Requires the hubs:read scope. Reads only.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            hubId: z.string().uuid().optional().describe("Hub UUID: report the allowance of this hub's owner."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ hubId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        const networks = await api.getBridgeNetworks({ hubId }).catch(withBridgeHint);
+        return jsonContent(networksOutput(networks, redactSecrets));
+    });
+    registerThalovantTool(server, "thalovant_list_bridges", {
+        title: "List Chat App Bridges",
+        description: "List chat app bridges (GET /v1/bridges): one hub's with hubId, otherwise every bridge the token may see (its own, and those of workspaces where it is a member above basic); ownerId narrows that to one owner. Each bridge has its network and connector, state (setup or active), the chats it answers in (allowed), require_mention, session_scope, paused, hold (why the platform paused it: plan_limit or account_suspended; null for the owner's own pause), the bot, its invite links, secrets_set (which secrets are stored, by name), its etag, and status: reason (Setup, Starting, Connected, Paused, Unavailable, TokenMissing, TokenRejected), phase, ready, applied (whether the latest change has reached the bridge) and summary, the status in plain words. The platform's own diagnostic message is never included. Requires the hubs:read scope. Reads only.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            hubId: z.string().uuid().optional().describe("Hub UUID: list only this hub's bridges."),
+            ownerId: z.string().uuid().optional().describe("Owner UUID: narrow the visible bridges to this owner's."),
+            limit: z.number().int().min(1).max(500).optional().describe("At most this many bridges, 1-500. The API answers up to 200 when omitted."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ hubId, ownerId, limit, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        const bridges = await api.listBridges({ hubId, ownerId, limit }).catch(withBridgeHint);
+        return jsonContent({ data: bridges.map((bridge) => bridgeView(bridge, redactSecrets)) });
+    });
+    registerThalovantTool(server, "thalovant_get_bridge", {
+        title: "Get Chat App Bridge",
+        description: "Fetch one chat app bridge (GET /v1/bridges/{id}) with the same fields as thalovant_list_bridges: status.reason, phase, ready, applied and summary (the status in plain words), hold, the chats it answers in, and the etag the write tools accept. The platform's own diagnostic message is never included. Requires the hubs:read scope. Reads only.",
+        inputSchema: { ...controlPlaneSchema, bridgeId: bridgeIdSchema },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ bridgeId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(bridgeView(await api.getBridge(bridgeId).catch(withBridgeHint), redactSecrets));
+    });
+    registerThalovantTool(server, "thalovant_list_bridge_chats", {
+        title: "List Bridge Chats",
+        description: "List the chats, channels or rooms a bridge's bot can see (GET /v1/bridges/{id}/chats), to choose from for allowed in thalovant_update_bridge. Each row has id, title, kind, the Discord server (guild_id, guild_name), allowed (it already answers there), and selectable (false for an encrypted room it cannot read). manual_entry true means this chat app cannot list its chats: type the ids instead, matching targets.pattern from thalovant_list_chat_app_connectors. Telegram lists only chats that wrote to the bot in the last 24 hours, and only while the bridge is paused (409 bridge_running otherwise): pause it with thalovant_pause_bridge, send /start@<bot username> in the new group, list, choose with thalovant_update_bridge, then resume. Listing is rate-limited per bridge. It changes nothing, but because it asks the chat network on the bot's behalf it needs the hubs:write scope, a paid plan, and the hub's owner or a workspace manager (403 for a hubs:read token, 402 on a plan without chat apps); THALOVANT_MCP_READONLY leaves it out.",
+        inputSchema: { ...controlPlaneSchema, bridgeId: bridgeIdSchema },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ bridgeId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(chatsOutput(await api.listBridgeChats(bridgeId).catch(withBridgeHint), redactSecrets));
+    });
+    registerThalovantTool(server, "thalovant_pause_bridge", {
+        title: "Pause Chat App Bridge",
+        description: "Pause a chat app bridge (PATCH /v1/bridges/{id} with paused: true): it stops answering in every chat until resumed, and keeps its chats, settings and token. Always allowed, whatever the plan. Returns the bridge; status.reason turns Paused once the bridge has stopped. Requires the hubs:write scope, and the hub's owner or a workspace manager.",
+        inputSchema: { ...controlPlaneSchema, bridgeId: bridgeIdSchema, etag: bridgeEtagSchema },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ bridgeId, etag, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(bridgeView(await api.updateBridge(bridgeId, { paused: true }, { etag }).catch(withBridgeHint), redactSecrets));
+    });
+    registerThalovantTool(server, "thalovant_resume_bridge", {
+        title: "Resume Chat App Bridge",
+        description: "Resume a paused chat app bridge (PATCH /v1/bridges/{id} with paused: false). Needs a paid plan with room for one more running bridge: 402 on a plan without chat apps, 403 plan_limit when its running bridges are already at the limit (thalovant_get_bridge_networks shows the allowance). A bridge paused because the account was deactivated (hold account_suspended) resumes when the account is reactivated. A bridge with no chats yet (status Setup) starts only once thalovant_update_bridge sets allowed. Returns the bridge; status.reason turns Connected once it runs. Requires the hubs:write scope, and the hub's owner or a workspace manager.",
+        inputSchema: { ...controlPlaneSchema, bridgeId: bridgeIdSchema, etag: bridgeEtagSchema },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ bridgeId, etag, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(bridgeView(await api.updateBridge(bridgeId, { paused: false }, { etag }).catch(withBridgeHint), redactSecrets));
+    });
+    registerThalovantTool(server, "thalovant_update_bridge", {
+        title: "Update Chat App Bridge",
+        description: `Change where and how a chat app bridge answers (PATCH /v1/bridges/{id}); send only what changes, at least one of allowed, requireMention, sessionScope and settings. allowed REPLACES the whole list of chats, channels or rooms the bridge answers in (1-50, never empty: pause it instead): keep the current ones from thalovant_get_bridge, add rows from thalovant_list_bridge_chats, or type ids matching the chat app's targets.pattern. Setting allowed the first time starts a bridge in setup. requireMention false makes it answer every message in its groups, which spends the daily allowance faster; a Discord bridge always needs a mention (422 bridge_mention_required). sessionScope person gives each person a conversation of their own, chat one per chat. settings are the chat app's non-secret settings (its settings form in thalovant_list_chat_app_connectors), merged into the stored ones and checked again; an address must be https on port 443 with a public host. A token or secret is never a setting: a setting name that looks like one is refused here before any request, and tokens and secrets are replaced in ${CONSOLE_REPLACE_TOKEN}. To pause or resume, use thalovant_pause_bridge or thalovant_resume_bridge. Needs a paid plan. Requires the hubs:write scope, and the hub's owner or a workspace manager.`,
+        inputSchema: {
+            ...controlPlaneSchema,
+            bridgeId: bridgeIdSchema,
+            allowed: z.array(bridgeAllowedChatSchema).min(1).max(50).optional().describe("Every chat the bridge should answer in, 1-50; replaces the stored list."),
+            requireMention: z.boolean().optional().describe("Answer only messages that mention the bot or reply to it. Discord bridges are always true."),
+            sessionScope: z.enum(["person", "chat"]).optional().describe("person: each person has a conversation of their own; chat: one conversation per chat."),
+            settings: jsonRecordSchema
+                .refine((value) => Object.keys(value).length <= 32, "At most 32 settings.")
+                .optional()
+                .describe("Non-secret settings to change, at most 32, by the setting keys of the chat app's settings form; merged into the stored ones."),
+            etag: bridgeEtagSchema,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ bridgeId, allowed, requireMention, sessionScope, settings, etag, ...auth }) => {
+        if (allowed === undefined && requireMention === undefined && sessionScope === undefined && settings === undefined) {
+            throw new Error("Nothing to change: pass at least one of allowed, requireMention, sessionScope and settings. To pause or resume, use thalovant_pause_bridge or thalovant_resume_bridge.");
+        }
+        const secretLooking = secretLookingSettings(settings, isSecretKeyName);
+        if (secretLooking.length)
+            throw new Error(secretSettingsRefusal(secretLooking));
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        const bridge = await api
+            .updateBridge(bridgeId, { allowed, requireMention, sessionScope, settings }, { etag })
+            .catch(withBridgeHint);
+        return jsonContent(bridgeView(bridge, redactSecrets));
+    });
+    registerThalovantTool(server, "thalovant_send_bridge_test_message", {
+        title: "Send Bridge Test Message",
+        description: "Post a short \"Connected to <hub>.\" message, in the hub's language, in one of a chat app bridge's allowed chats (POST /v1/bridges/{id}/test). Everyone in that chat sees it. chatId must be in the bridge's allowed list (422 bridge_chat_not_allowed otherwise). Only chat apps with the test_message helper have one (Telegram and Discord; 409 bridge_helper_unavailable otherwise: mention the bot in the chat instead). A few test messages an hour per bridge; past that, 429 says how long to wait. Needs a paid plan. Requires the hubs:write scope, and the hub's owner or a workspace manager.",
+        inputSchema: {
+            ...controlPlaneSchema,
+            bridgeId: bridgeIdSchema,
+            chatId: bridgeChatIdSchema.describe("An id from the bridge's allowed list."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async ({ bridgeId, chatId, ...auth }) => {
+        const api = await createControlPlane(auth);
+        ensureAuthenticated(api);
+        return jsonContent(redactSecrets(await api.sendBridgeTestMessage(bridgeId, chatId).catch(withBridgeHint)));
+    });
     if (destructiveToolsEnabled()) {
+        registerThalovantTool(server, "thalovant_delete_bridge", {
+            title: "Delete Chat App Bridge",
+            description: `Permanently delete a chat app bridge (DELETE /v1/bridges/{id}): it stops answering for the hub, and its stored token and secrets are removed from Thalovant. This cannot be undone: connecting the bot again means pasting its token in ${CONSOLE_CHAT_APPS}, which no tool can do. The bot itself stays in the person's Telegram account or Discord Developer Portal. To stop it answering for now, pause it with thalovant_pause_bridge instead. Always allowed, whatever the plan. Requires the hubs:write scope. This tool is disabled unless the operator sets THALOVANT_ENABLE_DESTRUCTIVE_TOOLS.`,
+            inputSchema: { ...controlPlaneSchema, bridgeId: bridgeIdSchema },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+        }, async ({ bridgeId, ...auth }) => {
+            const api = await createControlPlane(auth);
+            ensureAuthenticated(api);
+            await api.deleteBridge(bridgeId).catch(withBridgeHint);
+            return jsonContent({ deleted: true, bridgeId });
+        });
         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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.6.6",
+  "version": "0.7.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.9.9",
+    "@thalovant/sdk": "^0.10.0",
     "jose": "^6.2.8",
     "zod": "^4.6.6"
   },

package/server.json

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