mcp-tool-bridge 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,668 @@
+import { P as Principal, J as JsonSchemaObject, S as Sensitivity, A as ArgsSchema, T as ToolOutput, a as JsonObject, b as ArgIssue, c as JsonValue, d as ToolResult } from './types-tss7dg3j.cjs';
+export { e as AudioContent, C as ContentBlock, I as ImageContent, f as JsonPrimitive, g as ParseResult, h as SENSITIVITY_LEVELS, i as TextContent, j as isSensitivity, s as sensitivityRank } from './types-tss7dg3j.cjs';
+import { JSONSchema, FromSchema } from 'json-schema-to-ts';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+/**
+ * `auto` lets the bridge's policy decide from `sensitivity` and `reversible`.
+ * `always` forces a confirmation whatever the policy. There is deliberately
+ * no way to opt a tool *out* of the policy.
+ */
+type ConfirmMode = 'auto' | 'always';
+/** What a handler knows about the call it serves. */
+interface CallContext<TContext> {
+    readonly principal: Principal;
+    /** Whatever the host built for this principal (database client, tenant…). */
+    readonly context: TContext;
+    /** Aborted when the call times out or the client cancels it. */
+    readonly signal: AbortSignal;
+    /** Unique per call; the same id appears in every audit event of the call. */
+    readonly callId: string;
+}
+type ToolHandler<TArgs, TContext> = (args: TArgs, call: CallContext<TContext>) => Promise<ToolOutput>;
+/**
+ * A tool declaration. The governance fields — `sensitivity`, `reversible`,
+ * `roles` — are required and have no default: a tool nobody classified is a
+ * startup error, not a tool open to everyone.
+ */
+interface ToolDefinition<TArgs, TContext> {
+    /** Unique within a registry. MCP allows `A-Z a-z 0-9 _ - .`, 1 to 128 characters. */
+    readonly name: string;
+    readonly title?: string;
+    /** What the model reads to decide whether and how to call the tool. */
+    readonly description: string;
+    readonly args: ArgsSchema<TArgs>;
+    readonly sensitivity: Sensitivity;
+    /** Can the effect be undone? An irreversible tool is confirmed one level earlier. */
+    readonly reversible: boolean;
+    /** A principal needs at least one of these roles to see or call the tool. */
+    readonly roles: readonly [string, ...string[]];
+    readonly confirm?: ConfirmMode;
+    /** One sentence describing this specific call, shown to whoever confirms it. */
+    readonly summarize?: (args: NoInfer<TArgs>) => string;
+    /**
+     * What the audit log may keep of this tool's calls. By default, nothing but
+     * metadata (tool, principal, argument digest, verdict, duration). Keeping
+     * content is a written decision: JSON Pointers into the arguments
+     * (`args`) and into the structured result (`result`); `*` matches every
+     * element. A `read_email` tool would keep `{ args: ['/messageId'] }` and nothing else.
+     */
+    readonly audit?: AuditRetention;
+    readonly timeoutMs?: number;
+    readonly handler: ToolHandler<NoInfer<TArgs>, TContext>;
+}
+/** JSON Pointers of the fields the audit log may keep. Empty by default. */
+interface AuditRetention {
+    readonly args?: readonly string[];
+    readonly result?: readonly string[];
+}
+declare const contextType: unique symbol;
+/**
+ * A declared tool: an immutable descriptor. It carries no way to execute the
+ * handler; only the bridge can, after its checks. `TContext` is the context
+ * the handler expects; a tool that needs none fits any registry.
+ */
+interface Tool<TContext = unknown> {
+    readonly name: string;
+    readonly title: string | undefined;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+    readonly sensitivity: Sensitivity;
+    readonly reversible: boolean;
+    readonly roles: readonly string[];
+    readonly confirm: ConfirmMode;
+    /** What the audit may keep; both lists are empty unless the tool declared otherwise. */
+    readonly audit: {
+        readonly args: readonly string[];
+        readonly result: readonly string[];
+    };
+    readonly timeoutMs: number | undefined;
+    /** Type-level only: keeps a tool needing `{ db }` out of a registry that cannot provide it. */
+    readonly [contextType]?: (context: TContext) => void;
+}
+declare function defineTool<TArgs, TContext = unknown>(definition: ToolDefinition<TArgs, TContext>): Tool<TContext>;
+/** True for descriptors produced by `defineTool`, and only those. */
+declare function isTool(value: unknown): value is Tool;
+/** MCP behaviour hints, derived from the declaration. */
+interface ToolAnnotations {
+    readonly title?: string;
+    /** `sensitivity: "none"` means the tool has no side effect. */
+    readonly readOnlyHint: boolean;
+    /** Irreversible tools are flagged as destructive. */
+    readonly destructiveHint: boolean;
+}
+/** What the model is shown of a tool. Roles and sensitivity levels stay server-side. */
+interface ExposedTool {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+    readonly annotations: ToolAnnotations;
+}
+declare function exposeTool(tool: Tool<never>): ExposedTool;
+
+/**
+ * The single access rule, used both when listing tools and when executing
+ * one: the principal must hold at least one of the tool's roles. Role names
+ * are compared exactly; there is no wildcard and no hierarchy.
+ */
+declare function canAccess(tool: Pick<Tool<never>, 'roles'>, principal: Principal): boolean;
+/** The tools this principal may see, in registry order. */
+declare function visibleTools<TContext>(tools: Iterable<Tool<TContext>>, principal: Principal): Tool<TContext>[];
+/**
+ * Checks a principal coming from outside the type system (configuration,
+ * environment, an authentication hook) and returns a frozen copy, so that
+ * mutating the original between two checks changes nothing.
+ */
+declare function parsePrincipal(value: unknown): Principal;
+
+/** How to talk to an existing function: what to give it, and how to read its answer. */
+interface AdaptSpec<TArgs, TContext, TInput, TResult> {
+    /** Builds the function's input from the validated arguments and the call. */
+    readonly input: (args: TArgs, call: CallContext<TContext>) => TInput;
+    /** Turns the function's result into the tool output; `envelope()` fits here. */
+    readonly output: (result: TResult) => ToolOutput;
+}
+/**
+ * Turns an existing function into a handler, without rewriting it: the
+ * bridge validates the arguments, `input` maps them to what the function
+ * expects, and `output` maps its result back.
+ *
+ * ```ts
+ * handler: adapt((action: LegacyAction) => legacy.execute(action), {
+ *   input: (args, call) => ({ userId: call.principal.id, data: JSON.stringify(args) }),
+ *   output: fromLegacy, // an envelope()
+ * }),
+ * ```
+ *
+ * Pass methods bound (`legacy.execute.bind(legacy)`) or wrapped in an arrow
+ * function: `adapt` calls `fn` without a receiver.
+ */
+declare function adapt<TArgs, TContext, TInput, TResult>(fn: (input: TInput) => TResult | Promise<TResult>, spec: AdaptSpec<TArgs, TContext, TInput, TResult>): ToolHandler<TArgs, TContext>;
+
+/**
+ * What a foreign tool definition does not say: how much harm the tool can do
+ * and who may use it. Declared per tool, never defaulted.
+ */
+interface Governance {
+    readonly sensitivity: Sensitivity;
+    readonly reversible: boolean;
+    readonly roles: readonly [string, ...string[]];
+    readonly title?: string;
+    readonly confirm?: ConfirmMode;
+    /** What the audit log may keep; nothing but metadata by default. */
+    readonly audit?: AuditRetention;
+    readonly timeoutMs?: number;
+    readonly summarize?: (args: JsonObject) => string;
+}
+/** Runs any of the imported tools, by name. Arguments are already validated. */
+type Dispatcher<TContext> = (name: string, args: JsonObject, call: CallContext<TContext>) => Promise<ToolOutput>;
+/**
+ * Turns tool definitions written for an LLM API into bridge tools, with one
+ * dispatcher for all of them. Accepted shapes:
+ *
+ * - Anthropic: `{ name, description, input_schema }`
+ * - MCP: `{ name, description, inputSchema }`
+ * - OpenAI: `{ type: 'function', function: { name, description, parameters } }`,
+ *   or `{ type: 'function', name, description, parameters }`
+ *
+ * Every definition needs an entry in `governance`, and every entry a
+ * definition: a tool nobody classified, or a classification for a tool that
+ * does not exist (a typo), fails at startup, all names listed at once.
+ * Schemas are compiled in the same strict mode as `jsonSchema()`.
+ */
+declare function importDefinitions<TContext = unknown>(definitions: readonly unknown[], dispatch: Dispatcher<TContext>, governance: Readonly<Record<string, Governance>>): Tool<TContext>[];
+
+/** How to read the result envelope an existing function returns. */
+interface EnvelopeSpec<R> {
+    /** Did the call succeed? */
+    readonly ok: (result: R) => boolean;
+    /** What the model gets on success: a string, or `text()` / `json()`. */
+    readonly value: (result: R) => ToolOutput;
+    /**
+     * What the model reads on failure. It is shown as is: map raw errors
+     * (stack traces, hostnames, SQL) to something the model may read.
+     */
+    readonly message: (result: R) => string;
+}
+/**
+ * Plugs an existing implementation that reports failure in its return value
+ * (`{ success, data, error }`, `{ ok, detail }`…) into a handler, without
+ * rewriting it. A failed envelope becomes a `ToolError`, so the bridge treats
+ * it as an expected failure the model may read; a successful one becomes the
+ * tool's output.
+ *
+ * ```ts
+ * const fromLegacy = envelope<{ success: boolean; data?: Invoice; error?: string }>({
+ *   ok: (r) => r.success,
+ *   value: (r) => json({ invoiceId: r.data?.id ?? null }),
+ *   message: (r) => r.error ?? 'The invoice could not be sent.',
+ * })
+ * handler: async (args) => fromLegacy(await legacy.sendInvoice(args.invoiceId)),
+ * ```
+ */
+declare function envelope<R>(spec: EnvelopeSpec<R>): (result: R) => ToolOutput;
+
+type AuditTransport = 'stdio' | 'http' | 'direct';
+/**
+ * Why a call did not run. The model is told less: `forbidden` reaches it as
+ * `unknown_tool`, so that probing tool names reveals nothing.
+ */
+type RejectionReason = 'unknown_tool' | 'forbidden' | 'invalid_arguments' | 'confirmation_invalid' | 'confirmation_expired';
+/**
+ * Which check refused a confirmation token. Recorded in the audit log only:
+ * the model gets a generic refusal and never learns which check stopped it.
+ * These are the lines that show whether something is trying to force its way.
+ */
+type ConfirmationFailure = 'unknown' | 'consumed' | 'expired' | 'principal_mismatch' | 'tool_mismatch' | 'arguments_mismatch';
+/**
+ * - `tool_error`: the handler threw a ToolError, its message reached the model.
+ * - `exception`: anything else went wrong; the model only got a generic message.
+ * - `timeout`, `aborted`: the bridge stopped waiting. The handler may still be running.
+ * - `audit_unavailable`: the call was not executed because the audit log could not record it.
+ */
+type FailureKind = 'tool_error' | 'exception' | 'timeout' | 'aborted' | 'audit_unavailable';
+/**
+ * What the audit keeps of a result: whether it was an error, and the fields
+ * the tool declared it may keep (`audit.result`). Nothing else, no text.
+ */
+interface AuditedResult {
+    readonly isError: boolean;
+    /** Declared fields only, keyed by their JSON Pointer. Absent when none is declared. */
+    readonly kept?: JsonObject;
+}
+/** Fields every event carries. */
+interface AuditBase {
+    /** Unique per event. */
+    readonly id: string;
+    /** ISO 8601. */
+    readonly at: string;
+    /** Shared by every event of one call, including its confirmation and redemption. */
+    readonly callId: string;
+    readonly transport: AuditTransport;
+    readonly principal: {
+        readonly id: string;
+        readonly roles: readonly string[];
+    };
+    readonly tool: string;
+    /**
+     * SHA-256 of the canonical arguments: enough to tell two calls apart, or to
+     * match a call with its confirmation, without keeping what was sent.
+     * Absent when the arguments were not JSON.
+     */
+    readonly argsDigest?: string;
+    /** The argument fields the tool declared it may keep (`audit.args`), keyed by pointer. */
+    readonly args?: JsonObject;
+}
+/** What distinguishes one kind of event from another. */
+type AuditEventBody = {
+    readonly type: 'call.rejected';
+    readonly reason: RejectionReason;
+    readonly detail?: ConfirmationFailure;
+    readonly issues?: readonly ArgIssue[];
+} | {
+    readonly type: 'confirmation.issued';
+    readonly expiresAt: string;
+} | {
+    readonly type: 'confirmation.declined';
+} | {
+    readonly type: 'call.started';
+    readonly confirmed: boolean;
+} | {
+    readonly type: 'call.succeeded';
+    readonly confirmed: boolean;
+    readonly durationMs: number;
+    readonly result: AuditedResult;
+} | {
+    readonly type: 'call.failed';
+    readonly confirmed: boolean;
+    readonly durationMs: number;
+    readonly error: {
+        readonly kind: FailureKind;
+        readonly message: string;
+    };
+};
+/**
+ * One line of the audit log. A call that runs produces `call.started` then
+ * `call.succeeded` or `call.failed`; a confirmed call is preceded by
+ * `confirmation.issued`, under the same `callId`.
+ */
+type AuditEvent = AuditBase & AuditEventBody;
+type AuditEventType = AuditEvent['type'];
+/**
+ * Where audit events go. `write` may be synchronous or return a promise; the
+ * bridge waits for it before going on, so events are recorded in order.
+ */
+interface AuditSink {
+    write(event: AuditEvent): void | Promise<void>;
+}
+
+declare const REDACTED = "[REDACTED]";
+declare function isSecretKey(key: string): boolean;
+
+/**
+ * One JSON object per line on stderr. The default sink: under stdio, stdout
+ * carries the protocol and must never receive anything else.
+ */
+declare function stderrJsonSink(): AuditSink;
+interface MemorySink extends AuditSink {
+    readonly events: readonly AuditEvent[];
+    clear(): void;
+}
+/** Keeps events in memory. For tests, or to inspect what a host recorded. */
+declare function memorySink(): MemorySink;
+
+/** `none` is not a threshold: a tool with no side effect has nothing to confirm. */
+type ConfirmationThreshold = Exclude<Sensitivity, 'none'>;
+interface ConfirmationPolicy {
+    /** Tools at or above this level are confirmed. Default `high`. */
+    readonly threshold: ConfirmationThreshold;
+    /** Confirm irreversible tools one level below the threshold. Default true. */
+    readonly irreversibleLowersThreshold: boolean;
+}
+/**
+ * Whether a call to this tool must be confirmed before it runs. Decided from
+ * the declaration alone, never from the arguments or from anything the model
+ * says: the same tool is always confirmed, or never.
+ */
+declare function requiresConfirmation(tool: Pick<Tool<never>, 'sensitivity' | 'reversible' | 'confirm'>, policy?: ConfirmationPolicy): boolean;
+
+/** A call held back until someone confirms it. */
+interface ConfirmationRecord {
+    /** SHA-256 of the token. The token itself is never stored. */
+    readonly tokenHash: string;
+    /** The call this confirmation belongs to; its audit events share this id. */
+    readonly callId: string;
+    readonly principalId: string;
+    readonly tool: string;
+    /** The arguments as received, already validated once. They are what will run. */
+    readonly arguments: JsonValue;
+    readonly argumentsDigest: string;
+    readonly summary: string;
+    /** Epoch milliseconds. */
+    readonly createdAt: number;
+    /**
+     * Computed once, when the confirmation is issued, and stored with it. Never
+     * recomputed from a configuration that may have changed since.
+     */
+    readonly expiresAt: number;
+}
+/**
+ * What a redemption attempt found. Presenting a token consumes it, whatever
+ * the outcome: a second presentation finds it `consumed`. `expired` carries
+ * the record while it is still stored; once a store has evicted it, only the
+ * fact that it expired is remembered.
+ */
+type TakeResult = {
+    readonly status: 'taken';
+    readonly record: ConfirmationRecord;
+} | {
+    readonly status: 'expired';
+    readonly record?: ConfirmationRecord;
+} | {
+    readonly status: 'consumed';
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * Where pending confirmations wait.
+ *
+ * `take` must, in ONE atomic step, read the record, check its expiry against
+ * `now`, and mark it consumed: that is what makes a token single-use when two
+ * redemptions race, and what keeps an expired token from passing. Expiry is
+ * decided there, never by a cleanup job; cleanup only frees space.
+ *
+ * In SQL: `UPDATE confirmations SET consumed_at = now() WHERE token_hash = $1
+ * AND consumed_at IS NULL RETURNING *, expires_at <= now() AS expired`, then,
+ * when no row comes back, one read to tell `consumed` from `unknown`.
+ */
+interface ConfirmationStore {
+    put(record: ConfirmationRecord): Promise<void>;
+    take(tokenHash: string, now: number): Promise<TakeResult>;
+}
+interface MemoryConfirmationStoreOptions {
+    /** Upper bound on pending confirmations. Default 10 000. */
+    readonly maxEntries?: number;
+    /** Upper bound on remembered consumed tokens. Default 10 000. */
+    readonly maxConsumed?: number;
+    /**
+     * How long a consumed or expired token is remembered after its own expiry,
+     * so that a replay is reported as such rather than as unknown. Default 24 h.
+     */
+    readonly consumedRetentionMs?: number;
+    readonly now?: () => number;
+}
+/**
+ * In-process store, for a single process.
+ *
+ * Both maps are bounded, so a process that runs for months does not grow:
+ * pending records by `maxEntries`, consumed tokens by `maxConsumed` and by
+ * their retention. When a map is full, expired entries go first, then the
+ * oldest. A model that floods sensitive calls cannot make memory grow.
+ */
+declare class MemoryConfirmationStore implements ConfirmationStore {
+    #private;
+    constructor(options?: MemoryConfirmationStoreOptions);
+    /** Pending confirmations. */
+    get size(): number;
+    /** Remembered consumed or expired tokens. */
+    get consumedSize(): number;
+    put(record: ConfirmationRecord): Promise<void>;
+    take(tokenHash: string, now: number): Promise<TakeResult>;
+}
+
+/**
+ * The catalog of tools a bridge may expose. It only accepts descriptors
+ * built by `defineTool`, so every entry has passed the declaration checks.
+ */
+declare class ToolRegistry<TContext = unknown> {
+    #private;
+    /**
+     * Adds tools, all or none: if one of them is invalid or its name is taken
+     * (by an existing tool or by another tool in the same call), the registry
+     * is left unchanged.
+     */
+    register(...tools: readonly Tool<TContext>[]): this;
+    /** Removes a tool. Returns false if there was none by that name. */
+    unregister(name: string): boolean;
+    get(name: string): Tool<TContext> | undefined;
+    has(name: string): boolean;
+    /** Every tool, in registration order, regardless of who is asking. */
+    list(): readonly Tool<TContext>[];
+    get size(): number;
+    /**
+     * Called after every change. The MCP server uses it to send
+     * `notifications/tools/list_changed`. Returns an unsubscribe function.
+     */
+    onChange(listener: () => void): () => void;
+}
+
+/** Builds what handlers receive as `call.context`, once per executed call. */
+type ContextFactory<TContext> = (principal: Principal) => TContext | Promise<TContext>;
+interface ConfirmationOptions {
+    /** Default `high`. */
+    readonly threshold?: ConfirmationThreshold;
+    /** Default true: irreversible tools are confirmed one level below the threshold. */
+    readonly irreversibleLowersThreshold?: boolean;
+    /**
+     * How long a confirmation stays redeemable: one duration for every tool, or
+     * a table per sensitivity and reversibility. The expiry is computed when the
+     * confirmation is issued and stored with it; changing this later does not
+     * move confirmations already issued. Default 5 minutes.
+     */
+    readonly ttlMs?: number | ConfirmationTtlTable;
+    /** Default: in memory, for a single process. */
+    readonly store?: ConfirmationStore;
+}
+/**
+ * Lifetimes, in milliseconds, per sensitivity and reversibility. An
+ * irreversible action deserves a shorter window: past it, the context of the
+ * decision is not the one in which it was taken. A level or a case left out
+ * falls back to 5 minutes.
+ *
+ * ```ts
+ * const HOUR = 3_600_000
+ * ttlMs: {
+ *   medium: { reversible: 24 * HOUR, irreversible: 12 * HOUR },
+ *   high: { reversible: 12 * HOUR, irreversible: 4 * HOUR },
+ *   critical: { reversible: 4 * HOUR, irreversible: HOUR },
+ * }
+ * ```
+ */
+type ConfirmationTtlTable = Readonly<Partial<Record<Sensitivity, {
+    readonly reversible?: number;
+    readonly irreversible?: number;
+}>>>;
+interface BridgeOptions<TContext> {
+    readonly registry: ToolRegistry<TContext>;
+    readonly context: ContextFactory<TContext>;
+    readonly confirmation?: ConfirmationOptions;
+    /** Default: JSON lines on stderr. */
+    readonly audit?: AuditSink | readonly AuditSink[];
+    /**
+     * What to do when a sink fails. `continue` (default) warns on stderr and
+     * goes on. `block` refuses to start a call, or to issue a confirmation,
+     * that the audit log could not record.
+     */
+    readonly auditFailure?: 'continue' | 'block';
+    /** Clock, in epoch milliseconds. For tests. */
+    readonly now?: () => number;
+}
+interface CallRequest {
+    readonly name: string;
+    /** Omitted arguments are treated as `{}`, as MCP does. */
+    readonly arguments?: unknown;
+    /**
+     * A token from a previous `confirmation_required` outcome. Set by the host
+     * once a human has confirmed — never taken from the model's output.
+     */
+    readonly confirmationToken?: string;
+}
+interface CallOptions {
+    /** Cancels the call. The handler receives a signal that aborts with it. */
+    readonly signal?: AbortSignal;
+    /** Recorded in the audit log. The bundled servers set it; default `direct`. */
+    readonly transport?: AuditTransport;
+}
+/** For the host, not for the model: the token is what lets the call run. */
+interface PendingConfirmation {
+    readonly token: string;
+    /** ISO 8601. */
+    readonly expiresAt: string;
+    readonly tool: string;
+    readonly summary: string;
+}
+/** Every outcome carries the `callId` found in the audit log. */
+type CallOutcome = {
+    readonly status: 'ok';
+    readonly callId: string;
+    readonly result: ToolResult;
+} | {
+    readonly status: 'tool_error';
+    readonly callId: string;
+    readonly message: string;
+} | {
+    readonly status: 'invalid_arguments';
+    readonly callId: string;
+    readonly issues: readonly ArgIssue[];
+} | {
+    readonly status: 'confirmation_required';
+    readonly callId: string;
+    readonly confirmation: PendingConfirmation;
+} | {
+    readonly status: 'rejected';
+    readonly callId: string;
+    readonly reason: 'unknown_tool' | 'confirmation_invalid' | 'confirmation_expired';
+};
+interface Bridge<TContext> {
+    readonly registry: ToolRegistry<TContext>;
+    /** The tools this principal may see, as the model will see them. First filter. */
+    listTools(principal: Principal): readonly ExposedTool[];
+    /** Second filter, then validation, then the confirmation guard, then execution. */
+    callTool(principal: Principal, request: CallRequest, options?: CallOptions): Promise<CallOutcome>;
+    /**
+     * Runs a call held back for confirmation, for the principal it was issued
+     * to. For confirmations given later, outside the conversation.
+     */
+    executeConfirmed(principal: Principal, token: string, options?: CallOptions): Promise<CallOutcome>;
+    /**
+     * Withdraws a pending confirmation: the human said no. Returns false if
+     * there was nothing to withdraw for this principal. A token presented by
+     * another principal is destroyed all the same.
+     */
+    revokeConfirmation(principal: Principal, token: string, options?: CallOptions): Promise<boolean>;
+}
+declare function createBridge<TContext>(options: BridgeOptions<TContext>): Bridge<TContext>;
+
+type ToolDefinitionErrorCode = 'invalid_definition' | 'invalid_name' | 'invalid_title' | 'invalid_description' | 'invalid_schema' | 'invalid_sensitivity' | 'invalid_reversible' | 'invalid_roles' | 'invalid_confirm' | 'invalid_summarize' | 'invalid_audit' | 'invalid_timeout' | 'invalid_handler' | 'duplicate_name' | 'missing_governance' | 'unknown_governance' | 'not_a_tool';
+/**
+ * A tool declaration is wrong. Thrown at startup — by `defineTool`, a schema
+ * adapter or the registry — never while serving a call.
+ */
+declare class ToolDefinitionError extends Error {
+    readonly name = "ToolDefinitionError";
+    readonly code: ToolDefinitionErrorCode;
+    /** The offending tool, when its name is known. */
+    readonly tool: string | undefined;
+    constructor(code: ToolDefinitionErrorCode, message: string, options?: {
+        readonly tool?: string | undefined;
+        readonly cause?: unknown;
+    });
+}
+/**
+ * An expected failure that the model is allowed to read: "no invoice with
+ * this number", "the slot is already booked". Its message is returned as the
+ * tool result. Any other exception thrown by a handler is reported to the
+ * model as a generic failure, and its details go to the audit log only.
+ */
+declare class ToolError extends Error {
+    readonly name = "ToolError";
+}
+
+/** A result made of a single text block. */
+declare function text(value: string): ToolResult;
+/**
+ * A result carrying JSON. Objects also go into `structuredContent`, which
+ * MCP reserves for objects; every value is serialized as text too, for
+ * clients that only read `content`.
+ */
+declare function json(value: JsonValue): ToolResult;
+
+/** A JSON Schema literal whose root is an object. */
+type ObjectJsonSchema = Exclude<JSONSchema, boolean> & {
+    readonly type: 'object';
+};
+/**
+ * The argument type a schema describes. A property with a `default` stays
+ * optional: defaults are not applied (see `jsonSchema`), so the handler must
+ * not be told the property is always there.
+ */
+type ArgsOf<S> = S extends JSONSchema ? FromSchema<S, {
+    keepDefaultedPropertiesOptional: true;
+}> : never;
+/** `unknown` for a valid schema; otherwise the full JSON Schema type, to report the faulty keyword. */
+type ValidSchema<S> = S extends JSONSchema ? unknown : JSONSchema;
+/**
+ * Wraps a JSON Schema (draft 2020-12) literal. Declare it inline or `as const`
+ * and the handler's argument type is inferred from it.
+ *
+ * The schema is compiled once, here, in Ajv's strict mode: an unknown
+ * keyword, an unknown format or a `required` property missing from
+ * `properties` fails at startup instead of silently accepting bad input.
+ * Defaults are documentation for the model; they are not applied, and no
+ * type coercion takes place: `"3"` is not a number.
+ */
+declare function jsonSchema<const S extends {
+    readonly type: 'object';
+}>(schema: S & ValidSchema<NoInfer<S>>): ArgsSchema<ArgsOf<S>>;
+
+/**
+ * The `_meta` key carrying a pending confirmation: in a `confirmation_required`
+ * result, the server puts `{ token, expiresAt, callId }` there; to redeem it,
+ * the host repeats the same call with `{ token }` under the same key in the
+ * request's `_meta`. `_meta` is for the host: it is not meant to reach the model.
+ */
+declare const CONFIRMATION_META_KEY = "mcp-tool-bridge/confirmation";
+interface ServerInfo {
+    readonly name: string;
+    readonly version: string;
+    readonly title?: string;
+    /** Sent to the client at initialization; often shown to the model. */
+    readonly instructions?: string;
+}
+interface McpServerOptions {
+    readonly info: ServerInfo;
+    /**
+     * Who this server acts for, for its whole lifetime: under stdio, the
+     * identity is fixed when the process starts.
+     */
+    readonly principal: Principal;
+    /**
+     * When a call needs confirmation and the client supports MCP elicitation,
+     * ask the user directly and run the call on a yes. Default true. Without
+     * elicitation, the result carries the token in `_meta` for the host.
+     */
+    readonly elicitConfirmations?: boolean;
+    /** Recorded in the audit log. `serveStdio` sets `stdio`; default `direct`. */
+    readonly transport?: AuditTransport;
+}
+/**
+ * An MCP server, built on the SDK's low-level `Server`, that serves one
+ * principal from a bridge. Connect it to any transport; `serveStdio` does it
+ * for stdio.
+ */
+declare function createMcpServer<TContext>(bridge: Bridge<TContext>, options: McpServerOptions): Server;
+
+type StdioServerOptions = Omit<McpServerOptions, 'transport'>;
+interface StdioHandle {
+    readonly server: Server;
+    close(): Promise<void>;
+}
+/**
+ * Serves the bridge over stdin/stdout, for one principal fixed at launch.
+ * stdout carries the protocol and nothing else: the audit log and warnings
+ * go to stderr.
+ */
+declare function serveStdio<TContext>(bridge: Bridge<TContext>, options: StdioServerOptions): Promise<StdioHandle>;
+
+export { type AdaptSpec, ArgIssue, type ArgsOf, ArgsSchema, type AuditBase, type AuditEvent, type AuditEventBody, type AuditEventType, type AuditRetention, type AuditSink, type AuditTransport, type AuditedResult, type Bridge, type BridgeOptions, CONFIRMATION_META_KEY, type CallContext, type CallOptions, type CallOutcome, type CallRequest, type ConfirmMode, type ConfirmationFailure, type ConfirmationOptions, type ConfirmationPolicy, type ConfirmationRecord, type ConfirmationStore, type ConfirmationThreshold, type ContextFactory, type Dispatcher, type EnvelopeSpec, type ExposedTool, type FailureKind, type Governance, JsonObject, JsonSchemaObject, JsonValue, type McpServerOptions, MemoryConfirmationStore, type MemoryConfirmationStoreOptions, type MemorySink, type ObjectJsonSchema, type PendingConfirmation, Principal, REDACTED, type RejectionReason, Sensitivity, type ServerInfo, type StdioHandle, type StdioServerOptions, type TakeResult, type Tool, type ToolAnnotations, type ToolDefinition, ToolDefinitionError, type ToolDefinitionErrorCode, ToolError, type ToolHandler, ToolOutput, ToolRegistry, ToolResult, adapt, canAccess, createBridge, createMcpServer, defineTool, envelope, exposeTool, importDefinitions, isSecretKey, isTool, json, jsonSchema, memorySink, parsePrincipal, requiresConfirmation, serveStdio, stderrJsonSink, text, visibleTools };