skybridge 0.0.0-dev.8cced89 → 0.0.0-dev.8ceb3ae

package/dist/server/server.d.ts

@@ -1,16 +1,34 @@
-import { type ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
-import { McpServer as McpServerBase } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { AnySchema, SchemaOutput, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
-import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
-import type { ContentBlock, Implementation, ServerNotification, ServerRequest, ServerResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import type { ErrorRequestHandler, RequestHandler } from "express";
+import type { McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
+import { type CacheHint, type ContentBlock, type Icon, type Implementation, McpServer as McpServerBase, type PromptCallback, type ReadResourceCallback, type ReadResourceTemplateCallback, type RegisteredPrompt, type RegisteredResource, type RegisteredResourceTemplate, type RequestMeta, type ResourceMetadata, type ResourceTemplate, type Server as SdkServer, type ServerOptions, type ServerResult, type StandardSchemaV1, type StandardSchemaWithJSON, type ToolAnnotations } from "@modelcontextprotocol/server";
+import express, { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
+import type { InferSchemaOutput, RawInputShape } from "../standard-schema.js";
+import type { OAuthConfig } from "./auth/index.js";
+import type { ExtraClaims } from "./auth.js";
 import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
+import { type SkillsManifest } from "./skills.js";
+/**
+ * Type marker for a registered tool — carries its input, output, and response
+ * metadata shapes so views can infer types from `typeof server`.
+ *
+ * You normally never construct this by hand; it is produced by `registerTool`
+ * and consumed by helpers like {@link InferTools} and {@link generateHelpers}.
+ */
 export type ToolDef<TInput = unknown, TOutput = unknown, TResponseMetadata = unknown> = {
     input: TInput;
     output: TOutput;
     responseMetadata: TResponseMetadata;
 };
-export type ViewHostType = "apps-sdk" | "mcp-app";
+/**
+ * The runtime a served view page declares on `window.skybridge`. Every view
+ * emits a single ext-apps resource, so this is always `"mcp-app"`; the Apps
+ * SDK runtime is detected at load time via `window.openai` instead.
+ */
+export type ViewHostType = "mcp-app";
+/**
+ * Content Security Policy origins attached to a view's resource. Each list is
+ * passed through to the host's CSP for the view iframe; omit a field to inherit
+ * the host's default for that directive.
+ */
 export interface ViewCsp {
     /** Origins for static assets (images, fonts, scripts, styles). */
     resourceDomains?: string[];
@@ -23,24 +41,109 @@ export interface ViewCsp {
     /** Origins allowed in `<base href>` tags (mcp-apps only). */
     baseUriDomains?: string[];
 }
+/**
+ * Registry of view component names. The Skybridge Vite plugin augments this
+ * interface in the generated `.skybridge/views.d.ts` with one key per view
+ * file, which narrows {@link ViewName} from `string` to the concrete union.
+ */
 export interface ViewNameRegistry {
 }
-export type ViewName = keyof ViewNameRegistry & string;
+/**
+ * Resolve view component names from a registry: the union of its keys, or
+ * `string` when the registry is empty. The empty case happens before
+ * `.skybridge/views.d.ts` is generated; falling back to `string` keeps valid
+ * view names from erroring on a fresh checkout, and narrowing kicks in once
+ * the generated file augments the registry.
+ */
+export type ViewNameFor<Registry> = [keyof Registry & string] extends [never] ? string : keyof Registry & string;
+/** Union of valid view component names. Narrowed by {@link ViewNameRegistry}. */
+export type ViewName = ViewNameFor<ViewNameRegistry>;
+/**
+ * Pass under `view` in a tool's `registerTool` config to render the tool's
+ * result through a Skybridge view instead of a plain text response.
+ */
 export interface ViewConfig {
+    /** Filename of the view module (without extension) — matches a file in your `viewsDir`. */
     component: ViewName;
+    /** Human-readable label the host may show alongside the view. */
     description?: string;
-    hosts?: ViewHostType[];
+    /** Request a visible border around the view (forwarded as `ui.prefersBorder`). */
     prefersBorder?: boolean;
+    /** Override the iframe's served domain (advanced; forwarded as `ui.domain`). */
     domain?: string;
+    /** Per-view CSP overrides — see {@link ViewCsp}. */
     csp?: ViewCsp;
+    /** Free-form metadata forwarded on the view resource's `_meta`. */
     _meta?: Record<string, unknown>;
 }
+export type SecurityScheme = {
+    type: "noauth";
+} | {
+    type: "oauth2";
+    scopes?: string[];
+};
+/**
+ * Declarative per-tool auth. Enforced when the server has an `oauth` provider:
+ * anonymous or under-scoped calls are rejected before the handler runs. Omit
+ * `auth` entirely for the secure default (sign-in required, no specific scope).
+ */
+export type ToolAuth = {
+    /**
+     * When `true`, the tool is callable signed out; the token is still used when
+     * one is present. Omit (or `false`) to require sign-in.
+     */
+    allowsAnonymous?: boolean;
+    /** OAuth scopes the caller's token must carry to invoke the tool. */
+    scopes?: string[];
+};
+/**
+ * Options forwarded to the built-in `express.json()` body parser. Derived
+ * from Express's own types so the public API doesn't depend on `body-parser`.
+ */
+export type JsonOptions = NonNullable<Parameters<typeof express.json>[0]>;
+/**
+ * Skybridge-specific server options, passed as the third `McpServer` constructor
+ * argument.
+ *
+ * @typeParam TAuthExtra - Claims the `oauth` verifier populates. Inferred from
+ * the config a provider returns, and carried on to tool handlers.
+ */
+export interface SkybridgeServerOptions<TAuthExtra extends ExtraClaims = ExtraClaims> {
+    /** Options for the built-in `express.json()` middleware, e.g. `{ limit: "10mb" }`. */
+    json?: JsonOptions;
+    /** Resource-server OAuth config. When set, mounts well-known metadata and bearer auth on `/mcp`. */
+    oauth?: OAuthConfig<TAuthExtra>;
+    /**
+     * @experimental Serve Agent Skills from `src/skills` over MCP (SEP-2640).
+     * API may change.
+     */
+    skills?: boolean;
+}
+/**
+ * Well-known keys recognized by host runtimes when set on a tool's `_meta`.
+ * Use {@link ToolMeta} to also pass arbitrary custom metadata alongside these.
+ *
+ * @see https://developers.openai.com/apps-sdk/reference#tool-descriptor-parameters
+ */
 export interface KnownToolMeta {
+    /** Apps SDK: allow the rendered view to call this tool from inside its iframe. */
     "openai/widgetAccessible"?: boolean;
+    /** Apps SDK: status text shown while the tool is running (e.g. `"Searching trips"`). */
     "openai/toolInvocation/invoking"?: string;
+    /** Apps SDK: status text shown once the tool returns (e.g. `"Found 3 trips"`). */
     "openai/toolInvocation/invoked"?: string;
+    /** Apps SDK: input parameters that hold file references — the host attaches uploaded files to them. */
+    "openai/fileParams"?: string[];
+    /** MCP Apps: control whether the tool is exposed to the model, the app, or both. */
+    ui?: Pick<McpUiToolMeta, "visibility">;
 }
+/** {@link KnownToolMeta} merged with arbitrary string-keyed metadata for custom flags. */
 export type ToolMeta = KnownToolMeta & Record<string, unknown>;
+/**
+ * Convenient return type for tool handlers — a plain string, a single
+ * {@link ContentBlock}, or an array. Skybridge normalizes it to the MCP
+ * `content: ContentBlock[]` shape before responding.
+ */
 export type HandlerContent = string | ContentBlock | ContentBlock[];
 /**
  * Type-level marker interface for cross-package type inference.
@@ -58,10 +161,10 @@ export interface McpServerTypes<TTools extends Record<string, ToolDef>> {
 type Simplify<T> = {
     [K in keyof T]: T[K];
 };
-type ShapeOutput<Shape extends ZodRawShapeCompat> = Simplify<{
-    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? never : K]: SchemaOutput<Shape[K]>;
+type ShapeOutput<Shape extends RawInputShape> = Simplify<{
+    [K in keyof Shape as undefined extends InferSchemaOutput<Shape[K]> ? never : K]: InferSchemaOutput<Shape[K]>;
 } & {
-    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? K : never]?: SchemaOutput<Shape[K]>;
+    [K in keyof Shape as undefined extends InferSchemaOutput<Shape[K]> ? K : never]?: InferSchemaOutput<Shape[K]>;
 }>;
 type ExtractStructuredContent<T> = T extends {
     structuredContent: infer SC;
@@ -73,50 +176,194 @@ type ExtractMeta<T> = [Extract<T, {
 }> extends {
     _meta: infer M;
 } ? Simplify<M> : unknown;
-type AddTool<TTools, TName extends string, TInput extends ZodRawShapeCompat, TOutput, TResponseMetadata = unknown> = McpServer<TTools & {
+type AddTool<TTools, TName extends string, TInput extends RawInputShape, TOutput, TResponseMetadata = unknown, TAuthExtra extends ExtraClaims = ExtraClaims> = McpServer<TTools & {
     [K in TName]: ToolDef<ShapeOutput<TInput>, TOutput, TResponseMetadata>;
-}>;
-interface ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> {
+}, TAuthExtra>;
+interface ToolConfigBase<TInput extends RawInputShape | StandardSchemaV1> {
     name: string;
     title?: string;
     description?: string;
     inputSchema?: TInput;
-    outputSchema?: ZodRawShapeCompat | AnySchema;
+    outputSchema?: RawInputShape | StandardSchemaV1;
     annotations?: ToolAnnotations;
     view?: ViewConfig;
     _meta?: ToolMeta;
 }
-type ToolHandler<TInput extends ZodRawShapeCompat, TReturn extends {
+/**
+ * The auth face of a tool config: either the high-level `auth` shorthand or the
+ * low-level `securitySchemes` escape hatch, never both.
+ */
+type ToolAuthConfig = {
+    auth?: ToolAuth;
+    securitySchemes?: never;
+} | {
+    auth?: never;
+    /**
+     * Declares which auth schemes this tool supports (e.g. `noauth`, `oauth2`).
+     * Lets clients label tools that require sign-in before calling, and pass
+     * the right scopes through the OAuth flow. Listing both `noauth` and
+     * `oauth2` signals that the tool works for anonymous callers and gives
+     * enhanced behavior to authenticated ones.
+     */
+    securitySchemes?: SecurityScheme[];
+};
+type ToolConfig<TInput extends RawInputShape | StandardSchemaV1> = ToolConfigBase<TInput> & ToolAuthConfig;
+/**
+ * Optional client-supplied hints attached to `params._meta` on every tool call
+ * by the Apps SDK host. Hints only: never use for authorization, and tolerate
+ * absence.
+ * @see https://developers.openai.com/apps-sdk/reference#_meta-fields-the-client-provides
+ */
+export interface ClientHintsMeta {
+    /** Requested locale (BCP-47, e.g. `"en-US"`). */
+    "openai/locale"?: string;
+    /** Browser user-agent */
+    "openai/userAgent"?: string;
+    /** Coarse user location. May be partially populated. */
+    "openai/userLocation"?: {
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+        longitude?: number;
+        latitude?: number;
+    };
+    /** Anonymized user id. */
+    "openai/subject"?: string;
+    /** Anonymized conversation id, stable within a ChatGPT session. */
+    "openai/session"?: string;
+    /** Anonymized organization id, when the user account is part of an organization. */
+    "openai/organization"?: string;
+    /** Stable id for the currently mounted widget instance. */
+    "openai/widgetSessionId"?: string;
+}
+type ToolHandlerExtra<TAuthExtra extends ExtraClaims = ExtraClaims> = Omit<McpExtra<TAuthExtra>, "mcpReq"> & {
+    mcpReq: Omit<McpExtra<TAuthExtra>["mcpReq"], "_meta"> & {
+        _meta?: RequestMeta & ClientHintsMeta;
+    };
+};
+type ToolHandler<TInput extends RawInputShape, TReturn extends {
     content?: HandlerContent;
 } = {
     content?: HandlerContent;
-}> = (args: ShapeOutput<TInput>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => TReturn | Promise<TReturn>;
+}, TAuthExtra extends ExtraClaims = ExtraClaims> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra<TAuthExtra>) => TReturn | Promise<TReturn>;
+/**
+ * Coerce a tool handler's return value into an MCP `content` array. Strings
+ * become a single `TextContent`; a single block is wrapped in an array;
+ * `undefined` produces `[]`. Mostly used internally — exported so consumers
+ * who build content lazily can apply the same normalization.
+ */
 export declare function normalizeContent(content: HandlerContent | undefined): ContentBlock[];
-interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "connect"> {
+interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "registerResource" | "registerPrompt" | "connect"> {
 }
 declare const McpServerBaseOmitted: new (...args: ConstructorParameters<typeof McpServerBase>) => McpServerBaseOmitted;
-export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBaseOmitted {
+/**
+ * Prime the build-time Vite manifest before user code constructs its
+ * `McpServer`. Called from the generated `dist/__entry.js`; not part of the
+ * user-facing API.
+ *
+ * @internal
+ */
+export declare function __setBuildManifest(manifest: Record<string, {
+    file: string;
+}>): void;
+export declare function __setSkillsManifest(manifest: SkillsManifest): void;
+export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>, TAuthExtra extends ExtraClaims = ExtraClaims> extends McpServerBaseOmitted {
     readonly $types: McpServerTypes<TTools>;
-    private express?;
-    private customMiddleware;
+    /**
+     * The underlying Express app. Use this to extend the HTTP server with
+     * custom routes, middleware, or settings — e.g.
+     * `server.express.get("/health", ...)`.
+     *
+     * `express.json()` is pre-applied — tune it via the constructor's third
+     * argument, e.g. `new McpServer(info, {}, { json: { limit: "10mb" } })`.
+     * Register your handlers before `run()`;
+     * after `run()`, dev-mode middleware, the `/mcp` route, and the default
+     * error handler are appended in that order.
+     *
+     * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work
+     * locally and on self-hosted deployments.
+     */
+    readonly express: Express;
     private customErrorMiddleware;
     private mcpMiddlewareEntries;
     private mcpMiddlewareApplied;
+    private middlewareEntriesCache;
+    private readonly registrations;
     private claimedViews;
+    private viewMetaBuilders;
+    /**
+     * Maps a view resource's query-less path to its canonical registered URI
+     * (the one carrying the `?v=` cache key). Lets `resources/read` resolve the
+     * underlying view no matter which version param the consumer sends, since
+     * the param is only a cache key, not part of the resource's identity.
+     */
+    private viewUriByPath;
+    private viteManifest;
     private readonly serverInfo;
     private readonly serverOptions?;
-    constructor(serverInfo: Implementation, options?: ServerOptions);
+    private oauthEnabled;
+    private resolveResourceMetadataUrl?;
+    private securitySchemesByTool;
+    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions<TAuthExtra>);
+    /**
+     * Register a resource, recorded so every per-request instance carries it.
+     * Signature owned by Skybridge (not inherited) so a typed wrapper can land
+     * in a minor without a type-level break.
+     */
+    registerResource(name: string, uri: string, config: ResourceMetadata & {
+        cacheHint?: CacheHint;
+    }, readCallback: ReadResourceCallback): RegisteredResource;
+    registerResource(name: string, template: ResourceTemplate, config: ResourceMetadata & {
+        cacheHint?: CacheHint;
+    }, readCallback: ReadResourceTemplateCallback): RegisteredResourceTemplate;
+    /**
+     * Register a prompt, recorded so every per-request instance carries it.
+     * Signature owned by Skybridge (not inherited) so a typed wrapper can land
+     * in a minor without a type-level break.
+     */
+    registerPrompt<Args extends StandardSchemaWithJSON>(name: string, config: {
+        title?: string;
+        description?: string;
+        argsSchema?: Args;
+        icons?: Icon[];
+        _meta?: Record<string, unknown>;
+    }, cb: PromptCallback<Args>): RegisteredPrompt;
+    private recordInherited;
+    private skillRegistrar;
+    private setupSkills;
+    /**
+     * Register Express middleware on the underlying app. Mirrors `app.use` —
+     * pass handlers directly or a path-prefixed handler list. Register before
+     * {@link McpServer.run}; ordering matches Express.
+     *
+     * Note: Alpic Cloud only routes traffic to `/mcp`. Custom paths work
+     * locally and on self-hosted deployments.
+     */
     use(...handlers: RequestHandler[]): this;
     use(path: string, ...handlers: RequestHandler[]): this;
+    /**
+     * Register Express error-handling middleware to run after the built-in
+     * `/mcp` route (or your custom route). Use this to log or transform errors
+     * thrown by tool handlers before the default error handler responds.
+     *
+     * @example
+     * ```ts
+     * server.useOnError((err, _req, _res, next) => {
+     *   logger.error(err);
+     *   next(err);
+     * });
+     * ```
+     */
     useOnError(...handlers: ErrorRequestHandler[]): this;
     useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;
     /** Register MCP protocol-level middleware (catch-all). */
-    mcpMiddleware(handler: McpMiddlewareFn): this;
+    mcpMiddleware(handler: McpMiddlewareFn<TAuthExtra>): this;
     /** Register MCP protocol-level middleware for all requests (`extra` is `McpExtra`). */
     mcpMiddleware(filter: "request", handler: (request: {
         method: string;
         params: Record<string, unknown>;
-    }, extra: McpExtra, next: () => Promise<ServerResult>) => Promise<unknown> | unknown): this;
+    }, extra: McpExtra<TAuthExtra>, next: () => Promise<ServerResult>) => Promise<unknown> | unknown): this;
     /** Register MCP protocol-level middleware for all notifications (`extra` is `undefined`). */
     mcpMiddleware(filter: "notification", handler: (request: {
         method: string;
@@ -126,7 +373,7 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      * Register MCP protocol-level middleware for an exact method.
      * Narrows `params`, `extra`, and `next()` result based on the method string.
      */
-    mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M>): this;
+    mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M, TAuthExtra>): this;
     /**
      * Register MCP protocol-level middleware for a wildcard pattern (e.g. `"tools/*"`).
      * `next()` returns the union of result types for matching methods.
@@ -134,40 +381,114 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     mcpMiddleware<W extends McpWildcard>(filter: W, handler: (request: {
         method: string;
         params: Record<string, unknown>;
-    }, extra: McpExtraFor<W>, next: () => Promise<McpResultFor<W>>) => Promise<unknown> | unknown): this;
+    }, extra: McpExtraFor<W, TAuthExtra>, next: () => Promise<McpResultFor<W>>) => Promise<unknown> | unknown): this;
     /**
      * Register MCP protocol-level middleware with a method filter.
      * Filter can be an exact method (`"tools/call"`), wildcard (`"tools/*"`),
      * category (`"request"` | `"notification"`), or an array of those.
      */
-    mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn): this;
+    mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn<TAuthExtra>): this;
     private applyMcpMiddleware;
+    private instrumentHandlers;
+    /**
+     * Connect to an MCP transport (override of the SDK's `connect`). Use this
+     * when you're embedding Skybridge in a host that already manages its own
+     * transport (e.g. stdio for desktop apps); for HTTP, prefer {@link McpServer.run}
+     * which sets the transport up for you. Locks in any middleware registered
+     * via {@link McpServer.mcpMiddleware} — further calls to that method will
+     * throw afterwards.
+     */
     connect(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
     /**
-     * Per-request stateless connect. The SDK's `Protocol` only allows one
-     * transport per instance, so we can't reuse this `McpServer` across
-     * concurrent requests. The SDK's idiomatic fix is a `() => McpServer`
-     * factory, but that would break Skybridge's singleton API — so instead
-     * we build a fresh underlying `Server` per request and share the main
-     * server's handler maps by reference. The cast is unavoidable: there's
-     * no public API to inject handler maps. `getHandlerMaps` validates the
-     * read side and fails fast on SDK field renames.
-     */
-    connectStatelessTransport(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
-    run(): Promise<void>;
+     * Build a fresh server for one stateless HTTP request, as
+     * `createMcpHandler`'s factory contract requires: every registration is
+     * replayed onto the new instance so the SDK's handler closures belong to
+     * the instance whose protocol era it stamps. Sharing the singleton's
+     * handler maps instead would bind them to an instance that is never
+     * marked, pinning every request to the 2025 codec and letting concurrent
+     * callers overwrite each other's negotiated version.
+     */
+    createStatelessServerInstance(): SdkServer;
+    /**
+     * Apply an SDK registration to the singleton and remember it, so each
+     * per-request instance can be built with the same surface.
+     */
+    private record;
+    /** Records a raw request handler (used for methods the SDK has no sugar for). */
+    private recordRequestHandler;
+    /**
+     * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
+     * mounts the `/mcp` route, applies any custom Express middleware registered
+     * via {@link McpServer.use} / {@link McpServer.useOnError}, and locks in
+     * any MCP middleware registered via {@link McpServer.mcpMiddleware}.
+     *
+     * On Cloudflare Workers / workerd, returns an object exposing `fetch` so
+     * the runtime can bridge incoming requests to the Node HTTP server. On
+     * Vercel (`VERCEL === "1"`), returns the Express app directly so the
+     * serverless function entry can call it as a `(req, res)` handler. On
+     * Node, returns `undefined` once listening. When the process was spawned
+     * with an IPC channel, the bound port is reported to the parent as
+     * `{ type: "skybridge:listening", port }`, the readiness signal test runners
+     * wait on instead of polling.
+     */
+    run(): Promise<{
+        fetch: (...args: unknown[]) => unknown;
+    } | Express | undefined>;
     private enforceOneToolPerView;
+    private resolveViewRequestContext;
     private registerViewResources;
     private registerViewResource;
-    private wrapHandler;
+    private serveLegacyAppsSdkUrl;
+    private decorateToolHandler;
     private computeViewVersionParam;
     private lookupViewFile;
     private lookupDistFile;
+    /**
+     * Inject the Vite manifest as a value rather than letting `readManifest()`
+     * load it from disk. Required for runtimes without a usable filesystem
+     * (Cloudflare Workers, etc.) — the user's `skybridge build` emits the
+     * manifest as a JS module which the entry imports and passes here.
+     */
+    setViteManifest(manifest: Record<string, {
+        file: string;
+    }>): this;
     private readManifest;
-    registerTool<TName extends string, InputArgs extends ZodRawShapeCompat, TReturn extends {
+    /**
+     * Register a tool. Pass a `config` describing the tool (name, schemas,
+     * optional {@link ViewConfig}, optional {@link ToolMeta}) and a handler that
+     * returns the tool's result.
+     *
+     * Chain calls to build up a server: each call returns a new `McpServer`
+     * type that captures the tool's input/output/`_meta` shape so the
+     * resulting `typeof server` can drive {@link generateHelpers}.
+     *
+     * The handler's return shape determines the output types: the
+     * `structuredContent` field becomes the tool's typed output, and `_meta`
+     * becomes its `responseMetadata`. The `content` field is normalized through
+     * {@link normalizeContent}.
+     *
+     * @example
+     * ```ts
+     * server.registerTool({
+     *   name: "search",
+     *   inputSchema: { query: z.string() },
+     *   outputSchema: { results: z.array(z.string()) },
+     *   view: { component: "search" },
+     * }, async ({ query }) => ({
+     *   content: `Found results for ${query}`,
+     *   structuredContent: { results: [...] },
+     * }));
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-tool
+     */
+    registerTool<TName extends string, InputArgs extends RawInputShape, TReturn extends {
         content?: HandlerContent;
     }>(config: ToolConfig<InputArgs> & {
         name: TName;
-    }, cb: ToolHandler<InputArgs, TReturn>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>>;
-    registerTool<InputArgs extends ZodRawShapeCompat>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs>): this;
+    }, cb: ToolHandler<InputArgs, TReturn, TAuthExtra>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>, TAuthExtra>;
+    registerTool<InputArgs extends RawInputShape>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, {
+        content?: HandlerContent;
+    }, TAuthExtra>): this;
 }
 export {};