fettle-mcp 0.1.0

package/dist/config.js

@@ -0,0 +1,77 @@
+/**
+ * Runtime configuration, read once at startup from the environment.
+ *
+ * An MCP server is spawned by its client with an env block from a JSON config
+ * file the user hand-edits, so a missing or malformed value is the single most
+ * likely failure of this package — and the worst place to discover it is
+ * inside the first tool call, where the model reports it to the user as if the
+ * *monitor* were the problem. Everything here therefore fails at startup, on
+ * stderr, naming the variable and the file to fix.
+ */
+/** Where the public API lives when `FETTLE_API_URL` is not set. */
+export const DEFAULT_API_URL = "https://api.fettle.sh";
+/**
+ * How long one tool call may take before it is abandoned.
+ *
+ * A hung request is worse here than a slow one: the MCP client has no timeout
+ * of its own for a stdio server, so an unbounded `fetch` presents to the user
+ * as a permanently frozen assistant. 30s is well past the API's own latency
+ * and well short of a human's patience.
+ */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export class ConfigError extends Error {
+}
+function readApiUrl(raw) {
+    if (raw === undefined || raw.trim() === "") {
+        return DEFAULT_API_URL;
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw.trim());
+    }
+    catch {
+        throw new ConfigError(`FETTLE_API_URL is not a valid URL: ${raw}. Leave it unset to use ` +
+            `${DEFAULT_API_URL}.`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new ConfigError(`FETTLE_API_URL must be an http(s) URL; got ${parsed.protocol}//. Leave ` +
+            `it unset to use ${DEFAULT_API_URL}.`);
+    }
+    // Trailing slashes are stripped because every path in the contract is
+    // absolute and already leads with one — concatenating both would produce
+    // `//v1/monitors`, which the API answers with a 404 rather than the route
+    // the user plainly meant.
+    return parsed.toString().replace(/\/+$/, "");
+}
+function readTimeout(raw) {
+    if (raw === undefined || raw.trim() === "") {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    const parsed = Number.parseInt(raw.trim(), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new ConfigError(`FETTLE_TIMEOUT_MS must be a positive whole number of milliseconds; ` +
+            `got ${raw}. Leave it unset to use ${DEFAULT_TIMEOUT_MS}.`);
+    }
+    return parsed;
+}
+/**
+ * Build the configuration or explain what is missing.
+ *
+ * Throws:
+ *   ConfigError: `FETTLE_API_KEY` is absent or blank, `FETTLE_API_URL` is not a
+ *   usable http(s) URL, or `FETTLE_TIMEOUT_MS` is not a positive integer.
+ */
+export function loadConfig(env = process.env) {
+    const apiKey = env.FETTLE_API_KEY?.trim();
+    if (apiKey === undefined || apiKey === "") {
+        throw new ConfigError("FETTLE_API_KEY is not set. Create an API key in Settings → API Keys at " +
+            "https://fettle.sh and add it to the fettle-mcp entry of your MCP " +
+            'client configuration, e.g. "env": { "FETTLE_API_KEY": "fettle_…" }.');
+    }
+    return {
+        apiKey,
+        apiUrl: readApiUrl(env.FETTLE_API_URL),
+        timeoutMs: readTimeout(env.FETTLE_TIMEOUT_MS),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAQzC,MAAM,OAAO,WAAY,SAAQ,KAAK;CAAG;AAEzC,SAAS,UAAU,CAAC,GAAuB;IACzC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3C,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CACnB,sCAAsC,GAAG,0BAA0B;YACjE,GAAG,eAAe,GAAG,CACxB,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,WAAW,CACnB,8CAA8C,MAAM,CAAC,QAAQ,YAAY;YACvE,mBAAmB,eAAe,GAAG,CACxC,CAAC;IACJ,CAAC;IACD,sEAAsE;IACtE,yEAAyE;IACzE,0EAA0E;IAC1E,0BAA0B;IAC1B,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,WAAW,CAAC,GAAuB;IAC1C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3C,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,WAAW,CACnB,qEAAqE;YACnE,OAAO,GAAG,2BAA2B,kBAAkB,GAAG,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IAC1C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAC1C,MAAM,IAAI,WAAW,CACnB,yEAAyE;YACvE,mEAAmE;YACnE,qEAAqE,CACxE,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM;QACN,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC;QACtC,SAAS,EAAE,WAAW,CAAC,GAAG,CAAC,iBAAiB,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/dist/contract.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The tool contract: the one description both Fettle MCP channels interpret.
+ *
+ * The file this module loads is *generated* in the core backend
+ * (`scripts/generate_mcp_contract.py` from `src/mcp/registry.py`) and vendored
+ * here verbatim. Nothing in this package describes a tool by hand: adding a
+ * tool means re-vendoring the contract, not editing source. `pnpm
+ * contract:check` compares the vendored copy against what production serves at
+ * `GET /public-api/mcp-tools.json`, so drift is a failing check rather than a
+ * silent difference between the two channels.
+ */
+/** How to execute a tool as an HTTP request against the public API. */
+export interface ToolOperation {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    path: string;
+    path_params: string[];
+    query: string[];
+    body: boolean;
+}
+/** One agent-facing tool. */
+export interface ToolEntry {
+    name: string;
+    title: string;
+    description: string;
+    scope: "read" | "write";
+    input_schema: Record<string, unknown>;
+    operation: ToolOperation;
+}
+/** The whole document. */
+export interface ToolContract {
+    version: number;
+    tools: ToolEntry[];
+}
+/**
+ * The contract format version this code understands.
+ *
+ * Kept in lockstep with core's `SUPPORTED_CONTRACT_VERSION`. A guard, not a
+ * migration path — a future format bump surfaces as one legible message
+ * instead of an undefined field read at the first tool call.
+ */
+export declare const SUPPORTED_CONTRACT_VERSION = 1;
+/**
+ * Location of the vendored contract, resolved relative to this module rather
+ * than to the process's working directory: the package runs as `npx
+ * fettle-mcp` from wherever the MCP client happens to spawn it. `src/` and
+ * `dist/` both sit one level under the package root, so the same relative
+ * path is correct compiled and under test.
+ */
+export declare const CONTRACT_URL: import("url").URL;
+/**
+ * Validate a parsed contract document.
+ *
+ * Structural only — the per-tool `input_schema` is handed to Ajv unexamined,
+ * which is the point: this package must not develop its own opinion about what
+ * a tool's arguments look like.
+ */
+export declare function parseContract(raw: unknown): ToolContract;
+/** Read and validate the vendored contract. */
+export declare function loadContract(url?: URL): ToolContract;
+/** Resolve a tool by name, or `undefined` when the contract has no such tool. */
+export declare function findTool(contract: ToolContract, name: string): ToolEntry | undefined;

package/dist/contract.js

@@ -0,0 +1,113 @@
+/**
+ * The tool contract: the one description both Fettle MCP channels interpret.
+ *
+ * The file this module loads is *generated* in the core backend
+ * (`scripts/generate_mcp_contract.py` from `src/mcp/registry.py`) and vendored
+ * here verbatim. Nothing in this package describes a tool by hand: adding a
+ * tool means re-vendoring the contract, not editing source. `pnpm
+ * contract:check` compares the vendored copy against what production serves at
+ * `GET /public-api/mcp-tools.json`, so drift is a failing check rather than a
+ * silent difference between the two channels.
+ */
+import { readFileSync } from "node:fs";
+/**
+ * The contract format version this code understands.
+ *
+ * Kept in lockstep with core's `SUPPORTED_CONTRACT_VERSION`. A guard, not a
+ * migration path — a future format bump surfaces as one legible message
+ * instead of an undefined field read at the first tool call.
+ */
+export const SUPPORTED_CONTRACT_VERSION = 1;
+/**
+ * Location of the vendored contract, resolved relative to this module rather
+ * than to the process's working directory: the package runs as `npx
+ * fettle-mcp` from wherever the MCP client happens to spawn it. `src/` and
+ * `dist/` both sit one level under the package root, so the same relative
+ * path is correct compiled and under test.
+ */
+export const CONTRACT_URL = new URL("../contracts/mcp_tools.json", import.meta.url);
+const METHODS = new Set(["GET", "POST", "PATCH", "DELETE"]);
+function fail(message) {
+    throw new Error(`Invalid tool contract: ${message}`);
+}
+function assertOperation(operation, toolName) {
+    if (typeof operation !== "object" || operation === null) {
+        fail(`tool '${toolName}' has no operation object.`);
+    }
+    const candidate = operation;
+    if (typeof candidate.method !== "string" || !METHODS.has(candidate.method)) {
+        fail(`tool '${toolName}' has an unsupported method ${String(candidate.method)}.`);
+    }
+    if (typeof candidate.path !== "string" || !candidate.path.startsWith("/")) {
+        fail(`tool '${toolName}' has a non-absolute path.`);
+    }
+    const pathParams = candidate.path_params;
+    const query = candidate.query;
+    if (!Array.isArray(pathParams) || !Array.isArray(query)) {
+        fail(`tool '${toolName}' has malformed path_params/query.`);
+    }
+    return {
+        method: candidate.method,
+        path: candidate.path,
+        path_params: pathParams.map(String),
+        query: query.map(String),
+        body: candidate.body === true,
+    };
+}
+/**
+ * Validate a parsed contract document.
+ *
+ * Structural only — the per-tool `input_schema` is handed to Ajv unexamined,
+ * which is the point: this package must not develop its own opinion about what
+ * a tool's arguments look like.
+ */
+export function parseContract(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        fail("the document is not a JSON object.");
+    }
+    const document = raw;
+    if (document.version !== SUPPORTED_CONTRACT_VERSION) {
+        fail(`format version ${String(document.version)} is not the version ` +
+            `${SUPPORTED_CONTRACT_VERSION} this package understands. Upgrade ` +
+            `fettle-mcp (npm install -g fettle-mcp@latest) or pin an older one.`);
+    }
+    if (!Array.isArray(document.tools) || document.tools.length === 0) {
+        fail("the document carries no tools.");
+    }
+    const seen = new Set();
+    const tools = document.tools.map((entry) => {
+        if (typeof entry !== "object" || entry === null) {
+            fail("a tool entry is not an object.");
+        }
+        const candidate = entry;
+        const name = candidate.name;
+        if (typeof name !== "string" || name === "") {
+            fail("a tool entry has no name.");
+        }
+        if (seen.has(name)) {
+            fail(`tool '${name}' is declared twice.`);
+        }
+        seen.add(name);
+        if (typeof candidate.input_schema !== "object" || candidate.input_schema === null) {
+            fail(`tool '${name}' has no input_schema.`);
+        }
+        return {
+            name,
+            title: typeof candidate.title === "string" ? candidate.title : name,
+            description: typeof candidate.description === "string" ? candidate.description : "",
+            scope: candidate.scope === "write" ? "write" : "read",
+            input_schema: candidate.input_schema,
+            operation: assertOperation(candidate.operation, name),
+        };
+    });
+    return { version: document.version, tools };
+}
+/** Read and validate the vendored contract. */
+export function loadContract(url = CONTRACT_URL) {
+    return parseContract(JSON.parse(readFileSync(url, "utf8")));
+}
+/** Resolve a tool by name, or `undefined` when the contract has no such tool. */
+export function findTool(contract, name) {
+    return contract.tools.find((tool) => tool.name === name);
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turn a failed API response into a sentence that says what to fix.
+ *
+ * The counterpart of core's `src/mcp/executor.py::describe_failure`, and
+ * deliberately a port by meaning rather than a shared implementation — the two
+ * channels differ in exactly one respect that matters to the reader. On the
+ * remote channel the credential arrives as an HTTP header the client set; here
+ * it comes from the `FETTLE_API_KEY` environment variable in the user's MCP
+ * client config, so that is the thing the model must tell its user to change.
+ *
+ * Every branch answers "what should the caller do differently", never just
+ * "what went wrong": a model that reads "rate limited" retries immediately, a
+ * model that reads "retry after 43 seconds" waits.
+ */
+/** The API's two error body shapes, as core's exception handlers emit them. */
+interface ErrorBody {
+    detail?: unknown;
+    message?: unknown;
+    retry_after?: unknown;
+}
+/** Describe a non-2xx response in terms of what the caller should change. */
+export declare function describeFailure(statusCode: number, body: ErrorBody | null, headers?: Headers | null): string;
+/**
+ * Describe a request that never produced a response at all.
+ *
+ * A thrown `fetch` is not something the model can fix by changing arguments,
+ * but it is very often something the *user* can fix — a typo in
+ * `FETTLE_API_URL`, a machine with no network, a corporate proxy. Saying which
+ * URL was attempted turns an opaque "fetch failed" into a diagnosis.
+ */
+export declare function describeTransportFailure(baseUrl: string, cause: unknown): string;
+export {};

package/dist/errors.js

@@ -0,0 +1,141 @@
+/**
+ * Turn a failed API response into a sentence that says what to fix.
+ *
+ * The counterpart of core's `src/mcp/executor.py::describe_failure`, and
+ * deliberately a port by meaning rather than a shared implementation — the two
+ * channels differ in exactly one respect that matters to the reader. On the
+ * remote channel the credential arrives as an HTTP header the client set; here
+ * it comes from the `FETTLE_API_KEY` environment variable in the user's MCP
+ * client config, so that is the thing the model must tell its user to change.
+ *
+ * Every branch answers "what should the caller do differently", never just
+ * "what went wrong": a model that reads "rate limited" retries immediately, a
+ * model that reads "retry after 43 seconds" waits.
+ */
+/**
+ * The exact sentence core raises for an insufficient-scope 403
+ * (`PermissionDeniedException("API key scope is not sufficient")`). Matched
+ * verbatim rather than on the bare word "scope" so an unrelated 403 — a plan
+ * gate, say — whose message merely mentions scope in passing is never
+ * misdiagnosed as a key-scope problem.
+ */
+const SCOPE_INSUFFICIENT_MESSAGE = "API key scope is not sufficient";
+function extractMessage(body) {
+    if (body === null) {
+        return "";
+    }
+    if (typeof body.detail === "string") {
+        return body.detail;
+    }
+    if (typeof body.message === "string") {
+        return body.message;
+    }
+    return "";
+}
+/**
+ * Turn a FastAPI/pydantic `detail` list into a sentence naming each field.
+ *
+ * The `body`/`query`/`path` prefix pydantic puts at the head of every `loc` is
+ * dropped: it names the HTTP location, which is an implementation detail of a
+ * transport the model never sees. What is left is the argument name the model
+ * actually passed.
+ */
+function describeValidationErrors(detail) {
+    const parts = [];
+    for (const error of detail) {
+        if (typeof error !== "object" || error === null) {
+            continue;
+        }
+        const candidate = error;
+        const loc = Array.isArray(candidate.loc) ? candidate.loc : [];
+        const fieldParts = loc
+            .filter((part) => part !== "body" && part !== "query" && part !== "path")
+            .map((part) => String(part));
+        const field = fieldParts.length > 0 ? fieldParts.join(".") : "request";
+        const msg = typeof candidate.msg === "string" ? candidate.msg : "is invalid";
+        parts.push(`'${field}': ${msg}`);
+    }
+    if (parts.length === 0) {
+        return "The arguments failed validation. Check the argument values and retry.";
+    }
+    return `Invalid argument(s) — ${parts.join("; ")}. Fix the value(s) and retry.`;
+}
+/**
+ * Read the retry delay a 429 carries.
+ *
+ * Core answers rate limits with `retry_after` in the JSON body; the
+ * `Retry-After` header carries the same number and is read as a fallback,
+ * because unlike the remote channel this package also faces whatever sits in
+ * front of the API — a proxy that rate-limits before the application does
+ * answers with the header and no body of ours at all.
+ */
+function retryAfterSeconds(body, headers) {
+    const fromBody = body?.retry_after;
+    if (typeof fromBody === "number" && Number.isFinite(fromBody)) {
+        return fromBody;
+    }
+    const fromHeader = headers?.get("retry-after");
+    if (fromHeader !== null && fromHeader !== undefined) {
+        const parsed = Number.parseInt(fromHeader, 10);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return null;
+}
+/** Describe a non-2xx response in terms of what the caller should change. */
+export function describeFailure(statusCode, body, headers = null) {
+    const message = extractMessage(body);
+    if (statusCode === 401) {
+        return ("Authentication failed: Fettle rejected the API key. Check that " +
+            "FETTLE_API_KEY in the MCP client configuration holds a current, " +
+            "un-revoked key from Settings → API Keys at https://fettle.sh, then " +
+            "restart the MCP client so it picks the new value up.");
+    }
+    if (statusCode === 403) {
+        if (message.includes(SCOPE_INSUFFICIENT_MESSAGE)) {
+            return ("This tool needs an API key with write scope; FETTLE_API_KEY holds a " +
+                "read-only key. Create a write-scoped key in Settings → API Keys at " +
+                "https://fettle.sh and restart the MCP client with it.");
+        }
+        return `Forbidden: ${message || "the API key is not permitted to perform this action"}.`;
+    }
+    if (statusCode === 404) {
+        return (`Not found: ${message || "the requested resource does not exist"}. ` +
+            "Check the id and try again — list_monitors, list_incidents, " +
+            "list_heartbeats and list_status_pages return the current ids.");
+    }
+    if (statusCode === 422) {
+        const detail = body?.detail;
+        if (Array.isArray(detail)) {
+            return describeValidationErrors(detail);
+        }
+        return (`Invalid request: ${message || "the arguments failed validation"}. ` +
+            "Check the argument values and retry.");
+    }
+    if (statusCode === 429) {
+        const retryAfter = retryAfterSeconds(body, headers);
+        if (retryAfter !== null) {
+            return (`Rate limited by the plan's request budget: retry after ${retryAfter} ` +
+                "seconds, or upgrade the plan at https://fettle.sh/pricing.");
+        }
+        return "Rate limited by the plan's request budget: slow down and retry shortly.";
+    }
+    return (`Request failed with status ${statusCode}: ` +
+        `${message || "no further detail was provided"}.`);
+}
+/**
+ * Describe a request that never produced a response at all.
+ *
+ * A thrown `fetch` is not something the model can fix by changing arguments,
+ * but it is very often something the *user* can fix — a typo in
+ * `FETTLE_API_URL`, a machine with no network, a corporate proxy. Saying which
+ * URL was attempted turns an opaque "fetch failed" into a diagnosis.
+ */
+export function describeTransportFailure(baseUrl, cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return (`Could not reach the Fettle API at ${baseUrl}: ${reason}. Check network ` +
+        "connectivity and the FETTLE_API_URL setting (it defaults to " +
+        "https://api.fettle.sh and should not normally be set).");
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/executor.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Execute a tool call as a real HTTP request against the public API.
+ *
+ * The central decision of S2, held identically in both channels: an MCP tool
+ * call is a transport adapter, not a second implementation of the API. This
+ * module maps a `ToolEntry` plus the model's arguments onto an ordinary
+ * `/v1/...` request carrying the user's key as a Bearer token. Authentication,
+ * the `x-fettle-public-api` scope marker, the per-organization rate bucket,
+ * pydantic validation and pagination all execute in core, unchanged, because
+ * it is a real request hitting the real route.
+ *
+ * Where core's executor dispatches in-process through `httpx.ASGITransport`,
+ * this one goes over the network with `fetch` — but the argument-routing rules
+ * and the success/failure boundary are deliberately the same, so a tool
+ * behaves identically whichever channel a user picked.
+ */
+import type { ToolEntry } from "./contract.js";
+/**
+ * The MCP `tools/call` result shape.
+ *
+ * The index signature is what MCP's own result type requires — the protocol
+ * lets a result carry `_meta` and forward-compatible extras alongside the
+ * fields this package sets.
+ */
+export interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: boolean;
+    [key: string]: unknown;
+}
+/**
+ * An argument the model can fix: missing, wrongly typed, or aimed at a
+ * parameter this tool does not declare. Surfaces as an error *tool result*, so
+ * the model reads the explanation and retries.
+ */
+export declare class ToolArgumentError extends Error {
+}
+/**
+ * A failure the model cannot fix by retrying with different arguments — the
+ * API answered 5xx, or the request never got there. Surfaces as a JSON-RPC
+ * error, the same choice core makes for a 5xx.
+ */
+export declare class ToolProtocolError extends Error {
+}
+export interface ExecutorOptions {
+    apiUrl: string;
+    apiKey: string;
+    timeoutMs: number;
+    userAgent: string;
+    /** Injected in tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Dispatches `tools/call` invocations as requests against the public API. */
+export declare class ToolExecutor {
+    private readonly options;
+    private readonly fetchImpl;
+    constructor(options: ExecutorOptions);
+    /**
+     * Execute one tool call and return an MCP `tools/call` result.
+     *
+     * Flow:
+     * 1. Substitute the operation's declared path parameters into the URL
+     *    template, percent-encoding each value so it cannot introduce extra path
+     *    segments or a query string of its own.
+     * 2. Route the declared query parameters into the query string.
+     * 3. Route whatever arguments remain into the JSON body when the operation
+     *    declares one; otherwise an argument that matched no declared parameter
+     *    is rejected rather than silently dropped.
+     * 4. Dispatch the request with the user's key as a Bearer token, following
+     *    no redirects: a 3xx is reported, never chased, so the credential cannot
+     *    be replayed to a host the contract did not name.
+     * 5. Map the response — 2xx is a result, any other non-5xx is an actionable
+     *    tool error, 5xx and transport failures raise.
+     *
+     * Throws:
+     *   ToolArgumentError: an argument is missing, wrongly typed, or matched no
+     *   declared parameter on a tool with no request body.
+     *   ToolProtocolError: the API answered 5xx, or the request never completed.
+     */
+    execute(tool: ToolEntry, args: Record<string, unknown>): Promise<ToolResult>;
+}