feat: add optional resource annotations

src/server/mcp.test.ts

@@ -2111,6 +2111,11 @@ describe("resource()", () => {
       {
         description: "Test resource",
         mimeType: "text/plain",
+        annotations: {
+          audience: ["assistant"],
+          priority: 0.42,
+          lastModified: "2025-01-12T15:00:58Z"
+        }
       },
       async () => ({
         contents: [
@@ -2140,6 +2145,11 @@ describe("resource()", () => {
     expect(result.resources).toHaveLength(1);
     expect(result.resources[0].description).toBe("Test resource");
     expect(result.resources[0].mimeType).toBe("text/plain");
+    expect(result.resources[0].annotations).toEqual({
+      audience: ["assistant"],
+      priority: 0.42,
+      lastModified: "2025-01-12T15:00:58Z"
+    });
   });
 
   /***

src/spec.types.test.ts

@@ -439,6 +439,13 @@ function checkBlobResourceContents(
   sdk = spec;
   spec = sdk;
 }
+function checkResourceAnnotations(
+  sdk: RemovePassthrough<SDKTypes.ResourceAnnotations>,
+  spec: SpecTypes.Annotations
+) {
+  sdk = spec;
+  spec = sdk;
+}
 function checkResource(
   sdk: RemovePassthrough<SDKTypes.Resource>,
   spec: SpecTypes.Resource

src/types.ts

@@ -518,6 +518,28 @@ export const BlobResourceContentsSchema = ResourceContentsSchema.extend({
   blob: Base64Schema,
 });
 
+/**
+ * Optional annotations providing clients additional context about a resource.
+ */
+export const ResourceAnnotationsSchema = z
+  .object({
+    /**
+     * Intended audience(s) for the resource.
+     */
+    audience: z.optional(z.array(z.enum(["user", "assistant"]))),
+
+    /**
+     * Importance hint for the resource, from 0 (least) to 1 (most).
+     */
+    priority: z.optional(z.number().min(0).max(1)),
+
+    /**
+     * ISO 8601 timestamp for the most recent modification.
+     */
+    lastModified: z.optional(z.string().datetime({ offset: true })),
+  })
+  .passthrough();
+
 /**
  * A known resource that the server is capable of reading.
  */
@@ -539,6 +561,11 @@ export const ResourceSchema = BaseMetadataSchema.extend({
    */
   mimeType: z.optional(z.string()),
 
+  /**
+   * Optional annotations for the client.
+   */
+  annotations: z.optional(ResourceAnnotationsSchema),
+
   /**
    * An optional list of icons for this resource.
    */
@@ -1608,6 +1635,7 @@ export type PaginatedResult = Infer<typeof PaginatedResultSchema>;
 export type ResourceContents = Infer<typeof ResourceContentsSchema>;
 export type TextResourceContents = Infer<typeof TextResourceContentsSchema>;
 export type BlobResourceContents = Infer<typeof BlobResourceContentsSchema>;
+export type ResourceAnnotations = Infer<typeof ResourceAnnotationsSchema>;
 export type Resource = Infer<typeof ResourceSchema>;
 export type ResourceTemplate = Infer<typeof ResourceTemplateSchema>;
 export type ListResourcesRequest = Infer<typeof ListResourcesRequestSchema>;