avancement planning
This commit is contained in:
+89
-24
@@ -1,9 +1,11 @@
|
||||
import { Server, ServerOptions } from "./index.js";
|
||||
import { z, ZodRawShape, ZodObject, AnyZodObject, ZodTypeAny, ZodType, ZodTypeDef, ZodOptional } from "zod";
|
||||
import { Implementation, CallToolResult, Resource, ListResourcesResult, GetPromptResult, ReadResourceResult, ServerRequest, ServerNotification, ToolAnnotations } from "../types.js";
|
||||
import { UriTemplate, Variables } from "../shared/uriTemplate.js";
|
||||
import { RequestHandlerExtra } from "../shared/protocol.js";
|
||||
import { Transport } from "../shared/transport.js";
|
||||
import { Server, ServerOptions } from './index.js';
|
||||
import { AnySchema, AnyObjectSchema, ZodRawShapeCompat, SchemaOutput, ShapeOutput } from './zod-compat.js';
|
||||
import { Implementation, CallToolResult, Resource, ListResourcesResult, GetPromptResult, ReadResourceResult, ServerRequest, ServerNotification, ToolAnnotations, LoggingMessageNotification, Result, ToolExecution } from '../types.js';
|
||||
import { UriTemplate, Variables } from '../shared/uriTemplate.js';
|
||||
import { RequestHandlerExtra } from '../shared/protocol.js';
|
||||
import { Transport } from '../shared/transport.js';
|
||||
import { ExperimentalMcpServerTasks } from '../experimental/tasks/mcp-server.js';
|
||||
import type { ToolTaskHandler } from '../experimental/tasks/interfaces.js';
|
||||
/**
|
||||
* High-level MCP server that provides a simpler API for working with resources, tools, and prompts.
|
||||
* For advanced usage (like sending notifications or setting custom request handlers), use the underlying
|
||||
@@ -18,7 +20,18 @@ export declare class McpServer {
|
||||
private _registeredResourceTemplates;
|
||||
private _registeredTools;
|
||||
private _registeredPrompts;
|
||||
private _experimental?;
|
||||
constructor(serverInfo: Implementation, options?: ServerOptions);
|
||||
/**
|
||||
* Access experimental features.
|
||||
*
|
||||
* WARNING: These APIs are experimental and may change without notice.
|
||||
*
|
||||
* @experimental
|
||||
*/
|
||||
get experimental(): {
|
||||
tasks: ExperimentalMcpServerTasks;
|
||||
};
|
||||
/**
|
||||
* Attaches to the given transport, starts it, and starts listening for messages.
|
||||
*
|
||||
@@ -31,6 +44,29 @@ export declare class McpServer {
|
||||
close(): Promise<void>;
|
||||
private _toolHandlersInitialized;
|
||||
private setToolRequestHandlers;
|
||||
/**
|
||||
* Creates a tool error result.
|
||||
*
|
||||
* @param errorMessage - The error message.
|
||||
* @returns The tool error result.
|
||||
*/
|
||||
private createToolError;
|
||||
/**
|
||||
* Validates tool input arguments against the tool's input schema.
|
||||
*/
|
||||
private validateToolInput;
|
||||
/**
|
||||
* Validates tool output against the tool's output schema.
|
||||
*/
|
||||
private validateToolOutput;
|
||||
/**
|
||||
* Executes a tool handler (either regular or task-based).
|
||||
*/
|
||||
private executeToolHandler;
|
||||
/**
|
||||
* Handles automatic task polling for tools with taskSupport 'optional'.
|
||||
*/
|
||||
private handleAutomaticTaskPolling;
|
||||
private _completionHandlerInitialized;
|
||||
private setCompletionRequestHandler;
|
||||
private handlePromptCompletion;
|
||||
@@ -41,18 +77,22 @@ export declare class McpServer {
|
||||
private setPromptRequestHandlers;
|
||||
/**
|
||||
* Registers a resource `name` at a fixed URI, which will use the given callback to respond to read requests.
|
||||
* @deprecated Use `registerResource` instead.
|
||||
*/
|
||||
resource(name: string, uri: string, readCallback: ReadResourceCallback): RegisteredResource;
|
||||
/**
|
||||
* Registers a resource `name` at a fixed URI with metadata, which will use the given callback to respond to read requests.
|
||||
* @deprecated Use `registerResource` instead.
|
||||
*/
|
||||
resource(name: string, uri: string, metadata: ResourceMetadata, readCallback: ReadResourceCallback): RegisteredResource;
|
||||
/**
|
||||
* Registers a resource `name` with a template pattern, which will use the given callback to respond to read requests.
|
||||
* @deprecated Use `registerResource` instead.
|
||||
*/
|
||||
resource(name: string, template: ResourceTemplate, readCallback: ReadResourceTemplateCallback): RegisteredResourceTemplate;
|
||||
/**
|
||||
* Registers a resource `name` with a template pattern and metadata, which will use the given callback to respond to read requests.
|
||||
* @deprecated Use `registerResource` instead.
|
||||
*/
|
||||
resource(name: string, template: ResourceTemplate, metadata: ResourceMetadata, readCallback: ReadResourceTemplateCallback): RegisteredResourceTemplate;
|
||||
/**
|
||||
@@ -67,10 +107,12 @@ export declare class McpServer {
|
||||
private _createRegisteredTool;
|
||||
/**
|
||||
* Registers a zero-argument tool `name`, which will run the given function when the client calls it.
|
||||
* @deprecated Use `registerTool` instead.
|
||||
*/
|
||||
tool(name: string, cb: ToolCallback): RegisteredTool;
|
||||
/**
|
||||
* Registers a zero-argument tool `name` (with a description) which will run the given function when the client calls it.
|
||||
* @deprecated Use `registerTool` instead.
|
||||
*/
|
||||
tool(name: string, description: string, cb: ToolCallback): RegisteredTool;
|
||||
/**
|
||||
@@ -78,50 +120,59 @@ export declare class McpServer {
|
||||
* This unified overload handles both `tool(name, paramsSchema, cb)` and `tool(name, annotations, cb)` cases.
|
||||
*
|
||||
* Note: We use a union type for the second parameter because TypeScript cannot reliably disambiguate
|
||||
* between ToolAnnotations and ZodRawShape during overload resolution, as both are plain object types.
|
||||
* between ToolAnnotations and ZodRawShapeCompat during overload resolution, as both are plain object types.
|
||||
* @deprecated Use `registerTool` instead.
|
||||
*/
|
||||
tool<Args extends ZodRawShape>(name: string, paramsSchemaOrAnnotations: Args | ToolAnnotations, cb: ToolCallback<Args>): RegisteredTool;
|
||||
tool<Args extends ZodRawShapeCompat>(name: string, paramsSchemaOrAnnotations: Args | ToolAnnotations, cb: ToolCallback<Args>): RegisteredTool;
|
||||
/**
|
||||
* Registers a tool `name` (with a description) taking either parameter schema or annotations.
|
||||
* This unified overload handles both `tool(name, description, paramsSchema, cb)` and
|
||||
* `tool(name, description, annotations, cb)` cases.
|
||||
*
|
||||
* Note: We use a union type for the third parameter because TypeScript cannot reliably disambiguate
|
||||
* between ToolAnnotations and ZodRawShape during overload resolution, as both are plain object types.
|
||||
* between ToolAnnotations and ZodRawShapeCompat during overload resolution, as both are plain object types.
|
||||
* @deprecated Use `registerTool` instead.
|
||||
*/
|
||||
tool<Args extends ZodRawShape>(name: string, description: string, paramsSchemaOrAnnotations: Args | ToolAnnotations, cb: ToolCallback<Args>): RegisteredTool;
|
||||
tool<Args extends ZodRawShapeCompat>(name: string, description: string, paramsSchemaOrAnnotations: Args | ToolAnnotations, cb: ToolCallback<Args>): RegisteredTool;
|
||||
/**
|
||||
* Registers a tool with both parameter schema and annotations.
|
||||
* @deprecated Use `registerTool` instead.
|
||||
*/
|
||||
tool<Args extends ZodRawShape>(name: string, paramsSchema: Args, annotations: ToolAnnotations, cb: ToolCallback<Args>): RegisteredTool;
|
||||
tool<Args extends ZodRawShapeCompat>(name: string, paramsSchema: Args, annotations: ToolAnnotations, cb: ToolCallback<Args>): RegisteredTool;
|
||||
/**
|
||||
* Registers a tool with description, parameter schema, and annotations.
|
||||
* @deprecated Use `registerTool` instead.
|
||||
*/
|
||||
tool<Args extends ZodRawShape>(name: string, description: string, paramsSchema: Args, annotations: ToolAnnotations, cb: ToolCallback<Args>): RegisteredTool;
|
||||
tool<Args extends ZodRawShapeCompat>(name: string, description: string, paramsSchema: Args, annotations: ToolAnnotations, cb: ToolCallback<Args>): RegisteredTool;
|
||||
/**
|
||||
* Registers a tool with a config object and callback.
|
||||
*/
|
||||
registerTool<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape>(name: string, config: {
|
||||
registerTool<OutputArgs extends ZodRawShapeCompat | AnySchema, InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined>(name: string, config: {
|
||||
title?: string;
|
||||
description?: string;
|
||||
inputSchema?: InputArgs;
|
||||
outputSchema?: OutputArgs;
|
||||
annotations?: ToolAnnotations;
|
||||
_meta?: Record<string, unknown>;
|
||||
}, cb: ToolCallback<InputArgs>): RegisteredTool;
|
||||
/**
|
||||
* Registers a zero-argument prompt `name`, which will run the given function when the client calls it.
|
||||
* @deprecated Use `registerPrompt` instead.
|
||||
*/
|
||||
prompt(name: string, cb: PromptCallback): RegisteredPrompt;
|
||||
/**
|
||||
* Registers a zero-argument prompt `name` (with a description) which will run the given function when the client calls it.
|
||||
* @deprecated Use `registerPrompt` instead.
|
||||
*/
|
||||
prompt(name: string, description: string, cb: PromptCallback): RegisteredPrompt;
|
||||
/**
|
||||
* Registers a prompt `name` accepting the given arguments, which must be an object containing named properties associated with Zod schemas. When the client calls it, the function will be run with the parsed and validated arguments.
|
||||
* @deprecated Use `registerPrompt` instead.
|
||||
*/
|
||||
prompt<Args extends PromptArgsRawShape>(name: string, argsSchema: Args, cb: PromptCallback<Args>): RegisteredPrompt;
|
||||
/**
|
||||
* Registers a prompt `name` (with a description) accepting the given arguments, which must be an object containing named properties associated with Zod schemas. When the client calls it, the function will be run with the parsed and validated arguments.
|
||||
* @deprecated Use `registerPrompt` instead.
|
||||
*/
|
||||
prompt<Args extends PromptArgsRawShape>(name: string, description: string, argsSchema: Args, cb: PromptCallback<Args>): RegisteredPrompt;
|
||||
/**
|
||||
@@ -137,6 +188,14 @@ export declare class McpServer {
|
||||
* @returns True if the server is connected
|
||||
*/
|
||||
isConnected(): boolean;
|
||||
/**
|
||||
* Sends a logging message to the client, if connected.
|
||||
* Note: You only need to send the parameters object, not the entire JSON RPC message
|
||||
* @see LoggingMessageNotification
|
||||
* @param params
|
||||
* @param sessionId optional for stateless and backward compatibility
|
||||
*/
|
||||
sendLoggingMessage(params: LoggingMessageNotification['params'], sessionId?: string): Promise<void>;
|
||||
/**
|
||||
* Sends a resource list changed event to the client, if connected.
|
||||
*/
|
||||
@@ -188,6 +247,7 @@ export declare class ResourceTemplate {
|
||||
*/
|
||||
completeCallback(variable: string): CompleteResourceTemplateCallback | undefined;
|
||||
}
|
||||
export type BaseToolCallback<SendResultT extends Result, Extra extends RequestHandlerExtra<ServerRequest, ServerNotification>, Args extends undefined | ZodRawShapeCompat | AnySchema> = Args extends ZodRawShapeCompat ? (args: ShapeOutput<Args>, extra: Extra) => SendResultT | Promise<SendResultT> : Args extends AnySchema ? (args: SchemaOutput<Args>, extra: Extra) => SendResultT | Promise<SendResultT> : (extra: Extra) => SendResultT | Promise<SendResultT>;
|
||||
/**
|
||||
* Callback for a tool handler registered with Server.tool().
|
||||
*
|
||||
@@ -198,24 +258,31 @@ export declare class ResourceTemplate {
|
||||
* - `content` if the tool does not have an outputSchema
|
||||
* - Both fields are optional but typically one should be provided
|
||||
*/
|
||||
export type ToolCallback<Args extends undefined | ZodRawShape = undefined> = Args extends ZodRawShape ? (args: z.objectOutputType<Args, ZodTypeAny>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult> : (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult>;
|
||||
export type ToolCallback<Args extends undefined | ZodRawShapeCompat | AnySchema = undefined> = BaseToolCallback<CallToolResult, RequestHandlerExtra<ServerRequest, ServerNotification>, Args>;
|
||||
/**
|
||||
* Supertype that can handle both regular tools (simple callback) and task-based tools (task handler object).
|
||||
*/
|
||||
export type AnyToolHandler<Args extends undefined | ZodRawShapeCompat | AnySchema = undefined> = ToolCallback<Args> | ToolTaskHandler<Args>;
|
||||
export type RegisteredTool = {
|
||||
title?: string;
|
||||
description?: string;
|
||||
inputSchema?: AnyZodObject;
|
||||
outputSchema?: AnyZodObject;
|
||||
inputSchema?: AnySchema;
|
||||
outputSchema?: AnySchema;
|
||||
annotations?: ToolAnnotations;
|
||||
callback: ToolCallback<undefined | ZodRawShape>;
|
||||
execution?: ToolExecution;
|
||||
_meta?: Record<string, unknown>;
|
||||
handler: AnyToolHandler<undefined | ZodRawShapeCompat>;
|
||||
enabled: boolean;
|
||||
enable(): void;
|
||||
disable(): void;
|
||||
update<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape>(updates: {
|
||||
update<InputArgs extends ZodRawShapeCompat, OutputArgs extends ZodRawShapeCompat>(updates: {
|
||||
name?: string | null;
|
||||
title?: string;
|
||||
description?: string;
|
||||
paramsSchema?: InputArgs;
|
||||
outputSchema?: OutputArgs;
|
||||
annotations?: ToolAnnotations;
|
||||
_meta?: Record<string, unknown>;
|
||||
callback?: ToolCallback<InputArgs>;
|
||||
enabled?: boolean;
|
||||
}): void;
|
||||
@@ -224,7 +291,7 @@ export type RegisteredTool = {
|
||||
/**
|
||||
* Additional, optional information for annotating a resource.
|
||||
*/
|
||||
export type ResourceMetadata = Omit<Resource, "uri" | "name">;
|
||||
export type ResourceMetadata = Omit<Resource, 'uri' | 'name'>;
|
||||
/**
|
||||
* Callback to list all resources matching a given template.
|
||||
*/
|
||||
@@ -273,14 +340,12 @@ export type RegisteredResourceTemplate = {
|
||||
}): void;
|
||||
remove(): void;
|
||||
};
|
||||
type PromptArgsRawShape = {
|
||||
[k: string]: ZodType<string, ZodTypeDef, string> | ZodOptional<ZodType<string, ZodTypeDef, string>>;
|
||||
};
|
||||
export type PromptCallback<Args extends undefined | PromptArgsRawShape = undefined> = Args extends PromptArgsRawShape ? (args: z.objectOutputType<Args, ZodTypeAny>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult> : (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult>;
|
||||
type PromptArgsRawShape = ZodRawShapeCompat;
|
||||
export type PromptCallback<Args extends undefined | PromptArgsRawShape = undefined> = Args extends PromptArgsRawShape ? (args: ShapeOutput<Args>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult> : (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult>;
|
||||
export type RegisteredPrompt = {
|
||||
title?: string;
|
||||
description?: string;
|
||||
argsSchema?: ZodObject<PromptArgsRawShape>;
|
||||
argsSchema?: AnyObjectSchema;
|
||||
callback: PromptCallback<undefined | PromptArgsRawShape>;
|
||||
enabled: boolean;
|
||||
enable(): void;
|
||||
|
||||
Reference in New Issue
Block a user