MCP Server Framework - v1.0.0
    Preparing search index...

    Interface AppDefinition<TInput>

    Definition for an MCP App — a tool linked to a UI resource.

    MCP Apps combine a tool with a resource to create interactive experiences. The tool's _meta.ui.resourceUri links to the resource, and MCP clients use this to render the UI.

    defineApp() internally creates both a defineTool() and a defineResource(), auto-registering them in the global registries.

    import { defineApp, text, z } from 'mcp-server-framework';

    const calculator = defineApp({
      name: 'calculator',
      description: 'An interactive calculator app',
      resource: {
        uri: 'ui://calculator',
        mimeType: 'text/html',
        read: async () => '<html>...calculator UI...</html>',
      },
      input: z.object({ expression: z.string() }),
      handler: async ({ expression }) => text(String(eval(expression))),
    });
    interface AppDefinition<TInput extends ZodTypeAny = ZodTypeAny> {
        _meta?: Record<string, unknown>;
        annotations?: ToolAnnotations;
        description: string;
        handler: (
            args: TypeOf<TInput>,
            context: ToolContext,
        ) => Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                content: (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >;
        input: TInput;
        name: string;
        requiredScopes?: readonly string[];
        resource: AppResourceDefinition;
    }

    Type Parameters

    Index

    Properties

    _meta? annotations? description handler input name requiredScopes? resource

    Properties

    Optional Readonly_meta

    _meta?: Record<string, unknown>

    Additional _meta merged with the auto-generated ui.resourceUri. The ui.resourceUri key is always set automatically from the resource URI.

    annotations?: ToolAnnotations

    Optional tool annotations

    description: string

    Human-readable description

    handler: (
        args: TypeOf<TInput>,
        context: ToolContext,
    ) => Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            content: (
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    description?: string;
                    icons?: {
                        mimeType?: string;
                        sizes?: (...)[];
                        src: string;
                        theme?: "light" | "dark";
                    }[];
                    mimeType?: string;
                    name: string;
                    title?: string;
                    type: "resource_link";
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    resource: | {
                        _meta?: { [key: string]: unknown };
                        mimeType?: string;
                        text: string;
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        blob: string;
                        mimeType?: string;
                        uri: string;
                    };
                    type: "resource";
                }
            )[];
            isError?: boolean;
            structuredContent?: { [key: string]: unknown };
            [key: string]: unknown;
        },
    >

    Tool handler function.

    Type Declaration

      • (
            args: TypeOf<TInput>,
            context: ToolContext,
        ): Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                content: (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >

      • Parameters

        • args: TypeOf<TInput>

          Validated input (typed from Zod schema)

        • context: ToolContext

          Execution context with progress reporter, abort signal

        Returns Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                content: (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >

        MCP CallToolResult (use response helpers: text(), json(), error())

    input: TInput

    Zod schema for tool input validation

    name: string

    Unique app/tool name

    requiredScopes?: readonly string[]

    Scopes required to execute this app's tool (RBAC).

    Passed through to the internal defineTool() call. All listed scopes must be present (AND logic).

    resource: AppResourceDefinition

    Resource definition for the app's UI

    Settings

    Member Visibility

    On This Page

    Properties