queryCommands
Retrieve a filtered list of available commands for managing and manipulating notes in the SiYuan Note system, based on specified namespaces or command types.
Instructions
查询可用的命令列表
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | 命令命名空间过滤 | |
| type | No | 命令名称过滤 |
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 }; }