Granola MCP Server

Instructions

Implementation Reference

• src/server.ts:286-319 (handler)

  Main implementation of the list_folders tool - defines the tool with its name, description, parameters (optional workspace_id filter), and the execute function that retrieves folders from cache, filters by workspace if provided, and returns a formatted list of folders with their IDs and document counts.
  // Tool: list_folders server.addTool({ name: 'list_folders', description: 'List all document folders', parameters: z.object({ workspace_id: z.string().optional().describe('Optional workspace ID to filter by') }), execute: async ({ workspace_id }) => { await ensureDataLoaded(); let folders = foldersCache; if (workspace_id) { folders = folders.filter(f => f.workspace_id === workspace_id); } if (folders.length === 0) { return 'No folders found'; } const output: string[] = ['# Folders\n']; for (const folder of folders) { const name = folder.title || folder.name || 'Untitled'; const docIds = folder.document_ids || []; output.push(`## ${name}`); output.push(`**ID:** ${folder.id}`); output.push(`**Documents:** ${docIds.length}`); output.push(''); } return output.join('\n'); } });
• src/server.ts:286-319 (registration)

  Tool registration using server.addTool() - registers the list_folders tool with the MCP server, defining its schema and handler in a single call.
  // Tool: list_folders server.addTool({ name: 'list_folders', description: 'List all document folders', parameters: z.object({ workspace_id: z.string().optional().describe('Optional workspace ID to filter by') }), execute: async ({ workspace_id }) => { await ensureDataLoaded(); let folders = foldersCache; if (workspace_id) { folders = folders.filter(f => f.workspace_id === workspace_id); } if (folders.length === 0) { return 'No folders found'; } const output: string[] = ['# Folders\n']; for (const folder of folders) { const name = folder.title || folder.name || 'Untitled'; const docIds = folder.document_ids || []; output.push(`## ${name}`); output.push(`**ID:** ${folder.id}`); output.push(`**Documents:** ${docIds.length}`); output.push(''); } return output.join('\n'); } });
• src/server.ts:290-292 (schema)

  Input schema definition using zod - defines the parameters for list_folders as an optional workspace_id string that can be used to filter folders by workspace.
  parameters: z.object({ workspace_id: z.string().optional().describe('Optional workspace ID to filter by') }),
• src/types.ts:31-41 (schema)

  Type definition for DocumentList interface - defines the shape of folder objects including id, title, name, created_at, workspace_id, owner_id, document_ids array, and optional documents and is_favourite fields.
  export interface DocumentList { id: string; title?: string; name?: string; created_at: string; workspace_id?: string; owner_id?: string; document_ids?: string[]; documents?: GranolaDocument[]; is_favourite?: boolean; }
• src/server.ts:30-35 (helper)

  ensureDataLoaded() helper function - ensures the folder cache is populated and fresh by calling loadData() if the cache is empty or expired, used by the list_folders tool handler.
  async function ensureDataLoaded() { const now = Date.now(); if (documentsCache.size === 0 || (now - lastFetchTime) > CACHE_TTL) { await loadData(); } }