From f759d9eaa1192a1d950971077dca55230f83485a Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 10 Dec 2025 16:08:41 -0500 Subject: [PATCH] [WIP] Refactor everything server to be more modular and use recommended APIs. For tools where we seek to get some response from the server, renamed as an action, e.g., "Get Sum" rather than "Add" or "Get Annotated Message" rather than "Annotated Message", so that it's clear what the intent of the tool is in a quick review. * Updated architecture.md * Refactor/renamed add.ts to get-sum.ts * Refactor/renamed annotated-message.ts to get-annotated-message.ts * In tools/index.ts - sorted presentation order --- src/everything/docs/architecture.md | 16 +++++++-------- ...ed-message.ts => get-annotated-message.ts} | 12 +++++------ src/everything/tools/{add.ts => get-sum.ts} | 20 +++++++++---------- src/everything/tools/index.ts | 10 +++++----- 4 files changed, 29 insertions(+), 29 deletions(-) rename src/everything/tools/{annotated-message.ts => get-annotated-message.ts} (89%) rename src/everything/tools/{add.ts => get-sum.ts} (67%) diff --git a/src/everything/docs/architecture.md b/src/everything/docs/architecture.md index 18e904a7..e6088e48 100644 --- a/src/everything/docs/architecture.md +++ b/src/everything/docs/architecture.md @@ -43,14 +43,14 @@ src/everything │ └── streamableHttp.ts ├── tools │ ├── index.ts -│ ├── add.ts -│ ├── annotated-message.ts │ ├── echo.ts +│ ├── get-annotated-message.ts │ ├── get-env.ts │ ├── get-tiny-image.ts │ ├── get-resource-links.ts │ ├── get-resource-reference.ts │ ├── get-structured-content.ts +│ ├── get-sum.ts │ ├── long-running-operation.ts │ ├── sampling-request.ts │ ├── toggle-logging.ts @@ -95,16 +95,16 @@ At `src/everything`: - index.ts - `registerTools(server)` orchestrator; delegates to basic tools and control tools. - - 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-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. - get-env.ts - Registers a `get-env` tool that returns the current process environment variables as formatted JSON text; useful for debugging configuration. - 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. + - get-sum.ts + - Registers an `get-sum` tool with a Zod input schema that sums two numbers `a` and `b` and returns the result. - 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`. - sampling-request.ts @@ -188,13 +188,13 @@ 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-annotated-message` (tools/get-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`. - `get-env` (tools/get-env.ts): Returns all environment variables from the running process as pretty-printed JSON text. - `get-resource-links` (tools/get-resource-links.ts): Returns an intro `text` block followed by multiple `resource_link` items. For a requested `count` (1–10), alternates between dynamic Text and Blob resources using URIs from `resources/templates.ts`. - `get-resource-reference` (tools/get-resource-reference.ts): Accepts `resourceType` (`text` or `blob`) and `resourceId` (positive integer). Returns a concrete `resource` content block (with its `uri`, `mimeType`, and data) with surrounding explanatory `text`. - `get-structured-content` (tools/get-structured-content.ts): Demonstrates structured responses. Accepts `location` input and returns both backward‑compatible `content` (a `text` block containing JSON) and `structuredContent` validated by an `outputSchema` (temperature, conditions, humidity). + - `get-sum` (tools/get-sum.ts): For two numbers `a` and `b` calculates and returns their sum. 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. - `sampling-request` (tools/sampling-request.ts): Issues a `sampling/createMessage` request to the client/LLM using provided `prompt` and optional generation controls; returns the LLM’s response payload. diff --git a/src/everything/tools/annotated-message.ts b/src/everything/tools/get-annotated-message.ts similarity index 89% rename from src/everything/tools/annotated-message.ts rename to src/everything/tools/get-annotated-message.ts index bb1389c2..b440d069 100644 --- a/src/everything/tools/annotated-message.ts +++ b/src/everything/tools/get-annotated-message.ts @@ -4,7 +4,7 @@ import { z } from "zod"; import { MCP_TINY_IMAGE } from "./get-tiny-image.js"; // Tool input schema -const AnnotatedMessageSchema = z.object({ +const GetAnnotatedMessageSchema = z.object({ messageType: z .enum(["error", "success", "debug"]) .describe("Type of message to demonstrate different annotation patterns"), @@ -15,12 +15,12 @@ const AnnotatedMessageSchema = z.object({ }); // Tool configuration -const name = "annotated-message"; +const name = "get-annotated-message"; const config = { - title: "Annotated Message Tool", + title: "Get Annotated Message Tool", description: "Demonstrates how annotations can be used to provide metadata about content.", - inputSchema: AnnotatedMessageSchema, + inputSchema: GetAnnotatedMessageSchema, }; /** @@ -35,9 +35,9 @@ const config = { * @function * @param {McpServer} server - The MCP server instance where the Annotated Message Tool is to be registered. */ -export const registerAnnotatedMessageTool = (server: McpServer) => { +export const registerGetAnnotatedMessageTool = (server: McpServer) => { server.registerTool(name, config, async (args): Promise => { - const { messageType, includeImage } = AnnotatedMessageSchema.parse(args); + const { messageType, includeImage } = GetAnnotatedMessageSchema.parse(args); const content: CallToolResult["content"] = []; diff --git a/src/everything/tools/add.ts b/src/everything/tools/get-sum.ts similarity index 67% rename from src/everything/tools/add.ts rename to src/everything/tools/get-sum.ts index e6819c9f..b292dccb 100644 --- a/src/everything/tools/add.ts +++ b/src/everything/tools/get-sum.ts @@ -3,35 +3,35 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; // Tool input schema -const AddSchema = z.object({ +const GetSumSchema = z.object({ a: z.number().describe("First number"), b: z.number().describe("Second number"), }); // Tool configuration -const name = "add"; +const name = "get-sum"; const config = { - title: "Add Tool", - description: "Adds two numbers", - inputSchema: AddSchema, + title: "Get Sum Tool", + description: "Gets the sum of two numbers", + inputSchema: GetSumSchema, }; /** - * Registers the 'add' tool with the provided McpServer instance. + * Registers the 'get-sum' tool with the provided McpServer instance. ** * The registered tool processes input arguments, validates them using a predefined schema, - * performs addition on two numeric values, and returns the result in a structured format. + * calculates the sum of two numeric values, and returns the result in a content block. * * Expects input arguments to conform to a specific schema that includes two numeric properties, `a` and `b`. * Validation is performed to ensure the input adheres to the expected structure before calculating the sum. * * The result is returned as a Promise resolving to an object containing the computed sum in a text format. * - * @param {McpServer} server - The server instance where the addition tool will be registered. + * @param {McpServer} server - The server instance where the sum tool will be registered. */ -export const registerAddTool = (server: McpServer) => { +export const registerGetSumTool = (server: McpServer) => { server.registerTool(name, config, async (args): Promise => { - const validatedArgs = AddSchema.parse(args); + const validatedArgs = GetSumSchema.parse(args); const sum = validatedArgs.a + validatedArgs.b; return { content: [ diff --git a/src/everything/tools/index.ts b/src/everything/tools/index.ts index 8cbf087d..603defaf 100644 --- a/src/everything/tools/index.ts +++ b/src/everything/tools/index.ts @@ -1,29 +1,29 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; -import { registerAddTool } from "./add.js"; -import { registerAnnotatedMessageTool } from "./annotated-message.js"; +import { registerGetAnnotatedMessageTool } from "./get-annotated-message.js"; import { registerEchoTool } from "./echo.js"; import { registerGetEnvTool } from "./get-env.js"; import { registerGetResourceLinksTool } from "./get-resource-links.js"; import { registerGetResourceReferenceTool } from "./get-resource-reference.js"; +import { registerGetStructuredContentTool } from "./get-structured-content.js"; +import { registerGetSumTool } from "./get-sum.js"; import { registerGetTinyImageTool } from "./get-tiny-image.js"; import { registerLongRunningOperationTool } from "./long-running-operation.js"; import { registerSamplingRequestTool } from "./sampling-request.js"; import { registerToggleLoggingTool } from "./toggle-logging.js"; import { registerToggleSubscriberUpdatesTool } from "./toggle-subscriber-updates.js"; -import { registerGetStructuredContentTool } from "./get-structured-content.js"; /** * Register the tools with the MCP server. * @param server */ export const registerTools = (server: McpServer) => { - registerAddTool(server); - registerAnnotatedMessageTool(server); registerEchoTool(server); + registerGetAnnotatedMessageTool(server); registerGetEnvTool(server); registerGetResourceLinksTool(server); registerGetResourceReferenceTool(server); registerGetStructuredContentTool(server); + registerGetSumTool(server); registerGetTinyImageTool(server); registerLongRunningOperationTool(server); registerSamplingRequestTool(server);