jrnl MCP Server

Instructions

Implementation Reference

• src/handlers/journalHandlers.ts:12-58 (handler)

  The primary handler function for the 'list_journals' tool. Executes 'jrnl --list' via executor, parses the output to identify journals (with default marker), structures as JournalInfo array with optional currentJournal, and handles parsing errors.

  export async function listJournals(
    executor: JrnlExecutor,
  ): Promise<{ journals: JournalInfo[]; currentJournal?: string }> {
    const command = buildListJournalsCommand();
    const result = await executor.execute(command);
  
    try {
      // Parse jrnl --list output
      // Format can be:
      // Journals defined in config (/path/to/config)
      // * default -> /path/to/default.txt
      //   work -> /path/to/work.txt
      const lines = result.trim().split("\n");
      const journals: JournalInfo[] = [];
  
      for (const line of lines) {
        // Skip header lines
        if (line.includes("Journals defined in config") || line.trim() === "") {
          continue;
        }
  
        const match = line.match(/^(\s*\*?\s*)(\w+)\s*->\s*(.+)$/);
        if (match) {
          const isDefault = line.trim().startsWith("*");
          const name = match[2].trim();
          const path = match[3].trim();
  
          journals.push({
            name,
            path,
            isDefault,
          });
  
          if (isDefault && !currentJournal) {
            currentJournal = name;
          }
        }
      }
  
      return {
        journals,
        currentJournal,
      };
    } catch (error) {
      throw new Error(`Failed to parse journal list: ${error}`);
    }
  }

• src/handlers/journalHandlers.ts:4-8 (schema)

  Type definition for journal information returned by listJournals handler.

  export interface JournalInfo {
    name: string;
    path: string;
    isDefault: boolean;
  }

• src/index.ts:120-127 (registration)

  Registers the 'list_journals' tool in the MCP server's tool list, including name, description, and empty input schema (no parameters required).

  {
    name: "list_journals",
    description: "List all available journals",
    inputSchema: {
      type: "object",
      properties: {},
    },
  },

• src/index.ts:219-227 (registration)

  Dispatch handler in CallToolRequestSchema that invokes listJournals(executor) and formats response as JSON text content.

  case "list_journals":
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(await listJournals(executor), null, 2),
        },
      ],
    };

• src/utils/commandBuilder.ts:84-86 (helper)

  Helper function that constructs the 'jrnl --list' command arguments, used by the listJournals handler.

  export function buildListJournalsCommand(): string[] {
    return ["--list"];
  }