From 2ce87b168ce005daed4e3aff6b77af63e31d59ce Mon Sep 17 00:00:00 2001 From: cliffhall Date: Tue, 9 Dec 2025 10:17:37 -0500 Subject: [PATCH] [WIP] Refactor everything server to be more modular and use recommended APIs. * Added git-tiny-image.ts - registers a tool that returns a tiny MCP logo * In all other tools, updated function docs --- src/everything/docs/architecture.md | 23 ++++++--- src/everything/tools/add.ts | 10 ++-- src/everything/tools/echo.ts | 6 +-- src/everything/tools/get-tiny-image.ts | 47 +++++++++++++++++++ src/everything/tools/index.ts | 2 + .../tools/long-running-operation.ts | 5 +- src/everything/tools/print-env.ts | 7 +-- src/everything/tools/sampling-request.ts | 7 ++- src/everything/tools/toggle-logging.ts | 5 +- .../tools/toggle-subscriber-updates.ts | 6 +-- 10 files changed, 89 insertions(+), 29 deletions(-) create mode 100644 src/everything/tools/get-tiny-image.ts diff --git a/src/everything/docs/architecture.md b/src/everything/docs/architecture.md index c76a811e..e42196e0 100644 --- a/src/everything/docs/architecture.md +++ b/src/everything/docs/architecture.md @@ -24,27 +24,33 @@ src/everything │ ├── logging.ts │ └── everything.ts ├── transports -│ ├── stdio.ts │ ├── sse.ts +│ ├── stdio.ts │ └── streamableHttp.ts ├── tools │ ├── index.ts +│ ├── add.ts │ ├── echo.ts -│ └── add.ts +│ ├── get-tiny-image.ts +│ ├── long-running-operation.ts +│ ├── print-env.ts +│ ├── sampling-request.ts +│ ├── toggle-logging.ts +│ └── toggle-subscriber-updates.ts ├── prompts │ ├── index.ts -│ ├── simple.ts │ ├── args.ts │ ├── completions.ts +│ ├── simple.ts │ └── resource.ts ├── resources │ ├── index.ts -│ ├── templates.ts │ ├── files.ts -│ └── subscriptions.ts +│ ├── subscriptions.ts +│ └── templates.ts ├── docs -│ ├── server-instructions.md -│ └── architecture.md +│ ├── architecture.md +│ └── server-instructions.md └── package.json ``` @@ -88,6 +94,8 @@ At `src/everything`: - 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 @@ -175,6 +183,7 @@ At `src/everything`: - `add` (tools/add.ts): Adds two numbers `a` and `b` and returns their sum. Uses Zod to validate inputs. - `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. - `print-env` (tools/print-env.ts): Returns all environment variables from the running process as pretty-printed JSON text. - `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/add.ts b/src/everything/tools/add.ts index 261c117d..e6819c9f 100644 --- a/src/everything/tools/add.ts +++ b/src/everything/tools/add.ts @@ -17,17 +17,17 @@ const config = { }; /** - * Registers a tool on the given server to handle addition operations. - * - * @param {McpServer} server - The server instance where the addition tool will be registered. - * + * Registers the 'add' 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. * - * The tool expects input arguments to conform to a specific schema that includes two numeric properties, `a` and `b`. + * 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. */ export const registerAddTool = (server: McpServer) => { server.registerTool(name, config, async (args): Promise => { diff --git a/src/everything/tools/echo.ts b/src/everything/tools/echo.ts index 23501dc3..c7fe3eff 100644 --- a/src/everything/tools/echo.ts +++ b/src/everything/tools/echo.ts @@ -16,10 +16,10 @@ const config = { }; /** - * Registers the Echo Tool with the provided McpServer instance. + * Registers the 'echo' Tool with the provided McpServer instance. * - * The Echo Tool validates input arguments using the EchoSchema and returns - * a response that echoes the message provided in the arguments. + * The registered tool validates input arguments using the EchoSchema and + * returns a response that echoes the message provided in the arguments. * * @param {McpServer} server - The server instance where the Echo Tool will be registered. * @returns {void} diff --git a/src/everything/tools/get-tiny-image.ts b/src/everything/tools/get-tiny-image.ts new file mode 100644 index 00000000..36baf90c --- /dev/null +++ b/src/everything/tools/get-tiny-image.ts @@ -0,0 +1,47 @@ +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; + +// A tiny encoded MCP logo image +export const MCP_TINY_IMAGE = + "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"; + +// Tool configuration +const name = "get-tiny-image"; +const config = { + title: "Get Tiny Image Tool", + description: "Returns a tiny MCP logo image.", + inputSchema: {}, +}; + +/** + * Registers the "get-tiny-image" tool with the provided McpServer instance. + * + * The registered tool returns a response containing a small image alongside some + * descriptive text. + * + * The response structure includes textual content before and after the image. + * The image is served as a PNG data type and represents the default MCP tiny image. + * + * @param server - An instance of McpServer where the tool will be registered. + */ +export const registerGetTinyImageTool = (server: McpServer) => { + server.registerTool(name, config, async (args): Promise => { + return { + content: [ + { + type: "text", + text: "Here's the image you requested:", + }, + { + type: "image", + data: MCP_TINY_IMAGE, + mimeType: "image/png", + }, + { + type: "text", + text: "The image above is the MCP logo.", + }, + ], + }; + }); +}; diff --git a/src/everything/tools/index.ts b/src/everything/tools/index.ts index 8e550bf0..dcbdab9e 100644 --- a/src/everything/tools/index.ts +++ b/src/everything/tools/index.ts @@ -1,6 +1,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { registerAddTool } from "./add.js"; import { registerEchoTool } from "./echo.js"; +import { registerGetTinyImageTool } from "./get-tiny-image.js"; import { registerLongRunningOperationTool } from "./long-running-operation.js"; import { registerPrintEnvTool } from "./print-env.js"; import { registerSamplingRequestTool } from "./sampling-request.js"; @@ -14,6 +15,7 @@ import { registerToggleSubscriberUpdatesTool } from "./toggle-subscriber-updates export const registerTools = (server: McpServer) => { registerAddTool(server); registerEchoTool(server); + registerGetTinyImageTool(server); registerLongRunningOperationTool(server); registerPrintEnvTool(server); registerSamplingRequestTool(server); diff --git a/src/everything/tools/long-running-operation.ts b/src/everything/tools/long-running-operation.ts index f2fff4af..1b4037ad 100644 --- a/src/everything/tools/long-running-operation.ts +++ b/src/everything/tools/long-running-operation.ts @@ -20,13 +20,14 @@ const config = { }; /** - * Registers a tool to demonstrate long-running operations on the server. + * Registers the 'long-running-operation' tool with the provided McpServer instance. * * This function defines and registers a tool with the provided server instance that performs a * long-running operation defined by a specific duration and number of steps. The progress * of the operation is reported back to the client through notifications. * - * The tool processes the operation in steps, with each step having equal duration. + * The registered tool processes the operation in steps, with each step having equal duration. + * * Progress notifications are sent back to the client at each step, if a `progressToken` * is provided in the metadata. At the end of the operation, the tool returns a message * indicating the completion of the operation, including the total duration and steps. diff --git a/src/everything/tools/print-env.ts b/src/everything/tools/print-env.ts index 5f7f4e0d..421f51fb 100644 --- a/src/everything/tools/print-env.ts +++ b/src/everything/tools/print-env.ts @@ -11,9 +11,10 @@ const config = { }; /** - * Registers the Echo Tool with the given MCP server. This tool, when invoked, - * retrieves and returns the environment variables of the current process - * as a JSON-formatted string encapsulated in a text response. + * Registers the 'print-env' tool with the given MCP server. + * + * The registered tool Retrieves and returns the environment variables + * of the current process as a JSON-formatted string encapsulated in a text response. * * @param {McpServer} server - The MCP server instance where the Echo Tool is to be registered. * @returns {void} diff --git a/src/everything/tools/sampling-request.ts b/src/everything/tools/sampling-request.ts index 88c1faa3..24a55403 100644 --- a/src/everything/tools/sampling-request.ts +++ b/src/everything/tools/sampling-request.ts @@ -24,11 +24,10 @@ const config = { }; /** - * Registers a sampling request tool within the given MCP server. + * Registers the 'sampling-request' tool within the provided McpServer instance. * - * This tool allows the server to handle sampling requests by parsing input - * arguments, generating a sampling request for an LLM, and returning the - * result to the client. + * Allows the server to handle sampling requests by parsing input arguments, + * generating a sampling request for an LLM, and returning the result to the client. * * The registered tool performs the following operations: * - Validates incoming arguments using `SampleLLMSchema`. diff --git a/src/everything/tools/toggle-logging.ts b/src/everything/tools/toggle-logging.ts index f14d7f3a..f46b2184 100644 --- a/src/everything/tools/toggle-logging.ts +++ b/src/everything/tools/toggle-logging.ts @@ -18,8 +18,9 @@ const clients: Set = new Set(); /** * Registers the `toggle-subscriber-updates` tool with the provided MCP server. - * This tool enables or disables sending of periodic, random-leveled logging - * messages the connected client. + * + * The registered tool enables or disables the sending of periodic, random-leveled + * logging messages the connected client. * * When invoked, it either starts or stops simulated logging based on the session's * current state. If logging for the specified session is active, it will be stopped; diff --git a/src/everything/tools/toggle-subscriber-updates.ts b/src/everything/tools/toggle-subscriber-updates.ts index d99303e7..44772351 100644 --- a/src/everything/tools/toggle-subscriber-updates.ts +++ b/src/everything/tools/toggle-subscriber-updates.ts @@ -21,9 +21,9 @@ const clients: Set = new Set(); * This tool enables or disables simulated resource update notifications for a client. * * - * Toggles the state of the updates based on whether the session is already active. - * When enabled, the simulated resource updates are sent to the client at a regular interval. - * When disabled, updates are stopped for the session. + * The registered tool toggles the state of the updates based on whether the session is already active. + * - When enabled, the simulated resource updates are sent to the client at a regular interval. + * - When disabled, updates are stopped for the session. * * The response provides feedback indicating whether simulated updates were started or stopped, * including the session ID.