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
查询可用的命令列表
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "queryCommands"
}
}Input 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 }; }