MQScript MCP Server

Instructions

Implementation Reference

• src/tools/basic-commands.ts:484-505 (handler)

  The main handler function for the 'mqscript_findcolor' tool. It constructs and returns an MQScript code snippet that declares variables, calls FindColor with the provided parameters, and includes a conditional trace print based on the search result.

  handler: async (args: { 
    left?: number; top?: number; right?: number; bottom?: number; 
    colorValue: string; direction?: number; similarity?: number;
    xVariable?: string; yVariable?: string; resultVariable?: string;
  }) => {
    const { 
      left = 0, top = 0, right = 0, bottom = 0, 
      colorValue, direction = 0, similarity = 0.9,
      xVariable = 'intX', yVariable = 'intY', resultVariable = 'result'
    } = args;
    
    const script = `Dim ${xVariable}, ${yVariable}, ${resultVariable}\n${resultVariable} = FindColor(${left}, ${top}, ${right}, ${bottom}, "${colorValue}", ${direction}, ${similarity}, ${xVariable}, ${yVariable})\nIf ${resultVariable} > -1 Then\n    TracePrint "Found color at:", ${xVariable}, ${yVariable}\nElse\n    TracePrint "Color not found"\nEnd If`;
    
    return {
      content: [
        {
          type: 'text',
          text: `Generated MQScript find color command:\n\`\`\`\n${script}\n\`\`\`\n\nThis searches for color "${colorValue}" in region (${left},${top})-(${right},${bottom}) with ${similarity} similarity.`
        }
      ]
    };
  }

• src/tools/basic-commands.ts:429-483 (schema)

  Zod input schema defining the parameters for the findColor tool, including search region, color specs, direction, similarity, and output variable names.

  inputSchema: {
    type: 'object' as const,
    properties: {
      left: {
        type: 'number',
        description: 'Left boundary of search region (0 for full screen)',
        default: 0
      },
      top: {
        type: 'number',
        description: 'Top boundary of search region (0 for full screen)',
        default: 0
      },
      right: {
        type: 'number',
        description: 'Right boundary of search region (0 for full screen)',
        default: 0
      },
      bottom: {
        type: 'number',
        description: 'Bottom boundary of search region (0 for full screen)',
        default: 0
      },
      colorValue: {
        type: 'string',
        description: 'Color value in BBGGRR format, multiple colors separated by |, deviation with - (e.g., "FFFFFF-101010|123456")'
      },
      direction: {
        type: 'number',
        description: 'Search direction: 0=top-left to bottom-right, 1=center outward, 2=bottom-right to top-left, 3=bottom-left to top-right, 4=top-right to bottom-left',
        default: 0
      },
      similarity: {
        type: 'number',
        description: 'Color similarity (0-1, higher is more similar)',
        default: 0.9
      },
      xVariable: {
        type: 'string',
        description: 'Variable name to store found X coordinate',
        default: 'intX'
      },
      yVariable: {
        type: 'string',
        description: 'Variable name to store found Y coordinate',
        default: 'intY'
      },
      resultVariable: {
        type: 'string',
        description: 'Variable name to store result index',
        default: 'result'
      }
    },
    required: ['colorValue']
  },

• src/index.ts:32-61 (registration)

  The ALL_TOOLS object spreads ColorCommands (containing mqscript_findcolor) along with other command sets. This registry is used by the MCP server handlers to list and execute tools dynamically.

  const ALL_TOOLS = {
    // Basic Commands - 基础命令
    ...TouchCommands,
    ...ControlCommands,
    ...ColorCommands,
    ...OtherCommands,
    
    // Standard Library - 标准库函数
    ...MathFunctions,
    ...StringFunctions,
    ...TypeConversionFunctions,
    ...ArrayFunctions,
    
    // UI Commands - 界面命令
    ...UIControlCommands,
    ...UIPropertyCommands,
    ...FloatingWindowCommands,
    
    // Extension Commands - 扩展命令
    ...ElementCommands,
    ...DeviceCommands,
    ...PhoneCommands,
    ...SysCommands,
    
    // Plugin Commands - 插件命令
    ...CJsonCommands,
    ...DateTimeCommands,
    ...FileCommands,
    ...TuringCommands,
  };

• src/index.ts:64-72 (registration)

  MCP ListTools handler that exposes the mqscript_findcolor tool's metadata from the ALL_TOOLS registry.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: Object.values(ALL_TOOLS).map(tool => ({
        name: tool.name,
        description: tool.description,
        inputSchema: tool.inputSchema,
      })),
    };
  });

• src/index.ts:75-88 (registration)

  MCP CallTool handler that dynamically finds and invokes the handler for 'mqscript_findcolor' from the ALL_TOOLS registry.

  server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => {
    const { name, arguments: args } = request.params;
    
    const tool = Object.values(ALL_TOOLS).find(t => t.name === name);
    if (!tool) {
      throw new Error(`Unknown tool: ${name}`);
    }
    
    try {
      return await tool.handler(args as any || {});
    } catch (error) {
      throw new Error(`Error executing tool ${name}: ${error instanceof Error ? error.message : String(error)}`);
    }
  });