QIT MCP Server

Instructions

Implementation Reference

• src/tools/packages.ts:109-193 (handler)

  The core handler logic for the list_packages tool: runs 'qit package:list', parses table output into structured data, applies client-side filtering (search, type), limits results to 20 by default, and formats a compact bullet list with summary.

  handler: async (args: { search?: string; type?: string; limit?: number }) => {
    const cmdArgs = ["package:list"];
    if (args.type) {
      cmdArgs.push("--type", args.type);
    }
  
    const result = await executeQitCommand(cmdArgs);
  
    if (!result.success && !result.stdout.includes("Package")) {
      return {
        content: result.stderr || result.stdout || "Failed to list packages",
        isError: true,
      };
    }
  
    // Parse the table output format
    // | Package ID | Namespace | Version | Size | Visibility | Created |
    const lines = (result.stdout + "\n" + result.stderr)
      .split("\n")
      .filter(line => !line.includes("Deprecated:") && !line.includes("PHP Deprecated:"));
  
    let packages: Array<{
      id: string;
      namespace: string;
      version: string;
      size: string;
      visibility: string;
    }> = [];
  
    for (const line of lines) {
      // Skip non-table lines
      if (!line.startsWith("|") || line.includes("---") || line.includes("Package ID")) {
        continue;
      }
  
      const parts = line.split("|").map(p => p.trim()).filter(p => p);
      if (parts.length >= 5) {
        packages.push({
          id: parts[0],
          namespace: parts[1],
          version: parts[2],
          size: parts[3],
          visibility: parts[4].replace("🌐 ", "").replace("🔒 ", ""),
        });
      }
    }
  
    const totalCount = packages.length;
  
    // Filter by search term if provided
    if (args.search) {
      const searchLower = args.search.toLowerCase();
      packages = packages.filter(pkg =>
        pkg.id.toLowerCase().includes(searchLower) ||
        pkg.namespace.toLowerCase().includes(searchLower)
      );
    }
  
    // Apply limit (default 20)
    const limit = args.limit ?? 20;
    const limited = packages.slice(0, limit);
    const hasMore = packages.length > limit;
  
    if (packages.length === 0) {
      let msg = "No packages found";
      if (args.search) msg += ` matching "${args.search}"`;
      if (args.type) msg += ` of type "${args.type}"`;
      return { content: msg + ".", isError: false };
    }
  
    // Compact text format
    const outputLines = limited.map(pkg =>
      `- ${pkg.id} (${pkg.visibility}, ${pkg.size})`
    );
  
    let output = `Packages (showing ${limited.length} of ${packages.length}`;
    if (args.search) output += ` matching "${args.search}"`;
    output += `, ${totalCount} total):\n${outputLines.join("\n")}`;
  
    if (hasMore) {
      output += `\n\n... and ${packages.length - limit} more. Use 'limit' to see more or 'search' to filter.`;
    }
  
    return { content: output, isError: false };
  },

• src/tools/packages.ts:95-108 (schema)

  Input schema using Zod for validating tool arguments: optional search string, type enum ('e2e' or 'utility'), and limit number.

  inputSchema: z.object({
    search: z
      .string()
      .optional()
      .describe("Search/filter packages by name or namespace"),
    type: z
      .enum(["e2e", "utility"])
      .optional()
      .describe("Filter by package type"),
    limit: z
      .number()
      .optional()
      .describe("Maximum number of packages to return (default: 20)"),
  }),

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

  Aggregates and exports allTools object by spreading packagesTools (which contains list_packages) along with other tool groups.

  export const allTools = {
    ...authTools,
    ...testExecutionTools,
    ...testResultsTools,
    ...groupsTools,
    ...environmentTools,
    ...packagesTools,
    ...configTools,
    ...utilitiesTools,
  };

• src/server.ts:29-35 (registration)

  Registers list_packages (via allTools) for MCP's listTools request by mapping to MCP tool format (name, description, jsonSchema), with CLI detection note if missing.

  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),
  }));

• src/server.ts:44-44 (registration)

  Looks up the list_packages handler (via allTools) by name in MCP's callTool request handler.

  const tool = allTools[name as ToolName];