jrnl MCP Server

Instructions

Implementation Reference

• src/handlers/statisticsHandlers.ts:19-99 (handler)

  The core handler function for the 'get_statistics' tool. It executes a jrnl stats command, parses the JSON output, computes total entries, total words, average words per entry, optional time-grouped statistics, and top 10 tags.

  export async function getStatistics(
    journal: string | undefined,
    timeGrouping: string | undefined,
    includeTopTags: boolean,
    executor: JrnlExecutor,
  ): Promise<{ statistics: JournalStatistics }> {
    const command = buildStatsCommand(journal);
    const result = await executor.execute(command);
  
    try {
      const data = JSON.parse(result);
      const entries = data.entries || [];
  
      // Calculate basic statistics
      const totalEntries = entries.length;
      const totalWords = entries.reduce((sum: number, entry: any) => {
        const bodyWords = entry.body ? entry.body.split(/\s+/).length : 0;
        const titleWords = entry.title ? entry.title.split(/\s+/).length : 0;
        return sum + bodyWords + titleWords;
      }, 0);
  
      const averageWordsPerEntry =
        totalEntries > 0 ? Math.round(totalWords / totalEntries) : 0;
  
      const statistics: JournalStatistics = {
        totalEntries,
        totalWords,
        averageWordsPerEntry,
      };
  
      // Time grouping statistics
      if (timeGrouping) {
        const grouping = parseTimeGrouping(timeGrouping);
        const grouped = groupEntriesByTime(entries, grouping);
  
        statistics.timeGrouping = Object.entries(grouped).map(
          ([period, entries]) => {
            const wordCount = entries.reduce((sum: number, entry: any) => {
              const bodyWords = entry.body ? entry.body.split(/\s+/).length : 0;
              const titleWords = entry.title
                ? entry.title.split(/\s+/).length
                : 0;
              return sum + bodyWords + titleWords;
            }, 0);
  
            return {
              period,
              entryCount: entries.length,
              wordCount,
            };
          },
        );
      }
  
      // Top tags
      if (includeTopTags) {
        const tagCounts = new Map<string, number>();
  
        entries.forEach((entry: any) => {
          if (entry.tags) {
            entry.tags.forEach((tag: string) => {
              const normalizedTag = tag.startsWith("@") ? tag : `@${tag}`;
              tagCounts.set(
                normalizedTag,
                (tagCounts.get(normalizedTag) || 0) + 1,
              );
            });
          }
        });
  
        statistics.topTags = Array.from(tagCounts.entries())
          .map(([tag, count]) => ({ tag, count }))
          .sort((a, b) => b.count - a.count)
          .slice(0, 10); // Top 10 tags
      }
  
      return { statistics };
    } catch (error) {
      throw new Error(`Failed to calculate statistics: ${error}`);
    }
  }

• src/handlers/statisticsHandlers.ts:5-17 (schema)

  TypeScript interfaces defining the structure of the statistics output returned by the get_statistics tool.

  export interface TimeGroupStats {
    period: string;
    entryCount: number;
    wordCount: number;
  }
  
  export interface JournalStatistics {
    totalEntries: number;
    totalWords: number;
    averageWordsPerEntry: number;
    timeGrouping?: TimeGroupStats[];
    topTags?: Array<{ tag: string; count: number }>;
  }

• src/index.ts:98-119 (registration)

  Tool registration in the ListTools handler, defining the name, description, and input schema for get_statistics.

  {
    name: "get_statistics",
    description: "Get journal statistics and analytics",
    inputSchema: {
      type: "object",
      properties: {
        journal: {
          type: "string",
          description: "Journal name (uses current/default if not specified)",
        },
        timeGrouping: {
          type: "string",
          enum: ["day", "week", "month", "year"],
          description: "Group statistics by time period",
        },
        includeTopTags: {
          type: "boolean",
          description: "Include top tags in statistics",
        },
      },
    },
  },

• src/index.ts:196-217 (registration)

  Dispatch case in the CallTool handler that invokes the getStatistics function with parsed arguments.

  case "get_statistics":
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await getStatistics(
              journal,
              typeof args?.timeGrouping === "string"
                ? args.timeGrouping
                : undefined,
              typeof args?.includeTopTags === "boolean"
                ? args.includeTopTags
                : true,
              executor,
            ),
            null,
            2,
          ),
        },
      ],
    };

• src/handlers/statisticsHandlers.ts:101-148 (helper)

  Helper functions for grouping entries by time periods (daily, weekly, monthly, yearly) and calculating week numbers, used by the getStatistics handler.

  function groupEntriesByTime(
    entries: any[],
    grouping: string,
  ): Record<string, any[]> {
    const grouped: Record<string, any[]> = {};
  
    entries.forEach((entry: any) => {
      const date = new Date(entry.date);
      let key: string;
  
      switch (grouping) {
        case "daily":
          key = date.toISOString().split("T")[0];
          break;
        case "weekly": {
          // Get week number
          const weekNum = getWeekNumber(date);
          key = `${date.getFullYear()}-W${weekNum}`;
          break;
        }
        case "monthly":
          key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
          break;
        case "yearly":
          key = date.getFullYear().toString();
          break;
        default:
          key = date.toISOString().split("T")[0];
      }
  
      if (!grouped[key]) {
        grouped[key] = [];
      }
      grouped[key].push(entry);
    });
  
    return grouped;
  }
  
  function getWeekNumber(date: Date): number {
    const d = new Date(
      Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()),
    );
    const dayNum = d.getUTCDay() || 7;
    d.setUTCDate(d.getUTCDate() + 4 - dayNum);
    const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
    return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
  }