queryCommands

Instructions

Implementation Reference

• src/tools/queries.ts:14-52 (handler)

  The handler function for 'queryCommands' tool. It calls registry.listCommands to fetch filtered commands, formats them into a readable list, and returns an MCP response with text content and metadata. Handles errors gracefully.

  async ({ namespace, type }) => {
      try {
          const result = registry.listCommands(namespace, type);
          const commands = (result._meta || []).map(cmd => ({
              type: cmd.namespace ? `${cmd.namespace}.${cmd.name}` : cmd.name,
              description: cmd.description,
              params: Object.entries(cmd.params)
                  .map(([name, info]) => `${name}: ${info.type}${info.required ? ' (必填)' : ' (可选)'} - ${info.description}`)
                  .join('\n    ') || '无参数'
          }));
          
          const commandList = commands.map(cmd => 
              `${cmd.type}: ${cmd.description}\n  参数: ${cmd.params}`
          ).join('\n');
          
          return {
              content: [
                  {
                      type: 'text' as const,
                      text: `可用命令列表：\n${commandList}`
                  }
              ],
              _meta: {
                  commands: commands
              },
              isError: false
          };
      } catch (error) {
          return {
              content: [
                  {
                      type: 'text' as const,
                      text: error instanceof Error ? error.message : '查询失败'
                  }
              ],
              isError: true
          };
      }
  }

• src/tools/queries.ts:10-13 (schema)

  Zod input schema for the tool, defining optional 'namespace' and 'type' string parameters to filter the command list.

  {
      namespace: z.string().optional().describe('命令命名空间过滤'),
      type: z.string().optional().describe('命令名称过滤')
  },

• src/tools/queries.ts:6-54 (registration)

  The registerQueryTool function registers the 'queryCommands' tool on the MCP server using server.tool(), including name, description, input schema, and handler.

  export function registerQueryTool(server: McpServer) {
      server.tool(
          'queryCommands',
          '查询可用的命令列表',
          {
              namespace: z.string().optional().describe('命令命名空间过滤'),
              type: z.string().optional().describe('命令名称过滤')
          },
          async ({ namespace, type }) => {
              try {
                  const result = registry.listCommands(namespace, type);
                  const commands = (result._meta || []).map(cmd => ({
                      type: cmd.namespace ? `${cmd.namespace}.${cmd.name}` : cmd.name,
                      description: cmd.description,
                      params: Object.entries(cmd.params)
                          .map(([name, info]) => `${name}: ${info.type}${info.required ? ' (必填)' : ' (可选)'} - ${info.description}`)
                          .join('\n    ') || '无参数'
                  }));
                  
                  const commandList = commands.map(cmd => 
                      `${cmd.type}: ${cmd.description}\n  参数: ${cmd.params}`
                  ).join('\n');
                  
                  return {
                      content: [
                          {
                              type: 'text' as const,
                              text: `可用命令列表：\n${commandList}`
                          }
                      ],
                      _meta: {
                          commands: commands
                      },
                      isError: false
                  };
              } catch (error) {
                  return {
                      content: [
                          {
                              type: 'text' as const,
                              text: error instanceof Error ? error.message : '查询失败'
                          }
                      ],
                      isError: true
                  };
              }
          }
      );
  } 

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

  Invocation of registerQueryTool on the main MCP server instance, effecting the tool registration.

  registerQueryTool(server);

• src/utils/registry.ts:118-186 (helper)

  The listCommands method of CommandRegistry, used by the tool handler to retrieve and filter registered commands, extract parameter info from Zod schemas, and format the response.

  public listCommands(namespace?: string, type?: string): McpResponse<Array<{
      namespace: string;
      name: string;
      description: string;
      params: Record<string, {
          type: string;
          description: string;
          required: boolean;
      }>;
  }>> {
      const commands = Array.from(this.commands.entries()).filter(([fullName, cmd]) => {
          const [cmdNamespace] = this.parseFullCommandName(fullName);
          if (namespace && !cmdNamespace.includes(namespace)) return false;
          if (type && !cmd.name.includes(type)) return false;
          return true;
      }).map(([fullName, cmd]) => {
          // 获取参数说明
          const params: Record<string, {
              type: string;
              description: string;
              required: boolean;
          }> = {};
  
          try {
              if (cmd.params instanceof z.ZodObject) {
                  const shape = cmd.params._def.shape();
                  Object.entries(shape).forEach(([key, value]) => {
                      if (value instanceof z.ZodType) {
                          const isOptional = value instanceof z.ZodOptional;
                          params[key] = {
                              type: value._def.typeName || 'unknown',
                              description: value.description || '无说明',
                              required: !isOptional
                          };
                      }
                  });
              }
          } catch {
              // 如果无法获取 shape，返回空对象
          }
  
          const [cmdNamespace, cmdName] = this.parseFullCommandName(fullName);
          return {
              namespace: cmdNamespace,
              name: cmdName,
              description: cmd.description,
              params
          };
      });
  
      const commandList = commands.map(cmd => {
          const fullName = cmd.namespace ? `${cmd.namespace}.${cmd.name}` : cmd.name;
          const paramsList = Object.entries(cmd.params).map(([name, info]) => 
              `    ${name}: ${info.type}${info.required ? ' (必填)' : ' (可选)'} - ${info.description}`
          ).join('\n');
          
          return `${fullName}: ${cmd.description}\n${paramsList ? `  参数:\n${paramsList}` : '  参数: 无参数'}`;
      }).join('\n\n');
  
      return {
          content: [
              {
                  type: 'text',
                  text: `可用命令列表：\n${commandList}`
              }
          ],
          _meta: commands
      };
  }