Skip to main content

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​

SymbolKind
audioPartFromPathFunction
CallToolContentType alias
CallToolResultInterface
connectFunction
createNodeTransportFunction
DaemonInfoInterface
imagePartFromPathFunction
NodeClientInterface
NodeConnectOptionsType alias
NodeTransportCommonOptionsInterface
NodeTransportOptionsType alias
queryFunction
QueryInterface
QueryOptionsInterface
spawnFunction
SpawnedClientInterface
SpawnOptionsInterface
ToolDefinitionInterface
ToolHandlerType alias
ToolHandlerContextInterface
ToolJsonValueType alias
ToolOptionsInterface
ToolRegistrationErrorClass
ToolRegistrationReasonType alias
ToolSchemaType 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, Bun, or Deno 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 gRPC in Node.js, Bun, or Deno.

export interface NodeTransportCommonOptions extends CredentialOptions

NodeTransportCommonOptions.nodeOptions​

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

nodeOptions?: Omit<SecureClientSessionOptions, "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 Node.js or Bun 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>>;