MCP Workbench MCP Server

Instructions

Implementation Reference

• src/tools/generateSpec.ts:24-47 (handler)

  The main handler function for the generate_spec tool, which calls the CLI runner and formats the results.

  export async function generateSpec(
    input: GenerateSpecInput,
  ): Promise<GenerateSpecOutput> {
    const args = buildArgs(input);
    const result = await runCli(args, { timeoutMs: input.timeoutMs });
  
    const yaml = result.stdout;
    const testCount = countTests(yaml);
    const warnings = detectWarnings(yaml);
  
    const textParts = [`Generated spec \u2014 ${testCount} tests`];
    if (warnings.length > 0) {
      textParts.push("");
      textParts.push("Warnings:");
      for (const w of warnings) {
        textParts.push(`  - ${w}`);
      }
    }
  
    return {
      text: textParts.join("\n"),
      structured: { yaml, testCount, warnings },
    };
  }

• src/tools/generateSpec.ts:3-13 (schema)

  Input and output type definitions for the generate_spec tool.

  export interface GenerateSpecInput {
    transport: "stdio" | "streamable-http";
    url?: string;
    command?: string;
    args?: string | string[];
    headers?: Record<string, string>;
    include?: Array<"tools" | "resources" | "prompts">;
    exclude?: Array<"tools" | "resources" | "prompts">;
    depth?: "shallow" | "deep";
    timeoutMs?: number;
  }

• src/server.ts:58-118 (registration)

  Registration of the generate_spec tool within the MCP server's tool list.

  {
    name: "generate_spec",
    description:
      "Generate a YAML test spec by discovering the capabilities of an MCP server. Returns a ready-to-run spec.",
    inputSchema: {
      type: "object" as const,
      properties: {
        transport: {
          type: "string",
          enum: ["stdio", "streamable-http"],
          description: "Transport type to use for connecting to the server",
        },
        url: {
          type: "string",
          description:
            "Server URL (required for streamable-http transport)",
        },
        command: {
          type: "string",
          description:
            "Command to launch the server (required for stdio transport)",
        },
        args: {
          oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
          description: "Arguments to pass to the server command",
        },
        headers: {
          type: "object",
          additionalProperties: { type: "string" },
          description: "HTTP headers to send (e.g. Authorization)",
        },
        include: {
          type: "array",
          items: {
            type: "string",
            enum: ["tools", "resources", "prompts"],
          },
          description: "Only include these capability types in the spec",
        },
        exclude: {
          type: "array",
          items: {
            type: "string",
            enum: ["tools", "resources", "prompts"],
          },
          description: "Exclude these capability types from the spec",
        },
        depth: {
          type: "string",
          enum: ["shallow", "deep"],
          description:
            "Discovery depth: shallow (list only) or deep (call each tool/resource/prompt)",
        },
        timeoutMs: {
          type: "number",
          description: "Timeout in milliseconds (default: 30000)",
        },
      },
      required: ["transport"],
    },
  },

• src/tools/generateSpec.ts:49-83 (helper)

  Helper function to convert input parameters into CLI arguments.

  export function buildArgs(input: GenerateSpecInput): string[] {
    const args = ["generate", "--stdout", "--transport", input.transport];
  
    if (input.command) {
      args.push("--command", input.command);
    }
    if (input.url) {
      args.push("--url", input.url);
    }
    if (input.args) {
      const argsValue = Array.isArray(input.args)
        ? input.args.join(" ")
        : input.args;
      args.push("--args", argsValue);
    }
    if (input.headers) {
      for (const [key, value] of Object.entries(input.headers)) {
        args.push("--header", `${key}: ${value}`);
      }
    }
    if (input.include && input.include.length > 0) {
      args.push("--include", input.include.join(","));
    }
    if (input.exclude && input.exclude.length > 0) {
      args.push("--exclude", input.exclude.join(","));
    }
    if (input.depth) {
      args.push("--depth", input.depth);
    }
    if (input.timeoutMs !== undefined) {
      args.push("--timeout", String(input.timeoutMs));
    }
  
    return args;
  }