@modelcontextprotocol/server-everything 2025.12.18 → 2026.1.26

package/dist/tools/simulate-research-query.js

@@ -0,0 +1,249 @@
+import { z } from "zod";
+import { ElicitResultSchema, } from "@modelcontextprotocol/sdk/types.js";
+// Tool input schema
+const SimulateResearchQuerySchema = z.object({
+    topic: z.string().describe("The research topic to investigate"),
+    ambiguous: z
+        .boolean()
+        .default(false)
+        .describe("Simulate an ambiguous query that requires clarification (triggers input_required status)"),
+});
+// Research stages
+const STAGES = [
+    "Gathering sources",
+    "Analyzing content",
+    "Synthesizing findings",
+    "Generating report",
+];
+// Duration per stage in milliseconds
+const STAGE_DURATION = 1000;
+// Map to store research state per task
+const researchStates = new Map();
+/**
+ * Runs the background research process.
+ * Updates task status as it progresses through stages.
+ * If clarification is needed, attempts elicitation via sendRequest.
+ *
+ * Note: Elicitation only works on STDIO transport. On HTTP transport,
+ * sendRequest will fail and the task will use a default interpretation.
+ * Full HTTP support requires SDK PR #1210's elicitInputStream API.
+ */
+async function runResearchProcess(taskId, args, taskStore, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+sendRequest) {
+    const state = researchStates.get(taskId);
+    if (!state)
+        return;
+    // Process each stage
+    for (let i = state.currentStage; i < STAGES.length; i++) {
+        state.currentStage = i;
+        // Check if task was cancelled externally
+        if (state.completed)
+            return;
+        // Update status message for current stage
+        await taskStore.updateTaskStatus(taskId, "working", `${STAGES[i]}...`);
+        // At synthesis stage (index 2), check if clarification is needed
+        if (i === 2 && state.ambiguous && !state.clarification) {
+            // Update status to show we're requesting input (spec SHOULD)
+            await taskStore.updateTaskStatus(taskId, "input_required", `Found multiple interpretations for "${state.topic}". Requesting clarification...`);
+            try {
+                // Try elicitation via sendRequest (works on STDIO, fails on HTTP)
+                const elicitResult = await sendRequest({
+                    method: "elicitation/create",
+                    params: {
+                        message: `The research query "${state.topic}" could have multiple interpretations. Please clarify what you're looking for:`,
+                        requestedSchema: {
+                            type: "object",
+                            properties: {
+                                interpretation: {
+                                    type: "string",
+                                    title: "Clarification",
+                                    description: "Which interpretation of the topic do you mean?",
+                                    oneOf: getInterpretationsForTopic(state.topic),
+                                },
+                            },
+                            required: ["interpretation"],
+                        },
+                    },
+                }, ElicitResultSchema);
+                // Process elicitation response
+                if (elicitResult.action === "accept" && elicitResult.content) {
+                    state.clarification =
+                        elicitResult.content
+                            .interpretation || "User accepted without selection";
+                }
+                else if (elicitResult.action === "decline") {
+                    state.clarification = "User declined - using default interpretation";
+                }
+                else {
+                    state.clarification = "User cancelled - using default interpretation";
+                }
+            }
+            catch (error) {
+                // Elicitation failed (likely HTTP transport without streaming support)
+                // Use default interpretation and continue - task should still complete
+                console.warn(`Elicitation failed for task ${taskId} (HTTP transport?):`, error instanceof Error ? error.message : String(error));
+                state.clarification =
+                    "technical (default - elicitation unavailable on HTTP)";
+            }
+            // Resume with working status (spec SHOULD)
+            await taskStore.updateTaskStatus(taskId, "working", `Continuing with interpretation: "${state.clarification}"...`);
+            // Continue processing (no return - just keep going through the loop)
+        }
+        // Simulate work for this stage
+        await new Promise((resolve) => setTimeout(resolve, STAGE_DURATION));
+    }
+    // All stages complete - generate result
+    state.completed = true;
+    const result = generateResearchReport(state);
+    state.result = result;
+    await taskStore.storeTaskResult(taskId, "completed", result);
+}
+/**
+ * Generates the final research report with educational content about tasks.
+ */
+function generateResearchReport(state) {
+    const topic = state.clarification
+        ? `${state.topic} (${state.clarification})`
+        : state.topic;
+    const report = `# Research Report: ${topic}
+
+## Research Parameters
+- **Topic**: ${state.topic}
+${state.clarification ? `- **Clarification**: ${state.clarification}` : ""}
+
+## Synthesis
+This research query was processed through ${STAGES.length} stages:
+${STAGES.map((s, i) => `- Stage ${i + 1}: ${s} ✓`).join("\n")}
+
+---
+
+## About This Demo (SEP-1686: Tasks)
+
+This tool demonstrates MCP's task-based execution pattern for long-running operations:
+
+**Task Lifecycle Demonstrated:**
+1. \`tools/call\` with \`task\` parameter → Server returns \`CreateTaskResult\` (not the final result)
+2. Client polls \`tasks/get\` → Server returns current status and \`statusMessage\`
+3. Status progressed: \`working\` → ${state.clarification ? `\`input_required\` → \`working\` → ` : ""}\`completed\`
+4. Client calls \`tasks/result\` → Server returns this final result
+
+${state.clarification
+        ? `**Elicitation Flow:**
+When the query was ambiguous, the server sent an \`elicitation/create\` request
+to the client. The task status changed to \`input_required\` while awaiting user input.
+${state.clarification.includes("unavailable on HTTP")
+            ? `
+**Note:** Elicitation was skipped because this server is running over HTTP transport.
+The current SDK's \`sendRequest\` only works over STDIO. Full HTTP elicitation support
+requires SDK PR #1210's streaming \`elicitInputStream\` API.
+`
+            : `After receiving clarification ("${state.clarification}"), the task resumed processing and completed.`}
+`
+        : ""}
+**Key Concepts:**
+- Tasks enable "call now, fetch later" patterns
+- \`statusMessage\` provides human-readable progress updates
+- Tasks have TTL (time-to-live) for automatic cleanup
+- \`pollInterval\` suggests how often to check status
+- Elicitation requests can be sent directly during task execution
+
+*This is a simulated research report from the Everything MCP Server.*
+`;
+    return {
+        content: [
+            {
+                type: "text",
+                text: report,
+            },
+        ],
+    };
+}
+/**
+ * Registers the 'simulate-research-query' tool as a task-based tool.
+ *
+ * This tool demonstrates the MCP Tasks feature (SEP-1686) with a real-world scenario:
+ * a research tool that gathers and synthesizes information from multiple sources.
+ * If the query is ambiguous, it pauses to ask for clarification before completing.
+ *
+ * @param {McpServer} server - The McpServer instance where the tool will be registered.
+ */
+export const registerSimulateResearchQueryTool = (server) => {
+    // Check if client supports elicitation (needed for input_required flow)
+    const clientCapabilities = server.server.getClientCapabilities() || {};
+    const clientSupportsElicitation = clientCapabilities.elicitation !== undefined;
+    server.experimental.tasks.registerToolTask("simulate-research-query", {
+        title: "Simulate Research Query",
+        description: "Simulates a deep research operation that gathers, analyzes, and synthesizes information. " +
+            "Demonstrates MCP task-based operations with progress through multiple stages. " +
+            "If 'ambiguous' is true and client supports elicitation, sends an elicitation request for clarification.",
+        inputSchema: SimulateResearchQuerySchema,
+        execution: { taskSupport: "required" },
+    }, {
+        /**
+         * Creates a new research task and starts background processing.
+         */
+        createTask: async (args, extra) => {
+            const validatedArgs = SimulateResearchQuerySchema.parse(args);
+            // Create the task in the store
+            const task = await extra.taskStore.createTask({
+                ttl: 300000, // 5 minutes
+                pollInterval: 1000,
+            });
+            // Initialize research state
+            const state = {
+                topic: validatedArgs.topic,
+                ambiguous: validatedArgs.ambiguous && clientSupportsElicitation,
+                currentStage: 0,
+                completed: false,
+            };
+            researchStates.set(task.taskId, state);
+            // Start background research (don't await - runs asynchronously)
+            // Pass sendRequest for elicitation (works on STDIO, gracefully degrades on HTTP)
+            runResearchProcess(task.taskId, validatedArgs, extra.taskStore, extra.sendRequest).catch((error) => {
+                console.error(`Research task ${task.taskId} failed:`, error);
+                extra.taskStore
+                    .updateTaskStatus(task.taskId, "failed", String(error))
+                    .catch(console.error);
+            });
+            return { task };
+        },
+        /**
+         * Returns the current status of the research task.
+         */
+        getTask: async (args, extra) => {
+            return await extra.taskStore.getTask(extra.taskId);
+        },
+        /**
+         * Returns the task result.
+         * Elicitation is now handled directly in the background process.
+         */
+        getTaskResult: async (args, extra) => {
+            // Return the stored result
+            const result = await extra.taskStore.getTaskResult(extra.taskId);
+            // Clean up state
+            researchStates.delete(extra.taskId);
+            return result;
+        },
+    });
+};
+/**
+ * Returns contextual interpretation options based on the topic.
+ */
+function getInterpretationsForTopic(topic) {
+    const lowerTopic = topic.toLowerCase();
+    // Example: contextual interpretations for "python"
+    if (lowerTopic.includes("python")) {
+        return [
+            { const: "programming", title: "Python programming language" },
+            { const: "snake", title: "Python snake species" },
+            { const: "comedy", title: "Monty Python comedy group" },
+        ];
+    }
+    // Default generic interpretations
+    return [
+        { const: "technical", title: "Technical/scientific perspective" },
+        { const: "historical", title: "Historical perspective" },
+        { const: "current", title: "Current events/news perspective" },
+    ];
+}

package/dist/tools/toggle-simulated-logging.js

@@ -0,0 +1,41 @@
+import { beginSimulatedLogging, stopSimulatedLogging, } from "../server/logging.js";
+// Tool configuration
+const name = "toggle-simulated-logging";
+const config = {
+    title: "Toggle Simulated Logging",
+    description: "Toggles simulated, random-leveled logging on or off.",
+    inputSchema: {},
+};
+// Track enabled clients by session id
+const clients = new Set();
+/**
+ * Registers the `toggle-simulated-logging` tool.
+ *
+ * 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;
+ * if it is inactive, logging will be started.
+ *
+ * @param {McpServer} server - The McpServer instance where the tool will be registered.
+ */
+export const registerToggleSimulatedLoggingTool = (server) => {
+    server.registerTool(name, config, async (_args, extra) => {
+        const sessionId = extra?.sessionId;
+        let response;
+        if (clients.has(sessionId)) {
+            stopSimulatedLogging(sessionId);
+            clients.delete(sessionId);
+            response = `Stopped simulated logging for session ${sessionId}`;
+        }
+        else {
+            beginSimulatedLogging(server, sessionId);
+            clients.add(sessionId);
+            response = `Started simulated, random-leveled logging for session ${sessionId} at a 5 second pace. Client's selected logging level will be respected. If an interval elapses and the message to be sent is below the selected level, it will not be sent. Thus at higher chosen logging levels, messages should arrive further apart. `;
+        }
+        return {
+            content: [{ type: "text", text: `${response}` }],
+        };
+    });
+};

package/dist/tools/toggle-subscriber-updates.js

@@ -0,0 +1,44 @@
+import { beginSimulatedResourceUpdates, stopSimulatedResourceUpdates, } from "../resources/subscriptions.js";
+// Tool configuration
+const name = "toggle-subscriber-updates";
+const config = {
+    title: "Toggle Subscriber Updates",
+    description: "Toggles simulated resource subscription updates on or off.",
+    inputSchema: {},
+};
+// Track enabled clients by session id
+const clients = new Set();
+/**
+ * Registers the `toggle-subscriber-updates` tool.
+ *
+ * The registered tool enables or disables the sending of periodic, simulated resource
+ * update messages the connected client for any subscriptions they have made.
+ *
+ * When invoked, it either starts or stops simulated resource updates based on the session's
+ * current state. If simulated updates for the specified session is active, it will be stopped;
+ * if it is inactive, simulated updates will be started.
+ *
+ * The response provides feedback indicating whether simulated updates were started or stopped,
+ * including the session ID.
+ *
+ * @param {McpServer} server - The McpServer instance where the tool will be registered.
+ */
+export const registerToggleSubscriberUpdatesTool = (server) => {
+    server.registerTool(name, config, async (_args, extra) => {
+        const sessionId = extra?.sessionId;
+        let response;
+        if (clients.has(sessionId)) {
+            stopSimulatedResourceUpdates(sessionId);
+            clients.delete(sessionId);
+            response = `Stopped simulated resource updates for session ${sessionId}`;
+        }
+        else {
+            beginSimulatedResourceUpdates(server, sessionId);
+            clients.add(sessionId);
+            response = `Started simulated resource updated notifications for session ${sessionId} at a 5 second pace. Client will receive updates for any resources the it is subscribed to.`;
+        }
+        return {
+            content: [{ type: "text", text: `${response}` }],
+        };
+    });
+};

package/dist/tools/trigger-elicitation-request-async.js

@@ -0,0 +1,202 @@
+import { z } from "zod";
+// Tool configuration
+const name = "trigger-elicitation-request-async";
+const config = {
+    title: "Trigger Async Elicitation Request Tool",
+    description: "Trigger an async elicitation request that the CLIENT executes as a background task. " +
+        "Demonstrates bidirectional MCP tasks where the server sends an elicitation request and " +
+        "the client handles user input asynchronously, allowing the server to poll for completion.",
+    inputSchema: {},
+};
+// Poll interval in milliseconds
+const POLL_INTERVAL = 1000;
+// Maximum poll attempts before timeout (10 minutes for user input)
+const MAX_POLL_ATTEMPTS = 600;
+/**
+ * Registers the 'trigger-elicitation-request-async' tool.
+ *
+ * This tool demonstrates bidirectional MCP tasks for elicitation:
+ * - Server sends elicitation request to client with task metadata
+ * - Client creates a task and returns CreateTaskResult
+ * - Client prompts user for input (task status: input_required)
+ * - Server polls client's tasks/get endpoint for status
+ * - Server fetches final result from client's tasks/result endpoint
+ *
+ * @param {McpServer} server - The McpServer instance where the tool will be registered.
+ */
+export const registerTriggerElicitationRequestAsyncTool = (server) => {
+    // Check client capabilities
+    const clientCapabilities = server.server.getClientCapabilities() || {};
+    // Client must support elicitation AND tasks.requests.elicitation
+    const clientSupportsElicitation = clientCapabilities.elicitation !== undefined;
+    const clientTasksCapability = clientCapabilities.tasks;
+    const clientSupportsAsyncElicitation = clientTasksCapability?.requests?.elicitation?.create !== undefined;
+    if (clientSupportsElicitation && clientSupportsAsyncElicitation) {
+        server.registerTool(name, config, async (args, extra) => {
+            // Create the elicitation request WITH task metadata
+            // Using z.any() schema to avoid complex type matching with _meta
+            const request = {
+                method: "elicitation/create",
+                params: {
+                    task: {
+                        ttl: 600000, // 10 minutes (user input may take a while)
+                    },
+                    message: "Please provide inputs for the following fields (async task demo):",
+                    requestedSchema: {
+                        type: "object",
+                        properties: {
+                            name: {
+                                title: "Your Name",
+                                type: "string",
+                                description: "Your full name",
+                            },
+                            favoriteColor: {
+                                title: "Favorite Color",
+                                type: "string",
+                                description: "What is your favorite color?",
+                                enum: ["Red", "Blue", "Green", "Yellow", "Purple"],
+                            },
+                            agreeToTerms: {
+                                title: "Terms Agreement",
+                                type: "boolean",
+                                description: "Do you agree to the terms and conditions?",
+                            },
+                        },
+                        required: ["name"],
+                    },
+                },
+            };
+            // Send the elicitation request
+            // Client may return either:
+            // - ElicitResult (synchronous execution)
+            // - CreateTaskResult (task-based execution with { task } object)
+            const elicitResponse = await extra.sendRequest(request, z.union([
+                // CreateTaskResult - client created a task
+                z.object({
+                    task: z.object({
+                        taskId: z.string(),
+                        status: z.string(),
+                        pollInterval: z.number().optional(),
+                        statusMessage: z.string().optional(),
+                    }),
+                }),
+                // ElicitResult - synchronous execution
+                z.object({
+                    action: z.string(),
+                    content: z.any().optional(),
+                }),
+            ]));
+            // Check if client returned CreateTaskResult (has task object)
+            const isTaskResult = "task" in elicitResponse && elicitResponse.task;
+            if (!isTaskResult) {
+                // Client executed synchronously - return the direct response
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `[SYNC] Client executed synchronously:\n${JSON.stringify(elicitResponse, null, 2)}`,
+                        },
+                    ],
+                };
+            }
+            const taskId = elicitResponse.task.taskId;
+            const statusMessages = [];
+            statusMessages.push(`Task created: ${taskId}`);
+            // Poll for task completion
+            let attempts = 0;
+            let taskStatus = elicitResponse.task.status;
+            let taskStatusMessage;
+            while (taskStatus !== "completed" &&
+                taskStatus !== "failed" &&
+                taskStatus !== "cancelled" &&
+                attempts < MAX_POLL_ATTEMPTS) {
+                // Wait before polling
+                await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+                attempts++;
+                // Get task status from client
+                const pollResult = await extra.sendRequest({
+                    method: "tasks/get",
+                    params: { taskId },
+                }, z
+                    .object({
+                    status: z.string(),
+                    statusMessage: z.string().optional(),
+                })
+                    .passthrough());
+                taskStatus = pollResult.status;
+                taskStatusMessage = pollResult.statusMessage;
+                // Only log status changes or every 10 polls to avoid spam
+                if (attempts === 1 ||
+                    attempts % 10 === 0 ||
+                    taskStatus !== "input_required") {
+                    statusMessages.push(`Poll ${attempts}: ${taskStatus}${taskStatusMessage ? ` - ${taskStatusMessage}` : ""}`);
+                }
+            }
+            // Check for timeout
+            if (attempts >= MAX_POLL_ATTEMPTS) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `[TIMEOUT] Task timed out after ${MAX_POLL_ATTEMPTS} poll attempts\n\nProgress:\n${statusMessages.join("\n")}`,
+                        },
+                    ],
+                };
+            }
+            // Check for failure/cancellation
+            if (taskStatus === "failed" || taskStatus === "cancelled") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `[${taskStatus.toUpperCase()}] ${taskStatusMessage || "No message"}\n\nProgress:\n${statusMessages.join("\n")}`,
+                        },
+                    ],
+                };
+            }
+            // Fetch the final result
+            const result = await extra.sendRequest({
+                method: "tasks/result",
+                params: { taskId },
+            }, z.any());
+            // Format the elicitation result
+            const content = [];
+            if (result.action === "accept" && result.content) {
+                content.push({
+                    type: "text",
+                    text: `[COMPLETED] User provided the requested information!`,
+                });
+                const userData = result.content;
+                const lines = [];
+                if (userData.name)
+                    lines.push(`- Name: ${userData.name}`);
+                if (userData.favoriteColor)
+                    lines.push(`- Favorite Color: ${userData.favoriteColor}`);
+                if (userData.agreeToTerms !== undefined)
+                    lines.push(`- Agreed to terms: ${userData.agreeToTerms}`);
+                content.push({
+                    type: "text",
+                    text: `User inputs:\n${lines.join("\n")}`,
+                });
+            }
+            else if (result.action === "decline") {
+                content.push({
+                    type: "text",
+                    text: `[DECLINED] User declined to provide the requested information.`,
+                });
+            }
+            else if (result.action === "cancel") {
+                content.push({
+                    type: "text",
+                    text: `[CANCELLED] User cancelled the elicitation dialog.`,
+                });
+            }
+            // Include progress and raw result for debugging
+            content.push({
+                type: "text",
+                text: `\nProgress:\n${statusMessages.join("\n")}\n\nRaw result: ${JSON.stringify(result, null, 2)}`,
+            });
+            return { content };
+        });
+    }
+};