Merge branch 'main' into fix/tool-annotations
This commit is contained in:
Ola Hungerford
GitHub
commit
59e60b5a69
5 changed files with 2824 additions and 413 deletions
|
|
@ -14,6 +14,9 @@ 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 { registerTriggerSamplingRequestAsyncTool } from "./trigger-sampling-request-async.js";
|
||||
import { registerTriggerElicitationRequestAsyncTool } from "./trigger-elicitation-request-async.js";
|
||||
import { registerSimulateResearchQueryTool } from "./simulate-research-query.js";
|
||||
|
||||
/**
|
||||
* Register the tools with the MCP server.
|
||||
|
|
@ -42,4 +45,9 @@ export const registerConditionalTools = (server: McpServer) => {
|
|||
registerGetRootsListTool(server);
|
||||
registerTriggerElicitationRequestTool(server);
|
||||
registerTriggerSamplingRequestTool(server);
|
||||
// Task-based research tool (uses experimental tasks API)
|
||||
registerSimulateResearchQueryTool(server);
|
||||
// Bidirectional task tools - server sends requests that client executes as tasks
|
||||
registerTriggerSamplingRequestAsyncTool(server);
|
||||
registerTriggerElicitationRequestAsyncTool(server);
|
||||
};
|
||||
|
|
|
|||
345
src/everything/tools/simulate-research-query.ts
Normal file
345
src/everything/tools/simulate-research-query.ts
Normal file
|
|
@ -0,0 +1,345 @@
|
|||
import { z } from "zod";
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import {
|
||||
CallToolResult,
|
||||
GetTaskResult,
|
||||
Task,
|
||||
ElicitResult,
|
||||
ElicitResultSchema,
|
||||
} from "@modelcontextprotocol/sdk/types.js";
|
||||
import { CreateTaskResult } from "@modelcontextprotocol/sdk/experimental/tasks";
|
||||
|
||||
// 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;
|
||||
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.
|
||||
* 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: 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>;
|
||||
},
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
sendRequest: any
|
||||
): 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) {
|
||||
// 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: 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 as { interpretation?: string })
|
||||
.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: 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
|
||||
? `**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: 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, sends an elicitation request for clarification.",
|
||||
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,
|
||||
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): Promise<GetTaskResult> => {
|
||||
return await extra.taskStore.getTask(extra.taskId);
|
||||
},
|
||||
|
||||
/**
|
||||
* Returns the task result.
|
||||
* Elicitation is now handled directly in the background process.
|
||||
*/
|
||||
getTaskResult: async (args, extra): Promise<CallToolResult> => {
|
||||
// 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" },
|
||||
];
|
||||
}
|
||||
265
src/everything/tools/trigger-elicitation-request-async.ts
Normal file
265
src/everything/tools/trigger-elicitation-request-async.ts
Normal file
|
|
@ -0,0 +1,265 @@
|
|||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
|
||||
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: McpServer
|
||||
) => {
|
||||
// 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 as
|
||||
| {
|
||||
requests?: { elicitation?: { create?: object } };
|
||||
}
|
||||
| undefined;
|
||||
const clientSupportsAsyncElicitation =
|
||||
clientTasksCapability?.requests?.elicitation?.create !== undefined;
|
||||
|
||||
if (clientSupportsElicitation && clientSupportsAsyncElicitation) {
|
||||
server.registerTool(
|
||||
name,
|
||||
config,
|
||||
async (args, extra): Promise<CallToolResult> => {
|
||||
// Create the elicitation request WITH task metadata
|
||||
// Using z.any() schema to avoid complex type matching with _meta
|
||||
const request = {
|
||||
method: "elicitation/create" as const,
|
||||
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" as const,
|
||||
properties: {
|
||||
name: {
|
||||
title: "Your Name",
|
||||
type: "string" as const,
|
||||
description: "Your full name",
|
||||
},
|
||||
favoriteColor: {
|
||||
title: "Favorite Color",
|
||||
type: "string" as const,
|
||||
description: "What is your favorite color?",
|
||||
enum: ["Red", "Blue", "Green", "Yellow", "Purple"],
|
||||
},
|
||||
agreeToTerms: {
|
||||
title: "Terms Agreement",
|
||||
type: "boolean" as const,
|
||||
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 as Parameters<typeof extra.sendRequest>[0],
|
||||
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: string[] = [];
|
||||
statusMessages.push(`Task created: ${taskId}`);
|
||||
|
||||
// Poll for task completion
|
||||
let attempts = 0;
|
||||
let taskStatus = elicitResponse.task.status;
|
||||
let taskStatusMessage: string | undefined;
|
||||
|
||||
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: CallToolResult["content"] = [];
|
||||
|
||||
if (result.action === "accept" && result.content) {
|
||||
content.push({
|
||||
type: "text",
|
||||
text: `[COMPLETED] User provided the requested information!`,
|
||||
});
|
||||
|
||||
const userData = result.content as Record<string, unknown>;
|
||||
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 };
|
||||
}
|
||||
);
|
||||
}
|
||||
};
|
||||
|
|
@ -1,6 +1,8 @@
|
|||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { ElicitResultSchema } from "@modelcontextprotocol/sdk/types.js";
|
||||
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
|
||||
import {
|
||||
ElicitResultSchema,
|
||||
CallToolResult,
|
||||
} from "@modelcontextprotocol/sdk/types.js";
|
||||
|
||||
// Tool configuration
|
||||
const name = "trigger-elicitation-request";
|
||||
|
|
|
|||
230
src/everything/tools/trigger-sampling-request-async.ts
Normal file
230
src/everything/tools/trigger-sampling-request-async.ts
Normal file
|
|
@ -0,0 +1,230 @@
|
|||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import {
|
||||
CallToolResult,
|
||||
CreateMessageRequest,
|
||||
} from "@modelcontextprotocol/sdk/types.js";
|
||||
import { z } from "zod";
|
||||
|
||||
// Tool input schema
|
||||
const TriggerSamplingRequestAsyncSchema = z.object({
|
||||
prompt: z.string().describe("The prompt to send to the LLM"),
|
||||
maxTokens: z
|
||||
.number()
|
||||
.default(100)
|
||||
.describe("Maximum number of tokens to generate"),
|
||||
});
|
||||
|
||||
// Tool configuration
|
||||
const name = "trigger-sampling-request-async";
|
||||
const config = {
|
||||
title: "Trigger Async Sampling Request Tool",
|
||||
description:
|
||||
"Trigger an async sampling request that the CLIENT executes as a background task. " +
|
||||
"Demonstrates bidirectional MCP tasks where the server sends a request and the client " +
|
||||
"executes it asynchronously, allowing the server to poll for progress and results.",
|
||||
inputSchema: TriggerSamplingRequestAsyncSchema,
|
||||
};
|
||||
|
||||
// Poll interval in milliseconds
|
||||
const POLL_INTERVAL = 1000;
|
||||
|
||||
// Maximum poll attempts before timeout
|
||||
const MAX_POLL_ATTEMPTS = 60;
|
||||
|
||||
/**
|
||||
* Registers the 'trigger-sampling-request-async' tool.
|
||||
*
|
||||
* This tool demonstrates bidirectional MCP tasks:
|
||||
* - Server sends sampling request to client with task metadata
|
||||
* - Client creates a task and returns CreateTaskResult
|
||||
* - 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 registerTriggerSamplingRequestAsyncTool = (server: McpServer) => {
|
||||
// Check client capabilities
|
||||
const clientCapabilities = server.server.getClientCapabilities() || {};
|
||||
|
||||
// Client must support sampling AND tasks.requests.sampling
|
||||
const clientSupportsSampling = clientCapabilities.sampling !== undefined;
|
||||
const clientTasksCapability = clientCapabilities.tasks as
|
||||
| {
|
||||
requests?: { sampling?: { createMessage?: object } };
|
||||
}
|
||||
| undefined;
|
||||
const clientSupportsAsyncSampling =
|
||||
clientTasksCapability?.requests?.sampling?.createMessage !== undefined;
|
||||
|
||||
if (clientSupportsSampling && clientSupportsAsyncSampling) {
|
||||
server.registerTool(
|
||||
name,
|
||||
config,
|
||||
async (args, extra): Promise<CallToolResult> => {
|
||||
const validatedArgs = TriggerSamplingRequestAsyncSchema.parse(args);
|
||||
const { prompt, maxTokens } = validatedArgs;
|
||||
|
||||
// Create the sampling request WITH task metadata
|
||||
// The params.task field signals to the client that this should be executed as a task
|
||||
const request: CreateMessageRequest & {
|
||||
params: { task?: { ttl: number } };
|
||||
} = {
|
||||
method: "sampling/createMessage",
|
||||
params: {
|
||||
task: {
|
||||
ttl: 300000, // 5 minutes
|
||||
},
|
||||
messages: [
|
||||
{
|
||||
role: "user",
|
||||
content: {
|
||||
type: "text",
|
||||
text: `Resource ${name} context: ${prompt}`,
|
||||
},
|
||||
},
|
||||
],
|
||||
systemPrompt: "You are a helpful test server.",
|
||||
maxTokens,
|
||||
temperature: 0.7,
|
||||
},
|
||||
};
|
||||
|
||||
// Send the sampling request
|
||||
// Client may return either:
|
||||
// - CreateMessageResult (synchronous execution)
|
||||
// - CreateTaskResult (task-based execution with { task } object)
|
||||
const samplingResponse = 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(),
|
||||
}),
|
||||
}),
|
||||
// CreateMessageResult - synchronous execution
|
||||
z.object({
|
||||
role: z.string(),
|
||||
content: z.any(),
|
||||
model: z.string(),
|
||||
stopReason: z.string().optional(),
|
||||
}),
|
||||
])
|
||||
);
|
||||
|
||||
// Check if client returned CreateTaskResult (has task object)
|
||||
const isTaskResult =
|
||||
"task" in samplingResponse && samplingResponse.task;
|
||||
if (!isTaskResult) {
|
||||
// Client executed synchronously - return the direct response
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: `[SYNC] Client executed synchronously:\n${JSON.stringify(
|
||||
samplingResponse,
|
||||
null,
|
||||
2
|
||||
)}`,
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
const taskId = samplingResponse.task.taskId;
|
||||
const statusMessages: string[] = [];
|
||||
statusMessages.push(`Task created: ${taskId}`);
|
||||
|
||||
// Poll for task completion
|
||||
let attempts = 0;
|
||||
let taskStatus = samplingResponse.task.status;
|
||||
let taskStatusMessage: string | undefined;
|
||||
|
||||
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;
|
||||
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()
|
||||
);
|
||||
|
||||
// Return the result with status history
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: `[COMPLETED] Async sampling completed!\n\n**Progress:**\n${statusMessages.join(
|
||||
"\n"
|
||||
)}\n\n**Result:**\n${JSON.stringify(result, null, 2)}`,
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
);
|
||||
}
|
||||
};
|
||||
Loading…
Reference in a new issue