@twitterapis/mcp 0.6.9 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.7.2 (2026-08-14)
+
+### Added
+
+- **3 new compat tools for tweet monitoring** (task #87): `twitter_x_user_stream_add_user`, `twitter_x_user_stream_remove_user`, `twitter_x_user_stream_list_users` -- drop-in equivalents of `twitter_monitor_create`/`twitter_monitor_delete`/`twitter_monitor_list` using an alternate request/response envelope shape, for migrating an existing integration built against that shape without a rewrite. Free per call, same underlying monitor system, same safety checks as the native tools. The catalog is now **74 tools: 45 reads and 29 write actions**.
+
+### Fixed
+
+- **The generator's `toolPathFor` only special-cased `/account/*` as un-prefixed** (billing reads mounted at the API root rather than under `/twitter/`); the 3 new compat routes live at `/oapi/x_user_stream/*`, the same shape of gap, now handled identically.
+
+## 0.7.1 (2026-08-14)
+
+### Added
+
+- **10 new tools for account monitoring + webhooks** (task #49, backend build plan Phase 5): watch an X account for new posts and get them pushed to your own HTTPS endpoint instead of polling. `twitter_monitor_create`, `twitter_monitor_list`, `twitter_monitor_update`, `twitter_monitor_delete`, `twitter_monitor_health`, `twitter_monitor_deliveries`, `twitter_monitor_webhook_create`, `twitter_monitor_webhook_list`, `twitter_monitor_webhook_delete`, `twitter_monitor_webhook_test`. Free per call (account administration, not a metered Twitter read); needs only your API key, no linked X session. The catalog is now **71 tools: 44 reads and 27 write actions**.
+
+### Fixed
+
+- **The generator (`scripts/gen-tools.mjs`) could not represent a DELETE route, or two HTTP methods on the same REST path**, which is exactly the shape the monitor/webhook endpoints need (`/monitor/{id}` is POST to update and DELETE to remove; `/monitor` and `/webhook` are each GET to list and POST to create). The endpoint table was keyed by path alone (a second method on the same path silently overwrote the first) and skipped every method that wasn't `get`/`post` outright, so a vendored `delete` operation never reached the catalog at all. Endpoints are now keyed by `(method, path)`; an override targeting an ambiguous path sets `method: "..."` to say which one. A `{name}` URL-template segment (this API's spec declares no formal `in: "path"` parameter for one) is synthesized as a required arg and threaded through as the tool's `pathParams`, which the runtime (`src/index.js`, via the new `resolvePathParams` in `src/query.js`) substitutes into the URL instead of sending as a query-string or JSON-body field. Regression-tested against a synthetic route table in `test/gen-tools-endpoints.mjs`, independent of the real spec.
+
+## 0.7.0 (2026-08-11)
+
+### Removed
+
+- **`twitter_users_by_ids` removed from the tool list.** X refuses the batch `UsersByRestIds` lookup for the pooled cookie sessions this package's REST backend reads through (confirmed by instrumenting the request and verifying a token was actually attached before it was rejected, not just repeated 403s). The REST endpoint itself stays live and returns an honest `503 endpoint_unavailable` rather than being deleted, but a tool the model can call and always get a hard failure from is worse than no tool at all, so it is out of the catalog. Use `twitter_user_info_by_id` instead: same user object, one id per call. The catalog is now **61 tools: 40 reads and 21 write actions**.
+
 ## 0.6.9 (2026-08-10)
 
 ### Added

package/README.md

@@ -91,9 +91,9 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-62 tools: 41 reads and 21 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page. Two of the reads are free account/billing lookups (`twitter_account_me`, `twitter_account_payments`).
+74 tools: 45 reads and 29 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page. Two of the reads are free account/billing lookups (`twitter_account_me`, `twitter_account_payments`); the 13 monitoring tools are also free (account administration, not metered reads).
 
-Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **all write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark) are annotated `destructiveHint: true` so MCP clients can prompt before running them.
+Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **most write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark, monitor/webhook delete) are annotated `destructiveHint: true` so MCP clients can prompt before running them. The **monitoring** tools (see below) are the one exception: they administer your twitterapis.com account, not an X session, so they need only your API key, no linked session and no inline credentials.
 
 ### Reads
 
@@ -103,7 +103,6 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_user_search` | Find user accounts by name or keyword |
 | `twitter_user_info` | Full profile by handle (bio, counts, verification, location) |
 | `twitter_user_info_by_id` | Full profile by numeric user id |
-| `twitter_users_by_ids` | Up to 100 numeric user ids resolved to full profiles in one call |
 | `twitter_user_about` | A user's structured About object (category, professional/business labels, verification + identity-verification flags, joined date, and X's 'About this account' transparency panel) |
 | `twitter_user_affiliates` | Accounts affiliated with an organization profile |
 | `twitter_check_follow_relationship` | Follow relationship between two user ids (who follows whom) |
@@ -167,6 +166,26 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 
 See also `twitter_article_get` and `twitter_article_list` above.
 
+### Monitoring _(webhook delivery of new posts; free, not metered)_
+
+Watch an X account for new posts and get them pushed to your own HTTPS endpoint, HMAC-signed, instead of polling. Register a webhook first, then create a monitor; every new post from a watched handle is delivered to every active webhook on your account (or a restricted subset via `webhook_ids`). Monitor/webhook CRUD is account administration, not a metered Twitter read, so every tool below is free.
+
+| Tool | What it does |
+|---|---|
+| `twitter_monitor_create` | Start watching an X account (`handle`) for new posts |
+| `twitter_monitor_list` | List every monitor on your account |
+| `twitter_monitor_update` | Pause/resume a monitor or change its `webhook_ids` restriction |
+| `twitter_monitor_delete` | Stop and remove a monitor (irreversible) |
+| `twitter_monitor_health` | One monitor's status, degradation flag, poll interval, cursor position |
+| `twitter_monitor_deliveries` | Recent delivery events across every monitor, with detection + delivery latency |
+| `twitter_x_user_stream_add_user` | Compat drop-in for `twitter_monitor_create` using an x_user_stream-shaped envelope |
+| `twitter_x_user_stream_remove_user` | Compat drop-in for `twitter_monitor_delete` using an x_user_stream-shaped envelope |
+| `twitter_x_user_stream_list_users` | Compat drop-in for `twitter_monitor_list` using an x_user_stream-shaped envelope |
+| `twitter_monitor_webhook_create` | Register an HTTPS delivery URL; returns the HMAC signing secret **once** |
+| `twitter_monitor_webhook_list` | List every webhook registered on your account |
+| `twitter_monitor_webhook_delete` | Soft-delete a webhook by id (irreversible from the caller's side) |
+| `twitter_monitor_webhook_test` | Send one signed test event to a webhook right now, synchronously |
+
 ### Session setup
 
 Link an X account to your key once, so the account-only reads and write actions act as it (or pass per-call `auth_token`/`ct0` instead).
@@ -257,7 +276,7 @@ Calls are billed to your twitterapis.com account. Almost every endpoint is $0.00
 
 **Do I need an X (Twitter) developer account?** No. Get an API key at [twitterapis.com/signup](https://www.twitterapis.com/signup); there is no application or approval step.
 
-**Is it read-only?** No. 41 read tools work with just your API key; 21 write actions (post, like, retweet, follow, DM, media upload, article create/edit/publish/delete) act as a linked X account or per-call inline credentials.
+**Is it read-only?** No. 45 read tools work with just your API key; 29 write actions (post, like, retweet, follow, DM, media upload, article create/edit/publish/delete, monitor/webhook create/update/delete) act as a linked X account or per-call inline credentials, except monitor/webhook CRUD, which is account administration and needs only your API key.
 
 **Which clients are supported?** Claude Desktop, Cursor, Windsurf, and VS Code (Copilot agent mode), or any Model Context Protocol client.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twitterapis/mcp",
-  "version": "0.6.9",
+  "version": "0.7.2",
   "description": "Official MCP server for twitterapis.com, the Twitter/X API (search, users, followers, tweets, threads, lists, likes, bookmarks, DMs) plus write actions (post/like/retweet/follow) as native tools for Claude, Cursor, and any MCP client.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "build": "node scripts/gen-tools.mjs --write",
     "build:check": "node scripts/gen-tools.mjs --check",
     "openapi:refresh": "node scripts/openapi-refresh.mjs",
-    "test": "node scripts/gen-tools.mjs --check && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs",
+    "test": "node scripts/gen-tools.mjs --check && node test/gen-tools-endpoints.mjs && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs",
     "prepublishOnly": "npm test && node test/publish-provenance.mjs",
     "check:openapi-parity": "node test/openapi-parity.mjs",
     "check:firewall": "node test/firewall.mjs",

package/src/index.js

@@ -24,7 +24,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // places and drifted: the package shipped 0.5.0 while the MCP handshake and the
 // outbound user-agent both still advertised 0.3.0.
 const VERSION = createRequire(import.meta.url)("../package.json").version;
-import { TOOLS, buildQuery } from "./tools.js";
+import { TOOLS, buildQuery, resolvePathParams, MissingPathParamError } from "./tools.js";
 
 const API_KEY = process.env.TWITTERAPIS_KEY;
 const BASE_URL = (
@@ -44,9 +44,26 @@ if (!API_KEY) {
 // from the query string, so the same buildQuery path serves both and only the
 // HTTP method differs. A few POST endpoints (customer/session, user_login,
 // media/upload) instead read a JSON request body; those tools set jsonBody:true
-// and callEndpoint sends the args in the body rather than the query string.
-async function callEndpoint(path, args, method = "GET", jsonBody = false) {
-  const all = args || {};
+// and callEndpoint sends the args in the body rather than the query string. A
+// handful of monitoring endpoints (/monitor/{id}, /webhook/{id}, ...) carry a
+// REST path parameter instead: those tools set pathParams (the arg names to
+// substitute into the URL template) and callEndpoint splices them into path
+// before building the query string or body, so a pathParams arg never leaks
+// into either.
+async function callEndpoint(path, args, method = "GET", jsonBody = false, pathParams = []) {
+  // Fill {name} URL segments from args and strip those keys, so a pathParams arg
+  // (e.g. a monitor/webhook id) never also leaks into the query string or JSON
+  // body. A missing value fails loudly rather than shipping a request that still
+  // contains the literal "{id}" against the API.
+  let resolvedPath, all;
+  try {
+    ({ path: resolvedPath, args: all } = resolvePathParams(path, pathParams, args));
+  } catch (err) {
+    if (err instanceof MissingPathParamError) {
+      return { isError: true, content: [{ type: "text", text: err.message }] };
+    }
+    throw err;
+  }
 
   const headers = {
     // The API accepts either header; send both for maximum compatibility.
@@ -64,7 +81,7 @@ async function callEndpoint(path, args, method = "GET", jsonBody = false) {
     // and user_login the credentials ARE the payload the handler reads from the
     // body, so they must NOT be diverted into x-* headers the way per-call inline
     // creds are on the query-string tools.
-    url = `${BASE_URL}${path}`;
+    url = `${BASE_URL}${resolvedPath}`;
     headers["content-type"] = "application/json";
     reqBody = JSON.stringify(all);
   } else {
@@ -75,7 +92,7 @@ async function callEndpoint(path, args, method = "GET", jsonBody = false) {
     // session is used. Lets a single key act as many accounts.
     const { auth_token, ct0, user_agent, proxy_url, ...rest } = all;
     const q = buildQuery(rest);
-    url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
+    url = `${BASE_URL}${resolvedPath}${q ? `?${q}` : ""}`;
     if (auth_token && ct0) {
       headers["x-auth-token"] = auth_token;
       headers["x-ct0"] = ct0;
@@ -138,7 +155,7 @@ for (const tool of TOOLS) {
   server.registerTool(
     tool.name,
     { description: tool.description, inputSchema: tool.shape, annotations },
-    async (args) => callEndpoint(tool.path, args, method, Boolean(tool.jsonBody)),
+    async (args) => callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || []),
   );
 }
 

package/src/query.js

@@ -14,3 +14,35 @@ export function buildQuery(args) {
   }
   return qs.toString();
 }
+
+// Thrown by resolvePathParams when a tool's pathParams arg is missing/empty. The
+// caller decides how to surface it (index.js turns it into an MCP tool error);
+// this module stays a pure mechanical helper with no knowledge of MCP shapes.
+export class MissingPathParamError extends Error {
+  constructor(name, path) {
+    super(`Missing required path parameter "${name}" for ${path}.`);
+    this.name = "MissingPathParamError";
+    this.paramName = name;
+  }
+}
+
+// Substitutes {name} URL-template segments (e.g. "/monitor/{id}") from `args`,
+// for the handful of REST endpoints that carry a path parameter instead of a
+// query/body one (monitor/webhook CRUD by id). Returns the resolved path plus
+// args with every consumed key REMOVED, so a pathParams arg never also leaks
+// into the query string or JSON body downstream. Throws MissingPathParamError
+// rather than silently shipping a request that still contains the literal
+// "{id}" against the API.
+export function resolvePathParams(path, pathParams, args) {
+  const rest = { ...(args || {}) };
+  let resolved = path;
+  for (const name of pathParams || []) {
+    const value = rest[name];
+    delete rest[name];
+    if (value === undefined || value === null || value === "") {
+      throw new MissingPathParamError(name, path);
+    }
+    resolved = resolved.replace(`{${name}}`, encodeURIComponent(String(value)));
+  }
+  return { path: resolved, args: rest };
+}

package/src/tools.js

@@ -8,18 +8,22 @@
 // file in memory and fails if it does not match what is committed, so a hand edit
 // here is caught rather than shipped.
 //
-// Catalog: 62 tools (41 reads, 21 writes).
+// Catalog: 74 tools (45 reads, 29 writes).
 //
 // Each tool maps 1:1 to a REST endpoint at https://api.twitterapis.com. Tool arg
 // names map 1:1 to endpoint query params (every endpoint, including the POST
 // write actions, reads its params from the query string), except the per-call
-// inline credentials, which travel as x-* request headers, and the 4
-// jsonBody tools, whose fields travel in a JSON request body. A tool with
-// `method: "POST"` is a write that acts on behalf of the authenticated account
-// behind your API key; reads are GET and default when `method` is omitted.
+// inline credentials, which travel as x-* request headers, the 4
+// jsonBody tools, whose fields travel in a JSON request body, and any arg listed
+// in pathParams, which is substituted into the URL path (e.g. {id}) instead. A
+// tool with `method: "POST"` or `method: "DELETE"` is a write that acts on
+// behalf of the authenticated account behind your API key; reads are GET and
+// default when `method` is omitted.
 //
 // write:true       -> action mutates account/Twitter state (readOnlyHint:false)
 // destructive:true -> action removes/reverses state (delete, un-follow/like/RT/bookmark)
+// pathParams        -> arg names substituted into the URL template, not sent as
+//                      query-string or body fields (e.g. ["id"] for /monitor/{id})
 import { z } from "zod";
 
 export const TOOLS = [
@@ -82,17 +86,6 @@ export const TOOLS = [
       ),
     },
   },
-  {
-    name: "twitter_users_by_ids",
-    path: "/twitter/users/by_ids",
-    description:
-      "Resolve up to 100 numeric user ids into full profiles in ONE call. Same user object as twitter_user_info_by_id, returned as a list. Use this whenever you hold several ids and would otherwise loop twitter_user_info_by_id, for example hydrating the authors of a batch of tweets. Ids that no longer resolve (suspended or deleted accounts) are omitted rather than returned as nulls; compare the requested and resolved counts in the response, or diff the returned ids against the ones you sent, to see which were dropped. Sending more than 100 ids is rejected rather than truncated, so a short list always means those accounts are gone, never that the request was clipped.",
-    shape: {
-      user_ids: z.string().describe(
-        "Comma-separated numeric Twitter/X user ids, up to 100 (e.g. '44196397,745273'). Duplicates are collapsed and billed once.",
-      ),
-    },
-  },
   {
     name: "twitter_user_about",
     path: "/twitter/user/user_about",
@@ -1372,8 +1365,173 @@ export const TOOLS = [
       ),
     },
   },
+  {
+    name: "twitter_monitor_create",
+    path: "/twitter/monitor",
+    method: "POST",
+    write: true,
+    description:
+      "Start watching an X account for new posts. Every new post from that handle is HMAC-signed and delivered to your registered webhook(s) on a shared poll interval (see twitter_monitor_webhook_create to register a delivery URL first). Free: monitor creation is account administration, not a metered read. Returns the new monitor's id, plus its normalized handle, status, and poll_interval_ms.",
+    shape: {
+      handle: z.string().min(1).describe(
+        "The X username to watch, without the leading @ (e.g. 'elonmusk').",
+      ),
+      webhook_ids: z.string().optional().describe(
+        "Optional. Comma-separated webhook id(s) from twitter_monitor_webhook_create to restrict this monitor's deliveries to. Omit to deliver to every active webhook on the account (the default).",
+      ),
+    },
+  },
+  {
+    name: "twitter_monitor_list",
+    path: "/twitter/monitor",
+    description:
+      "List every monitor on your account: id, subject (its from:<handle> query), kind, status ('active' or 'paused'), degraded flag, events_possibly_missed, webhook_ids restriction, and created_at. Takes no arguments.",
+    shape: {},
+  },
+  {
+    name: "twitter_monitor_update",
+    path: "/twitter/monitor/{id}",
+    method: "POST",
+    write: true,
+    pathParams: ["id"],
+    description:
+      "Partially update an existing monitor: pause or resume it via status, change which webhooks receive its events via webhook_ids, or both in the same call (applied atomically). Resuming a paused monitor re-runs the same capacity and per-account cap checks as creating a new one, since it adds load back to the shared pool. Free per call. Both fields are optional; omit either to leave it unchanged.",
+    shape: {
+      id: z.string().describe(
+        "The monitor's id, from twitter_monitor_create or twitter_monitor_list.",
+      ),
+      status: z.enum(["active","paused"]).optional().describe(
+        "'paused' to pause the monitor, 'active' to resume it. Omit to leave status unchanged.",
+      ),
+      webhook_ids: z.string().optional().describe(
+        "Optional. Comma-separated webhook id(s) to restrict delivery to. Pass an empty string to clear the restriction back to 'deliver to every active webhook'. Omit entirely to leave it unchanged.",
+      ),
+    },
+  },
+  {
+    name: "twitter_monitor_delete",
+    path: "/twitter/monitor/{id}",
+    method: "DELETE",
+    write: true,
+    destructive: true,
+    pathParams: ["id"],
+    description:
+      "Stop and remove a monitor by id. Irreversible: create a new monitor with twitter_monitor_create if you want to watch that handle again. Delivery history referencing this monitor is retained, not cascade-deleted. Free per call.",
+    shape: {
+      id: z.string().describe(
+        "The monitor's id, from twitter_monitor_create or twitter_monitor_list.",
+      ),
+    },
+  },
+  {
+    name: "twitter_monitor_health",
+    path: "/twitter/monitor/{id}/health",
+    pathParams: ["id"],
+    description:
+      "Read one monitor's current status, degradation flag, poll interval, possibly-missed-event count, and cursor position (last_tweet_id, last_poll_at), for building your own health dashboard. Free per call.",
+    shape: {
+      id: z.string().describe(
+        "The monitor's id, from twitter_monitor_create or twitter_monitor_list.",
+      ),
+    },
+  },
+  {
+    name: "twitter_monitor_deliveries",
+    path: "/twitter/monitor/deliveries",
+    description:
+      "List your most recent monitor delivery events across every monitor, most recent first: id, monitor_id, tweet_id, status, tweet_created_at, and the real measured latency (detected_lag_ms, from X's own post timestamp to enqueue; delivery_lag_ms, the separate queue-to-webhook-POST time; total_lag_ms). Free per call.",
+    shape: {
+      limit: z.number().int().min(1).max(200).optional().describe(
+        "Max delivery events to return, 1 to 200. Defaults to 50 when omitted.",
+      ),
+    },
+  },
+  {
+    name: "twitter_x_user_stream_add_user",
+    path: "/oapi/x_user_stream/add_user_to_monitor_tweet",
+    method: "POST",
+    write: true,
+    description:
+      "Compat drop-in for twitter_monitor_create using an x_user_stream-shaped request/response envelope: watch an X account for new posts, translated onto the same underlying monitor system. Free per call. Prefer twitter_monitor_create for new integrations; this exists for migrating an existing x_user_stream-shaped integration without a rewrite.",
+    shape: {
+      x_user_name: z.string().describe(
+        "The X username to watch, without the @.",
+      ),
+    },
+  },
+  {
+    name: "twitter_x_user_stream_remove_user",
+    path: "/oapi/x_user_stream/remove_user_to_monitor_tweet",
+    method: "POST",
+    write: true,
+    destructive: true,
+    description:
+      "Compat drop-in for twitter_monitor_delete using an x_user_stream-shaped envelope: stop watching an account. Irreversible. Free per call.",
+    shape: {
+      id_for_user: z.string().describe(
+        "The monitor id, from twitter_x_user_stream_list_users. Same value as a twitter_monitor_* tool's monitor id.",
+      ),
+    },
+  },
+  {
+    name: "twitter_x_user_stream_list_users",
+    path: "/oapi/x_user_stream/get_user_to_monitor_tweet",
+    description:
+      "Compat drop-in for twitter_monitor_list using an x_user_stream-shaped envelope: list every account you are currently tweet-monitoring. Honest field mapping, not fabricated: x_user_id is always null (this API stores no numeric Twitter user id) and is_monitor_profile is always 0 (profile-change monitoring is not a capability this API has). Free per call.",
+    shape: {},
+  },
+  {
+    name: "twitter_monitor_webhook_create",
+    path: "/twitter/webhook",
+    method: "POST",
+    write: true,
+    description:
+      "Register an HTTPS endpoint to receive signed monitor events. The HMAC signing secret is returned ONLY in this response, store it immediately: it cannot be retrieved again, and it is what you use to verify the X-TwitterAPIs-Signature header on every delivery. Free per call.",
+    shape: {
+      url: z.string().min(1).describe(
+        "Your https delivery endpoint, e.g. 'https://example.com/webhooks/twitterapis'. Private, loopback, link-local, and metadata IPs are refused, re-checked at every delivery, not just at registration.",
+      ),
+    },
+  },
+  {
+    name: "twitter_monitor_webhook_list",
+    path: "/twitter/webhook",
+    description:
+      "List every webhook registered on your account: id, url, status ('active' delivers, 'disabled' means the endpoint returned a 410 Gone and needs re-registering to reactivate), and created_at. The signing secret is never returned here, only at creation. Takes no arguments.",
+    shape: {},
+  },
+  {
+    name: "twitter_monitor_webhook_delete",
+    path: "/twitter/webhook/{id}",
+    method: "DELETE",
+    write: true,
+    destructive: true,
+    pathParams: ["id"],
+    description:
+      "Soft-delete a webhook by id: it stops receiving deliveries immediately and disappears from twitter_monitor_webhook_list, but delivery history referencing it is retained rather than cascade-deleted. Irreversible from the caller's side (register a new webhook with twitter_monitor_webhook_create to resume delivery). Free per call.",
+    shape: {
+      id: z.string().describe(
+        "The webhook's id, from twitter_monitor_webhook_create or twitter_monitor_webhook_list.",
+      ),
+    },
+  },
+  {
+    name: "twitter_monitor_webhook_test",
+    path: "/twitter/webhook/{id}/test",
+    method: "POST",
+    write: true,
+    pathParams: ["id"],
+    description:
+      "Send one HMAC-signed test event to this webhook's URL right now and return the outcome synchronously: delivered (true if your endpoint returned a 2xx within the delivery timeout), status_code, and error. Unlike a real monitor event, a test send is never queued, retried, or dead-lettered, it is a one-shot diagnostic to confirm your endpoint and signature verification both work before relying on the webhook. Free per call.",
+    shape: {
+      id: z.string().describe(
+        "The webhook's id, from twitter_monitor_webhook_create or twitter_monitor_webhook_list.",
+      ),
+    },
+  },
 ];
 
-// The query-string builder is hand-written logic, not catalog data, so it lives
-// in its own module and is re-exported here to keep this file's one import path.
-export { buildQuery } from "./query.js";
+// The query-string builder and the path-param substitution helper are
+// hand-written logic, not catalog data, so they live in their own module and
+// are re-exported here to keep this file's one import path.
+export { buildQuery, resolvePathParams, MissingPathParamError } from "./query.js";