create_node

Instructions

Implementation Reference

• src/tools/workflowy.ts:73-107 (handler)

  The tool definition and handler for 'create_node'. Defines the input schema (parentId, name, description), and the handler that calls workflowyClient.createNode() and returns the result.

  create_node: {
    description: "Create a new node",
    inputSchema: {
      parentId: z.string().optional().describe("ID of the parent node. If omitted, creates at root level."),
      name: z.string().describe("Name/title for the new node"),
      description: z.string().optional().describe("Description/note for the new node")
    },
    annotations: {
        title: "Create a new node in Workflowy",
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false
    },
    handler: async ({ parentId, name, description, username, password }:
        { parentId: string | undefined, name: string, description?: string, username?: string, password?: string },
        client: typeof workflowyClient) => {
      try {
        const newNodeId = await workflowyClient.createNode(parentId, name, description, username, password);
        return {
          content: [{
            type: "text",
            text: JSON.stringify({ success: true, nodeId: newNodeId, name, parentId: parentId || "root" })
          }]
        };
      } catch (error: any) {
        return {
          content: [{
            type: "text",
            text: `Error creating node: ${error.message}`
          }]
        };
      }
    }
  },

• src/tools/workflowy.ts:75-79 (schema)

  Input schema for create_node: parentId (optional string), name (required string), description (optional string).

  inputSchema: {
    parentId: z.string().optional().describe("ID of the parent node. If omitted, creates at root level."),
    name: z.string().describe("Name/title for the new node"),
    description: z.string().optional().describe("Description/note for the new node")
  },

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

  The central tool registry (toolRegistry) includes workflowyTools. The registerTools() function iterates over the registry and registers each tool (including create_node) with the FastMCP server.

  export const toolRegistry: Record<string, any> = {
    ...workflowyTools,
    // Add more tool categories here
  };
  
  // Helper to register tools with MCP server
  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/workflowy/client.ts:98-123 (helper)

  The WorkflowyClient.createNode() method. Authenticates, gets the document, finds the parent node (or uses root), creates a child item, sets its name and optional note, saves, and returns the new node ID.

  /**
   * Create a new node at a specific location
   */
  async createNode(parentId: string | undefined, name: string, description?: string, username?: string, password?: string) {
      const { wf } = await this.createAuthenticatedClient(username, password);
      const doc = await wf.getDocument();
  
      let parent;
      if (parentId) {
          parent = this.findNodeById(doc.root, parentId);
          if (!parent) {
              throw new Error(`Parent node with ID ${parentId} not found.`);
          }
      } else {
          parent = doc.root;
      }
  
      const newNode = await parent.createItem();
      newNode.setName(name);
      if (description) {
          newNode.setNote(description);
      }
      // Always save - isDirty() may not detect all changes
      await doc.save();
      return newNode.id;
  }