Dynalist MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:327-389 (handler)

  The primary MCP tool handler for 'send_to_inbox'. Parses input content as a hierarchical tree using parseMarkdownBullets, sends the first node to Dynalist inbox via client.sendToInbox, inserts its children, then adds remaining top-level siblings after the first node and their children.

  async ({ content, note, checkbox }) => {
    // Parse content as markdown to detect hierarchy
    const tree = parseMarkdownBullets(content);
  
    if (tree.length === 0) {
      return {
        content: [{ type: "text", text: "No content to add (empty input)" }],
        isError: true,
      };
    }
  
    // Step 1: Add first top-level item via inbox API (to get inbox file_id)
    const firstResponse = await client.sendToInbox({
      content: tree[0].content,
      note,
      checkbox,
    });
  
    const inboxFileId = firstResponse.file_id;
    const firstNodeId = firstResponse.node_id;
    let totalCreated = 1;
  
    // Step 2: Insert children of first node (if any)
    if (tree[0].children.length > 0) {
      const result = await insertTreeUnderParent(client, inboxFileId, firstNodeId, tree[0].children, { checkbox });
      totalCreated += result.totalCreated;
    }
  
    // Step 3: Insert remaining top-level items with their children
    if (tree.length > 1) {
      const inboxDoc = await client.readDocument(inboxFileId);
      const inboxRootId = findRootNodeId(inboxDoc.nodes);
      const rootNode = inboxDoc.nodes.find(n => n.id === inboxRootId);
      const firstNodeIndex = rootNode?.children?.indexOf(firstNodeId) ?? -1;
  
      // Remaining top-level items (without their children first)
      const remainingTopLevel: ParsedNode[] = tree.slice(1).map(n => ({ content: n.content, children: [] }));
      const topResult = await insertTreeUnderParent(client, inboxFileId, inboxRootId, remainingTopLevel, {
        startIndex: firstNodeIndex + 1,
        checkbox,
      });
      totalCreated += topResult.totalCreated;
  
      // Now insert children of each remaining top-level node
      for (let i = 0; i < topResult.rootNodeIds.length; i++) {
        const parentId = topResult.rootNodeIds[i];
        const children = tree[i + 1].children;
        if (children.length > 0) {
          const childResult = await insertTreeUnderParent(client, inboxFileId, parentId, children, { checkbox });
          totalCreated += childResult.totalCreated;
        }
      }
    }
  
    return {
      content: [
        {
          type: "text",
          text: `Successfully added ${totalCreated} items to inbox!\nDocument: ${inboxFileId}\nFirst node: ${buildDynalistUrl(inboxFileId, firstNodeId)}`,
        },
      ],
    };
  }

• src/tools/index.ts:322-326 (schema)

  Zod input schema defining parameters for the send_to_inbox tool: content (required string), note (optional string), checkbox (optional boolean, default false).

  {
    content: z.string().describe("The text content - can be single line or indented markdown with '- bullets'"),
    note: z.string().optional().describe("Optional note for the first/root item"),
    checkbox: z.boolean().optional().default(false).describe("Whether to add checkboxes to items"),
  },

• src/tools/index.ts:319-321 (registration)

  MCP server tool registration call for 'send_to_inbox', specifying name, description, schema, and handler function.

  server.tool(
    "send_to_inbox",
    "Send items to your Dynalist inbox. Supports indented markdown/bullets for hierarchical content.",

• src/tools/index.ts:95-148 (helper)

  Helper function used by the handler to insert a full tree of parsed nodes (multiple levels) under a given parent ID in a Dynalist document, preserving hierarchy level-by-level.

  async function insertTreeUnderParent(
    client: DynalistClient,
    fileId: string,
    parentId: string,
    tree: ParsedNode[],
    options: { startIndex?: number; checkbox?: boolean } = {}
  ): Promise<{ totalCreated: number; rootNodeIds: string[] }> {
    if (tree.length === 0) {
      return { totalCreated: 0, rootNodeIds: [] };
    }
  
    const levels = groupByLevel(tree);
    let totalCreated = 0;
    let rootNodeIds: string[] = [];
    let previousLevelIds: string[] = [];
  
    for (let levelIdx = 0; levelIdx < levels.length; levelIdx++) {
      const level = levels[levelIdx];
      const changes: { action: string; parent_id: string; index: number; content: string; checkbox?: boolean }[] = [];
      const childCountPerParent = new Map<string, number>();
  
      for (const node of level) {
        const nodeParentId = node.parentLevelIndex === -1
          ? parentId
          : previousLevelIds[node.parentLevelIndex];
  
        const baseIndex = (levelIdx === 0 && options.startIndex !== undefined)
          ? options.startIndex
          : 0;
        const count = childCountPerParent.get(nodeParentId) || 0;
  
        changes.push({
          action: "insert",
          parent_id: nodeParentId,
          index: baseIndex + count,
          content: node.content,
          checkbox: options.checkbox || undefined,
        });
        childCountPerParent.set(nodeParentId, count + 1);
      }
  
      const response = await client.editDocument(fileId, changes as any);
      const newIds = response.new_node_ids || [];
  
      if (levelIdx === 0) {
        rootNodeIds = newIds;
      }
  
      totalCreated += newIds.length;
      previousLevelIds = newIds;
    }
  
    return { totalCreated, rootNodeIds };
  }

• src/dynalist-client.ts:125-136 (helper)

  DynalistClient helper method that performs the actual API request to Dynalist's /inbox/add endpoint to create the first inbox node, called directly by the tool handler.

    async sendToInbox(options: {
      content: string;
      note?: string;
      index?: number;
      checked?: boolean;
      checkbox?: boolean;
      heading?: number;
      color?: number;
    }): Promise<InboxAddResponse> {
      return this.request<InboxAddResponse>("/inbox/add", options);
    }
  }