Add missing type definitions from spec.types.ts

- Add Annotations schema and type export - Add annotations field to TextContent, ImageContent, AudioContent schemas - Add annotations field to Resource and ResourceTemplate schemas - Add size field to Resource schema - Add annotations field to EmbeddedResource schema - Add ModelHint schema and type export - Update ModelPreferences schema to include hints array and detailed documentation - Uncomment spec type tests These changes align types.ts with the latest spec definitions to ensure full compatibility. Co-Authored-By: Claude <noreply@anthropic.com>

Author: ochafik

src/spec.types.test.ts

@@ -659,32 +659,29 @@ function checkServerNotification(
  spec = sdk;
 }
 
-// TODO(bug): missing type in SDK. This dead code is checked by the test suite below.
-// function checkModelHint(
-// RemovePassthrough< sdk: SDKTypes.ModelHint>,
-// spec: SpecTypes.ModelHint
-// ) {
-// sdk = spec;
-// spec = sdk;
-// }
+function checkModelHint(
+ sdk: RemovePassthrough<SDKTypes.ModelHint>,
+ spec: SpecTypes.ModelHint
+) {
+ sdk = spec;
+ spec = sdk;
+}
 
-// TODO(bug): missing type in SDK. This dead code is checked by the test suite below.
-// function checkModelPreferences(
-// RemovePassthrough< sdk: SDKTypes.ModelPreferences>,
-// spec: SpecTypes.ModelPreferences
-// ) {
-// sdk = spec;
-// spec = sdk;
-// }
+function checkModelPreferences(
+ sdk: RemovePassthrough<SDKTypes.ModelPreferences>,
+ spec: SpecTypes.ModelPreferences
+) {
+ sdk = spec;
+ spec = sdk;
+}
 
-// TODO(bug): missing type in SDK. This dead code is checked by the test suite below.
-// function checkAnnotations(
-// RemovePassthrough< sdk: SDKTypes.Annotations>,
-// spec: SpecTypes.Annotations
-// ) {
-// sdk = spec;
-// spec = sdk;
-// }
+function checkAnnotations(
+ sdk: RemovePassthrough<SDKTypes.Annotations>,
+ spec: SpecTypes.Annotations
+) {
+ sdk = spec;
+ spec = sdk;
+}
 
 // This file is .gitignore'd, and fetched by `npm run fetch:spec-types` (called by `npm run test`)
 const SPEC_TYPES_FILE = 'src/spec.types.ts';

src/types.ts

@@ -429,6 +429,40 @@ export const PaginatedResultSchema = ResultSchema.extend({
  nextCursor: z.optional(CursorSchema),
 });
 
+/* Annotations */
+/**
+ * Optional annotations for the client. The client can use annotations to inform how objects are used or displayed
+ */
+export const AnnotationsSchema = z
+ .object({
+ /**
+ * Describes who the intended customer of this object or data is.
+ *
+ * It can include multiple entries to indicate content useful for multiple audiences (e.g., `["user", "assistant"]`).
+ */
+ audience: z.optional(z.array(z.enum(["user", "assistant"]))),
+
+ /**
+ * Describes how important this data is for operating the server.
+ *
+ * A value of 1 means "most important," and indicates that the data is
+ * effectively required, while 0 means "least important," and indicates that
+ * the data is entirely optional.
+ */
+ priority: z.optional(z.number().min(0).max(1)),
+
+ /**
+ * The moment the resource was last modified, as an ISO 8601 formatted string.
+ *
+ * Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z").
+ *
+ * Examples: last activity timestamp in an open file, timestamp when the resource
+ * was attached, etc.
+ */
+ lastModified: z.optional(z.string()),
+ })
+ .passthrough();
+
 /* Resources */
 /**
  * The contents of a specific resource or sub-resource.
@@ -486,6 +520,18 @@ export const ResourceSchema = BaseMetadataSchema.extend({
  */
  mimeType: z.optional(z.string()),
 
+ /**
+ * Optional annotations for the client.
+ */
+ annotations: z.optional(AnnotationsSchema),
+
+ /**
+ * The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.
+ *
+ * This can be used by Hosts to display file sizes and estimate context window usage.
+ */
+ size: z.optional(z.number()),
+
  /**
  * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
  * for notes on _meta usage.
@@ -514,6 +560,11 @@ export const ResourceTemplateSchema = BaseMetadataSchema.extend({
  */
  mimeType: z.optional(z.string()),
 
+ /**
+ * Optional annotations for the client.
+ */
+ annotations: z.optional(AnnotationsSchema),
+
  /**
  * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
  * for notes on _meta usage.
@@ -701,6 +752,11 @@ export const TextContentSchema = z
  */
  text: z.string(),
 
+ /**
+ * Optional annotations for the client.
+ */
+ annotations: z.optional(AnnotationsSchema),
+
  /**
  * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
  * for notes on _meta usage.
@@ -724,6 +780,11 @@ export const ImageContentSchema = z
  */
  mimeType: z.string(),
 
+ /**
+ * Optional annotations for the client.
+ */
+ annotations: z.optional(AnnotationsSchema),
+
  /**
  * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
  * for notes on _meta usage.
@@ -747,6 +808,11 @@ export const AudioContentSchema = z
  */
  mimeType: z.string(),
 
+ /**
+ * Optional annotations for the client.
+ */
+ annotations: z.optional(AnnotationsSchema),
+
  /**
  * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
  * for notes on _meta usage.
@@ -762,6 +828,10 @@ export const EmbeddedResourceSchema = z
  .object({
  type: z.literal("resource"),
  resource: z.union([TextResourceContentsSchema, BlobResourceContentsSchema]),
+ /**
+ * Optional annotations for the client.
+ */
+ annotations: z.optional(AnnotationsSchema),
  /**
  * See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)
  * for notes on _meta usage.
@@ -1046,23 +1116,50 @@ export const LoggingMessageNotificationSchema = NotificationSchema.extend({
 /* Sampling */
 /**
  * Hints to use for model selection.
+ *
+ * Keys not declared here are currently left unspecified by the spec and are up
+ * to the client to interpret.
  */
 export const ModelHintSchema = z
  .object({
  /**
  * A hint for a model name.
+ *
+ * The client SHOULD treat this as a substring of a model name; for example:
+ * - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`
+ * - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.
+ * - `claude` should match any Claude model
+ *
+ * The client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:
+ * - `gemini-1.5-flash` could match `claude-3-haiku-20240307`
  */
  name: z.string().optional(),
  })
  .passthrough();
 
 /**
  * The server's preferences for model selection, requested of the client during sampling.
+ *
+ * Because LLMs can vary along multiple dimensions, choosing the "best" model is
+ * rarely straightforward. Different models excel in different areas—some are
+ * faster but less capable, others are more capable but more expensive, and so
+ * on. This interface allows servers to express their priorities across multiple
+ * dimensions to help clients make an appropriate selection for their use case.
+ *
+ * These preferences are always advisory. The client MAY ignore them. It is also
+ * up to the client to decide how to interpret these preferences and how to
+ * balance them against other considerations.
  */
 export const ModelPreferencesSchema = z
  .object({
  /**
  * Optional hints to use for model selection.
+ *
+ * If multiple hints are specified, the client MUST evaluate them in order
+ * (such that the first match is taken).
+ *
+ * The client SHOULD prioritize these hints over the numeric priorities, but
+ * MAY still use the priorities to select from ambiguous matches.
  */
  hints: z.optional(z.array(ModelHintSchema)),
  /**
@@ -1569,6 +1666,9 @@ export type PromptMessage = Infer<typeof PromptMessageSchema>;
 export type GetPromptResult = Infer<typeof GetPromptResultSchema>;
 export type PromptListChangedNotification = Infer<typeof PromptListChangedNotificationSchema>;
 
+/* Annotations */
+export type Annotations = Infer<typeof AnnotationsSchema>;
+
 /* Tools */
 export type ToolAnnotations = Infer<typeof ToolAnnotationsSchema>;
 export type Tool = Infer<typeof ToolSchema>;
@@ -1585,6 +1685,8 @@ export type SetLevelRequest = Infer<typeof SetLevelRequestSchema>;
 export type LoggingMessageNotification = Infer<typeof LoggingMessageNotificationSchema>;
 
 /* Sampling */
+export type ModelHint = Infer<typeof ModelHintSchema>;
+export type ModelPreferences = Infer<typeof ModelPreferencesSchema>;
 export type SamplingMessage = Infer<typeof SamplingMessageSchema>;
 export type CreateMessageRequest = Infer<typeof CreateMessageRequestSchema>;
 export type CreateMessageResult = Infer<typeof CreateMessageResultSchema>;