QIT MCP Server

Instructions

Implementation Reference

• src/tools/packages.ts:37-88 (handler)

  The main handler function implementing the 'manage_package' tool. It handles different actions by setting up CLI commands and flags, then executes them using shared executor functions.

  handler: async (args: {
    action: (typeof packageActions)[number];
    package_name?: string;
    path?: string;
    type?: "e2e" | "utility";
    json?: boolean;
  }) => {
    let command: string;
    let positional: string[] = [];
    const flags: Record<string, string | boolean | undefined> = {
      json: args.json,
    };
  
    switch (args.action) {
      case "publish":
        command = "package:publish";
        if (args.path) positional.push(args.path);
        break;
  
      case "download":
        command = "package:download";
        if (args.package_name) positional.push(args.package_name);
        if (args.path) flags.output = args.path;
        break;
  
      case "scaffold":
        command = "package:scaffold";
        if (args.package_name) positional.push(args.package_name);
        if (args.type) flags.type = args.type;
        if (args.path) flags.output = args.path;
        break;
  
      case "delete":
        command = "package:delete";
        if (args.package_name) positional.push(args.package_name);
        break;
  
      case "show":
        command = "package:show";
        if (args.package_name) positional.push(args.package_name);
        break;
  
      default:
        return {
          content: `Unknown action: ${args.action}`,
          isError: true,
        };
    }
  
    const cmdArgs = buildArgs(command, positional, flags);
    return executeAndFormat(cmdArgs);
  },

• src/tools/packages.ts:16-36 (schema)

  Zod input schema defining parameters for the manage_package tool: action (enum), package_name, path, type, json.

  inputSchema: z.object({
    action: z
      .enum(packageActions)
      .describe("The package management action to perform"),
    package_name: z
      .string()
      .optional()
      .describe("Full package ID with version (e.g., 'namespace/name:version'). Required for download, show, delete actions."),
    path: z
      .string()
      .optional()
      .describe("Path for scaffold output or package location"),
    type: z
      .enum(["e2e", "utility"])
      .optional()
      .describe("Package type for scaffold action"),
    json: z
      .boolean()
      .optional()
      .describe("Return output in JSON format"),
  }),

• src/tools/packages.ts:13-89 (registration)

  Local tool object definition and export within packagesTools, including name, description, schema, and handler.

  manage_package: {
    name: "manage_package",
    description: `Manage QIT test packages. Actions: ${packageActions.join(", ")}`,
    inputSchema: z.object({
      action: z
        .enum(packageActions)
        .describe("The package management action to perform"),
      package_name: z
        .string()
        .optional()
        .describe("Full package ID with version (e.g., 'namespace/name:version'). Required for download, show, delete actions."),
      path: z
        .string()
        .optional()
        .describe("Path for scaffold output or package location"),
      type: z
        .enum(["e2e", "utility"])
        .optional()
        .describe("Package type for scaffold action"),
      json: z
        .boolean()
        .optional()
        .describe("Return output in JSON format"),
    }),
    handler: async (args: {
      action: (typeof packageActions)[number];
      package_name?: string;
      path?: string;
      type?: "e2e" | "utility";
      json?: boolean;
    }) => {
      let command: string;
      let positional: string[] = [];
      const flags: Record<string, string | boolean | undefined> = {
        json: args.json,
      };
  
      switch (args.action) {
        case "publish":
          command = "package:publish";
          if (args.path) positional.push(args.path);
          break;
  
        case "download":
          command = "package:download";
          if (args.package_name) positional.push(args.package_name);
          if (args.path) flags.output = args.path;
          break;
  
        case "scaffold":
          command = "package:scaffold";
          if (args.package_name) positional.push(args.package_name);
          if (args.type) flags.type = args.type;
          if (args.path) flags.output = args.path;
          break;
  
        case "delete":
          command = "package:delete";
          if (args.package_name) positional.push(args.package_name);
          break;
  
        case "show":
          command = "package:show";
          if (args.package_name) positional.push(args.package_name);
          break;
  
        default:
          return {
            content: `Unknown action: ${args.action}`,
            isError: true,
          };
      }
  
      const cmdArgs = buildArgs(command, positional, flags);
      return executeAndFormat(cmdArgs);
    },
  },

• src/tools/index.ts:10-16 (registration)

  Registration of packagesTools (containing manage_package) into the central allTools object by spreading.

  export const allTools = {
    ...authTools,
    ...testExecutionTools,
    ...testResultsTools,
    ...groupsTools,
    ...environmentTools,
    ...packagesTools,

• src/server.ts:25-38 (registration)

  MCP server lists all tools from allTools, converting Zod schemas to JSON schema for the protocol.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    // Check if QIT CLI is available
    const cliInfo = detectQitCli();
  
    const tools = Object.entries(allTools).map(([_, tool]) => ({
      name: tool.name,
      description: cliInfo
        ? tool.description
        : `${tool.description}\n\n⚠️ QIT CLI not detected. ${getQitCliNotFoundError()}`,
      inputSchema: zodToJsonSchema(tool.inputSchema),
    }));
  
    return { tools };
  });