[WIP] Refactor everything server to be more modular and use recommended APIs.

Adding the annotated message tool

* Updated architecture.md

* Added annotated-message.ts
  - registers a tool that returns a message with annotations on different content types

* In package.json
  - updated TS SDK version

package-lock.json

@@ -3750,7 +3750,7 @@
       "version": "2.0.0",
       "license": "MIT",
       "dependencies": {
-        "@modelcontextprotocol/sdk": "^1.24.0",
+        "@modelcontextprotocol/sdk": "^1.24.3",
         "cors": "^2.8.5",
         "express": "^5.2.1",
         "jszip": "^3.10.1",
@@ -3768,6 +3768,43 @@
         "typescript": "^5.6.2"
       }
     },
+    "src/everything/node_modules/@modelcontextprotocol/sdk": {
+      "version": "1.24.3",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.24.3.tgz",
+      "integrity": "sha512-YgSHW29fuzKKAHTGe9zjNoo+yF8KaQPzDC2W9Pv41E7/57IfY+AMGJ/aDFlgTLcVVELoggKE4syABCE75u3NCw==",
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1",
+        "content-type": "^1.0.5",
+        "cors": "^2.8.5",
+        "cross-spawn": "^7.0.5",
+        "eventsource": "^3.0.2",
+        "eventsource-parser": "^3.0.0",
+        "express": "^5.0.1",
+        "express-rate-limit": "^7.5.0",
+        "jose": "^6.1.1",
+        "pkce-challenge": "^5.0.0",
+        "raw-body": "^3.0.0",
+        "zod": "^3.25 || ^4.0",
+        "zod-to-json-schema": "^3.25.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@cfworker/json-schema": "^4.1.1",
+        "zod": "^3.25 || ^4.0"
+      },
+      "peerDependenciesMeta": {
+        "@cfworker/json-schema": {
+          "optional": true
+        },
+        "zod": {
+          "optional": false
+        }
+      }
+    },
     "src/filesystem": {
       "name": "@modelcontextprotocol/server-filesystem",
       "version": "0.6.3",

src/everything/docs/architecture.md

@@ -29,6 +29,7 @@ src/everything
 │   └── streamableHttp.ts
 ├── tools
 │   ├── index.ts
+│   ├── annotated-message.ts
 │   ├── add.ts
 │   ├── echo.ts
 │   ├── get-tiny-image.ts
@@ -90,22 +91,24 @@ At `src/everything`:
 
   - index.ts
     - `registerTools(server)` orchestrator; delegates to basic tools and control tools.
-  - add.ts
-    - Defines an `add` tool with a Zod input schema that sums two numbers `a` and `b` and returns the result.
-  - echo.ts
-    - Defines a minimal `echo` tool with a Zod input schema and returns `Echo: {message}`.
-  - get-tiny-image.ts
-    - Defines `get-tiny-image` tool, which returns a tiny PNG MCP logo as an `image` content item, along with surrounding descriptive `text` items.
-  - long-running-operation.ts
-    - Defines `long-running-operation`: simulates a long-running task over a specified `duration` (seconds) and number of `steps`; emits `notifications/progress` updates when the client supplies a `progressToken`.
-  - print-env.ts
-    - Defines `print-env`: returns the current process environment variables as formatted JSON text; useful for debugging configuration.
-  - toggle-logging.ts
-    - Defines `toggle-logging`: starts/stops simulated logging for the invoking session.
-  - toggle-subscriber-updates.ts
-    - Defines `toggle-subscriber-updates`: starts/stops simulated resource subscription update checks for the invoking session.
-  - sampling-request.ts
-    - Defines `sampling-request`: sends a `sampling/createMessage` request to the client/LLM and returns the sampling result.
+    - add.ts
+      - Registers an `add` tool with a Zod input schema that sums two numbers `a` and `b` and returns the result.
+    - annotated-message.ts
+        - Registers an `annotated-message` tool which demonstrates annotated content items by emitting a primary `text` message with `annotations` that vary by `messageType` (`"error" | "success" | "debug"`), and optionally includes an annotated `image` (tiny PNG) when `includeImage` is true.
+    - echo.ts
+      - Registers an `echo` tool that takes a message and returns `Echo: {message}`.
+    - get-tiny-image.ts
+      - Registers a `get-tiny-image` tool, which returns a tiny PNG MCP logo as an `image` content item, along with surrounding descriptive `text` items.
+    - long-running-operation.ts
+      - Registers a `long-running-operation` tool that simulates a long-running task over a specified `duration` (seconds) and number of `steps`; emits `notifications/progress` updates when the client supplies a `progressToken`.
+    - print-env.ts
+      - Registers a `print-env` tool that returns the current process environment variables as formatted JSON text; useful for debugging configuration.
+    - sampling-request.ts
+        - Registers a `sampling-request` tool that sends a `sampling/createMessage` request to the client/LLM and returns the sampling result.
+    - toggle-logging.ts
+      - Registers a `toggle-logging` tool, which starts or stops simulated logging for the invoking session.
+    - toggle-subscriber-updates.ts
+      - Registers a `toggle-subscriber-updates` tool, which starts or stops simulated resource subscription update checks for the invoking session.
 
 - prompts/
 
@@ -182,6 +185,7 @@ At `src/everything`:
 - Tools
 
   - `add` (tools/add.ts): Adds two numbers `a` and `b` and returns their sum. Uses Zod to validate inputs.
+  - `annotated-message` (tools/annotated-message.ts): Returns a `text` message annotated with `priority` and `audience` based on `messageType` (`error`, `success`, or `debug`); can optionally include an annotated `image`.
   - `echo` (tools/echo.ts): Echoes the provided `message: string`. Uses Zod to validate inputs.
   - `get-tiny-image` (tools/get-tiny-image.ts): Returns a tiny PNG MCP logo as an `image` content item with brief descriptive text before and after.
   - `long-running-operation` (tools/long-running-operation.ts): Simulates a multi-step operation over a given `duration` and number of `steps`; reports progress via `notifications/progress` when a `progressToken` is provided by the client.

src/everything/package.json

@@ -29,7 +29,7 @@
     "prettier-check": "prettier --check ."
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.24.0",
+    "@modelcontextprotocol/sdk": "^1.24.3",
     "cors": "^2.8.5",
     "express": "^5.2.1",
     "jszip": "^3.10.1",

src/everything/tools/annotated-message.ts

@@ -0,0 +1,89 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import {MCP_TINY_IMAGE} from "./get-tiny-image.js";
+
+// Tool input schema
+const AnnotatedMessageSchema = z.object({
+  messageType: z
+    .enum(["error", "success", "debug"])
+    .describe("Type of message to demonstrate different annotation patterns"),
+  includeImage: z
+    .boolean()
+    .default(false)
+    .describe("Whether to include an example image"),
+});
+
+// Tool configuration
+const name = "annotated-message";
+const config = {
+  title: "Annotated Message Tool",
+  description: "Demonstrates how annotations can be used to provide metadata about content.",
+  inputSchema: AnnotatedMessageSchema,
+};
+
+
+/**
+ * Registers the 'annotated-message' tool with the provided McpServer instance.
+ *
+ * The registered tool generates and sends messages with specific types, such as error,
+ * success, or debug, carrying associated annotations like priority level and intended
+ * audience.
+ *
+ * Optionally, it can include an annotated image in the response.
+ *
+ * @function
+ * @param {McpServer} server - The MCP server instance where the Annotated Message Tool is to be registered.
+ */
+export const registerAnnotatedMessageTool = (server: McpServer) => {
+  server.registerTool(name, config, async (args): Promise<CallToolResult> => {
+    const { messageType, includeImage } = AnnotatedMessageSchema.parse(args);
+
+    const content:  CallToolResult["content"]  = [];
+
+    // Main message with different priorities/audiences based on type
+    if (messageType === "error") {
+      content.push({
+        type: "text",
+        text: "Error: Operation failed",
+        annotations: {
+          priority: 1.0, // Errors are highest priority
+          audience: ["user", "assistant"], // Both need to know about errors
+        },
+      });
+    } else if (messageType === "success") {
+      content.push({
+        type: "text",
+        text: "Operation completed successfully",
+        annotations: {
+          priority: 0.7, // Success messages are important but not critical
+          audience: ["user"], // Success mainly for user consumption
+        },
+      });
+    } else if (messageType === "debug") {
+      content.push({
+        type: "text",
+        text: "Debug: Cache hit ratio 0.95, latency 150ms",
+        annotations: {
+          priority: 0.3, // Debug info is low priority
+          audience: ["assistant"], // Technical details for assistant
+        },
+      });
+    }
+
+    // Optional image with its own annotations
+    if (includeImage) {
+      content.push({
+        type: "image",
+        data: MCP_TINY_IMAGE,
+        mimeType: "image/png",
+        annotations: {
+          priority: 0.5,
+          audience: ["user"], // Images primarily for user visualization
+        },
+      });
+    }
+
+    return { content };
+  });
+};

src/everything/tools/index.ts

@@ -7,6 +7,7 @@ import { registerPrintEnvTool } from "./print-env.js";
 import { registerSamplingRequestTool } from "./sampling-request.js";
 import { registerToggleLoggingTool } from "./toggle-logging.js";
 import { registerToggleSubscriberUpdatesTool } from "./toggle-subscriber-updates.js";
+import {registerAnnotatedMessageTool} from "./annotated-message.js";
 
 /**
  * Register the tools with the MCP server.
@@ -14,6 +15,7 @@ import { registerToggleSubscriberUpdatesTool } from "./toggle-subscriber-updates
  */
 export const registerTools = (server: McpServer) => {
   registerAddTool(server);
+  registerAnnotatedMessageTool(server);
   registerEchoTool(server);
   registerGetTinyImageTool(server);
   registerLongRunningOperationTool(server);