list_periodic_notes
Retrieve periodic notes from your Obsidian vault by type and date range to organize and access time-based documentation efficiently.
Instructions
List periodic notes of a specific type
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | No | End date (YYYY-MM-DD) | |
| startDate | No | Start date (YYYY-MM-DD) | |
| type | Yes | Note type | |
| vault | Yes | Vault name |
Implementation Reference
- Core handler function that lists periodic notes by scanning the configured folder for .md files, parsing dates from filenames based on format, filtering by optional date range, sorting by date descending, and returning an array of PeriodicNoteInfo objects.async listPeriodicNotes( vaultPath: string, type: PeriodicNoteType, startDate?: Date, endDate?: Date ): Promise<VaultOperationResult<PeriodicNoteInfo[]>> { try { const config = this.settings[type]; const folderPath = path.join(vaultPath, config.folder); // Check if folder exists try { await fs.access(folderPath); } catch { return { success: true, data: [] }; } const { glob } = await import('glob'); const pattern = path.join(folderPath, '**/*.md'); const files = await glob(pattern); const notes: PeriodicNoteInfo[] = []; for (const file of files) { const relativePath = path.relative(vaultPath, file); const filename = path.basename(file, '.md'); // Try to parse date from filename const date = this.parseDateFromFilename(filename, config.format); if (!date) continue; // Filter by date range if specified if (startDate && date < startDate) continue; if (endDate && date > endDate) continue; notes.push({ type, date, path: relativePath, title: filename, exists: true, }); } // Sort by date descending notes.sort((a, b) => b.date.getTime() - a.date.getTime()); return { success: true, data: notes }; } catch (error) { return { success: false, error: `Failed to list ${type} notes: ${error instanceof Error ? error.message : String(error)}` }; } }
- src/index.ts:969-988 (handler)MCP server request handler for the list_periodic_notes tool. Validates vault connector, parses input arguments including type and date ranges, delegates to PeriodicNotesService.listPeriodicNotes, and formats the result as MCP content response.case 'list_periodic_notes': { const connector = this.connectors.get(args?.vault as string); if (!connector || !connector.vaultPath) { throw new Error(`Vault "${args?.vault}" not found or not a local vault`); } const type = args?.type as 'daily' | 'weekly' | 'monthly' | 'yearly'; const startDate = args?.startDate ? new Date(args.startDate as string) : undefined; const endDate = args?.endDate ? new Date(args.endDate as string) : undefined; const result = await this.periodicNotesService.listPeriodicNotes( connector.vaultPath, type, startDate, endDate ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }
- src/index.ts:459-472 (registration)Tool registration in the ListTools handler, defining the name, description, and input schema for list_periodic_notes.{ name: 'list_periodic_notes', description: 'List periodic notes of a specific type', inputSchema: { type: 'object', properties: { vault: { type: 'string', description: 'Vault name' }, type: { type: 'string', enum: ['daily', 'weekly', 'monthly', 'yearly'], description: 'Note type' }, startDate: { type: 'string', description: 'Start date (YYYY-MM-DD)' }, endDate: { type: 'string', description: 'End date (YYYY-MM-DD)' }, }, required: ['vault', 'type'], }, },
- src/index.ts:462-471 (schema)Input schema definition for the list_periodic_notes tool, specifying required vault and type, optional date ranges.inputSchema: { type: 'object', properties: { vault: { type: 'string', description: 'Vault name' }, type: { type: 'string', enum: ['daily', 'weekly', 'monthly', 'yearly'], description: 'Note type' }, startDate: { type: 'string', description: 'Start date (YYYY-MM-DD)' }, endDate: { type: 'string', description: 'End date (YYYY-MM-DD)' }, }, required: ['vault', 'type'], },