Obsidian MCP Server

Instructions

Implementation Reference

• src/services/PeriodicNotesService.ts:34-99 (handler)

  Core handler function that implements the logic for creating periodic notes, including yearly notes (when type='yearly'). Handles path generation, template rendering or default content, file creation.

  async createPeriodicNote(
    vaultPath: string,
    type: PeriodicNoteType,
    date?: Date,
    variables?: Record<string, any>
  ): Promise<VaultOperationResult<string>> {
    try {
      const noteDate = date || new Date();
      const config = this.settings[type];
  
      if (!config.enabled) {
        return { success: false, error: `${type} notes are not enabled` };
      }
  
      // Generate note path
      const notePath = this.getPeriodicNotePath(type, noteDate);
      const fullPath = path.join(vaultPath, notePath);
  
      // Check if note already exists
      try {
        await fs.access(fullPath);
        return { success: true, data: notePath }; // Already exists
      } catch {
        // Note doesn't exist, continue to create
      }
  
      // Ensure directory exists
      await fs.mkdir(path.dirname(fullPath), { recursive: true });
  
      let content: string;
  
      // Use template if specified
      if (config.templatePath) {
        const renderResult = await this.templateService.renderTemplate(
          vaultPath,
          config.templatePath,
          {
            targetPath: notePath,
            variables: {
              ...this.getPeriodicNoteVariables(type, noteDate),
              ...variables,
            },
          }
        );
  
        if (!renderResult.success || !renderResult.data) {
          return { success: false, error: renderResult.error };
        }
  
        content = renderResult.data.content;
      } else {
        // Generate default content
        content = this.generateDefaultContent(type, noteDate);
      }
  
      // Write file
      await fs.writeFile(fullPath, content, 'utf-8');
  
      return { success: true, data: notePath };
    } catch (error) {
      return {
        success: false,
        error: `Failed to create ${type} note: ${error instanceof Error ? error.message : String(error)}`
      };
    }
  }

• src/index.ts:931-948 (handler)

  Tool handler dispatch in the main server switch statement that extracts parameters and delegates to PeriodicNotesService.createPeriodicNote with type 'yearly'.

  case 'create_yearly_note': {
    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 date = args?.date ? new Date(args.date as string) : undefined;
    const result = await this.periodicNotesService.createPeriodicNote(
      connector.vaultPath,
      'yearly',
      date,
      args?.variables as Record<string, any> | undefined
    );
  
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/index.ts:433-445 (registration)

  Registration of the 'create_yearly_note' tool including its description and input schema in the tools list provided to the MCP server.

  {
    name: 'create_yearly_note',
    description: 'Create a yearly note for a specific year',
    inputSchema: {
      type: 'object',
      properties: {
        vault: { type: 'string', description: 'Vault name' },
        date: { type: 'string', description: 'Date in the year (YYYY-MM-DD), defaults to this year' },
        variables: { type: 'object', description: 'Additional template variables' },
      },
      required: ['vault'],
    },
  },

• src/index.ts:436-445 (schema)

  Input schema definition for the create_yearly_note tool.

    inputSchema: {
      type: 'object',
      properties: {
        vault: { type: 'string', description: 'Vault name' },
        date: { type: 'string', description: 'Date in the year (YYYY-MM-DD), defaults to this year' },
        variables: { type: 'object', description: 'Additional template variables' },
      },
      required: ['vault'],
    },
  },