Dynalist MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:467-504 (handler)

  The handler function for the 'insert_node' tool. It parses the input URL or file_id to get the document ID, constructs an 'insert' change object for the Dynalist client, calls editDocument to insert the new node, and returns a success message with the new node ID and URL.

    let documentId = file_id;
  
    if (url) {
      const parsed = parseDynalistUrl(url);
      documentId = parsed.documentId;
    }
  
    if (!documentId) {
      return {
        content: [{ type: "text", text: "Error: Either 'url' or 'file_id' must be provided" }],
        isError: true,
      };
    }
  
    const change: Record<string, unknown> = {
      action: "insert",
      parent_id,
      index,
      content,
    };
  
    if (note) change.note = note;
    if (checkbox) change.checkbox = checkbox;
    if (heading) change.heading = heading;
  
    const response = await client.editDocument(documentId, [change as any]);
  
    const newNodeId = response.new_node_ids?.[0];
  
    return {
      content: [
        {
          type: "text",
          text: `Node inserted successfully!\nDocument: ${documentId}\nParent: ${parent_id}\nNew Node ID: ${newNodeId || "unknown"}\nURL: ${buildDynalistUrl(documentId, newNodeId)}`,
        },
      ],
    };
  }

• src/tools/index.ts:456-466 (schema)

  The Zod schema defining the input parameters for the 'insert_node' tool, including url/file_id, parent_id, content, and optional fields like note, index, checkbox, and heading.

  {
    url: z.string().optional().describe("Dynalist URL (document or with parent node deep link)"),
    file_id: z.string().optional().describe("Document ID (alternative to URL)"),
    parent_id: z.string().describe("Parent node ID to insert under"),
    content: z.string().describe("Content text for the new node"),
    note: z.string().optional().describe("Note text for the new node"),
    index: z.number().optional().default(-1).describe("Position under parent (-1 = end, 0 = top)"),
    checkbox: z.boolean().optional().default(false).describe("Whether to add a checkbox"),
    heading: z.number().min(0).max(3).optional().describe("Heading level (0-3)"),
  },
  async ({ url, file_id, parent_id, content, note, index, checkbox, heading }) => {

• src/tools/index.ts:453-505 (registration)

  The registration of the 'insert_node' tool using server.tool(), including name, description, schema, and handler function.

  server.tool(
    "insert_node",
    "Insert a new node into a Dynalist document",
    {
      url: z.string().optional().describe("Dynalist URL (document or with parent node deep link)"),
      file_id: z.string().optional().describe("Document ID (alternative to URL)"),
      parent_id: z.string().describe("Parent node ID to insert under"),
      content: z.string().describe("Content text for the new node"),
      note: z.string().optional().describe("Note text for the new node"),
      index: z.number().optional().default(-1).describe("Position under parent (-1 = end, 0 = top)"),
      checkbox: z.boolean().optional().default(false).describe("Whether to add a checkbox"),
      heading: z.number().min(0).max(3).optional().describe("Heading level (0-3)"),
    },
    async ({ url, file_id, parent_id, content, note, index, checkbox, heading }) => {
      let documentId = file_id;
  
      if (url) {
        const parsed = parseDynalistUrl(url);
        documentId = parsed.documentId;
      }
  
      if (!documentId) {
        return {
          content: [{ type: "text", text: "Error: Either 'url' or 'file_id' must be provided" }],
          isError: true,
        };
      }
  
      const change: Record<string, unknown> = {
        action: "insert",
        parent_id,
        index,
        content,
      };
  
      if (note) change.note = note;
      if (checkbox) change.checkbox = checkbox;
      if (heading) change.heading = heading;
  
      const response = await client.editDocument(documentId, [change as any]);
  
      const newNodeId = response.new_node_ids?.[0];
  
      return {
        content: [
          {
            type: "text",
            text: `Node inserted successfully!\nDocument: ${documentId}\nParent: ${parent_id}\nNew Node ID: ${newNodeId || "unknown"}\nURL: ${buildDynalistUrl(documentId, newNodeId)}`,
          },
        ],
      };
    }
  );