feat(everything): add SEP-1686 Tasks support

- Add tasks capability with list, cancel, and requests.tools.call
- Add InMemoryTaskStore and InMemoryTaskMessageQueue from SDK experimental
- Add simulate-research-query tool demonstrating task lifecycle
- Task demonstrates working -> input_required -> completed status flow
- Uses elicitation for ambiguous queries when client supports it

Closes #3037

🦉 Generated with [Claude Code](https://claude.ai/code)

src/everything/docs/features.md

@@ -22,7 +22,8 @@
 - `trigger-long-running-operation` (tools/trigger-trigger-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.
 - `toggle-simulated-logging` (tools/toggle-simulated-logging.ts): Starts or stops simulated, random‑leveled logging for the invoking session. Respects the client’s selected minimum logging level.
 - `toggle-subscriber-updates` (tools/toggle-subscriber-updates.ts): Starts or stops simulated resource update notifications for URIs the invoking session has subscribed to.
-- `trigger-sampling-request` (tools/trigger-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.
+- `trigger-sampling-request` (tools/trigger-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.
+- `simulate-research-query` (tools/simulate-research-query.ts): Demonstrates MCP Tasks (SEP-1686) with a simulated multi-stage research operation. Accepts `topic` and `ambiguous` parameters. Returns a task that progresses through stages with status updates. If `ambiguous` is true and client supports elicitation, pauses with `input_required` status to gather clarification.
 
 ## Prompts
 
@@ -50,3 +51,30 @@
 - Simulated logging is available but off by default.
 - Use the `toggle-simulated-logging` tool to start/stop periodic log messages of varying levels (debug, info, notice, warning, error, critical, alert, emergency) per session.
 - Clients can control the minimum level they receive via the standard MCP `logging/setLevel` request.
+
+## Tasks (SEP-1686)
+
+The server advertises support for MCP Tasks, enabling long-running operations with status tracking:
+
+- **Capabilities advertised**: `tasks.list`, `tasks.cancel`, `tasks.requests.tools.call`
+- **Task Store**: Uses `InMemoryTaskStore` from SDK experimental for task lifecycle management
+- **Message Queue**: Uses `InMemoryTaskMessageQueue` for task-related messaging
+
+### Task Lifecycle
+
+1. Client calls `tools/call` with `task: true` parameter
+2. Server returns `CreateTaskResult` with `taskId` instead of immediate result
+3. Client polls `tasks/get` to check status and receive `statusMessage` updates
+4. When status is `completed`, client calls `tasks/result` to retrieve the final result
+
+### Task Statuses
+
+- `working`: Task is actively processing
+- `input_required`: Task needs additional input (demonstrated via elicitation side-channel)
+- `completed`: Task finished successfully
+- `failed`: Task encountered an error
+- `cancelled`: Task was cancelled by client
+
+### Demo Tool
+
+Use the `simulate-research-query` tool to exercise the full task lifecycle. Set `ambiguous: true` to trigger the `input_required` flow with elicitation.

src/everything/server/index.ts

@@ -1,4 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  InMemoryTaskStore,
+  InMemoryTaskMessageQueue,
+} from "@modelcontextprotocol/sdk/experimental";
 import {
   setSubscriptionHandlers,
   stopSimulatedResourceUpdates,
@@ -32,6 +36,10 @@ export const createServer: () => ServerFactoryResponse = () => {
   // Read the server instructions
   const instructions = readInstructions();
 
+  // Create task store and message queue for task support
+  const taskStore = new InMemoryTaskStore();
+  const taskMessageQueue = new InMemoryTaskMessageQueue();
+
   // Create the server
   const server = new McpServer(
     {
@@ -52,8 +60,19 @@ export const createServer: () => ServerFactoryResponse = () => {
           listChanged: true,
         },
         logging: {},
+        tasks: {
+          list: {},
+          cancel: {},
+          requests: {
+            tools: {
+              call: {},
+            },
+          },
+        },
       },
       instructions,
+      taskStore,
+      taskMessageQueue,
     }
   );
 
@@ -89,6 +108,8 @@ export const createServer: () => ServerFactoryResponse = () => {
       // Stop any simulated logging or resource updates that may have been initiated.
       stopSimulatedLogging(sessionId);
       stopSimulatedResourceUpdates(sessionId);
+      // Clean up task store timers
+      taskStore.cleanup();
     },
   } satisfies ServerFactoryResponse;
 };

src/everything/tools/index.ts

@@ -14,6 +14,7 @@ import { registerToggleSubscriberUpdatesTool } from "./toggle-subscriber-updates
 import { registerTriggerElicitationRequestTool } from "./trigger-elicitation-request.js";
 import { registerTriggerLongRunningOperationTool } from "./trigger-long-running-operation.js";
 import { registerTriggerSamplingRequestTool } from "./trigger-sampling-request.js";
+import { registerSimulateResearchQueryTool } from "./simulate-research-query.js";
 
 /**
  * Register the tools with the MCP server.
@@ -42,4 +43,6 @@ export const registerConditionalTools = (server: McpServer) => {
   registerGetRootsListTool(server);
   registerTriggerElicitationRequestTool(server);
   registerTriggerSamplingRequestTool(server);
+  // Task-based research tool (uses experimental tasks API)
+  registerSimulateResearchQueryTool(server);
 };

src/everything/tools/simulate-research-query.ts

@@ -0,0 +1,336 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  CallToolResult,
+  GetTaskResult,
+  Task,
+  ElicitResultSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { CreateTaskResult } from "@modelcontextprotocol/sdk/experimental";
+
+// 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;
+
+// Internal state for tracking research tasks
+interface ResearchState {
+  topic: string;
+  ambiguous: boolean;
+  currentStage: number;
+  clarification?: string;
+  waitingForClarification: boolean;
+  completed: boolean;
+  result?: CallToolResult;
+}
+
+// Map to store research state per task
+const researchStates = new Map<string, ResearchState>();
+
+/**
+ * Runs the background research process.
+ * Updates task status as it progresses through stages.
+ */
+async function runResearchProcess(
+  taskId: string,
+  args: z.infer<typeof SimulateResearchQuerySchema>,
+  taskStore: {
+    updateTaskStatus: (
+      taskId: string,
+      status: Task["status"],
+      message?: string
+    ) => Promise<void>;
+    storeTaskResult: (
+      taskId: string,
+      status: "completed" | "failed",
+      result: CallToolResult
+    ) => Promise<void>;
+  }
+): Promise<void> {
+  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) {
+      state.waitingForClarification = true;
+      await taskStore.updateTaskStatus(
+        taskId,
+        "input_required",
+        `Found multiple interpretations for "${state.topic}". Please clarify your intent.`
+      );
+      // Wait for clarification - the getTaskResult handler will resume this
+      return;
+    }
+
+    // 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: ResearchState): CallToolResult {
+  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 ? `**input_required Flow:**
+When the query was ambiguous, the task paused with \`input_required\` status.
+The client called \`tasks/result\` prematurely, which triggered an elicitation
+request via the side-channel. After receiving clarification ("${state.clarification}"),
+the task resumed processing.
+` : ""}
+**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
+
+*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: McpServer) => {
+  // Check if client supports elicitation (needed for input_required flow)
+  const clientCapabilities = server.server.getClientCapabilities() || {};
+  const clientSupportsElicitation: boolean =
+    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, pauses for clarification (input_required status).",
+      inputSchema: SimulateResearchQuerySchema,
+      execution: { taskSupport: "required" },
+    },
+    {
+      /**
+       * Creates a new research task and starts background processing.
+       */
+      createTask: async (args, extra): Promise<CreateTaskResult> => {
+        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: ResearchState = {
+          topic: validatedArgs.topic,
+          ambiguous: validatedArgs.ambiguous && clientSupportsElicitation,
+          currentStage: 0,
+          waitingForClarification: false,
+          completed: false,
+        };
+        researchStates.set(task.taskId, state);
+
+        // Start background research (don't await - runs asynchronously)
+        runResearchProcess(task.taskId, validatedArgs, extra.taskStore).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): Promise<GetTaskResult> => {
+        const task = await extra.taskStore.getTask(extra.taskId);
+        // The SDK's RequestTaskStore.getTask throws if not found, so task is always defined
+        return task;
+      },
+
+      /**
+       * Returns the task result, or handles input_required via elicitation side-channel.
+       */
+      getTaskResult: async (args, extra): Promise<CallToolResult> => {
+        const task = await extra.taskStore.getTask(extra.taskId);
+        const state = researchStates.get(extra.taskId);
+
+        // Handle input_required - use tasks/result as side-channel for elicitation
+        if (task?.status === "input_required" && state?.waitingForClarification) {
+          // Send elicitation request through the side-channel
+          const elicitationResult = await extra.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,
+            { timeout: 5 * 60 * 1000 /* 5 minutes */ }
+          );
+
+          // Process elicitation response
+          if (
+            elicitationResult.action === "accept" &&
+            elicitationResult.content
+          ) {
+            state.clarification =
+              (elicitationResult.content as { interpretation?: string })
+                .interpretation || "User accepted without selection";
+          } else if (elicitationResult.action === "decline") {
+            state.clarification = "User declined - using default interpretation";
+          } else {
+            state.clarification = "User cancelled - using default interpretation";
+          }
+
+          state.waitingForClarification = false;
+
+          // Resume background processing from current stage
+          runResearchProcess(extra.taskId, {
+            topic: state.topic,
+            ambiguous: false, // Don't ask again
+          }, extra.taskStore).catch((error) => {
+            console.error(`Research task ${extra.taskId} failed:`, error);
+            extra.taskStore
+              .updateTaskStatus(extra.taskId, "failed", String(error))
+              .catch(console.error);
+          });
+
+          // Return indication that work is resuming (client should poll again)
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Resuming research with clarification: "${state.clarification}"`,
+              },
+            ],
+          };
+        }
+
+        // Normal case: return the stored result
+        const result = await extra.taskStore.getTaskResult(extra.taskId);
+
+        // Clean up state
+        researchStates.delete(extra.taskId);
+
+        return result as CallToolResult;
+      },
+    }
+  );
+};
+
+/**
+ * Returns contextual interpretation options based on the topic.
+ */
+function getInterpretationsForTopic(
+  topic: string
+): Array<{ const: string; title: string }> {
+  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" },
+  ];
+}