@modelcontextprotocol/server-everything 2026.1.14 → 2026.7.4

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

@@ -0,0 +1,248 @@
+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, sends elicitation via sendRequest with relatedTask,
+ * which queues the request in the task message queue. The SDK delivers it through
+ * the tasks/result stream when the client calls tasks/result (per spec input_required flow).
+ * This works on all transports (STDIO, SSE, Streamable HTTP).
+ */
+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 {
+                // relatedTask queues elicitation via task message queue → delivered through tasks/result on all transports
+                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, { relatedTask: { taskId } });
+                // 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 - use default interpretation and continue
+                console.warn(`Elicitation failed for task ${taskId}:`, error instanceof Error ? error.message : String(error));
+                state.clarification = "technical (default - elicitation unavailable)";
+            }
+            // 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")
+            ? `**Note:** Elicitation failed and a default interpretation was used.`
+            : `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 use \`relatedTask\` to queue via tasks/result (works on all transports)
+
+*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" },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, {
+        /**
+         * 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 (queued via task message queue, works on all transports)
+            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

@@ -5,6 +5,12 @@ const config = {
     title: "Toggle Simulated Logging",
     description: "Toggles simulated, random-leveled logging on or off.",
     inputSchema: {},
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
 };
 // Track enabled clients by session id
 const clients = new Set();

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

@@ -5,6 +5,12 @@ const config = {
     title: "Toggle Subscriber Updates",
     description: "Toggles simulated resource subscription updates on or off.",
     inputSchema: {},
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
 };
 // Track enabled clients by session id
 const clients = new Set();

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

@@ -0,0 +1,206 @@
+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: {},
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+};
+// 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.looseObject({
+                    status: z.string(),
+                    statusMessage: z.string().optional(),
+                }));
+                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 };
+        });
+    }
+};

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

@@ -1,10 +1,16 @@
-import { ElicitResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { ElicitResultSchema, } from "@modelcontextprotocol/sdk/types.js";
 // Tool configuration
 const name = "trigger-elicitation-request";
 const config = {
     title: "Trigger Elicitation Request Tool",
     description: "Trigger a Request from the Server for User Elicitation",
     inputSchema: {},
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
 };
 /**
  * Registers the 'trigger-elicitation-request' tool.

package/dist/tools/trigger-long-running-operation.js

@@ -13,6 +13,12 @@ const config = {
     title: "Trigger Long Running Operation Tool",
     description: "Demonstrates a long running operation with progress updates.",
     inputSchema: TriggerLongRunningOperationSchema,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
 };
 /**
  * Registers the 'trigger-tong-running-operation' tool.