servers-modelcontextprotocol/src/everything/tools/trigger-elicitation-request.ts

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { ElicitResultSchema } from "@modelcontextprotocol/sdk/types.js";
import { CallToolResult } 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: {},
};

/**
 * Registers the 'trigger-elicitation-request' tool within the provided McpServer instance.
 *
 * The registered tool performs the following operations:
 *
 * This tool sends a detailed request for the user to provide information based
 * on a pre-defined schema of fields including text inputs, booleans, numbers,
 * email, dates, etc. It uses validation and handles multiple possible outcomes
 * from the user's response, such as acceptance with content, decline, or
 * cancellation of the dialog. The process also ensures parsing and validating
 * the elicitation input arguments at runtime.
 *
 * The tool resolves the elicitation dialog response into a structured result,
 * which contains both user-submitted input data (if provided) and debugging
 * information, including raw results.
 *
 * @param {McpServer} server - The MCP server instance to which the tool will be registered.
 */
export const registerTriggerElicitationRequestTool = (server: McpServer) => {
  server.registerTool(
    name,
    config,
    async (args, extra): Promise<CallToolResult> => {
      const elicitationResult = await extra.sendRequest(
        {
          method: "elicitation/create",
          params: {
            message: "Please provide inputs for the following fields:",
            requestedSchema: {
              type: "object",
              properties: {
                name: {
                  title: "String",
                  type: "string",
                  description: "Your full, legal name",
                },
                check: {
                  title: "Boolean",
                  type: "boolean",
                  description: "Agree to the terms and conditions",
                },
                firstLine: {
                  title: "String with default",
                  type: "string",
                  description: "Favorite first line of a story",
                  default: "It was a dark and stormy night.",
                },
                email: {
                  title: "String with email format",
                  type: "string",
                  format: "email",
                  description:
                    "Your email address (will be verified, and never shared with anyone else)",
                },
                homepage: {
                  type: "string",
                  format: "uri",
                  title: "String with uri format",
                  description: "Portfolio / personal website",
                },
                birthdate: {
                  title: "String with date format",
                  type: "string",
                  format: "date",
                  description: "Your date of birth",
                },
                integer: {
                  title: "Integer",
                  type: "integer",
                  description:
                    "Your favorite integer (do not give us your phone number, pin, or other sensitive info)",
                  minimum: 1,
                  maximum: 100,
                  default: 42,
                },
                number: {
                  title: "Number in range 1-1000",
                  type: "number",
                  description: "Favorite number (there are no wrong answers)",
                  minimum: 0,
                  maximum: 1000,
                  default: 3.14,
                },
                untitledSingleSelectEnum: {
                  type: "string",
                  title: "Untitled Single Select Enum",
                  description: "Choose your favorite friend",
                  enum: [
                    "Monica",
                    "Rachel",
                    "Joey",
                    "Chandler",
                    "Ross",
                    "Phoebe",
                  ],
                  default: "Monica",
                },
                untitledMultipleSelectEnum: {
                  type: "array",
                  title: "Untitled Multiple Select Enum",
                  description: "Choose your favorite instruments",
                  minItems: 1,
                  maxItems: 3,
                  items: {
                    type: "string",
                    enum: ["Guitar", "Piano", "Violin", "Drums", "Bass"],
                  },
                  default: ["Guitar"],
                },
                titledSingleSelectEnum: {
                  type: "string",
                  title: "Titled Single Select Enum",
                  description: "Choose your favorite hero",
                  oneOf: [
                    { const: "hero-1", title: "Superman" },
                    { const: "hero-2", title: "Green Lantern" },
                    { const: "hero-3", title: "Wonder Woman" },
                  ],
                  default: "hero-1",
                },
                titledMultipleSelectEnum: {
                  type: "array",
                  title: "Titled Multiple Select Enum",
                  description: "Choose your favorite types of fish",
                  minItems: 1,
                  maxItems: 3,
                  items: {
                    anyOf: [
                      { const: "fish-1", title: "Tuna" },
                      { const: "fish-2", title: "Salmon" },
                      { const: "fish-3", title: "Trout" },
                    ],
                  },
                  default: ["fish-1"],
                },
                legacyTitledEnum: {
                  type: "string",
                  title: "Legacy Titled Single Select Enum",
                  description: "Choose your favorite type of pet",
                  enum: ["pet-1", "pet-2", "pet-3", "pet-4", "pet-5"],
                  enumNames: ["Cats", "Dogs", "Birds", "Fish", "Reptiles"],
                  default: "pet-1",
                },
              },
              required: ["name"],
            },
          },
        },
        ElicitResultSchema,
        { timeout: 10 * 60 * 1000 /* 10 minutes */ }
      );

      // Handle different response actions
      const content: CallToolResult["content"] = [];

      if (elicitationResult.action === "accept" && elicitationResult.content) {
        content.push({
          type: "text",
          text: `✅ User provided the requested information!`,
        });

        // Only access elicitationResult.content when action is accept
        const userData = elicitationResult.content;
        const lines = [];
        if (userData.name) lines.push(`- Name: ${userData.name}`);
        if (userData.check !== undefined)
          lines.push(`- Agreed to terms: ${userData.check}`);
        if (userData.color) lines.push(`- Favorite Color: ${userData.color}`);
        if (userData.email) lines.push(`- Email: ${userData.email}`);
        if (userData.homepage) lines.push(`- Homepage: ${userData.homepage}`);
        if (userData.birthdate)
          lines.push(`- Birthdate: ${userData.birthdate}`);
        if (userData.integer !== undefined)
          lines.push(`- Favorite Integer: ${userData.integer}`);
        if (userData.number !== undefined)
          lines.push(`- Favorite Number: ${userData.number}`);
        if (userData.petType) lines.push(`- Pet Type: ${userData.petType}`);

        content.push({
          type: "text",
          text: `User inputs:\n${lines.join("\n")}`,
        });
      } else if (elicitationResult.action === "decline") {
        content.push({
          type: "text",
          text: `❌ User declined to provide the requested information.`,
        });
      } else if (elicitationResult.action === "cancel") {
        content.push({
          type: "text",
          text: `⚠️ User cancelled the elicitation dialog.`,
        });
      }

      // Include raw result for debugging
      content.push({
        type: "text",
        text: `\nRaw result: ${JSON.stringify(elicitationResult, null, 2)}`,
      });

      return { content };
    }
  );
};