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();
    }
  }