TypeScript SDK Node.js and Bun API

This page lists declarations added or changed by @stacklok-oss/mecatl-sdk/node. The entry point also exports the shared core API.

Symbol index

Symbol	Kind
audioPartFromPath	Function
CallToolContent	Type alias
CallToolResult	Interface
connect	Function
createNodeTransport	Function
DaemonInfo	Interface
imagePartFromPath	Function
NodeClient	Interface
NodeConnectOptions	Type alias
NodeTransportCommonOptions	Interface
NodeTransportOptions	Type alias
query	Function
Query	Interface
QueryOptions	Interface
spawn	Function
SpawnedClient	Interface
SpawnOptions	Interface
ToolDefinition	Interface
ToolHandler	Type alias
ToolHandlerContext	Interface
ToolJsonValue	Type alias
ToolOptions	Interface
ToolRegistrationError	Class
ToolRegistrationReason	Type alias
ToolSchema	Type alias

Classes

ToolRegistrationError

A callback tool could not be added to the client registry.

export declare class ToolRegistrationError extends MecatlError

Callable members: constructor

ToolRegistrationError.constructor

Constructs a new instance of the ToolRegistrationError class

constructor(reason: ToolRegistrationReason, message: string, cause?: unknown);

Parameters:

• reason (ToolRegistrationReason)
• message (string)
• cause (unknown, optional)

ToolRegistrationError.reason

Stable reason distinguishing the rejected registration input.

readonly reason: ToolRegistrationReason;

Functions

audioPartFromPath

Reads a Node.js or Bun path into an audio prompt part.

export declare function audioPartFromPath(path: string | URL, mimeType: string): Promise<AudioPromptPart>;

Parameters:

• path (string | URL): File path or file URL to read.
• mimeType (string): Audio MIME type for the file contents.

Returns: Promise<AudioPromptPart>: A validated audio prompt part containing the file's bytes.

Throws: PromptValidationError when the MIME type or size is invalid.

connect

Creates a client for Node.js or Bun over gRPC or a caller-provided transport.

export declare function connect(options: NodeConnectOptions): NodeClient;

Parameters:

• options (NodeConnectOptions): gRPC endpoint, credentials, diagnostics, or a caller-owned transport.

Returns: NodeClient: A high-level client with callback-tool registration.

createNodeTransport

Creates a gRPC transport for Node.js or Bun over HTTP/2 or a Unix domain socket.

export declare function createNodeTransport(options: NodeTransportOptions): Transport;

Parameters:

• options (NodeTransportOptions): TCP authority or Unix socket plus credentials and HTTP/2 settings.

Returns: Transport: A Connect-ES gRPC transport.

imagePartFromPath

Reads a Node.js or Bun path into an image prompt part.

export declare function imagePartFromPath(path: string | URL, mimeType: string): Promise<ImagePromptPart>;

Parameters:

• path (string | URL): File path or file URL to read.
• mimeType (string): Image MIME type for the file contents.

Returns: Promise<ImagePromptPart>: A validated image prompt part containing the file's bytes.

Throws: PromptValidationError when the MIME type or size is invalid.

query

Spawns if needed, creates one session, runs one prompt, and cleans up owned resources.

export declare function query(prompt: PromptInput, options?: QueryOptions): Promise<Query>;

Parameters:

• prompt (PromptInput): Text or ordered text, image, and audio parts for the run.
• options (QueryOptions, optional): Session, responder, cancellation, retention, and daemon options.

Returns: Promise<Query>: A single-consumption event stream for the query-created session.

Throws: PlanApprovalRequiredError when plan mode has no approval responder.

spawn

Starts one local mecated daemon and resolves when it reports that it is ready.

export declare function spawn(options?: SpawnOptions): Promise<SpawnedClient>;

Parameters:

• options (SpawnOptions, optional): Executable, environment, daemon, readiness, and diagnostic options.

Returns: Promise<SpawnedClient>: A client that owns the ready daemon and its private runtime directory.

Throws: MecatlError with unsupported_platform on an unsupported operating system.

Throws: MecatlError with spawn_failed when the daemon cannot start correctly.

Throws: MecatlError with readiness_timeout when a live daemon misses its deadline.

Interfaces

CallToolResult

An explicit MCP callback-tool result, including intentional error results.

export interface CallToolResult

CallToolResult.content

readonly content: readonly CallToolContent[];

CallToolResult.isError

readonly isError?: boolean;

CallToolResult.structuredContent

readonly structuredContent?: ToolJsonValue;

DaemonInfo

Non-secret facts published by an SDK-owned daemon.

export interface DaemonInfo

DaemonInfo.apiMajor

The ready document's wire API major.

readonly apiMajor: number;

DaemonInfo.features

Deployment-scoped feature identifiers reported by the daemon.

readonly features: readonly string[];

DaemonInfo.pid

The spawned daemon's process identifier.

readonly pid: number;

DaemonInfo.socketPath

The private Unix-domain gRPC socket path.

readonly socketPath: string;

DaemonInfo.transport

Spawned clients always use the Unix-domain gRPC transport.

readonly transport: "unix";

NodeClient

A client for Node.js or Bun with local callback-tool registration.

export interface NodeClient extends Client

Callable members: tool()

NodeClient.tool

Registers one callback tool in the client-wide immutable tool set.

tool(name: string, schema: ToolSchema, handler: ToolHandler, options?: ToolOptions): ToolDefinition;

Parameters:

• name (string): Name advertised by the local MCP server.
• schema (ToolSchema): JSON Schema 2020-12 value for the tool arguments.
• handler (ToolHandler): Function invoked with validated arguments and an abort signal.
• options (ToolOptions, optional): Read-only assertion and per-tool concurrency limit.

Returns: ToolDefinition: The immutable registered-tool description and model-facing name.

Throws: ToolRegistrationError when the name, schema, or options are invalid.

NodeTransportCommonOptions

Shared credentials and HTTP/2 settings for the gRPC transport in Node.js or Bun.

export interface NodeTransportCommonOptions extends CredentialOptions

NodeTransportCommonOptions.nodeOptions

Additional HTTP/2 session options. The SDK controls createConnection when using socketPath.

nodeOptions?: Omit<ClientSessionOptions, "createConnection">;

Query

One query-owned event stream and its created session ID.

export interface Query extends AsyncIterable<Event>

Query.sessionId

The ID of the session created for this query.

readonly sessionId: string;

QueryOptions

Options for one query() call.

export interface QueryOptions

QueryOptions.client

Use an existing client instead of spawning a local daemon. The client remains caller-owned.

client?: Client;

QueryOptions.onPermissionAsk

Automatically answer permission asks. With no responder, query denies each ask safely.

onPermissionAsk?: PermissionAskResponder;

QueryOptions.onPlanApproval

Required in plan mode and invoked only for PresentPlan approval asks.

onPlanApproval?: PlanApprovalResponder;

QueryOptions.retainSession

Keep the created session after the query. SDK-spawned daemons use an in-memory store.

retainSession?: boolean;

QueryOptions.session

Fields applied when query creates its session.

session?: CreateSessionOptions;

QueryOptions.signal

Abort this query and clean up every resource it created.

signal?: AbortSignal;

QueryOptions.spawn

Daemon options used only when query creates its own client.

spawn?: SpawnOptions;

SpawnedClient

A Client that owns one locally spawned daemon.

export interface SpawnedClient extends NodeClient

SpawnedClient.daemon

The ready document's non-secret daemon facts.

readonly daemon: DaemonInfo;

SpawnOptions

Options for starting one SDK-owned local daemon.

export interface SpawnOptions extends ClientDiagnosticsOptions

SpawnOptions.args

Additional daemon arguments. SDK-owned listener and lifecycle flags cannot be replaced.

args?: readonly string[];

SpawnOptions.binaryPath

Explicit mecated executable. Resolution otherwise uses MECATED_BIN, then PATH.

binaryPath?: string;

SpawnOptions.env

Environment overrides merged over the parent process environment.

env?: Readonly<NodeJS.ProcessEnv>;

SpawnOptions.http

Also expose the daemon's HTTP/SSE listener on an ephemeral loopback port.

http?: boolean;

SpawnOptions.lifetimePipe

Keep the daemon tied to the parent-liveness descriptor. Defaults to true.

lifetimePipe?: boolean;

SpawnOptions.readinessTimeoutMs

Deadline for publication of a complete supported ready document.

readinessTimeoutMs?: number;

SpawnOptions.toolServerName

Stable MCP namespace for callback tools. Defaults to sdk.

toolServerName?: string;

ToolDefinition

The immutable public description returned for a registered callback tool.

export interface ToolDefinition

ToolDefinition.concurrency

Per-tool handler concurrency cap, when one was requested.

readonly concurrency: number | undefined;

ToolDefinition.modelName

Model-facing name after applying the client-wide MCP server namespace.

readonly modelName: string;

ToolDefinition.name

Name advertised by the local MCP server.

readonly name: string;

ToolDefinition.readOnly

The unverified read-only assertion carried as MCP readOnlyHint.

readonly readOnly: boolean;

ToolDefinition.schema

The JSON Schema 2020-12 value advertised for tool arguments.

readonly schema: ToolSchema;

ToolHandlerContext

Context supplied to one callback tool invocation.

export interface ToolHandlerContext

ToolHandlerContext.signal

Aborted when the host cancels this invocation or shuts down.

readonly signal: AbortSignal;

ToolOptions

Registration options for one callback tool.

export interface ToolOptions

ToolOptions.concurrency

Tightens the client-wide handler concurrency cap for this tool. Values above the client cap never raise it.

concurrency?: number;

ToolOptions.readOnly

Unverified caller assertion that the callback has no side effects. The SDK carries this as MCP's readOnlyHint; Mecatl trusts that hint when scheduling concurrent read-only calls. A callback marked read-only may run concurrently even if it has side effects. Plan mode does not automatically classify MCP tool names as mutations.

readOnly?: boolean;

Type aliases

CallToolContent

One JSON-serializable MCP content block returned by a callback tool.

export type CallToolContent = Readonly<Record<string, ToolJsonValue>> & {
    readonly type: string;
};

NodeConnectOptions

Options accepted by connect() in Node.js or Bun.

export type NodeConnectOptions = (NodeTransportOptions | InjectedTransportOptions) & ClientDiagnosticsOptions;

NodeTransportOptions

Selects a TCP authority or Unix domain socket for the gRPC transport.

export type NodeTransportOptions = NodeTransportCommonOptions & ({
    baseUrl: string;
    socketPath?: never;
} | {
    baseUrl?: string;
    socketPath: string;
});

ToolHandler

A locally registered callback tool implementation.

export type ToolHandler = (arguments_: Readonly<Record<string, ToolJsonValue>>, context: ToolHandlerContext) => unknown | Promise<unknown>;

ToolJsonValue

The JSON values accepted by callback tool schemas and handlers.

export type ToolJsonValue = boolean | number | string | null | readonly ToolJsonValue[] | {
    readonly [key: string]: ToolJsonValue;
};

ToolRegistrationReason

Stable authoring-error reasons carried by ToolRegistrationError.

export type ToolRegistrationReason = "duplicate_name" | "invalid_options" | "invalid_schema" | "invalid_server_name" | "invalid_tool_name";

ToolSchema

A plain JSON Schema 2020-12 value; no schema-builder library is required.

export type ToolSchema = boolean | Readonly<Record<string, ToolJsonValue>>;