@browserstack/mcp-server 2.2.2-beta.2 → 2.3.0-beta.1

package/dist/tools/capability-registry/index-loader.js

@@ -6,12 +6,23 @@
  * lets searchCapability rank across products from N single-product files.
  */
 import { readFileSync } from "node:fs";
+import appConfig from "../../config.js";
 import { basename, dirname } from "node:path";
 import { ENVELOPE_KEYS, SUPPORTED_SCHEMA_VERSION, } from "./types.js";
 export class IndexError extends Error {
 }
 /** Thrown to the caller as a tool error, so the wording is caller-facing. */
 export class InvocationError extends Error {
+    /**
+     * Set when the handle exists in the artifact but this surface withholds it.
+     *
+     * The MESSAGE deliberately does not say so — a caller is told the capability does not
+     * exist, because "withheld" invites a retry, a search for synonyms, or a question to the
+     * user about enabling it, none of which can succeed here. The flag keeps the distinction
+     * for telemetry, where knowing how often a withheld handle is reached for is how we learn
+     * whether withholding it was the right call.
+     */
+    withheld;
 }
 /** The file inside a product subdirectory, for the earlier nested layout. */
 export const INDEX_FILE = "index.json";
@@ -43,9 +54,59 @@ export function endpointKey(method, path) {
  * FAILS CLOSED: any truthy `disabled` hides it, not just `=== true`. The flag exists to
  * suppress something that cannot work, so an unexpected shape must hide it rather than be
  * ignored — the opposite default would turn a typo into a silently re-enabled capability.
+ *
+ * `local_only` withholds on a remote server only, for a capability that reads the caller's
+ * own machine: there, the path it would take resolves against the operator's disk instead.
+ * Read at call time rather than captured, because the remote server builds its config per
+ * session and a value captured at module load would outlive the deployment it described.
  */
 export function isDisabled(capability) {
-    return Boolean(capability.disabled);
+    if (capability.disabled)
+        return true;
+    return Boolean(capability.local_only) && Boolean(appConfig.REMOTE_MCP);
+}
+/**
+ * Is this capability published for reference only on this surface?
+ *
+ * `local_only` on a remote server. The capability is real and the caller may well be asking
+ * for exactly it, so hiding it leaves the agent concluding no such route exists. Publishing
+ * it without the means to call it, and with a note saying what to do instead, answers the
+ * question it was asked.
+ */
+export function isReferenceOnly(capability) {
+    if (capability.disabled)
+        return false;
+    return Boolean(capability.local_only) && Boolean(appConfig.REMOTE_MCP);
+}
+/**
+ * The reference form: what it is and what to do instead, and nothing to call it with.
+ *
+ * The parameters and response shapes go because publishing them invites the attempt — a
+ * model handed a body schema will fill it in. `intent` stays, because that is what the
+ * search matched on, and `mode` stays so a reader can still see what kind of operation it
+ * would have been.
+ */
+function asReference(capability) {
+    const reference = { ...capability };
+    for (const field of [
+        "path_params",
+        "query",
+        "body",
+        "responses",
+        "returns",
+        "paginated",
+        "max_page_size",
+        "encoding",
+    ]) {
+        delete reference[field];
+    }
+    return {
+        ...reference,
+        invocable: false,
+        guidance: capability.unavailable_note
+            ? [capability.unavailable_note]
+            : ["This capability cannot be called on this server."],
+    };
 }
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -181,6 +242,16 @@ export class CapabilityRegistry {
                 // between a disabled name and a live one is still a broken artifact, and skipping
                 // the disabled half would mean re-enabling the flag could fail the load later,
                 // somewhere with less context than here.
+                if (isReferenceOnly(capability)) {
+                    // PUBLISHED, BUT NOT CALLABLE. It keeps its name and intent so the search that
+                    // should find it does, and loses everything a caller would need to invoke it.
+                    const reference = asReference(capability);
+                    enabled.push(reference);
+                    lookup.set(endpointKey(capability.method, capability.path), reference);
+                    if (capability.name)
+                        names.set(capability.name, reference);
+                    continue;
+                }
                 if (isDisabled(capability)) {
                     withheld.set(endpointKey(capability.method, capability.path), capability);
                     if (capability.name)
@@ -219,26 +290,25 @@ export class CapabilityRegistry {
         this.index = { ...index, products };
     }
     /**
-     * The `capability_disabled` message for a handle this build withholds, if it is one.
+     * Does this build withhold the handle?
      *
-     * Says THAT it is disabled and nothing about why. The reason is documentation and lives
-     * with the decision; repeating it here would put four copies of a paragraph in the
-     * shipped artifact to serve a path the flag itself makes rare.
+     * WHAT THE CALLER IS TOLD IS THAT IT DOES NOT EXIST, which is why this returns a boolean
+     * rather than a message. Saying "withheld" describes the artifact rather than the
+     * surface, and every action it invites — retry, hunt for a synonym, ask the user to turn
+     * it on — fails here. A capability absent from search, describe and every listing should
+     * read the same way at invocation as it does everywhere else.
      *
-     * Returns undefined for anything else, so the caller falls through to its own
-     * not-found wording.
+     * The caller raises its own not-found error and marks it `withheld`, so the distinction
+     * survives in telemetry without reaching the agent.
      */
-    withheldMatch(handle, product) {
+    isWithheld(handle, product) {
         for (const [owner, withheld] of this.withheld) {
             if (product && owner !== product)
                 continue;
-            if (!withheld.has(handle))
-                continue;
-            return (`capability_disabled: ${handle} is disabled on this surface. This is ` +
-                `deliberate — it is withheld by the ${owner} index, not missing from it — so ` +
-                `retrying will not help.`);
+            if (withheld.has(handle))
+                return true;
         }
-        return undefined;
+        return false;
     }
     /** How many capabilities each product withholds. Startup logging only. */
     disabledCounts() {
@@ -326,13 +396,13 @@ export class CapabilityRegistry {
                 matches.push({ product: owner, capability });
         }
         if (matches.length === 0) {
-            // WITHHELD IS A DIFFERENT ANSWER FROM ABSENT, and only here. Search cannot surface a
-            // disabled capability, so reaching this branch means the caller already held the
-            // exact handle — from an older index, a doc, or a human. "unknown_capability" would
-            // send it hunting for a synonym that does not exist; the reason ends the attempt.
-            const off = this.withheldMatch(name, product);
-            if (off)
-                throw new InvocationError(off);
+            // A WITHHELD HANDLE ANSWERS THE SAME WAY AS AN ABSENT ONE. Search, describe and the
+            // listings already behave as though it does not exist, and invocation is no place to
+            // contradict them: "withheld" is a fact about the artifact, not about this surface,
+            // and it invites a retry, a hunt for a synonym, or a question to the user about
+            // enabling something that cannot be enabled here. The error carries `withheld` so the
+            // attempt is still countable in telemetry.
+            const withheldHere = this.isWithheld(name, product);
             // Say whether names are published at all for the product asked about: "no such name"
             // and "this product does not name its capabilities" need different fixes.
             const unnamed = [...this.byName]
@@ -342,7 +412,10 @@ export class CapabilityRegistry {
                 ? ` ${unnamed.sort().join(", ")} ${unnamed.length > 1 ? "publish" : "publishes"} ` +
                     `no capability names yet — call those by \`method\` and \`path\` instead.`
                 : " Search again — names come from searchCapability and describeEntity.";
-            throw new InvocationError(`unknown_capability: ${name}.${hint}`);
+            const error = new InvocationError(`unknown_capability: ${name}.${hint}`);
+            if (withheldHere)
+                error.withheld = true;
+            throw error;
         }
         if (matches.length > 1 && !product) {
             const owners = matches
@@ -371,11 +444,11 @@ export class CapabilityRegistry {
                 matches.push({ product: name, capability });
         }
         if (matches.length === 0) {
-            const off = this.withheldMatch(key, product);
-            if (off)
-                throw new InvocationError(off);
-            throw new InvocationError(`unknown_endpoint: ${key}. Search again — send \`method\` and \`path\` exactly as ` +
+            const error = new InvocationError(`unknown_endpoint: ${key}. Search again — send \`method\` and \`path\` exactly as ` +
                 `searchCapability returned them, placeholders included.`);
+            if (this.isWithheld(key, product))
+                error.withheld = true;
+            throw error;
         }
         if (matches.length > 1 && !product) {
             const owners = matches

package/dist/tools/capability-registry/register.d.ts

@@ -32,7 +32,7 @@ export interface RegistryDeps {
      * Per-product base URL. Never baked into the artifact — it is environment AND account
      * specific: tm is region-sharded, so this is resolved per call, not once at startup.
      */
-    baseUrlFor: (product: string) => Promise<string>;
+    baseUrlFor: (product: string, host?: string) => Promise<string>;
     credentialsFor: () => Credentials;
     transport?: Transport;
 }

package/dist/tools/capability-registry/register.js

@@ -81,7 +81,7 @@ export function addCapabilityRegistryToolsFromConfig(server, config) {
         registry,
         // The whole product bundle, not just its host: a region-sharded product declares
         // several candidates and the probe needs an endpoint from its own capabilities.
-        baseUrlFor: (product) => resolveBaseUrl(product, config, registry.index.products[product]),
+        baseUrlFor: (product, host) => resolveBaseUrl(product, config, registry.index.products[product], undefined, host),
         // Read per call, not captured: the remote server rebuilds config per session, so a
         // captured credential would outlive the session it belongs to.
         credentialsFor: () => ({
@@ -147,7 +147,12 @@ export function addCapabilityRegistryTools(server, deps, config) {
      * below pin each branch against the message its source actually produces; if you reword
      * a refusal, one of them will tell you.
      */
-    const invocationReason = (message) => {
+    const invocationReason = (message, error) => {
+        // A WITHHELD HANDLE IS REPORTED TO THE CALLER AS NOT FOUND, so the message cannot be
+        // what distinguishes it. The flag on the error can, which keeps the refusal countable
+        // without the wording admitting the capability exists.
+        if (error instanceof InvocationError && error.withheld)
+            return "capability_disabled";
         if (message.startsWith("unknown_capability:"))
             return "unknown_capability";
         if (message.startsWith("unknown_endpoint:"))
@@ -189,11 +194,24 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         return failed(message, extra);
     };
-    tools.listProducts = server.tool("listProducts", "List BrowserStack products and their entities. START HERE: searchCapability needs a product name from this. Pass the user's request as `query`; if it reports a clash, ask the user which product they mean and wait. Never pick for them or merge products.", {
+    tools.listProducts = server.tool("listProducts", "List the BrowserStack products this surface can reach: what each one does, the " +
+        "entities it models, and a line saying what each entity is. START HERE — " +
+        "searchCapability needs a product, and this is what tells you which one. If two " +
+        "products could both fit the task, ask the user rather than choosing for them. " +
+        "ALWAYS pass the user's request, in their own words, as `query`: the answer then " +
+        "says outright whether the products clash over the words in it. WHEN IT REPORTS A " +
+        "CLASH — two products claiming the same word for different things — ASK THE USER " +
+        "WHICH PRODUCT THEY MEAN AND WAIT FOR THEIR ANSWER BEFORE SEARCHING OR INVOKING " +
+        "ANYTHING. The response carries the question to put to them and what the shared " +
+        "word means in each product. Choosing for them, or searching each product in turn " +
+        "and merging the results, is the failure this call exists to prevent.", {
         query: z
             .string()
             .optional()
-            .describe("The user's request, in their own words; enables clash detection."),
+            .describe("The user's request, in their own words. With it the response carries a " +
+            "`routing` block saying whether the products share the vocabulary this " +
+            "request uses — and, when they do, the question to put to the user before " +
+            "searching either product."),
     }, {
         title: "List Capability Products",
         readOnlyHint: true,
@@ -336,7 +354,9 @@ export function addCapabilityRegistryTools(server, deps, config) {
     // each. That is the right trade while routing is the problem it solves (you cannot
     // choose between products by looking at one of them), but past a dozen products it may
     // need a names-only default with aliases on request.
-    tools.describeEntity = server.tool("describeEntity", "Describe an entity: identifiers, relations and product vocabulary. Read before filtering or writing; ids often need resolving first.", {
+    tools.describeEntity = server.tool("describeEntity", "Describe one entity: what it is, what identifies it, what it relates to, and the " +
+        "vocabulary the product uses for it. Read this before filtering or writing, because " +
+        "ids and field values usually have to be resolved first.", {
         product: productArg().describe(`Which product the entity belongs to: ${productList}.`),
         entity: z.string().describe("Entity name, as listProducts returns it."),
     }, {
@@ -356,10 +376,38 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         return ok({ product, entity, ...doc });
     });
-    tools.searchCapability = server.tool("searchCapability", "Find capabilities in ONE product by plain language. CALL listProducts FIRST; `product` must be spelled exactly as listProducts spells it. If `weak_match` is true, search again with `suggested_vocabulary` before invoking. Results are a shortlist: call describeCapability for the contract, then invokeCapability. query='*' lists all; page with `next_offset`.", {
+    tools.searchCapability = server.tool("searchCapability", "Find endpoints this surface can call, by plain language, within ONE product. " +
+        "CALL listProducts FIRST, passing the user's request as its `query`: it names the " +
+        "products, says whether they clash over the words in that request, and gives you " +
+        "the question to ask when they do. You need it anyway — `product` here takes a name " +
+        "exactly as listProducts spells it. Where two products use the same word for " +
+        "different things, ask the USER and wait for an answer rather than picking. " +
+        "Search matches the product's OWN words, not synonyms. When your words are not the " +
+        "product's, the response says so: `weak_match: true` with a `suggested_vocabulary` " +
+        "map of the product's entities and their aliases. Results are still returned, but " +
+        "treat them as unconfirmed — pick the closest entity from that map and search again " +
+        "using its vocabulary, or call describeEntity on it for the fuller picture. That one " +
+        "extra round trip is far cheaper than invoking the wrong capability. " +
+        "Narrowing further with `entity` sharpens results. " +
+        "THIS IS A SHORTLIST, NOT A CONTRACT. Each result carries only what you need to " +
+        "CHOOSE: `name` (the handle), `product`, `mode` (whether it writes), `intent` and " +
+        "`guidance` (what it does and what goes wrong), and `method`/`path` for products " +
+        "that publish no name yet. " +
+        "It does NOT carry parameters or response shapes. Once you have picked one, call " +
+        "describeCapability for its full contract, then invokeCapability. Fetching the " +
+        "contract only for the one you chose is the difference between ~1k and ~8.6k tokens " +
+        "a search. Results are ranked and capped. " +
+        "TO SEE EVERYTHING rather than search, pass query='*' — that lists the product " +
+        "(honouring `entity` and `mode`) in a stable order instead of ranking it, which is " +
+        "what you want when the task is 'what can this product do' rather than a lookup. " +
+        "TO PAGE, send `offset`: every response carries `offset` and, when more matched, " +
+        "`next_offset` — resend the SAME query with that value. `next_offset` is absent on " +
+        "the last page, so walk until it stops rather than comparing counts.", {
         query: z
             .string()
-            .describe("Goal in plain language, or '*' to list every capability."),
+            .describe("What you are trying to do, in plain language. Pass '*' (or 'all') to BROWSE " +
+            "instead of search: every capability in the product, in a stable order, " +
+            "paginated — use it when you want to see the surface rather than find one thing."),
         entity: z
             .string()
             .optional()
@@ -387,7 +435,9 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // refused here instead, by a message that names listProducts.
         product: z
             .string()
-            .describe("Product name, exactly as listProducts spells it."),
+            .describe("Which product to search, named exactly as listProducts spells it. Call " +
+            "listProducts with the user's request to get the name — and to find out " +
+            "whether the products clash over it, in which case ask the user first."),
         // `product_choice` USED TO LIVE HERE, AND WAS ITS OWN DEFEAT.
         //
         // A required enum of 'user_confirmed' | 'not_asked' publishes, in the schema every
@@ -400,11 +450,18 @@ export function addCapabilityRegistryTools(server, deps, config) {
         routing_token: z
             .string()
             .optional()
-            .describe("Latest `routing_token` from listProducts or a clash refusal; send with `user_words` after a clash."),
+            .describe("The `routing_token` from the last listProducts call or product_ambiguous " +
+            "refusal — it carries what that step concluded about the user's request, " +
+            "signed. Always pass the most recent one. When it reports a clash, send the " +
+            "user's answer in `user_words` alongside it; neither works alone."),
         user_words: z
             .string()
             .optional()
-            .describe("The user's own words, verbatim, naming the product or a term only it uses. Never paraphrase."),
+            .describe("The USER'S OWN words, verbatim, that settle which product this is — either " +
+            "the product's name or a term only one product uses ('quality gate', 'test " +
+            "plan'). Quote them; do not paraphrase, and do not write words the user did " +
+            "not say. When a query could mean either product this is what lifts the " +
+            "refusal, because it is checked against the index rather than taken on trust."),
         mode: z
             .enum(["read", "write", "destructive"])
             .optional()
@@ -413,7 +470,8 @@ export function addCapabilityRegistryTools(server, deps, config) {
         offset: z
             .number()
             .optional()
-            .describe("`next_offset` from the previous page, with the same query."),
+            .describe("Skip this many results — send the `next_offset` from the previous response " +
+            "with the SAME query to get the next page. Omit for the first page."),
     }, {
         title: "Search Capabilities",
         readOnlyHint: true,
@@ -670,7 +728,16 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 : {}),
         });
     });
-    tools.describeCapability = server.tool("describeCapability", "Full contract (parameters, returns, response shapes) for ONE capability from searchCapability. Call it before invokeCapability. Identify by `name`; use `method` + `path` only when no name was returned.", {
+    tools.describeCapability = server.tool("describeCapability", "The full contract for ONE capability you picked from searchCapability: its " +
+        "parameters grouped into path_params / query / body under the spec's own names, " +
+        "what it returns, and its declared response shapes fully expanded. Call this after " +
+        "search and before invokeCapability — search deliberately omits all of it, because " +
+        "it is only needed for the one capability you actually call. " +
+        "Identify it by `name`, exactly as search returned it; only when a result carries " +
+        "no `name` (some products publish none yet) pass `method` and `path` instead. " +
+        "Every parameter lists its type, whether it is required, its allowed values where " +
+        "the set is closed, and any limits the product declares — obey those before calling " +
+        "rather than discovering them from a rejected request.", {
         name: z
             .string()
             .optional()
@@ -685,11 +752,14 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .describe("Path with {placeholders} intact — only for capabilities returned without a `name`."),
         product: productArg()
             .optional()
-            .describe("Owning product; needed only when names or paths collide."),
+            .describe(`Which product owns it (${productList}). searchCapability returns it on every ` +
+            "result; required only when two products share a name or a path."),
         include_responses: z
             .enum(["success", "all", "none"])
             .optional()
-            .describe("'success' (default), 'all' (adds error shapes, larger) or 'none'."),
+            .describe("Which declared responses to expand: 'success' (default, the 2xx shape), 'all' " +
+            "(adds the error shapes — several times larger, and near-identical across " +
+            "endpoints), or 'none'."),
     }, {
         title: "Describe Capability",
         readOnlyHint: true,
@@ -747,12 +817,22 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         catch (error) {
             if (error instanceof InvocationError)
-                return refuse("describeCapability", invocationReason(error.message), error.message, undefined, identity);
+                return refuse("describeCapability", invocationReason(error.message, error), error.message, undefined, identity);
             logger.error("describeCapability failed: %s", error instanceof Error ? error.message : String(error));
             return refuse("describeCapability", "unexpected_error", "that capability could not be described", undefined, identity);
         }
     });
-    tools.invokeCapability = server.tool("invokeCapability", "Run a capability after describeCapability, by `name` (or `method` + `path` if unnamed); args go in path_params / query / body. If `completed` is false, fetch the next page. Writes: ask the user first, then resend with user_permission='granted' and a change_summary. Deletes are refused; archive, close and merge are writes.", {
+    tools.invokeCapability = server.tool("invokeCapability", "Call a capability whose contract you have from describeCapability. Pass `name` exactly " +
+        "as given — that is the handle. Only when a result carries no `name` (some products " +
+        "do not publish them yet) pass `method` and `path` instead, exactly as returned. " +
+        "Arguments go in path_params / query / body under the spec's own names. One call " +
+        "makes exactly one request and returns the product's own response untouched; when " +
+        "`completed` is false there is another page, which you fetch by sending the " +
+        "capability's own page parameter. If the mode is 'write' you MUST ask the user " +
+        "first, then resend with user_permission='granted' and a change_summary; both are " +
+        "recorded. Capabilities whose mode is 'destructive' (deletes) are refused outright — " +
+        "archiving, closing and merging are ordinary writes and DO run, so read the mode and " +
+        "intent before confirming with the user.", {
         name: z
             .string()
             .optional()
@@ -780,7 +860,8 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .describe("Body fields, under the spec's names."),
         product: productArg()
             .optional()
-            .describe("Owning product; needed only when names or paths collide."),
+            .describe(`Which product owns the capability (${productList}). searchCapability returns it ` +
+            "on every result; required only when two products share a name or a path."),
         user_permission: z
             .enum(PERMISSION_VALUES)
             .optional()
@@ -834,6 +915,17 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 query: input.query,
                 body: input.body,
             };
+            if (capability.invocable === false) {
+                // THE ONE PLACE describe AND invoke DIVERGE, deliberately. Everywhere else a name
+                // that describes is a name that invokes, and breaking that is its own bug class —
+                // but a reference-only capability exists precisely to be read and not called. The
+                // refusal carries the instruction, because the note is the whole point of it
+                // still being published.
+                return refuse("invokeCapability", "capability_not_invocable", `${handle} cannot be called on this server. ` +
+                    (capability.guidance?.[0] ??
+                        "Describe it for what to do instead.") +
+                    " Follow that instead of retrying.", undefined, identity);
+            }
             if (capability.mode === "destructive") {
                 // Refused before binding, so consent is never sought for something that cannot run.
                 return refuse("invokeCapability", "destructive_blocked", `${handle} is a destructive operation and is not available through this surface`, undefined, identity);
@@ -856,7 +948,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
                     return refuse("invokeCapability", "change_summary_missing", "change_summary is required: state what will change", undefined, identity);
                 }
             }
-            const result = await invoke(capability, args, await deps.baseUrlFor(product), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
+            const result = await invoke(capability, args, await deps.baseUrlFor(product, capability.host), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
             // The one row for a completed invoke. invoke() returns a 4xx/5xx rather than
             // throwing, so `success` keeps its tool-level meaning and these two fields carry
             // whether the product call worked. Status 0 means it could not be reached.
@@ -870,7 +962,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         catch (error) {
             if (error instanceof InvocationError)
-                return refuse("invokeCapability", invocationReason(error.message), error.message, undefined, identity);
+                return refuse("invokeCapability", invocationReason(error.message, error), error.message, undefined, identity);
             logger.error("invokeCapability failed: %s", error instanceof Error ? error.message : String(error));
             return refuse("invokeCapability", "unexpected_error", "that capability could not be invoked", undefined, identity);
         }

package/dist/tools/capability-registry/resolve.js

@@ -16,6 +16,8 @@ import { invalidateToken } from "../../lib/central-oauth.js";
 import { bind } from "./bind.js";
 import { authHeaders } from "./egress.js";
 import { resolveScope, resolveTokenUrl } from "./oauth.js";
+import { openAsBlob } from "node:fs";
+import { basename } from "node:path";
 import { InvocationError } from "./index-loader.js";
 function hasNextPage(body) {
     if (typeof body !== "object" || body === null || Array.isArray(body))
@@ -63,6 +65,30 @@ function assertTransportSafe(baseUrl) {
         `carries your BrowserStack access key, so the base URL must be https (or a local ` +
         `host for development). Check CAPABILITY_REGISTRY_BASE_URL_* for a typo.`);
 }
+/**
+ * Turn a bound body into a FormData, streaming any `file` parameter from disk.
+ *
+ * `bind` has already canonicalised and checked the path, so what arrives here is a file
+ * this server is configured to read. The blob is opened rather than buffered: an app build
+ * runs to gigabytes and reading one into memory to post it is how a server falls over.
+ */
+async function multipartBody(capability, body) {
+    const form = new FormData();
+    for (const param of capability.body || []) {
+        const value = body?.[param.name];
+        if (value === undefined || value === null)
+            continue;
+        if (param.type === "file") {
+            const path = String(value);
+            const blob = await openAsBlob(path);
+            form.append(param.name, blob, basename(path));
+        }
+        else {
+            form.append(param.name, String(value));
+        }
+    }
+    return form;
+}
 export async function invoke(capability, args, baseUrl, credentials, transport, auth, product) {
     if (!baseUrl)
         throw new InvocationError("no base URL is configured for that product");
@@ -71,7 +97,22 @@ export async function invoke(capability, args, baseUrl, credentials, transport,
     // Before binding would be wrong and after sending is too late: a scheme that mints a
     // token must not spend a round trip on a call that `bind` was going to reject anyway.
     const url = `${baseUrl.replace(/\/$/, "")}${bound.path}`;
-    const send = async () => transport(capability.method, url, await authHeaders(credentials, auth, product), bound.query, bound.body);
+    const multipart = capability.encoding === "multipart"
+        ? await multipartBody(capability, bound.body)
+        : undefined;
+    const send = async () => {
+        const headers = await authHeaders(credentials, auth, product);
+        if (multipart) {
+            // fetch writes its own Content-Type with the boundary. Leaving the JSON one on sends
+            // a body the product cannot parse, under a header that says it should be able to.
+            delete headers["Content-Type"];
+        }
+        const payload = multipart ??
+            (bound.body === undefined && capability.send_empty_body
+                ? {}
+                : bound.body);
+        return transport(capability.method, url, headers, bound.query, payload);
+    };
     let response = await send();
     /**
      * One replay, for a minted token the product rejected.

package/dist/tools/capability-registry/types.d.ts

@@ -116,6 +116,23 @@ export interface Capability {
     name?: string;
     method: string;
     path: string;
+    /**
+     * Which of the product's named `hosts` serves this one capability, when it is not the
+     * product's own `base_url`.
+     *
+     * A product is normally one host. App Automate is not: the account-level API (devices,
+     * app builds, plan, session records) answers on one origin and the Appium hub that
+     * drives the device answers on another, and neither serves the other's paths. Splitting
+     * them into two products would split one entity too — the session a hub capability
+     * creates is the session the account-level API reports on — and a caller holding the id
+     * would have to know it had changed products to use it.
+     *
+     * Unset means the product's own host, so every existing index is unaffected. A name that
+     * `hosts` does not define is refused by name at invocation rather than quietly falling
+     * back, because the fallback would send the call to a host that cannot serve the path and
+     * return a 404 that reads like the caller's mistake.
+     */
+    host?: string;
     mode: Mode;
     entity: string;
     path_params?: WireParam[];
@@ -155,6 +172,63 @@ export interface Capability {
      * suppression must not be ignored for arriving in an unexpected shape.
      */
     disabled?: boolean;
+    /**
+     * Withheld when the server is not running on the caller's own machine.
+     *
+     * Some capabilities only mean anything when the person and the process share a computer:
+     * one that reads a file the caller names is the clear case. On a remote server that path
+     * resolves against the OPERATOR's disk, so honouring it would read one user's files on
+     * another's behalf — the capability does not become unreliable there, it becomes wrong.
+     *
+     * Distinct from `disabled`, which withholds a capability everywhere. This one is a claim
+     * about where it can run, so the same artifact serves both deployments: a local server
+     * publishes it and a remote one does not.
+     *
+     * FAILS CLOSED in the same way, and takes the same `capability_disabled` path at
+     * invocation, so a caller holding the handle is told the absence is deliberate rather
+     * than hunting for a synonym.
+     */
+    local_only?: boolean;
+    /**
+     * What to do instead, on a surface where this capability cannot run.
+     *
+     * A `local_only` capability is NOT hidden on a remote server: the query that should find
+     * it still finds it, because an agent asked to upload a file from the user's machine
+     * needs to learn that the route exists and what replaces it here. What it loses is the
+     * means to call it — the parameters and response shapes are stripped at load, and
+     * invocation is refused — so the note is the whole of what remains.
+     *
+     * Write it as the instruction the caller should follow, not as an apology.
+     */
+    unavailable_note?: string;
+    /**
+     * FALSE when this build publishes the capability for reference but will not call it.
+     *
+     * Set by the loader, never authored: it is the surface's answer, not the artifact's.
+     */
+    invocable?: boolean;
+    /**
+     * How the request body is encoded. Absent means JSON, which is every capability today.
+     *
+     * `multipart` exists for endpoints that take the bytes of a file rather than a reference
+     * to one. A capability declaring it must also declare a `file` parameter, and should be
+     * `local_only`: the path names the caller's own machine.
+     */
+    encoding?: "multipart";
+    /**
+     * Send `{}` rather than no body at all, for an endpoint that takes no parameters.
+     *
+     * Normally a capability with nothing to send sends nothing, which is right for a REST API
+     * and wrong for W3C WebDriver: Chrome answers 400 "invalid argument" to a parameterless
+     * POST with the body omitted and 200 to the same call carrying `{}`. Appium tolerates the
+     * omission, which is why the identical capability needs this on Automate and not on App
+     * Automate.
+     *
+     * Opt-in per capability rather than a rule for every bodyless POST, because 27 of those
+     * exist across the shipped indexes and changing what reaches their products is not
+     * something this can verify.
+     */
+    send_empty_body?: boolean;
     paginated?: boolean;
     /** The largest page the operation declares. */
     max_page_size?: number;
@@ -313,6 +387,18 @@ export interface ProductIndex {
      * (see `discovery.probePath`); declare it when the derived choice would be wrong.
      */
     probe_path?: string;
+    /**
+     * Additional hosts this product is served from, by name, for capabilities that declare
+     * `host`.
+     *
+     * DISTINCT FROM `base_urls`, which is a list of CANDIDATES for one host — probed in turn
+     * so a region-sharded product lands on the account's own region. These are several hosts
+     * that all serve the product at once, each addressing a different part of it, and the
+     * capability says which it needs rather than the server discovering it.
+     *
+     * `base_url` remains the default for every capability that names no host.
+     */
+    hosts?: Record<string, string>;
     capabilities: Capability[];
     entities: Record<string, EntityDoc>;
     paging?: Record<string, PagingRule>;

package/dist/tools/get-failure-logs.js

@@ -115,7 +115,7 @@ export async function getFailureLogs(args, config) {
 // Register tool with the MCP server
 export default function registerGetFailureLogs(server, config) {
     const tools = {};
-    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch logs or the video URL for an Automate/App Automate session." +
+    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch logs, or the session video URL, for an Automate/App Automate session." +
         NEEDS_SESSION_ID, {
         sessionType: z
             .enum([SessionType.Automate, SessionType.AppAutomate])