Obsidian MCP Server

Instructions

Implementation Reference

• src/services/PeriodicNotesService.ts:142-196 (handler)

  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'],
  },