Dynalist MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:522-608 (handler)

  Main handler function: parses input, fetches document, filters nodes matching query in content or notes, adds optional parent/children context, checks result size with warning, returns JSON array of matches.

  async ({ url, file_id, query, search_notes, parent_levels, include_children, bypass_warning }) => {
    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 doc = await client.readDocument(documentId);
    const nodeMap = buildNodeMap(doc.nodes);
    const queryLower = query.toLowerCase();
  
    const matches = doc.nodes
      .filter((node) => {
        const contentMatch = node.content?.toLowerCase().includes(queryLower);
        const noteMatch = search_notes && node.note?.toLowerCase().includes(queryLower);
        return contentMatch || noteMatch;
      })
      .map((node) => {
        const result: {
          id: string;
          content: string;
          note?: string;
          url: string;
          parents?: { id: string; content: string }[];
          children?: { id: string; content: string }[];
        } = {
          id: node.id,
          content: node.content,
          note: node.note || undefined,
          url: buildDynalistUrl(documentId!, node.id),
        };
  
        // Add parents if requested
        if (parent_levels > 0) {
          const parents = getAncestors(doc.nodes, node.id, parent_levels);
          if (parents.length > 0) {
            result.parents = parents;
          }
        }
  
        // Add children if requested
        if (include_children && node.children && node.children.length > 0) {
          result.children = node.children
            .map(childId => {
              const childNode = nodeMap.get(childId);
              return childNode ? { id: childNode.id, content: childNode.content } : null;
            })
            .filter((c): c is { id: string; content: string } => c !== null);
        }
  
        return result;
      });
  
    const resultText = matches.length > 0
      ? JSON.stringify(matches, null, 2)
      : `No matches found for "${query}"`;
  
    // Check content size
    const sizeCheck = checkContentSize(resultText, bypass_warning || false, [
      "Use a more specific query to reduce matches",
      "Use parent_levels: 0 to exclude parent context",
      "Use include_children: false to exclude children",
    ]);
  
    if (sizeCheck) {
      return {
        content: [{ type: "text", text: sizeCheck.warning }],
      };
    }
  
    return {
      content: [
        {
          type: "text",
          text: resultText,
        },
      ],
    };
  }

• src/tools/index.ts:513-521 (schema)

  Zod input schema defining parameters for the search_in_document tool.

  {
    url: z.string().optional().describe("Dynalist URL"),
    file_id: z.string().optional().describe("Document ID (alternative to URL)"),
    query: z.string().describe("Text to search for (case-insensitive)"),
    search_notes: z.boolean().optional().default(true).describe("Also search in notes"),
    parent_levels: z.number().optional().default(1).describe("How many parent levels to include (0 = none, 1 = direct parent, 2+ = ancestors)"),
    include_children: z.boolean().optional().default(false).describe("Include direct children (level 1) of each match"),
    bypass_warning: z.boolean().optional().default(false).describe("ONLY use after receiving a size warning. Do NOT set true on first request."),
  },

• src/tools/index.ts:510-609 (registration)

  MCP server.tool registration call for search_in_document, including name, description, schema, and handler function.

  server.tool(
    "search_in_document",
    "Search for text in a Dynalist document. Returns matching nodes with optional parent context and children. WARNING: Many matches with parents/children can return many words.",
    {
      url: z.string().optional().describe("Dynalist URL"),
      file_id: z.string().optional().describe("Document ID (alternative to URL)"),
      query: z.string().describe("Text to search for (case-insensitive)"),
      search_notes: z.boolean().optional().default(true).describe("Also search in notes"),
      parent_levels: z.number().optional().default(1).describe("How many parent levels to include (0 = none, 1 = direct parent, 2+ = ancestors)"),
      include_children: z.boolean().optional().default(false).describe("Include direct children (level 1) of each match"),
      bypass_warning: z.boolean().optional().default(false).describe("ONLY use after receiving a size warning. Do NOT set true on first request."),
    },
    async ({ url, file_id, query, search_notes, parent_levels, include_children, bypass_warning }) => {
      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 doc = await client.readDocument(documentId);
      const nodeMap = buildNodeMap(doc.nodes);
      const queryLower = query.toLowerCase();
  
      const matches = doc.nodes
        .filter((node) => {
          const contentMatch = node.content?.toLowerCase().includes(queryLower);
          const noteMatch = search_notes && node.note?.toLowerCase().includes(queryLower);
          return contentMatch || noteMatch;
        })
        .map((node) => {
          const result: {
            id: string;
            content: string;
            note?: string;
            url: string;
            parents?: { id: string; content: string }[];
            children?: { id: string; content: string }[];
          } = {
            id: node.id,
            content: node.content,
            note: node.note || undefined,
            url: buildDynalistUrl(documentId!, node.id),
          };
  
          // Add parents if requested
          if (parent_levels > 0) {
            const parents = getAncestors(doc.nodes, node.id, parent_levels);
            if (parents.length > 0) {
              result.parents = parents;
            }
          }
  
          // Add children if requested
          if (include_children && node.children && node.children.length > 0) {
            result.children = node.children
              .map(childId => {
                const childNode = nodeMap.get(childId);
                return childNode ? { id: childNode.id, content: childNode.content } : null;
              })
              .filter((c): c is { id: string; content: string } => c !== null);
          }
  
          return result;
        });
  
      const resultText = matches.length > 0
        ? JSON.stringify(matches, null, 2)
        : `No matches found for "${query}"`;
  
      // Check content size
      const sizeCheck = checkContentSize(resultText, bypass_warning || false, [
        "Use a more specific query to reduce matches",
        "Use parent_levels: 0 to exclude parent context",
        "Use include_children: false to exclude children",
      ]);
  
      if (sizeCheck) {
        return {
          content: [{ type: "text", text: sizeCheck.warning }],
        };
      }
  
      return {
        content: [
          {
            type: "text",
            text: resultText,
          },
        ],
      };
    }
  );

• src/tools/index.ts:67-89 (helper)

  Helper function to retrieve ancestor (parent) nodes for providing context around search matches.

  function getAncestors(
    nodes: import("../dynalist-client.js").DynalistNode[],
    nodeId: string,
    levels: number
  ): { id: string; content: string }[] {
    if (levels <= 0) return [];
  
    const ancestors: { id: string; content: string }[] = [];
    let currentId = nodeId;
  
    for (let i = 0; i < levels; i++) {
      const parentInfo = findNodeParent(nodes, currentId);
      if (!parentInfo) break; // Reached root or node not found
  
      const parentNode = nodes.find(n => n.id === parentInfo.parentId);
      if (!parentNode) break;
  
      ancestors.push({ id: parentNode.id, content: parentNode.content });
      currentId = parentNode.id;
    }
  
    return ancestors;
  }

• src/tools/index.ts:23-61 (helper)

  Helper to check result size and issue warnings or block large outputs, used before returning search results.

  function checkContentSize(
    content: string,
    bypassWarning: boolean,
    recommendations: string[]
  ): { warning: string; canBypass: boolean } | null {
    const tokenCount = estimateTokens(content);
  
    // If bypass was used preemptively (result is small), warn against this practice
    if (bypassWarning && tokenCount <= 5000) {
      return {
        warning: `⚠️ INCORRECT USAGE: You used bypass_warning: true preemptively.\n\n` +
          `The bypass_warning option should ONLY be used AFTER receiving a size warning, ` +
          `not on the first request. Please repeat the request WITHOUT bypass_warning to get the result.\n\n` +
          `This ensures you're aware of large results before they fill your context.`,
        canBypass: false,
      };
    }
  
    if (tokenCount <= 5000 || bypassWarning) {
      return null; // OK to return content
    }
  
    const canBypass = tokenCount <= 24500;
  
    let warning = `⚠️ LARGE RESULT WARNING\n`;
    warning += `This query would return ~${tokenCount.toLocaleString()} tokens which may fill your context.\n\n`;
    warning += `Recommendations:\n`;
    for (const rec of recommendations) {
      warning += `- ${rec}\n`;
    }
  
    if (canBypass) {
      warning += `\nTo receive the full result anyway (~${tokenCount.toLocaleString()} tokens), repeat the SAME request with bypass_warning: true`;
    } else {
      warning += `\n❌ Result too large (>${(24500).toLocaleString()} tokens). Please reduce the scope using the recommendations above.`;
    }
  
    return { warning, canBypass };
  }