@sriinnu/harmon-flow 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @sriinnu/harmon-flow
+
+![logo](./logo.svg)
+
+> Graph-based journal analysis plus MCP servers for local tooling and remote OpenAI/ChatGPT app integration.
+
+## Install
+
+```bash
+pnpm add @sriinnu/harmon-flow
+```
+
+## Quick Start
+
+```typescript
+import {
+  createFlowParser,
+  PatternGraphBuilder,
+  PatternDetector,
+  SuggestionEngine,
+} from '@sriinnu/harmon-flow';
+
+const parser = createFlowParser('./journal');
+const entries = parser.scanDirectory();
+const graph = new PatternGraphBuilder(entries).build();
+const patterns = new PatternDetector(graph, entries).getAllPatterns();
+const suggestions = new SuggestionEngine(graph, entries).suggest(
+  ['focused'],
+  'medium',
+  'morning',
+);
+```
+
+## API
+
+| Export | Description |
+|---|---|
+| `createFlowParser()` | Markdown journal parser |
+| `MarkdownParser` | Parser class for journal files with schema-validated frontmatter |
+| `PatternGraphBuilder` | Build a pattern graph from journal entries |
+| `PatternDetector` | Detect recurring patterns (time, mood, policy) |
+| `SuggestionEngine` | Generate session suggestions from patterns |
+| `createMCPServer()` | Start an MCP stdio server for flow analysis |
+| `createAppMCPServer()` | Start a remote streamable HTTP MCP server for OpenAI/ChatGPT app use |
+| `HarmonAppMCPServer` | Remote MCP app server class with daemon-backed runtime tools |
+| `JournalEntry` | Parsed journal entry type |
+| `PatternGraph` / `GraphNode` / `GraphEdge` | Graph structure types |
+| `Suggestion` | Generated suggestion type |
+
+## Server Modes
+
+From a fresh repo checkout, run `pnpm build` once before you start either server.
+
+```bash
+# Local stdio MCP server
+pnpm --filter @sriinnu/harmon-flow start
+
+# Remote streamable HTTP MCP server
+pnpm --filter @sriinnu/harmon-flow start:http
+```
+
+The remote MCP server exposes:
+
+- `search` and `fetch` for ChatGPT-compatible journal retrieval
+- `get_status`, `search_music`, `get_library_tracks`, `list_playlists`, `get_playlist_tracks`, and `get_now_playing` for daemon/runtime reads
+- `play_music`, `pause_music`, `next_track`, and `previous_track` for direct provider playback control
+- `start_session`, `nudge_session`, and `stop_session` for session orchestration
+
+Set `HARMON_ENDPOINT` to point at the daemon. If the daemon is protected, also set `HARMON_API_TOKEN` so the MCP server can authenticate upstream. Set `HARMON_MCP_BEARER_TOKEN` if you want bearer auth on the remote MCP endpoint. Without MCP auth, the remote server stays read-only by default. The default remote URL is `http://127.0.0.1:17400/mcp`.
+If you need bearer-backed write tools, either set `HARMON_MCP_BEARER_TOKEN_SCOPES="harmon.read harmon.write"` or use OAuth JWT auth. `HARMON_MCP_ALLOW_UNAUTHENTICATED_WRITES=1` is available only for local development on loopback binds like `127.0.0.1`.
+For OAuth-capable protected deployments, set `HARMON_MCP_OAUTH_ISSUER_URL`, `HARMON_MCP_OAUTH_AUTHORIZATION_ENDPOINT`, `HARMON_MCP_OAUTH_TOKEN_ENDPOINT`, `HARMON_MCP_OAUTH_JWKS_URL`, and `HARMON_MCP_PUBLIC_URL`. I fail fast without `HARMON_MCP_PUBLIC_URL` so the protected-resource metadata cannot accidentally advertise a local bind URL.
+
+## Architecture
+
+harmon-flow reads markdown journal entries, validates frontmatter metadata (mood, energy, context) against its declared schema, and builds an in-memory graph of patterns. The `SuggestionEngine` traverses this graph to recommend session policies based on time-of-day, mood history, and past listening behavior. It now exposes two MCP surfaces: a local stdio server for journal-analysis tools, and a remote streamable HTTP server that combines journal `search`/`fetch` tools with daemon-backed multi-provider runtime control for OpenAI/ChatGPT app use.
+
+## License
+
+GNU Affero General Public License v3.0 only. See [LICENSE](../../LICENSE).

package/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: harmon-flow
+description: Journal pattern detection, graph analysis, and MCP server for music session insights
+capabilities:
+  - Parse markdown journal entries with frontmatter into structured data
+  - Build pattern graphs from journal entries and detect time, mood, and policy patterns
+  - Expose pattern analysis as an MCP server with tool definitions for LLM integration
+tags:
+  - patterns
+  - journal
+  - mcp
+  - analysis
+provider: harmon
+version: 0.1.0
+---
+
+# Harmon Flow
+
+## What this does
+harmon-flow turns markdown journal entries into a queryable pattern graph. The MarkdownParser extracts and validates frontmatter (mood tags, energy level, session context, policy) from journal files. The PatternGraphBuilder constructs a directed graph of nodes and edges representing relationships between moods, energy levels, times, and policies. A PatternDetector finds recurring patterns, and the SuggestionEngine recommends session policies. The whole system is exposed as an MCP server for LLM tool use.
+
+## When to use
+- Analyzing journal history to find recurring mood-energy-time patterns
+- Generating session policy suggestions based on past listening behavior
+- Exposing harmon insights as MCP tools for Claude or other LLM agents
+
+## Key exports
+- `MarkdownParser` — parses markdown files with YAML frontmatter into JournalEntry objects
+- `PatternGraphBuilder` — builds a graph of mood, energy, time, and policy nodes with weighted edges
+- `HarmonFlowMCPServer` — MCP server that exposes pattern analysis as callable tools
+
+## Example
+```typescript
+import {
+  MarkdownParser,
+  PatternGraphBuilder,
+  createMCPServer,
+} from '@sriinnu/harmon-flow';
+
+const parser = new MarkdownParser({ path: './journals' });
+const entries = parser.scanDirectory();
+const graph = new PatternGraphBuilder(entries).build();
+const server = await createMCPServer({ flowDir: './journals' });
+```

package/dist/graph/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Pattern Graph - Build and query graph-based patterns from journal entries
+ */
+import type { JournalEntry, PatternGraph, TimePattern, MoodEnergyPattern, PolicyPattern, Suggestion } from '../types.js';
+export declare class PatternGraphBuilder {
+    private graph;
+    private entries;
+    constructor(entries: JournalEntry[]);
+    /**
+     * Build the complete pattern graph from entries
+     */
+    build(): PatternGraph;
+    /**
+     * Add nodes for an entry
+     */
+    private addEntryNodes;
+    /**
+     * Add edges for an entry (temporal relationships)
+     */
+    private addEntryEdges;
+    /**
+     * Add a node to the graph
+     */
+    private addNode;
+    /**
+     * Add an edge to the graph
+     */
+    private addEdge;
+    /**
+     * Normalize edge weights by max count
+     */
+    private normalizeEdgeWeights;
+    /**
+     * Find the previous entry in chronological order
+     */
+    private findPreviousEntry;
+    private getNodeKey;
+    /**
+     * Get the built graph
+     */
+    getGraph(): PatternGraph;
+}
+/**
+ * Pattern Detector - Extract high-level patterns from the graph
+ */
+export declare class PatternDetector {
+    private graph;
+    private entries;
+    constructor(graph: PatternGraph, entries: JournalEntry[]);
+    /**
+     * Detect time-based patterns
+     */
+    detectTimePatterns(): TimePattern[];
+    /**
+     * Detect mood-energy transition patterns
+     */
+    detectMoodEnergyPatterns(): MoodEnergyPattern[];
+    /**
+     * Cluster similar policies to find patterns
+     */
+    detectPolicyPatterns(): PolicyPattern[];
+    /**
+     * Simple hash function for policy objects
+     */
+    private hashPolicy;
+    /**
+     * Get all detected patterns
+     */
+    getAllPatterns(): {
+        timePatterns: TimePattern[];
+        moodEnergyPatterns: MoodEnergyPattern[];
+        policyPatterns: PolicyPattern[];
+    };
+}
+/**
+ * Suggestion Engine - Generate suggestions based on patterns
+ */
+export declare class SuggestionEngine {
+    private graph;
+    private entries;
+    private timePatterns;
+    private moodEnergyPatterns;
+    private policyPatterns;
+    constructor(graph: PatternGraph, entries: JournalEntry[]);
+    /**
+     * Generate suggestions based on current context
+     */
+    suggest(currentMood: string[], energy: 'low' | 'medium' | 'high', timeOfDay?: string): Suggestion[];
+    /**
+     * Get similar historical entries
+     */
+    findSimilarEntries(mood: string[], energy?: 'low' | 'medium' | 'high', limit?: number): Array<{
+        entry: JournalEntry;
+        similarity: number;
+    }>;
+    /**
+     * Get pattern statistics
+     */
+    getStats(): {
+        totalEntries: number;
+        timePatterns: number;
+        moodEnergyPatterns: number;
+        policyPatterns: number;
+        topMoodTags: {
+            mood: string;
+            count: number;
+        }[];
+        topEnergyLevels: {
+            level: string;
+            count: number;
+        }[];
+    };
+    private getTopMoodTags;
+    private getTopEnergyLevels;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGZ,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,UAAU,EACX,MAAM,aAAa,CAAC;AAuBrB,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAiB;gBAEpB,OAAO,EAAE,YAAY,EAAE;IASnC;;OAEG;IACH,KAAK,IAAI,YAAY;IAsBrB;;OAEG;IACH,OAAO,CAAC,aAAa;IA2DrB;;OAEG;IACH,OAAO,CAAC,aAAa;IA+BrB;;OAEG;IACH,OAAO,CAAC,OAAO;IAqBf;;OAEG;IACH,OAAO,CAAC,OAAO;IAkBf;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,QAAQ,IAAI,YAAY;CAGzB;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAiB;gBAEpB,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE;IAKxD;;OAEG;IACH,kBAAkB,IAAI,WAAW,EAAE;IA+CnC;;OAEG;IACH,wBAAwB,IAAI,iBAAiB,EAAE;IA2C/C;;OAEG;IACH,oBAAoB,IAAI,aAAa,EAAE;IAyCvC;;OAEG;IACH,OAAO,CAAC,UAAU;IAWlB;;OAEG;IACH,cAAc;;;;;CAOf;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,kBAAkB,CAAsB;IAChD,OAAO,CAAC,cAAc,CAAkB;gBAE5B,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE;IAUxD;;OAEG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAiEnG;;OAEG;IACH,kBAAkB,CAChB,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,EAClC,KAAK,SAAI,GACR,KAAK,CAAC;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAsBrD;;OAEG;IACH,QAAQ;;;;;;kBAWgC,MAAM;mBAAS,MAAM;;;mBAahB,MAAM;mBAAS,MAAM;;;IAblE,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,kBAAkB;CAW3B"}