list_nodes

Instructions

Implementation Reference

• src/tools/workflowy.ts:11-31 (handler)

  The main handler function for the list_nodes tool. It calls workflowyClient.getChildItems (if parentId provided) or workflowyClient.getRootItems (if omitted), then returns the result as JSON text. It handles depth limiting and error handling.

  handler: async ({ parentId, depth, username, password }: { parentId?: string, depth?: number, username?: string, password?: string }) => {
    try {
      const effectiveDepth = depth ?? 0;
      const items = !!parentId
        ? await workflowyClient.getChildItems(parentId, username, password, effectiveDepth)
        : await workflowyClient.getRootItems(username, password, effectiveDepth);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(items, null, 2)
        }]
      };
    } catch (error: any) {
      return {
        content: [{
          type: "text",
          text: `Error listing nodes: ${error.message}`
        }]
      };
    }
  },

• src/tools/workflowy.ts:6-10 (schema)

  Input schema for list_nodes: optional parentId (string) and optional depth (number, default 0, with -1 for unlimited). Defined using Zod.

  description: "List nodes in Workflowy. If a `parentId` is provided, it lists the child nodes of that parent. If omitted, it lists the root nodes. By default only returns top-level nodes (depth=0). WARNING: Using depth=-1 (unlimited) can return massive amounts of data and blow up your context - use sparingly!",
  inputSchema: {
    parentId: z.string().optional().describe("ID of the parent node to list children from. If omitted, returns root nodes."),
    depth: z.number().optional().describe("How many levels deep to return. 0 = top level only (default), 1 = include immediate children, -1 = unlimited (WARNING: can return huge amounts of data!)")
  },

• src/tools/index.ts:12-21 (registration)

  The registerTools function that registers all tools (including list_nodes) with the FastMCP server. It iterates over toolRegistry and calls server.addTool with name, description, parameters (from zod schema), annotations, and the handler as execute.

  export function registerTools(server: FastMCP): void {
    Object.entries(toolRegistry).forEach(([name, tool]) => {
      server.addTool({
        name,
        description: tool.description,
        parameters: z.object(tool.inputSchema),
        annotations: tool.annotations,
        execute: tool.handler
        });
    });

• src/tools/index.ts:6-9 (registration)

  The toolRegistry object which spreads workflowyTools (including list_nodes) into a central registry.

  export const toolRegistry: Record<string, any> = {
    ...workflowyTools,
    // Add more tool categories here
  };

• src/workflowy/client.ts:51-57 (helper)

  Helper method getRootItems on the WorkflowyClient class that retrieves root nodes from the Workflowy document, applying depth limiting via limitDepth.

  async getRootItems(username?: string, password?: string, depth: number = 0) {
      const { wf, client } = await this.createAuthenticatedClient(username, password);
      const doc = await wf.getDocument();
      client.getTreeData()
      const root = doc.root.toJson();
      return this.limitDepth(root, -1, depth);
  }