Dynalist MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:627-739 (handler)

  The core handler function executing the tool logic: parses Dynalist URL or file_id, validates timestamps, reads the document, filters nodes by creation/modification time within the range, determines change type, optionally includes parent nodes for context, sorts results, performs size check with bypass option, and returns formatted JSON or error/content.
  async ({ url, file_id, since, until, type, parent_levels, sort, 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, }; } // Parse timestamps const parseTimestamp = (val: string | number, endOfDay: boolean = false): number => { if (typeof val === "number") return val; const date = new Date(val); // If it's a date-only string (no time component) and endOfDay is true, use end of day if (endOfDay && /^\d{4}-\d{2}-\d{2}$/.test(val)) { date.setUTCHours(23, 59, 59, 999); } return date.getTime(); }; const sinceTs = parseTimestamp(since, false); const untilTs = until ? parseTimestamp(until, true) : Date.now(); if (isNaN(sinceTs)) { return { content: [{ type: "text", text: "Error: Invalid 'since' date format" }], isError: true, }; } const doc = await client.readDocument(documentId); // Filter nodes by time range and type const matches = doc.nodes .filter((node) => { const createdInRange = node.created >= sinceTs && node.created <= untilTs; const modifiedInRange = node.modified >= sinceTs && node.modified <= untilTs; if (type === "created") return createdInRange; if (type === "modified") return modifiedInRange && !createdInRange; // Modified but not newly created // "both" - either created or modified in range return createdInRange || modifiedInRange; }) .map((node) => { const createdInRange = node.created >= sinceTs && node.created <= untilTs; const result: { id: string; content: string; created: number; modified: number; url: string; change_type: string; parents?: { id: string; content: string }[]; } = { id: node.id, content: node.content, created: node.created, modified: node.modified, url: buildDynalistUrl(documentId!, node.id), change_type: createdInRange ? "created" : "modified", }; // Add parents if requested if (parent_levels > 0) { const parents = getAncestors(doc.nodes, node.id, parent_levels); if (parents.length > 0) { result.parents = parents; } } return result; }); // Sort matches.sort((a, b) => { const aTime = a.change_type === "created" ? a.created : a.modified; const bTime = b.change_type === "created" ? b.created : b.modified; return sort === "newest_first" ? bTime - aTime : aTime - bTime; }); const resultText = matches.length > 0 ? JSON.stringify(matches, null, 2) : `No changes found in the specified time period`; // Check content size const sizeCheck = checkContentSize(resultText, bypass_warning || false, [ "Use a shorter time period (narrower since/until range)", "Use parent_levels: 0 to exclude parent context", "Filter by type: 'created' or 'modified' instead of 'both'", ]); if (sizeCheck) { return { content: [{ type: "text", text: sizeCheck.warning }], }; } return { content: [ { type: "text", text: resultText, }, ], }; }
• src/tools/index.ts:617-626 (schema)

  Zod schema defining the input parameters for the get_recent_changes tool, including optional URL/file_id, required since timestamp, optional until/type/parent_levels/sort, and bypass_warning.
  { url: z.string().optional().describe("Dynalist URL"), file_id: z.string().optional().describe("Document ID (alternative to URL)"), since: z.union([z.string(), z.number()]).describe("Start date - ISO string (e.g. '2024-01-15') or timestamp in milliseconds"), until: z.union([z.string(), z.number()]).optional().describe("End date - ISO string or timestamp (default: now)"), type: z.enum(["created", "modified", "both"]).optional().default("modified").describe("Filter by change type"), parent_levels: z.number().optional().default(1).describe("How many parent levels to include for context"), sort: z.enum(["newest_first", "oldest_first"]).optional().default("newest_first").describe("Sort order by timestamp"), 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:614-740 (registration)

  The server.tool registration call that registers the get_recent_changes tool with its description, input schema, and handler function.
  server.tool( "get_recent_changes", "Get nodes created or modified within a time period. WARNING: Long time periods with active documents can return many words.", { url: z.string().optional().describe("Dynalist URL"), file_id: z.string().optional().describe("Document ID (alternative to URL)"), since: z.union([z.string(), z.number()]).describe("Start date - ISO string (e.g. '2024-01-15') or timestamp in milliseconds"), until: z.union([z.string(), z.number()]).optional().describe("End date - ISO string or timestamp (default: now)"), type: z.enum(["created", "modified", "both"]).optional().default("modified").describe("Filter by change type"), parent_levels: z.number().optional().default(1).describe("How many parent levels to include for context"), sort: z.enum(["newest_first", "oldest_first"]).optional().default("newest_first").describe("Sort order by timestamp"), 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, since, until, type, parent_levels, sort, 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, }; } // Parse timestamps const parseTimestamp = (val: string | number, endOfDay: boolean = false): number => { if (typeof val === "number") return val; const date = new Date(val); // If it's a date-only string (no time component) and endOfDay is true, use end of day if (endOfDay && /^\d{4}-\d{2}-\d{2}$/.test(val)) { date.setUTCHours(23, 59, 59, 999); } return date.getTime(); }; const sinceTs = parseTimestamp(since, false); const untilTs = until ? parseTimestamp(until, true) : Date.now(); if (isNaN(sinceTs)) { return { content: [{ type: "text", text: "Error: Invalid 'since' date format" }], isError: true, }; } const doc = await client.readDocument(documentId); // Filter nodes by time range and type const matches = doc.nodes .filter((node) => { const createdInRange = node.created >= sinceTs && node.created <= untilTs; const modifiedInRange = node.modified >= sinceTs && node.modified <= untilTs; if (type === "created") return createdInRange; if (type === "modified") return modifiedInRange && !createdInRange; // Modified but not newly created // "both" - either created or modified in range return createdInRange || modifiedInRange; }) .map((node) => { const createdInRange = node.created >= sinceTs && node.created <= untilTs; const result: { id: string; content: string; created: number; modified: number; url: string; change_type: string; parents?: { id: string; content: string }[]; } = { id: node.id, content: node.content, created: node.created, modified: node.modified, url: buildDynalistUrl(documentId!, node.id), change_type: createdInRange ? "created" : "modified", }; // Add parents if requested if (parent_levels > 0) { const parents = getAncestors(doc.nodes, node.id, parent_levels); if (parents.length > 0) { result.parents = parents; } } return result; }); // Sort matches.sort((a, b) => { const aTime = a.change_type === "created" ? a.created : a.modified; const bTime = b.change_type === "created" ? b.created : b.modified; return sort === "newest_first" ? bTime - aTime : aTime - bTime; }); const resultText = matches.length > 0 ? JSON.stringify(matches, null, 2) : `No changes found in the specified time period`; // Check content size const sizeCheck = checkContentSize(resultText, bypass_warning || false, [ "Use a shorter time period (narrower since/until range)", "Use parent_levels: 0 to exclude parent context", "Filter by type: 'created' or 'modified' instead of 'both'", ]); if (sizeCheck) { return { content: [{ type: "text", text: sizeCheck.warning }], }; } return { content: [ { type: "text", text: resultText, }, ], }; } );