add_entry

Instructions

Implementation Reference

• src/journal/manager.ts:233-311 (handler)

  Core implementation of addEntry function: creates journal entry, handles file locking, parsing existing content, appending or creating new daily file, extracting title/tags, and writing back with frontmatter.

  export async function addEntry(
    options: AddEntryOptions
  ): Promise<JournalEntry> {
    const t = now();
    const date = t.format('YYYY-MM-DD');
    const timestamp = t.format();
    const filePath = getDateFilePath(date);
  
    // Acquire file lock
    await acquireLock(filePath);
  
    let backupPath: string | null = null;
  
    try {
      // Create entry
      const entry: JournalEntry = {
        id: `${date}-${timestamp}`,
        title: extractTitle(options.content),
        content: options.content,
        tags: options.tags || extractTags(options.content),
        created: timestamp,
        updated: timestamp,
        timestamp: t.format('HH:mm'), // HH:MM format
      };
  
      // Read existing file or create new one
      const existingContent = await readFileIfExists(filePath);
      let journalFile: JournalFile;
  
      if (existingContent) {
        // Backup existing file
        backupPath = await backupFile(filePath);
  
        // Parse existing file
        journalFile = await parseJournalFile(filePath, existingContent);
  
        // Add new entry
        journalFile.entries.push(entry);
        journalFile.updated = timestamp;
        journalFile.entries_count = journalFile.entries.length;
  
        // Merge tags
        const allTags = new Set([...journalFile.tags, ...entry.tags]);
        journalFile.tags = Array.from(allTags).sort();
      } else {
        // Create new file
        journalFile = {
          title: date,
          tags: entry.tags,
          created: timestamp,
          updated: timestamp,
          entries_count: 1,
          entries: [entry],
          filePath,
          date,
        };
      }
  
      // Write file
      const content = formatJournalFile(journalFile);
      await writeFileWithDir(filePath, content);
  
      // Clean up backup file after successful write
      if (backupPath) {
        await deleteFile(backupPath);
      }
  
      return entry;
    } catch (error) {
      // If write failed and we have a backup, we can keep it for recovery
      // Log the backup path for manual recovery if needed
      if (backupPath) {
        console.error(`Write failed, backup file preserved at: ${backupPath}`);
      }
      throw error;
    } finally {
      releaseLock(filePath);
    }
  }

• src/mcp-server.ts:33-60 (registration)

  Registers the 'add_entry' MCP tool with Zod input schema (content, optional tags) and a handler that calls the addEntry function from manager.ts, returning formatted success response.

  this.server.tool(
    'add_entry',
    'Add a new journal entry. If an entry for today already exists, it will append to the same file.',
    {
      content: z.string().describe('The content of the journal entry'),
      tags: z
        .array(z.string())
        .optional()
        .describe(
          'Optional tags for the entry (will also extract from content)'
        ),
    },
    async (args) => {
      const entry = await addEntry(args);
      return {
        content: [
          {
            type: 'text',
            text: `✅ Journal entry added successfully!\n\n**Entry Details:**\n- ID: ${
              entry.id
            }\n- Title: ${entry.title}\n- Tags: ${
              entry.tags.join(', ') || 'None'
            }\n- Time: ${entry.timestamp}\n\n**Content:**\n${entry.content}`,
          },
        ],
      };
    }
  );

• src/journal/types.ts:50-53 (schema)

  TypeScript interface defining the input options for addEntry: required content string and optional tags array. Matches the Zod schema used in registration.

  export interface AddEntryOptions {
    content: string;
    tags?: string[];
  }