@modelcontextprotocol/server-everything 2025.12.18 → 2026.1.14

package/dist/resources/templates.js

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
+// Resource types
+export const RESOURCE_TYPE_TEXT = "Text";
+export const RESOURCE_TYPE_BLOB = "Blob";
+export const RESOURCE_TYPES = [
+    RESOURCE_TYPE_TEXT,
+    RESOURCE_TYPE_BLOB,
+];
+/**
+ * A completer function for resource types.
+ *
+ * This variable provides functionality to perform autocompletion for the resource types based on user input.
+ * It uses a schema description to validate the input and filters through a predefined list of resource types
+ * to return suggestions that start with the given input.
+ *
+ * The input value is expected to be a string representing the type of resource to fetch.
+ * The completion logic matches the input against available resource types.
+ */
+export const resourceTypeCompleter = completable(z.string().describe("Type of resource to fetch"), (value) => {
+    return RESOURCE_TYPES.filter((t) => t.startsWith(value));
+});
+/**
+ * A completer function for resource IDs as strings.
+ *
+ * The `resourceIdCompleter` accepts a string input representing the ID of a text resource
+ * and validates whether the provided value corresponds to an integer resource ID.
+ *
+ * NOTE: Currently, prompt arguments can only be strings since type is not field of `PromptArgument`
+ * Consequently, we must define it as a string and convert the argument to number before using it
+ * https://modelcontextprotocol.io/specification/2025-11-25/schema#promptargument
+ *
+ * If the value is a valid integer, it returns the value within an array.
+ * Otherwise, it returns an empty array.
+ *
+ * The input string is first transformed into a number and checked to ensure it is an integer.
+ * This helps validate and suggest appropriate resource IDs.
+ */
+export const resourceIdForPromptCompleter = completable(z.string().describe("ID of the text resource to fetch"), (value) => {
+    const resourceId = Number(value);
+    return Number.isInteger(resourceId) && resourceId > 0 ? [value] : [];
+});
+/**
+ * A callback function that acts as a completer for resource ID values, validating and returning
+ * the input value as part of a resource template.
+ *
+ * @typedef {CompleteResourceTemplateCallback}
+ * @param {string} value - The input string value to be evaluated as a resource ID.
+ * @returns {string[]} Returns an array containing the input value if it represents a positive
+ * integer resource ID, otherwise returns an empty array.
+ */
+export const resourceIdForResourceTemplateCompleter = (value) => {
+    const resourceId = Number(value);
+    return Number.isInteger(resourceId) && resourceId > 0 ? [value] : [];
+};
+const uriBase = "demo://resource/dynamic";
+const textUriBase = `${uriBase}/text`;
+const blobUriBase = `${uriBase}/blob`;
+const textUriTemplate = `${textUriBase}/{resourceId}`;
+const blobUriTemplate = `${blobUriBase}/{resourceId}`;
+/**
+ * Create a dynamic text resource
+ * - Exposed for use by embedded resource prompt example
+ * @param uri
+ * @param resourceId
+ */
+export const textResource = (uri, resourceId) => {
+    const timestamp = new Date().toLocaleTimeString();
+    return {
+        uri: uri.toString(),
+        mimeType: "text/plain",
+        text: `Resource ${resourceId}: This is a plaintext resource created at ${timestamp}`,
+    };
+};
+/**
+ * Create a dynamic blob resource
+ * - Exposed for use by embedded resource prompt example
+ * @param uri
+ * @param resourceId
+ */
+export const blobResource = (uri, resourceId) => {
+    const timestamp = new Date().toLocaleTimeString();
+    const resourceText = Buffer.from(`Resource ${resourceId}: This is a base64 blob created at ${timestamp}`).toString("base64");
+    return {
+        uri: uri.toString(),
+        mimeType: "text/plain",
+        blob: resourceText,
+    };
+};
+/**
+ * Create a dynamic text resource URI
+ * - Exposed for use by embedded resource prompt example
+ * @param resourceId
+ */
+export const textResourceUri = (resourceId) => new URL(`${textUriBase}/${resourceId}`);
+/**
+ * Create a dynamic blob resource URI
+ * - Exposed for use by embedded resource prompt example
+ * @param resourceId
+ */
+export const blobResourceUri = (resourceId) => new URL(`${blobUriBase}/${resourceId}`);
+/**
+ * Parses the resource identifier from the provided URI and validates it
+ * against the given variables. Throws an error if the URI corresponds
+ * to an unknown resource or if the resource identifier is invalid.
+ *
+ * @param {URL} uri - The URI of the resource to be parsed.
+ * @param {Record<string, unknown>} variables - A record containing context-specific variables that include the resourceId.
+ * @returns {number} The parsed and validated resource identifier as an integer.
+ * @throws {Error} Throws an error if the URI matches unsupported base URIs or if the resourceId is invalid.
+ */
+const parseResourceId = (uri, variables) => {
+    const uriError = `Unknown resource: ${uri.toString()}`;
+    if (uri.toString().startsWith(textUriBase) &&
+        uri.toString().startsWith(blobUriBase)) {
+        throw new Error(uriError);
+    }
+    else {
+        const idxStr = String(variables.resourceId ?? "");
+        const idx = Number(idxStr);
+        if (Number.isFinite(idx) && Number.isInteger(idx) && idx > 0) {
+            return idx;
+        }
+        else {
+            throw new Error(uriError);
+        }
+    }
+};
+/**
+ * Register resource templates with the MCP server.
+ * - Text and blob resources, dynamically generated from the URI {resourceId} variable
+ * - Any finite positive integer is acceptable for the resourceId variable
+ * - List resources method will not return these resources
+ * - These are only accessible via template URIs
+ * - Both blob and text resources:
+ *   - have content that is dynamically generated, including a timestamp
+ *   - have different template URIs
+ *     - Blob: "demo://resource/dynamic/blob/{resourceId}"
+ *     - Text: "demo://resource/dynamic/text/{resourceId}"
+ *
+ * @param server
+ */
+export const registerResourceTemplates = (server) => {
+    // Register the text resource template
+    server.registerResource("Dynamic Text Resource", new ResourceTemplate(textUriTemplate, {
+        list: undefined,
+        complete: { resourceId: resourceIdForResourceTemplateCompleter },
+    }), {
+        mimeType: "text/plain",
+        description: "Plaintext dynamic resource fabricated from the {resourceId} variable, which must be an integer.",
+    }, async (uri, variables) => {
+        const resourceId = parseResourceId(uri, variables);
+        return {
+            contents: [textResource(uri, resourceId)],
+        };
+    });
+    // Register the blob resource template
+    server.registerResource("Dynamic Blob Resource", new ResourceTemplate(blobUriTemplate, {
+        list: undefined,
+        complete: { resourceId: resourceIdForResourceTemplateCompleter },
+    }), {
+        mimeType: "application/octet-stream",
+        description: "Binary (base64) dynamic resource fabricated from the {resourceId} variable, which must be an integer.",
+    }, async (uri, variables) => {
+        const resourceId = parseResourceId(uri, variables);
+        return {
+            contents: [blobResource(uri, resourceId)],
+        };
+    });
+};

package/dist/server/index.js

@@ -0,0 +1,73 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { setSubscriptionHandlers, stopSimulatedResourceUpdates, } from "../resources/subscriptions.js";
+import { registerConditionalTools, registerTools } from "../tools/index.js";
+import { registerResources, readInstructions } from "../resources/index.js";
+import { registerPrompts } from "../prompts/index.js";
+import { stopSimulatedLogging } from "./logging.js";
+import { syncRoots } from "./roots.js";
+/**
+ * Server Factory
+ *
+ * This function initializes a `McpServer` with specific capabilities and instructions,
+ * registers tools, resources, and prompts, and configures resource subscription handlers.
+ *
+ * @returns {ServerFactoryResponse} An object containing the server instance, and a `cleanup`
+ * function for handling server-side cleanup when a session ends.
+ *
+ * Properties of the returned object:
+ * - `server` {Object}: The initialized server instance.
+ * - `cleanup` {Function}: Function to perform cleanup operations for a closing session.
+ */
+export const createServer = () => {
+    // Read the server instructions
+    const instructions = readInstructions();
+    // Create the server
+    const server = new McpServer({
+        name: "mcp-servers/everything",
+        title: "Everything Reference Server",
+        version: "2.0.0",
+    }, {
+        capabilities: {
+            tools: {
+                listChanged: true,
+            },
+            prompts: {
+                listChanged: true,
+            },
+            resources: {
+                subscribe: true,
+                listChanged: true,
+            },
+            logging: {},
+        },
+        instructions,
+    });
+    // Register the tools
+    registerTools(server);
+    // Register the resources
+    registerResources(server);
+    // Register the prompts
+    registerPrompts(server);
+    // Set resource subscription handlers
+    setSubscriptionHandlers(server);
+    // Perform post-initialization operations
+    server.server.oninitialized = async () => {
+        // Register conditional tools now that client capabilities are known.
+        // This finishes before the `notifications/initialized` handler finishes.
+        registerConditionalTools(server);
+        // Sync roots if the client supports them.
+        // This is delayed until after the `notifications/initialized` handler finishes,
+        // otherwise, the request gets lost.
+        const sessionId = server.server.transport?.sessionId;
+        setTimeout(() => syncRoots(server, sessionId), 350);
+    };
+    // Return the ServerFactoryResponse
+    return {
+        server,
+        cleanup: (sessionId) => {
+            // Stop any simulated logging or resource updates that may have been initiated.
+            stopSimulatedLogging(sessionId);
+            stopSimulatedResourceUpdates(sessionId);
+        },
+    };
+};

package/dist/server/logging.js

@@ -0,0 +1,64 @@
+// Map session ID to the interval for sending logging messages to the client
+const logsUpdateIntervals = new Map();
+/**
+ * Initiates a simulated logging process by sending random log messages to the client at a
+ * fixed interval. Each log message contains a random logging level and optional session ID.
+ *
+ * @param {McpServer} server - The server instance responsible for handling the logging messages.
+ * @param {string | undefined} sessionId - An optional identifier for the session. If provided,
+ * the session ID will be appended to log messages.
+ */
+export const beginSimulatedLogging = (server, sessionId) => {
+    const maybeAppendSessionId = sessionId ? ` - SessionId ${sessionId}` : "";
+    const messages = [
+        { level: "debug", data: `Debug-level message${maybeAppendSessionId}` },
+        { level: "info", data: `Info-level message${maybeAppendSessionId}` },
+        { level: "notice", data: `Notice-level message${maybeAppendSessionId}` },
+        {
+            level: "warning",
+            data: `Warning-level message${maybeAppendSessionId}`,
+        },
+        { level: "error", data: `Error-level message${maybeAppendSessionId}` },
+        {
+            level: "critical",
+            data: `Critical-level message${maybeAppendSessionId}`,
+        },
+        { level: "alert", data: `Alert level-message${maybeAppendSessionId}` },
+        {
+            level: "emergency",
+            data: `Emergency-level message${maybeAppendSessionId}`,
+        },
+    ];
+    /**
+     * Send a simulated logging message to the client
+     */
+    const sendSimulatedLoggingMessage = async (sessionId) => {
+        // By using the `sendLoggingMessage` function to send the message, we
+        // ensure that the client's chosen logging level will be respected
+        await server.sendLoggingMessage(messages[Math.floor(Math.random() * messages.length)], sessionId);
+    };
+    // Set the interval to send later logging messages to this client
+    if (!logsUpdateIntervals.has(sessionId)) {
+        // Send once immediately
+        sendSimulatedLoggingMessage(sessionId);
+        // Send a randomly-leveled log message every 5 seconds
+        logsUpdateIntervals.set(sessionId, setInterval(() => sendSimulatedLoggingMessage(sessionId), 5000));
+    }
+};
+/**
+ * Stops the simulated logging process for a given session.
+ *
+ * This function halts the periodic logging updates associated with the specified
+ * session ID by clearing the interval and removing the session's tracking
+ * reference. Session ID can be undefined for stdio.
+ *
+ * @param {string} [sessionId] - The optional unique identifier of the session.
+ */
+export const stopSimulatedLogging = (sessionId) => {
+    // Remove active intervals
+    if (logsUpdateIntervals.has(sessionId)) {
+        const logsUpdateInterval = logsUpdateIntervals.get(sessionId);
+        clearInterval(logsUpdateInterval);
+        logsUpdateIntervals.delete(sessionId);
+    }
+};

package/dist/server/roots.js

@@ -0,0 +1,69 @@
+import { RootsListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+// Track roots by session id
+export const roots = new Map();
+/**
+ * Get the latest the client roots list for the session.
+ *
+ * - Request and cache the roots list for the session if it has not been fetched before.
+ * - Return the cached roots list for the session if it exists.
+ *
+ * When requesting the roots list for a session, it also sets up a `roots/list_changed`
+ * notification handler. This ensures that updates are automatically fetched and handled
+ * in real-time.
+ *
+ * This function is idempotent. It should only request roots from the client once per session,
+ * returning the cached version thereafter.
+ *
+ * @param {McpServer} server - An instance of the MCP server used to communicate with the client.
+ * @param {string} [sessionId] - An optional session id used to associate the roots list with a specific client session.
+ *
+ * @throws {Error} In case of a failure to request the roots from the client, an error log message is sent.
+ */
+export const syncRoots = async (server, sessionId) => {
+    const clientCapabilities = server.server.getClientCapabilities() || {};
+    const clientSupportsRoots = clientCapabilities?.roots !== undefined;
+    // Fetch the roots list for this client
+    if (clientSupportsRoots) {
+        // Function to request the updated roots list from the client
+        const requestRoots = async () => {
+            try {
+                // Request the updated roots list from the client
+                const response = await server.server.listRoots();
+                if (response && "roots" in response) {
+                    // Store the roots list for this client
+                    roots.set(sessionId, response.roots);
+                    // Notify the client of roots received
+                    await server.sendLoggingMessage({
+                        level: "info",
+                        logger: "everything-server",
+                        data: `Roots updated: ${response?.roots?.length} root(s) received from client`,
+                    }, sessionId);
+                }
+                else {
+                    await server.sendLoggingMessage({
+                        level: "info",
+                        logger: "everything-server",
+                        data: "Client returned no roots set",
+                    }, sessionId);
+                }
+            }
+            catch (error) {
+                await server.sendLoggingMessage({
+                    level: "error",
+                    logger: "everything-server",
+                    data: `Failed to request roots from client: ${error instanceof Error ? error.message : String(error)}`,
+                }, sessionId);
+            }
+        };
+        // If the roots have not been synced for this client,
+        // set notification handler and request initial roots
+        if (!roots.has(sessionId)) {
+            // Set the list changed notification handler
+            server.server.setNotificationHandler(RootsListChangedNotificationSchema, requestRoots);
+            // Request the initial roots list immediately
+            await requestRoots();
+        }
+        // Return the roots list for this client
+        return roots.get(sessionId);
+    }
+};

package/dist/tools/echo.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+// Tool input schema
+export const EchoSchema = z.object({
+    message: z.string().describe("Message to echo"),
+});
+// Tool configuration
+const name = "echo";
+const config = {
+    title: "Echo Tool",
+    description: "Echoes back the input string",
+    inputSchema: EchoSchema,
+};
+/**
+ * Registers the 'echo' tool.
+ *
+ * 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 McpServer instance where the tool will be registered.
+ * @returns {void}
+ */
+export const registerEchoTool = (server) => {
+    server.registerTool(name, config, async (args) => {
+        const validatedArgs = EchoSchema.parse(args);
+        return {
+            content: [{ type: "text", text: `Echo: ${validatedArgs.message}` }],
+        };
+    });
+};

package/dist/tools/get-annotated-message.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { MCP_TINY_IMAGE } from "./get-tiny-image.js";
+// Tool input schema
+const GetAnnotatedMessageSchema = 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 = "get-annotated-message";
+const config = {
+    title: "Get Annotated Message Tool",
+    description: "Demonstrates how annotations can be used to provide metadata about content.",
+    inputSchema: GetAnnotatedMessageSchema,
+};
+/**
+ * Registers the 'get-annotated-message' tool.
+ *
+ * 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.
+ *
+ * The response will have annotations and optionally contain an annotated image.
+ *
+ * @function
+ * @param {McpServer} server - The McpServer instance where the tool will be registered.
+ */
+export const registerGetAnnotatedMessageTool = (server) => {
+    server.registerTool(name, config, async (args) => {
+        const { messageType, includeImage } = GetAnnotatedMessageSchema.parse(args);
+        const 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 };
+    });
+};

package/dist/tools/get-env.js

@@ -0,0 +1,28 @@
+// Tool configuration
+const name = "get-env";
+const config = {
+    title: "Print Environment Tool",
+    description: "Returns all environment variables, helpful for debugging MCP server configuration",
+    inputSchema: {},
+};
+/**
+ * Registers the 'get-env' tool.
+ *
+ * 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 McpServer instance where the tool will be registered.
+ * @returns {void}
+ */
+export const registerGetEnvTool = (server) => {
+    server.registerTool(name, config, async (args) => {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(process.env, null, 2),
+                },
+            ],
+        };
+    });
+};

package/dist/tools/get-resource-links.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { textResource, textResourceUri, blobResourceUri, blobResource, } from "../resources/templates.js";
+// Tool input schema
+const GetResourceLinksSchema = z.object({
+    count: z
+        .number()
+        .min(1)
+        .max(10)
+        .default(3)
+        .describe("Number of resource links to return (1-10)"),
+});
+// Tool configuration
+const name = "get-resource-links";
+const config = {
+    title: "Get Resource Links Tool",
+    description: "Returns up to ten resource links that reference different types of resources",
+    inputSchema: GetResourceLinksSchema,
+};
+/**
+ * Registers the 'get-resource-reference' tool.
+ *
+ * The registered tool retrieves a specified number of resource links and their metadata.
+ * Resource links are dynamically generated as either text or binary blob resources,
+ * based on their ID being even or odd.
+
+ * The response contains a "text" introductory block and multiple "resource_link" blocks.
+ *
+ * @param {McpServer} server - The McpServer instance where the tool will be registered.
+ */
+export const registerGetResourceLinksTool = (server) => {
+    server.registerTool(name, config, async (args) => {
+        const { count } = GetResourceLinksSchema.parse(args);
+        // Add intro text content block
+        const content = [];
+        content.push({
+            type: "text",
+            text: `Here are ${count} resource links to resources available in this server:`,
+        });
+        // Create resource link content blocks
+        for (let resourceId = 1; resourceId <= count; resourceId++) {
+            // Get resource uri for text or blob resource based on odd/even resourceId
+            const isOdd = resourceId % 2 === 0;
+            const uri = isOdd
+                ? textResourceUri(resourceId)
+                : blobResourceUri(resourceId);
+            // Get resource based on the resource type
+            const resource = isOdd
+                ? textResource(uri, resourceId)
+                : blobResource(uri, resourceId);
+            content.push({
+                type: "resource_link",
+                uri: resource.uri,
+                name: `${isOdd ? "Text" : "Blob"} Resource ${resourceId}`,
+                description: `Resource ${resourceId}: ${resource.mimeType === "text/plain"
+                    ? "plaintext resource"
+                    : "binary blob resource"}`,
+                mimeType: resource.mimeType,
+            });
+        }
+        return { content };
+    });
+};

package/dist/tools/get-resource-reference.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { textResource, textResourceUri, blobResourceUri, blobResource, RESOURCE_TYPE_BLOB, RESOURCE_TYPE_TEXT, RESOURCE_TYPES, } from "../resources/templates.js";
+// Tool input schema
+const GetResourceReferenceSchema = z.object({
+    resourceType: z
+        .enum([RESOURCE_TYPE_TEXT, RESOURCE_TYPE_BLOB])
+        .default(RESOURCE_TYPE_TEXT),
+    resourceId: z
+        .number()
+        .default(1)
+        .describe("ID of the text resource to fetch"),
+});
+// Tool configuration
+const name = "get-resource-reference";
+const config = {
+    title: "Get Resource Reference Tool",
+    description: "Returns a resource reference that can be used by MCP clients",
+    inputSchema: GetResourceReferenceSchema,
+};
+/**
+ * Registers the 'get-resource-reference' tool.
+ *
+ * The registered tool validates and processes arguments for retrieving a resource
+ * reference. Supported resource types include predefined `RESOURCE_TYPE_TEXT` and
+ * `RESOURCE_TYPE_BLOB`. The retrieved resource's reference will include the resource
+ * ID, type, and its associated URI.
+ *
+ * The tool performs the following operations:
+ * 1. Validates the `resourceType` argument to ensure it matches a supported type.
+ * 2. Validates the `resourceId` argument to ensure it is a finite positive integer.
+ * 3. Constructs a URI for the resource based on its type (text or blob).
+ * 4. Retrieves the resource and returns it in a content block.
+ *
+ * @param {McpServer} server - The McpServer instance where the tool will be registered.
+ */
+export const registerGetResourceReferenceTool = (server) => {
+    server.registerTool(name, config, async (args) => {
+        // Validate resource type argument
+        const { resourceType } = args;
+        if (!RESOURCE_TYPES.includes(resourceType)) {
+            throw new Error(`Invalid resourceType: ${args?.resourceType}. Must be ${RESOURCE_TYPE_TEXT} or ${RESOURCE_TYPE_BLOB}.`);
+        }
+        // Validate resourceId argument
+        const resourceId = Number(args?.resourceId);
+        if (!Number.isFinite(resourceId) ||
+            !Number.isInteger(resourceId) ||
+            resourceId < 1) {
+            throw new Error(`Invalid resourceId: ${args?.resourceId}. Must be a finite positive integer.`);
+        }
+        // Get resource based on the resource type
+        const uri = resourceType === RESOURCE_TYPE_TEXT
+            ? textResourceUri(resourceId)
+            : blobResourceUri(resourceId);
+        const resource = resourceType === RESOURCE_TYPE_TEXT
+            ? textResource(uri, resourceId)
+            : blobResource(uri, resourceId);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Returning resource reference for Resource ${resourceId}:`,
+                },
+                {
+                    type: "resource",
+                    resource: resource,
+                },
+                {
+                    type: "text",
+                    text: `You can access this resource using the URI: ${resource.uri}`,
+                },
+            ],
+        };
+    });
+};