mcp-use
Version:
Opinionated MCP Framework for TypeScript (@modelcontextprotocol/sdk compatible) - Build MCP Agents, Clients and Servers with support for ChatGPT Apps, Code Mode, OAuth, Notifications, Sampling, Observability and more.
301 lines • 9.49 kB
TypeScript
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
/**
* Typed CallToolResult that constrains the structuredContent property
* to match a specific type T. Used for output schema validation.
* T must be a record type (object) to match the SDK's CallToolResult interface.
*/
export interface TypedCallToolResult<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<CallToolResult, "structuredContent"> {
structuredContent?: T;
}
/**
* Create a text content response for MCP tools and resources
*
* @param content - The text content to return
* @returns CallToolResult with text content
*
* @example
* ```typescript
* // For tools
* server.tool({
* name: 'greet',
* schema: z.object({ name: z.string() }),
* cb: async ({ name }) => text(`Hello, ${name}!`)
* })
*
* // For resources
* server.resource(
* { name: 'greeting', uri: 'app://greeting' },
* async () => text('Hello World!')
* )
* ```
*/
export declare function text(content: string): CallToolResult;
/**
* Create an image content response for MCP tools and resources
*
* @param data - The image data (data URL or base64)
* @param mimeType - MIME type (e.g., 'image/png', defaults to 'image/png')
* @returns CallToolResult with image content
*
* @example
* ```typescript
* // For tools
* server.tool({
* name: 'generate-image',
* cb: async () => image('data:image/png;base64,...', 'image/png')
* })
*
* // For resources
* server.resource(
* { name: 'logo', uri: 'asset://logo' },
* async () => image(base64Data, 'image/png')
* )
* ```
*/
export declare function image(data: string, mimeType?: string): CallToolResult;
/**
* Create an audio content response for MCP tools and resources
*
* Accepts either base64 data or a file path. File paths will be automatically
* detected and read asynchronously, returning a Promise<CallToolResult>.
*
* @param dataOrPath - Audio data as base64 string, or path to audio file
* @param mimeType - MIME type (e.g., 'audio/wav'). If not provided, defaults to 'audio/wav'
* for base64 data, or inferred from file extension for file paths
* @returns CallToolResult for base64 data, or Promise<CallToolResult> for file paths
*
* @example
* ```typescript
* // With base64 data (synchronous)
* server.tool({
* name: 'generate-audio',
* cb: async () => audio(base64AudioData, 'audio/wav')
* })
*
* // With file path (asynchronous)
* server.resource(
* { name: 'notification', uri: 'audio://notification' },
* async () => await audio('./sounds/notification.wav')
* )
* ```
*/
export declare function audio(dataOrPath: string, mimeType?: string): CallToolResult | Promise<CallToolResult>;
/**
* Create a resource content response for MCP tools
*
* Supports two usage patterns:
* 1. Three arguments: resource(uri, mimeType, text)
* 2. Two arguments: resource(uri, content) where content is a CallToolResult from helpers
*
* @param uri - The resource URI
* @param mimeTypeOrContent - MIME type (3-arg pattern) or CallToolResult (2-arg pattern)
* @param text - Optional text content (only for 3-arg pattern)
* @returns CallToolResult with resource content
*
* @example
* ```typescript
* // 3-arg pattern: Explicit mimeType and text
* server.tool({
* name: 'get-config',
* cb: async () => resource('test://embedded', 'text/plain', 'This is text content')
* })
*
* // 2-arg pattern: Using text helper
* server.tool({
* name: 'get-greeting',
* cb: async () => resource('test://embedded', text('Hello'))
* })
*
* // 2-arg pattern: Using object helper
* server.tool({
* name: 'get-data',
* cb: async () => resource('test://data', object({ test: 'data', value: 123 }))
* })
* ```
*/
export declare function resource(uri: string, mimeTypeOrContent: string | CallToolResult | TypedCallToolResult<any>, text?: string): CallToolResult;
/**
* Create an error response for MCP tools
*
* @param message - The error message
* @returns CallToolResult marked as error
*
* @example
* ```typescript
* server.tool({
* name: 'risky-operation',
* cb: async () => {
* if (somethingWrong) {
* return error('Operation failed: invalid input')
* }
* return text('Success!')
* }
* })
* ```
*/
export declare function error(message: string): CallToolResult;
/**
* Create a JSON object response for MCP tools and resources
*
* @param data - The object to return as JSON
* @returns TypedCallToolResult with JSON text content and typed structuredContent
*
* @example
* ```typescript
* // For tools
* server.tool({
* name: 'get-user-info',
* cb: async (_args, _ctx, { auth }) => object({
* userId: auth.user.userId,
* email: auth.user.email
* })
* })
*
* // For resources
* server.resource(
* { name: 'config', uri: 'config://settings' },
* async () => object({ theme: 'dark', version: '1.0' })
* )
* ```
*/
export declare function object<T extends Record<string, any>>(data: T): TypedCallToolResult<T>;
export declare function array<T extends any[]>(data: T): TypedCallToolResult<{
data: T;
}>;
/**
* Create an HTML content response for MCP tools and resources
*
* @param content - The HTML content to return
* @returns CallToolResult with HTML text content and MIME type metadata
*
* @example
* ```typescript
* server.resource(
* { name: 'page', uri: 'ui://dashboard' },
* async () => html('<h1>Dashboard</h1><p>Welcome</p>')
* )
* ```
*/
export declare function html(content: string): CallToolResult;
/**
* Create a Markdown content response for MCP tools and resources
*
* @param content - The Markdown content to return
* @returns CallToolResult with Markdown text content and MIME type metadata
*
* @example
* ```typescript
* server.resource(
* { name: 'readme', uri: 'doc://readme' },
* async () => markdown('# Welcome\n\nGetting started...')
* )
* ```
*/
export declare function markdown(content: string): CallToolResult;
/**
* Create an XML content response for MCP tools and resources
*
* @param content - The XML content to return
* @returns CallToolResult with XML text content and MIME type metadata
*
* @example
* ```typescript
* server.resource(
* { name: 'sitemap', uri: 'data://sitemap' },
* async () => xml('<?xml version="1.0"?><root>...</root>')
* )
* ```
*/
export declare function xml(content: string): CallToolResult;
/**
* Create a CSS content response for MCP tools and resources
*
* @param content - The CSS content to return
* @returns CallToolResult with CSS text content and MIME type metadata
*
* @example
* ```typescript
* server.resource(
* { name: 'styles', uri: 'asset://theme.css' },
* async () => css('body { margin: 0; }')
* )
* ```
*/
export declare function css(content: string): CallToolResult;
/**
* Create a JavaScript content response for MCP tools and resources
*
* @param content - The JavaScript content to return
* @returns CallToolResult with JavaScript text content and MIME type metadata
*
* @example
* ```typescript
* server.resource(
* { name: 'script', uri: 'asset://main.js' },
* async () => javascript('console.log("Hello");')
* )
* ```
*/
export declare function javascript(content: string): CallToolResult;
/**
* Create a binary content response for MCP tools and resources
*
* @param base64Data - The base64-encoded binary data
* @param mimeType - The MIME type of the binary content
* @returns CallToolResult with binary content and MIME type metadata
*
* @example
* ```typescript
* server.resource(
* { name: 'document', uri: 'file://document.pdf' },
* async () => binary(base64PdfData, 'application/pdf')
* )
* ```
*/
export declare function binary(base64Data: string, mimeType: string): CallToolResult;
/**
* Configuration for widget response utility (runtime data only)
*/
export interface WidgetResponseConfig {
/** Widget-only data passed to useWidget().props (hidden from model) */
props?: Record<string, any>;
/** @deprecated Use `props` instead - Legacy alias for props */
data?: Record<string, any>;
/** Response helper result that the model sees (text(), json(), etc.) */
output?: CallToolResult | TypedCallToolResult<any>;
/** Optional override for the text message */
message?: string;
}
/**
* Create a widget response for MCP tools
*
* Returns runtime data for a widget. The widget configuration (name, invoking, invoked, etc.)
* should be set on the tool's `widget` property at registration time.
*
* @param config - Runtime data for the widget
* @returns CallToolResult with widget props in metadata and tool output in content
*
* @example
* ```typescript
* server.tool({
* name: 'get-weather',
* schema: z.object({ city: z.string() }),
* widget: {
* name: 'weather-display',
* invoking: 'Fetching weather...',
* invoked: 'Weather loaded'
* }
* }, async ({ city }) => {
* const weatherData = await fetchWeather(city);
* return widget({
* // Widget-only data (model doesn't see)
* props: { temperature: weatherData.temp, conditions: weatherData.conditions },
* // Model sees this summary
* output: text(`Weather in ${city}: ${weatherData.temp}°C`)
* });
* })
* ```
*/
export declare function widget(config: WidgetResponseConfig): CallToolResult;
export declare function mix(...results: CallToolResult[]): CallToolResult;
//# sourceMappingURL=response-helpers.d.ts.map