From 69daade65953996da7e29a2f634717ca9618e7fa Mon Sep 17 00:00:00 2001 From: Justin Spahr-Summers Date: Fri, 11 Oct 2024 14:01:35 +0100 Subject: [PATCH] Update to latest protocol version --- src/types.ts | 118 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 96 insertions(+), 22 deletions(-) diff --git a/src/types.ts b/src/types.ts index f7500d17..134b4ec8 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,5 +1,8 @@ import { z } from "zod"; +export const PROTOCOL_VERSION = "2024-10-07"; + + /* JSON-RPC types */ export const JSONRPC_VERSION = "2.0"; @@ -8,6 +11,11 @@ export const JSONRPC_VERSION = "2.0"; */ export const ProgressTokenSchema = z.union([z.string(), z.number().int()]); +/** + * An opaque token used to represent a cursor for pagination. + */ +export const CursorSchema = z.string(); + export const RequestSchema = z.object({ method: z.string(), params: z.optional( @@ -141,8 +149,6 @@ export const JSONRPCMessageSchema = z.union([ export const EmptyResultSchema = ResultSchema.strict(); /* Initialization */ -export const PROTOCOL_VERSION = 1; - /** * Text provided to or from an LLM. */ @@ -208,7 +214,7 @@ export const InitializeRequestSchema = RequestSchema.extend({ /** * The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well. */ - protocolVersion: z.number().int(), + protocolVersion: z.string().or(z.number().int()), capabilities: ClientCapabilitiesSchema, clientInfo: ImplementationSchema, }), @@ -229,24 +235,40 @@ export const ServerCapabilitiesSchema = z.object({ /** * Present if the server offers any prompt templates. */ - prompts: z.optional(z.object({}).passthrough()), + prompts: z.optional( + z.object({ + /** + * Whether this server supports notifications for changes to the prompt list. + */ + listChanged: z.optional(z.boolean()), + }).passthrough(), + ), /** * Present if the server offers any resources to read. */ resources: z.optional( - z - .object({ - /** - * Whether this server supports subscribing to resource updates. - */ - subscribe: z.optional(z.boolean()), - }) - .passthrough(), + z.object({ + /** + * Whether this server supports subscribing to resource updates. + */ + subscribe: z.optional(z.boolean()), + /** + * Whether this server supports notifications for changes to the resource list. + */ + listChanged: z.optional(z.boolean()), + }).passthrough(), ), /** * Present if the server offers any tools to call. */ - tools: z.optional(z.object({}).passthrough()), + tools: z.optional( + z.object({ + /** + * Whether this server supports notifications for changes to the tool list. + */ + listChanged: z.optional(z.boolean()), + }).passthrough(), + ), }); /** @@ -256,7 +278,7 @@ export const InitializeResultSchema = ResultSchema.extend({ /** * The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect. */ - protocolVersion: z.number().int(), + protocolVersion: z.string().or(z.number().int()), capabilities: ServerCapabilitiesSchema, serverInfo: ImplementationSchema, }); @@ -301,6 +323,27 @@ export const ProgressNotificationSchema = NotificationSchema.extend({ }), }); +/* Pagination */ +export const PaginatedRequestSchema = RequestSchema.extend({ + params: z.optional( + z.object({ + /** + * An opaque token representing the current pagination position. + * If provided, the server should return results starting after this cursor. + */ + cursor: z.optional(CursorSchema), + }), + ), +}); + +export const PaginatedResultSchema = ResultSchema.extend({ + /** + * An opaque token representing the pagination position after the last returned result. + * If present, there may be more results available. + */ + nextCursor: z.optional(CursorSchema), +}); + /* Resources */ /** * The contents of a specific resource or sub-resource. @@ -391,16 +434,29 @@ export const ResourceTemplateSchema = z.object({ /** * Sent from the client to request a list of resources the server has. */ -export const ListResourcesRequestSchema = RequestSchema.extend({ +export const ListResourcesRequestSchema = PaginatedRequestSchema.extend({ method: z.literal("resources/list"), }); /** * The server's response to a resources/list request from the client. */ -export const ListResourcesResultSchema = ResultSchema.extend({ - resourceTemplates: z.optional(z.array(ResourceTemplateSchema)), - resources: z.optional(z.array(ResourceSchema)), +export const ListResourcesResultSchema = PaginatedResultSchema.extend({ + resources: z.array(ResourceSchema), +}); + +/** + * Sent from the client to request a list of resource templates the server has. + */ +export const ListResourceTemplatesRequestSchema = PaginatedRequestSchema.extend({ + method: z.literal("resources/templates/list"), +}); + +/** + * The server's response to a resources/templates/list request from the client. + */ +export const ListResourceTemplatesResultSchema = PaginatedResultSchema.extend({ + resourceTemplates: z.array(ResourceTemplateSchema), }); /** @@ -511,14 +567,14 @@ export const PromptSchema = z.object({ /** * Sent from the client to request a list of prompts and prompt templates the server has. */ -export const ListPromptsRequestSchema = RequestSchema.extend({ +export const ListPromptsRequestSchema = PaginatedRequestSchema.extend({ method: z.literal("prompts/list"), }); /** * The server's response to a prompts/list request from the client. */ -export const ListPromptsResultSchema = ResultSchema.extend({ +export const ListPromptsResultSchema = PaginatedResultSchema.extend({ prompts: z.array(PromptSchema), }); @@ -550,6 +606,13 @@ export const GetPromptResultSchema = ResultSchema.extend({ messages: z.array(SamplingMessageSchema), }); +/** + * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client. + */ +export const PromptListChangedNotificationSchema = NotificationSchema.extend({ + method: z.literal("notifications/prompts/list_changed"), +}); + /* Tools */ /** * Definition for a tool the client can call. @@ -575,14 +638,14 @@ export const ToolSchema = z.object({ /** * Sent from the client to request a list of tools the server has. */ -export const ListToolsRequestSchema = RequestSchema.extend({ +export const ListToolsRequestSchema = PaginatedRequestSchema.extend({ method: z.literal("tools/list"), }); /** * The server's response to a tools/list request from the client. */ -export const ListToolsResultSchema = ResultSchema.extend({ +export const ListToolsResultSchema = PaginatedResultSchema.extend({ tools: z.array(ToolSchema), }); @@ -802,6 +865,7 @@ export const ServerNotificationSchema = z.union([ ResourceUpdatedNotificationSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, + PromptListChangedNotificationSchema, ]); export const ServerResultSchema = z.union([ @@ -828,6 +892,7 @@ export class McpError extends Error { /* JSON-RPC types */ export type ProgressToken = z.infer; +export type Cursor = z.infer; export type Request = z.infer; export type Notification = z.infer; export type Result = z.infer; @@ -861,6 +926,10 @@ export type PingRequest = z.infer; export type Progress = z.infer; export type ProgressNotification = z.infer; +/* Pagination */ +export type PaginatedRequest = z.infer; +export type PaginatedResult = z.infer; + /* Resources */ export type ResourceContents = z.infer; export type TextResourceContents = z.infer; @@ -869,6 +938,8 @@ export type Resource = z.infer; export type ResourceTemplate = z.infer; export type ListResourcesRequest = z.infer; export type ListResourcesResult = z.infer; +export type ListResourceTemplatesRequest = z.infer; +export type ListResourceTemplatesResult = z.infer; export type ReadResourceRequest = z.infer; export type ReadResourceResult = z.infer; export type ResourceListChangedNotification = z.infer< @@ -887,6 +958,9 @@ export type ListPromptsRequest = z.infer; export type ListPromptsResult = z.infer; export type GetPromptRequest = z.infer; export type GetPromptResult = z.infer; +export type PromptListChangedNotification = z.infer< + typeof PromptListChangedNotificationSchema +>; /* Tools */ export type Tool = z.infer;