Granola MCP Server

Instructions

Implementation Reference

• src/server.ts:357-397 (handler)

  Complete filter_by_folder tool implementation with registration, schema, and handler logic. The tool filters meetings by folder ID, retrieves documents from that folder, and returns a formatted list of document titles and dates.

  // Tool: filter_by_folder
  server.addTool({
    name: 'filter_by_folder',
    description: 'Filter meetings by folder',
    parameters: z.object({
      folder_id: z.string().describe('Folder ID to filter by')
    }),
    execute: async ({ folder_id }) => {
      await ensureDataLoaded();
  
      // Find the folder
      const folder = foldersCache.find(f => f.id === folder_id);
      if (!folder) {
        return `Folder '${folder_id}' not found`;
      }
  
      const folderName = folder.title || folder.name || 'Untitled';
      const docIds = folder.document_ids || [];
  
      const docs = docIds
        .map(id => documentsCache.get(id))
        .filter((doc): doc is GranolaDocument => doc !== undefined);
  
      if (docs.length === 0) {
        return `No documents found in folder '${folderName}'`;
      }
  
      const output: string[] = [
        `# Documents in Folder: ${folderName}\n`,
        `Found ${docs.length} document(s)\n`
      ];
  
      for (const doc of docs) {
        output.push(`• **${getTitle(doc)}** (${doc.id})`);
        output.push(`  Date: ${formatDate(doc.created_at)}`);
        output.push('');
      }
  
      return output.join('\n');
    }
  });

• src/server.ts:361-363 (schema)

  Zod schema defining the tool's input parameters: folder_id as a required string with description.

  parameters: z.object({
    folder_id: z.string().describe('Folder ID to filter by')
  }),

• src/server.ts:364-396 (handler)

  Execute function that implements the tool logic: loads data, finds folder by ID, retrieves documents, and formats output with titles and dates.

  execute: async ({ folder_id }) => {
    await ensureDataLoaded();
  
    // Find the folder
    const folder = foldersCache.find(f => f.id === folder_id);
    if (!folder) {
      return `Folder '${folder_id}' not found`;
    }
  
    const folderName = folder.title || folder.name || 'Untitled';
    const docIds = folder.document_ids || [];
  
    const docs = docIds
      .map(id => documentsCache.get(id))
      .filter((doc): doc is GranolaDocument => doc !== undefined);
  
    if (docs.length === 0) {
      return `No documents found in folder '${folderName}'`;
    }
  
    const output: string[] = [
      `# Documents in Folder: ${folderName}\n`,
      `Found ${docs.length} document(s)\n`
    ];
  
    for (const doc of docs) {
      output.push(`• **${getTitle(doc)}** (${doc.id})`);
      output.push(`  Date: ${formatDate(doc.created_at)}`);
      output.push('');
    }
  
    return output.join('\n');
  }

• src/server.ts:65-79 (helper)

  Helper function formatDate that converts date strings to formatted local date strings for display in the tool output.

  function formatDate(dateStr: string | null | undefined): string {
    if (!dateStr) return 'Unknown date';
    try {
      const date = new Date(dateStr);
      return date.toLocaleString('en-US', {
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
        hour: '2-digit',
        minute: '2-digit',
        hour12: false
      });
    } catch {
      return dateStr;
    }

• src/server.ts:92-94 (helper)

  Helper function getTitle that safely extracts document title with fallback to 'Untitled Meeting'.

  function getTitle(doc: GranolaDocument): string {
    return doc.title || 'Untitled Meeting';
  }