Merge pull request #502 from modelcontextprotocol/basil/progress_message

Add support for message field in progress notifications

Author: bhosmer-ant

src/server/mcp.test.ts

@@ -79,6 +79,99 @@ describe("McpServer", () => {
       }
     ])
   });
+
+  /***
+   * Test: Progress Notification with Message Field
+   */
+  test("should send progress notifications with message field", async () => {
+    const mcpServer = new McpServer(
+      {
+        name: "test server",
+        version: "1.0",
+      }
+    );
+
+    // Create a tool that sends progress updates
+    mcpServer.tool(
+      "long-operation",
+      "A long running operation with progress updates",
+      {
+        steps: z.number().min(1).describe("Number of steps to perform"),
+      },
+      async ({ steps }, { sendNotification, _meta }) => {
+        const progressToken = _meta?.progressToken;
+
+        if (progressToken) {
+          // Send progress notification for each step
+          for (let i = 1; i <= steps; i++) {
+            await sendNotification({
+              method: "notifications/progress",
+              params: {
+                progressToken,
+                progress: i,
+                total: steps,
+                message: `Completed step ${i} of ${steps}`,
+              },
+            });
+          }
+        }
+
+        return { content: [{ type: "text" as const, text: `Operation completed with ${steps} steps` }] };
+      }
+    );
+
+    const progressUpdates: Array<{ progress: number, total?: number, message?: string }> = [];
+
+    const client = new Client({
+      name: "test client",
+      version: "1.0",
+    });
+
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await Promise.all([
+      client.connect(clientTransport),
+      mcpServer.server.connect(serverTransport),
+    ]);
+
+    // Call the tool with progress tracking
+    await client.request(
+      {
+        method: "tools/call",
+        params: {
+          name: "long-operation",
+          arguments: { steps: 3 },
+          _meta: {
+            progressToken: "progress-test-1"
+          }
+        }
+      },
+      CallToolResultSchema,
+      {
+        onprogress: (progress) => {
+          progressUpdates.push(progress);
+        }
+      }
+    );
+
+    // Verify progress notifications were received with message field
+    expect(progressUpdates).toHaveLength(3);
+    expect(progressUpdates[0]).toMatchObject({
+      progress: 1,
+      total: 3,
+      message: "Completed step 1 of 3",
+    });
+    expect(progressUpdates[1]).toMatchObject({
+      progress: 2,
+      total: 3,
+      message: "Completed step 2 of 3",
+    });
+    expect(progressUpdates[2]).toMatchObject({
+      progress: 3,
+      total: 3,
+      message: "Completed step 3 of 3",
+    });
+  });
 });
 
 describe("ResourceTemplate", () => {

src/shared/protocol.test.ts

@@ -255,6 +255,74 @@ describe("protocol tests", () => {
       await Promise.resolve();
       await expect(requestPromise).resolves.toEqual({ result: "success" });
     });
+
+    test("should handle progress notifications with message field", async () => {
+      await protocol.connect(transport);
+      const request = { method: "example", params: {} };
+      const mockSchema: ZodType<{ result: string }> = z.object({
+        result: z.string(),
+      });
+      const onProgressMock = jest.fn();
+
+      const requestPromise = protocol.request(request, mockSchema, {
+        timeout: 1000,
+        onprogress: onProgressMock,
+      });
+
+      jest.advanceTimersByTime(200);
+
+      if (transport.onmessage) {
+        transport.onmessage({
+          jsonrpc: "2.0",
+          method: "notifications/progress",
+          params: {
+            progressToken: 0,
+            progress: 25,
+            total: 100,
+            message: "Initializing process...",
+          },
+        });
+      }
+      await Promise.resolve();
+
+      expect(onProgressMock).toHaveBeenCalledWith({
+        progress: 25,
+        total: 100,
+        message: "Initializing process...",
+      });
+
+      jest.advanceTimersByTime(200);
+
+      if (transport.onmessage) {
+        transport.onmessage({
+          jsonrpc: "2.0",
+          method: "notifications/progress",
+          params: {
+            progressToken: 0,
+            progress: 75,
+            total: 100,
+            message: "Processing data...",
+          },
+        });
+      }
+      await Promise.resolve();
+
+      expect(onProgressMock).toHaveBeenCalledWith({
+        progress: 75,
+        total: 100,
+        message: "Processing data...",
+      });
+
+      if (transport.onmessage) {
+        transport.onmessage({
+          jsonrpc: "2.0",
+          id: 0,
+          result: { result: "success" },
+        });
+      }
+      await Promise.resolve();
+      await expect(requestPromise).resolves.toEqual({ result: "success" });
+    });
   });
 });
 

src/types.ts

@@ -364,6 +364,10 @@ export const ProgressSchema = z
      * Total number of items to process (or total progress required), if known.
      */
     total: z.optional(z.number()),
+    /**
+     * An optional message describing the current progress.
+     */
+    message: z.optional(z.string()),
   })
   .passthrough();