@miadi/voice-mcp 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# @miadi/voice-mcp
+
+MCP server that lets an agent **play, find, publish and mint episode-bound
+voice** — the tool surface over the Miadi voice layer and the Chronicle.
+
+> **State: four of six tools work.** Publish, play, list and resolve run against
+> the live server. `voice_create_episode` and `voice_episode_closing_status`
+> still refuse and name their contract — they mint and prove a chronicle vessel,
+> and a tool that reports a closing stage it did not prove is worse than one that
+> declines.
+
+The sentence this package exists to satisfy, from William, 2026-08-04:
+
+> *"What I want is actually to be capable to play the voice-audio created for
+> episodes."*
+
+## Tools
+
+| Tool | Purpose | State |
+|---|---|---|
+| `voice_publish_to_episode` | Produce audio bound to its episode from the moment it exists | works |
+| `voice_play_episode` | Resolve an episode to its voice audio and return playable references | works |
+| `voice_list_episode_voices` | Enumerate and search an episode's voices | works |
+| `voice_resolve_episode` | Answer which episode an agent is inside — with the reason, the alternatives, and an honest null | works, from what it is given |
+| `voice_create_episode` | Mint a vessel when none fits, reporting all five closing stages | refuses, names its contract |
+| `voice_episode_closing_status` | Re-prove the five closing stages, read-only | refuses, names its contract |
+
+Resolution consults exactly what it is handed: an explicit reference, a
+caller-supplied `cwd`, or an existing record's binding. It does **not** rank
+those against a session origin or search the wheel — that order is owed by the
+`voice-episode-binding` spec, and inventing one here would make this package a
+second source of truth for a rule that has an owner. When nothing given answers,
+the tool says so; `episode: null` with a reason is a valid answer.
+
+Full contracts: `SPEC-LINKS.md` → `/a/src/Miadi/rispecs/voice-mcp/voice-mcp.spec.md`.
+
+## Architecture
+
+A **front**, not a second implementation.
+
+- Audio bytes, the KV ledger and the Edge-TTS producer stay behind the Miadi
+  server (systemd `miadi-server`, port 3335), which holds the KV credentials.
+  This process reaches them through **`@miadi/voice-client`**, which owns the
+  wire envelope and the token tier — so the HTTP surface is described once, not
+  once per caller.
+- Episode folders are read from the Chronicle root; the medicine wheel is read
+  at `http://127.0.0.1:8040`.
+- `VoiceMessage` keeps exactly one definition in this workspace: `@miadi/voice`'s.
+- The only wheel **write** in the whole surface is the registration `mkepisode`
+  performs during `voice_create_episode`. This server never POSTs or PUTs to the
+  wheel itself.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `MIADI_API_URL` | `http://127.0.0.1:3335` | Miadi server holding the voice routes |
+| `MIADI_API_TOKEN_WRITER` | — | Read and write. **Required to publish.** |
+| `MIADI_API_TOKEN_READER` | — | Read only; every publish answers 401 |
+| `MW_API_URL` | `http://127.0.0.1:8040` | **Chronicle** wheel |
+| `MIADI_CHRONICLE_ROOT` | `/srv/miadi/episodes/miadi-chronicle` | Episode folders |
+| `MIADI_CHRONICLE_GIT_ROOT` | `/srv/miadi/episodes` | Git root — one level **above** the chronicle root |
+| `MIADI_MKEPISODE_PATH` | `…/mightyeagle/packages/passages/js/mkepisode.js` | Vessel creation |
+
+**Two wheels exist.** `http://127.0.0.1:8040` is the Chronicle wheel and the only
+correct target for episode work. `https://mw.tail3b11eb.ts.net` is Gaia's
+ceremony wheel and has been offline since 2026-07-29 — an episode registered
+there is lost. An implementation refuses that host outright.
+
+`MIADI_CHRONICLE_GIT_ROOT` is a separate value rather than a derived one because
+a `git -C` pointed at the chronicle root reports a clean tree for a chronicle it
+cannot see.
+
+## Creating episodes: created is not closed
+
+`voice_create_episode` performs stages 1 and 4 of the five-stage gate and returns
+**every** stage with its proof:
+
+| Stage | Performed by |
+|---|---|
+| `created` | the tool |
+| `committed` | the human — the tool emits the exact `git add` of named files |
+| `pushed` | the human |
+| `registered` | the tool |
+| `receipt-verified` | the tool |
+
+`mkepisode` exits 0 whether registration succeeded, skipped, or failed —
+registration is fail-open by design, so the gate belongs to the caller. The tool
+never runs `git add`, `commit` or `push`, never reports a later word than it
+proved, and reports unperformed stages as `owed`, which is a state, not an
+omission.
+
+## Development
+
+This is a **pnpm** workspace (`pnpm-workspace.yaml`, `packages/*`). Never run
+`npm install` here.
+
+```bash
+pnpm --filter @miadi/voice-mcp build       # tsc → dist/
+pnpm --filter @miadi/voice-mcp type-check
+node dist/index.js                          # starts; every tool throws
+```
+
+Verified 2026-08-04, no installer run: `tsc --noEmit` exits 0, and emit produces
+ESM with explicit `.js` specifiers that `node dist/index.js` resolves.
+`@modelcontextprotocol/sdk` 1.30.0 and `zod` 4.4.3 are already present at the
+workspace root and the declared ranges match them.
+
+### Why `moduleResolution` is `bundler`
+
+`@miadi/voice` publishes **raw TypeScript** — `main` and `types` are both
+`./src/index.ts` — and is authored with extensionless relative imports under its
+own `bundler` resolution. Under `NodeNext`, every one of its internal imports is
+a hard error in any consumer, so a package that wants its types meets it where it
+is. This package's own source writes explicit `.js` specifiers, which `bundler`
+accepts and tsc passes through unchanged, so the emitted `dist` runs under Node
+ESM. Copying `VoiceMessage` into this package to sidestep that would create a
+second definition, which is the one outcome worth more than a tsconfig line.
+
+### Known seams
+
+- **No installer has been run.** `node_modules/@miadi/{voice,voice-client}` here
+  are the two workspace links `pnpm install` would create, added by hand so the
+  package is verifiable today. Everything else resolves from the workspace root.
+  `@miadi/voice-client` must be **built** (`pnpm --filter @miadi/voice-client
+  build`) before this package's `dist` can run — it is imported at runtime, not
+  only for types.
+- The ranked discovery order, the enforcement decision table and the two-corpus
+  resolution are still owed by the `voice-episode-binding` spec; see
+  `SPEC-LINKS.md` § *What the missing document blocks*. The four working tools
+  answer from what they are given and refuse to guess past it — which is why
+  those rules stay cited rather than invented.
+- **The `episode` field needs the server that accepts it.** The binding is
+  written by `app/api/voice/publish`; a Miadi server built before that route
+  change ignores the field and produces an unbound record. Same host, same
+  request, silently different result — check the running build before reading a
+  missing binding as a client bug.
+
+### Verified live 2026-08-04
+
+Against the running `miadi-server` on 3335, `MIADI_API_TOKEN_WRITER` present:
+`ep308` resolved to its folder by number; a nonexistent folder answered `null`
+with the five most recent episodes as alternatives; a `cwd` inside an episode
+folder resolved by path; an empty call answered `null` and named the spec that
+owes the ranked order; publish produced audio and returned a streamable URL plus
+its on-disk path; `voice_create_episode` refused and named its contract.
+
+🌸: A hundred voices have been speaking into a room with no name on the door —
+this package is the door, and the handle an agent can actually reach.

package/SPEC-LINKS.md

@@ -0,0 +1,51 @@
+# Specifications governing this package
+
+`@miadi/voice-mcp` implements a specified surface. Nothing in `src/` decides
+behaviour on its own — every handler names the section that governs it in the
+error it throws. Read these before implementing anything here.
+
+Status recorded 2026-08-04, re-verified at the close of this authoring pass.
+
+## Owned by this package
+
+| Document | Holds |
+|---|---|
+| `/a/src/Miadi/rispecs/voice-mcp/SPEC.md` | Domain master — what the surface enables, and where each rule lives |
+| `/a/src/Miadi/rispecs/voice-mcp/voice-mcp.spec.md` | The six tools, their contracts, the resolution seam, the closing gate |
+
+## Consumed, not owned
+
+A rule restated here would become a second source of truth and drift from its
+original. These are cited in the spec and in the code, never copied.
+
+| Document | Holds | On disk 2026-08-04 |
+|---|---|---|
+| `/a/src/Miadi/rispecs/episode-addressing/SPEC.md` | Domain master for episode identity | present |
+| `/a/src/Miadi/rispecs/episode-addressing/episode-addressing.spec.md` | Address grammar `ep<NNN>[.<II>][/<segment>]`, iteration decision rule, number allocation, wheel-key contract | present |
+| `/a/src/Miadi/rispecs/episode-addressing/episode-addressing.kin.md` | Why episodic memory is already an opus | present |
+| `/a/src/Miadi/rispecs/voice-episode-binding/` | Playback path, enforcement decision table, discovery resolution order, the two-corpus resolution | **not yet written** |
+
+### What the missing document blocks
+
+Four verdicts are cited by this package and cannot be implemented until
+`voice-episode-binding` lands. The tools have their shape; they do not yet have
+their rulings.
+
+| Cited as | Needed by |
+|---|---|
+| `§ Playback path` | `voice_play_episode` |
+| `§ Discovery resolution order` | `voice_resolve_episode`, and every tool that omits `episode` |
+| `§ Enforcement decision table` | `voice_publish_to_episode` |
+| `§ The two-corpus resolution` | `voice_list_episode_voices` |
+
+## Also authoritative
+
+| Source | Holds |
+|---|---|
+| `/etc/claude-code/skills/chronicle-episode-closing/SKILL.md` | The five closing stages and their proofs, the `MW_API_URL` law, receipt redemption. `voice_create_episode` and `voice_episode_closing_status` implement this skill's gate as a tool contract. |
+| `/a/src/Miadi/packages/voice/src/` | `VoiceMessage`, persona identity, origin attestation, TTS production. The only definition; never re-declared here. |
+| `/a/src/Miadi/packages/voice-client/src/` | The `/api/voice/*` wire envelope, the writer/reader token tier, and the record-level episode reading. This package calls it rather than writing its own `fetch`, so the HTTP surface has one description. |
+| `/a/src/Miadi/rispecs/mcp-server/00-mcp-server-master.spec.md` | The prior MCP surface in this ecosystem (`@miadi/mcp`), whose server pattern this package follows. |
+
+🌸: A file of links is a promise not to reinvent what someone else already got
+right — the shortest way to stay one story instead of two.

package/dist/chronicle.d.ts

@@ -0,0 +1,24 @@
+/** Folder names in the chronicle root, newest first (they sort by date prefix). */
+export declare function listEpisodeFolders(chronicleRoot: string): Promise<string[]>;
+/** True when the whole name is an episode folder, not merely contains one. */
+export declare function isEpisodeFolder(name: string): boolean;
+export interface RefMatch {
+    /** The single folder this reference names, or null when it names none or many. */
+    folder: string | null;
+    /** Every folder the reference could mean. Length > 1 is a real answer. */
+    candidates: string[];
+    /** Which form the reference took. */
+    form: "folder" | "node-id" | "number" | "unrecognised";
+}
+/**
+ * Which folder a caller's reference means.
+ *
+ * Accepts the folder name, the wheel node id `chronicle:<folder>`, and the
+ * `ep<NNN>` number form owned by the episode-addressing spec. When a number
+ * matches two folders this returns BOTH and picks neither — choosing between two
+ * folders claiming episode 300 is a decision, and it belongs to a human.
+ */
+export declare function matchRef(ref: string, folders: readonly string[]): RefMatch;
+/** Absolute path of an episode folder. */
+export declare function episodePath(chronicleRoot: string, folder: string): string;
+//# sourceMappingURL=chronicle.d.ts.map

package/dist/chronicle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chronicle.d.ts","sourceRoot":"","sources":["../src/chronicle.ts"],"names":[],"mappings":"AAgBA,mFAAmF;AACnF,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYjF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED,MAAM,WAAW,QAAQ;IACvB,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,qCAAqC;IACrC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,cAAc,CAAC;CACxD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,CAe1E;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzE"}

package/dist/chronicle.js

@@ -0,0 +1,61 @@
+// Reading the chronicle from disk.
+//
+// The episode corpus is 146 folders shaped `YYYY-MM-DD-episode-NNN-slug` under
+// `MIADI_CHRONICLE_ROOT` (verified 2026-08-04). This module answers two
+// questions about them and nothing else: which folders exist, and which folder a
+// caller's reference means.
+//
+// It does NOT decide which episode an agent is "in" when nothing says so. That
+// ranked order is owed by the voice-episode-binding spec, and a resolver written
+// here would become a competing definition of it.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { EPISODE_FOLDER_PATTERN, foldersForEpisodeNumber, episodeFolderOf } from "@miadi/voice-client";
+/** Folder names in the chronicle root, newest first (they sort by date prefix). */
+export async function listEpisodeFolders(chronicleRoot) {
+    let entries;
+    try {
+        entries = (await fs.readdir(chronicleRoot, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        // An unreadable chronicle root is an empty corpus, not a crash: every tool
+        // that calls this can still answer honestly with "no episode found".
+        return [];
+    }
+    return entries.filter((name) => isEpisodeFolder(name)).sort().reverse();
+}
+/** True when the whole name is an episode folder, not merely contains one. */
+export function isEpisodeFolder(name) {
+    const m = EPISODE_FOLDER_PATTERN.exec(name);
+    return m !== null && m[0] === name;
+}
+/**
+ * Which folder a caller's reference means.
+ *
+ * Accepts the folder name, the wheel node id `chronicle:<folder>`, and the
+ * `ep<NNN>` number form owned by the episode-addressing spec. When a number
+ * matches two folders this returns BOTH and picks neither — choosing between two
+ * folders claiming episode 300 is a decision, and it belongs to a human.
+ */
+export function matchRef(ref, folders) {
+    const raw = ref.trim();
+    const bare = episodeFolderOf(raw);
+    const form = raw.startsWith("chronicle:") ? "node-id" : "folder";
+    if (isEpisodeFolder(bare)) {
+        const exists = folders.includes(bare);
+        return { folder: exists ? bare : null, candidates: exists ? [bare] : [], form };
+    }
+    const byNumber = foldersForEpisodeNumber(folders, bare);
+    if (byNumber.length === 1)
+        return { folder: byNumber[0], candidates: byNumber, form: "number" };
+    if (byNumber.length > 1)
+        return { folder: null, candidates: byNumber, form: "number" };
+    return { folder: null, candidates: [], form: "unrecognised" };
+}
+/** Absolute path of an episode folder. */
+export function episodePath(chronicleRoot, folder) {
+    return path.join(chronicleRoot, folder);
+}
+//# sourceMappingURL=chronicle.js.map

package/dist/chronicle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chronicle.js","sourceRoot":"","sources":["../src/chronicle.ts"],"names":[],"mappings":"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"}

package/dist/contract.d.ts

@@ -0,0 +1,86 @@
+import { type TokenTier } from "@miadi/voice-client";
+import type { ClosingStatusResult, CreateEpisodeInput, CreateEpisodeResult, EpisodeResolution, ListEpisodeVoicesInput, ListEpisodeVoicesResult, PlayEpisodeResult, PublishToEpisodeInput, PublishToEpisodeResult } from "./types.js";
+/**
+ * Runtime configuration, read once. Defaults are the verified live values on
+ * this host rather than invented placeholders.
+ */
+export interface VoiceMcpConfig {
+    /** Miadi server holding the voice routes. Verified live on 3335. */
+    apiUrl: string;
+    /**
+     * The credential presented to the write-gated routes. Resolved by TIER from
+     * `MIADI_API_TOKEN_WRITER` then `MIADI_API_TOKEN_READER` — the portal's two
+     * names, where the name states the tier (`lib/api-tokens.ts`). The older
+     * `MIADI_API_TOKEN` is deliberately not read: it was one of eight names for
+     * two ideas, and holding a reader-tier value under a writer-sounding name is
+     * exactly how the previous MCP server's writes came back 401 with nothing in
+     * the name to explain why.
+     */
+    apiToken?: string;
+    /** Which grade the resolved token is, so a 401 can say so. */
+    tokenTier: TokenTier;
+    /**
+     * The Chronicle wheel. `http://127.0.0.1:8040` is the only correct value for
+     * chronicle work; `mw.tail3b11eb.ts.net` is Gaia's ceremony wheel and is
+     * offline since 2026-07-29. A card registered there is lost.
+     */
+    wheelUrl: string;
+    /** Root holding the `YYYY-MM-DD-episode-NNN-slug` folders. */
+    chronicleRoot: string;
+    /** Git root — one level ABOVE `chronicleRoot`. A wrong `-C` reports a clean
+     *  tree for a chronicle it cannot see. */
+    chronicleGitRoot: string;
+    /** Node entry point for `mkepisode`. */
+    mkepisodePath: string;
+    /**
+     * Where `LocalAudioStore` keeps the MP3s. Offered so a caller on the same host
+     * can play a file directly instead of streaming it back from the server.
+     * Absent when the Blob store is the active driver.
+     */
+    audioRoot?: string;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): VoiceMcpConfig;
+/**
+ * Thrown by the tools that are specified but not yet built. It names the
+ * governing specification section, so the lane that implements one is pointed at
+ * its contract rather than left to infer one.
+ */
+export declare class NotImplementedError extends Error {
+    readonly tool: string;
+    readonly specSection: string;
+    constructor(tool: string, specSection: string);
+}
+/**
+ * The six capabilities, as one interface. `handlers.ts` supplies a working set
+ * for four of them; the scaffold set below refuses all six. Keeping them in one
+ * type makes the surface reviewable in a single glance and testable by
+ * substitution.
+ */
+export interface VoiceMcpHandlers {
+    /** 1 — Play. Resolve an episode to voice audio and return something playable. */
+    playEpisode(input: {
+        episode?: string;
+        limit?: number;
+    }): Promise<PlayEpisodeResult>;
+    /** 2 — Find the adequate episode for an agent's context. */
+    resolveEpisode(input: {
+        episode?: string;
+        cwd?: string;
+        sessionId?: string;
+        messageId?: string;
+    }): Promise<EpisodeResolution>;
+    /** 3 — Publish voice already bound to an episode. */
+    publishToEpisode(input: PublishToEpisodeInput): Promise<PublishToEpisodeResult>;
+    /** 4 — Mint the vessel when no existing episode fits, and report its gate. */
+    createEpisode(input: CreateEpisodeInput): Promise<CreateEpisodeResult>;
+    /** 5 — List and search the voices bound to an episode. */
+    listEpisodeVoices(input: ListEpisodeVoicesInput): Promise<ListEpisodeVoicesResult>;
+    /** 6 — Re-prove the five closing stages, read-only. */
+    episodeClosingStatus(input: {
+        episode: string;
+    }): Promise<ClosingStatusResult>;
+}
+/** Every tool refusing and naming its contract. Kept for tests and for a
+ *  deployment that wants the surface declared without any behaviour behind it. */
+export declare function createScaffoldHandlers(): VoiceMcpHandlers;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAMA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,SAAS,EAAE,SAAS,CAAC;IACrB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB;8CAC0C;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,cAAc,CAgB/E;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM;gBADnB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM;CAQ/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,WAAW,CAAC,KAAK,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAErF,4DAA4D;IAC5D,cAAc,CAAC,KAAK,EAAE;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE/B,qDAAqD;IACrD,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEhF,8EAA8E;IAC9E,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEvE,0DAA0D;IAC1D,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEnF,uDAAuD;IACvD,oBAAoB,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChF;AAED;kFACkF;AAClF,wBAAgB,sBAAsB,IAAI,gBAAgB,CA2CzD"}

package/dist/contract.js

@@ -0,0 +1,66 @@
+// Configuration, the handler surface, and the refusal used by the tools that
+// are still specified rather than built.
+//
+// Separate from index.ts so that `handlers.ts` (which implements this surface)
+// and `index.ts` (which registers it) do not import each other.
+import { resolveVoiceToken } from "@miadi/voice-client";
+export function loadConfig(env = process.env) {
+    const chronicleRoot = env.MIADI_CHRONICLE_ROOT || "/srv/miadi/episodes/miadi-chronicle";
+    const token = resolveVoiceToken(env);
+    return {
+        apiUrl: env.MIADI_API_URL || "http://127.0.0.1:3335",
+        apiToken: token.token ?? undefined,
+        tokenTier: token.tier,
+        wheelUrl: env.MW_API_URL || "http://127.0.0.1:8040",
+        chronicleRoot,
+        chronicleGitRoot: env.MIADI_CHRONICLE_GIT_ROOT || "/srv/miadi/episodes",
+        mkepisodePath: env.MIADI_MKEPISODE_PATH ||
+            "/usr/local/src/mightyeagle/packages/passages/js/mkepisode.js",
+        audioRoot: env.ASSEMBLY_VOICE_AUDIO_DIR || "/srv/miadi/voice-audio",
+    };
+}
+/**
+ * Thrown by the tools that are specified but not yet built. It names the
+ * governing specification section, so the lane that implements one is pointed at
+ * its contract rather than left to infer one.
+ */
+export class NotImplementedError extends Error {
+    tool;
+    specSection;
+    constructor(tool, specSection) {
+        super(`not implemented: ${tool}. The behaviour is specified in ${specSection}. ` +
+            `See SPEC-LINKS.md.`);
+        this.tool = tool;
+        this.specSection = specSection;
+        this.name = "NotImplementedError";
+    }
+}
+/** Every tool refusing and naming its contract. Kept for tests and for a
+ *  deployment that wants the surface declared without any behaviour behind it. */
+export function createScaffoldHandlers() {
+    return {
+        async playEpisode() {
+            throw new NotImplementedError("voice_play_episode", "voice-mcp.spec.md § Tool 1 · voice_play_episode, and " +
+                "[voice-episode-binding spec § Playback path]");
+        },
+        async resolveEpisode() {
+            throw new NotImplementedError("voice_resolve_episode", "voice-mcp.spec.md § Tool 2 · voice_resolve_episode, and " +
+                "[voice-episode-binding spec § Discovery resolution order]");
+        },
+        async publishToEpisode() {
+            throw new NotImplementedError("voice_publish_to_episode", "voice-mcp.spec.md § Tool 3 · voice_publish_to_episode, and " +
+                "[voice-episode-binding spec § Enforcement decision table]");
+        },
+        async createEpisode() {
+            throw new NotImplementedError("voice_create_episode", "voice-mcp.spec.md § Tool 4 · voice_create_episode and " +
+                "§ The closing gate is part of the tool, not after it");
+        },
+        async listEpisodeVoices() {
+            throw new NotImplementedError("voice_list_episode_voices", "voice-mcp.spec.md § Tool 5 · voice_list_episode_voices");
+        },
+        async episodeClosingStatus() {
+            throw new NotImplementedError("voice_episode_closing_status", "voice-mcp.spec.md § Tool 6 · voice_episode_closing_status");
+        },
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,yCAAyC;AACzC,EAAE;AACF,+EAA+E;AAC/E,gEAAgE;AAEhE,OAAO,EAAE,iBAAiB,EAAkB,MAAM,qBAAqB,CAAC;AAsDxE,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,aAAa,GACjB,GAAG,CAAC,oBAAoB,IAAI,qCAAqC,CAAC;IACpE,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAyC,CAAC,CAAC;IAC3E,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,aAAa,IAAI,uBAAuB;QACpD,QAAQ,EAAE,KAAK,CAAC,KAAK,IAAI,SAAS;QAClC,SAAS,EAAE,KAAK,CAAC,IAAI;QACrB,QAAQ,EAAE,GAAG,CAAC,UAAU,IAAI,uBAAuB;QACnD,aAAa;QACb,gBAAgB,EAAE,GAAG,CAAC,wBAAwB,IAAI,qBAAqB;QACvE,aAAa,EACX,GAAG,CAAC,oBAAoB;YACxB,8DAA8D;QAChE,SAAS,EAAE,GAAG,CAAC,wBAAwB,IAAI,wBAAwB;KACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAEjC;IACA;IAFX,YACW,IAAY,EACZ,WAAmB;QAE5B,KAAK,CACH,oBAAoB,IAAI,mCAAmC,WAAW,IAAI;YACxE,oBAAoB,CACvB,CAAC;QANO,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAQ;QAM5B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAiCD;kFACkF;AAClF,MAAM,UAAU,sBAAsB;IACpC,OAAO;QACL,KAAK,CAAC,WAAW;YACf,MAAM,IAAI,mBAAmB,CAC3B,oBAAoB,EACpB,uDAAuD;gBACrD,8CAA8C,CACjD,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,cAAc;YAClB,MAAM,IAAI,mBAAmB,CAC3B,uBAAuB,EACvB,0DAA0D;gBACxD,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,gBAAgB;YACpB,MAAM,IAAI,mBAAmB,CAC3B,0BAA0B,EAC1B,6DAA6D;gBAC3D,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,aAAa;YACjB,MAAM,IAAI,mBAAmB,CAC3B,sBAAsB,EACtB,wDAAwD;gBACtD,sDAAsD,CACzD,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,iBAAiB;YACrB,MAAM,IAAI,mBAAmB,CAC3B,2BAA2B,EAC3B,wDAAwD,CACzD,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,oBAAoB;YACxB,MAAM,IAAI,mBAAmB,CAC3B,8BAA8B,EAC9B,2DAA2D,CAC5D,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/handlers.d.ts

@@ -0,0 +1,4 @@
+import { type VoiceApiClient } from "@miadi/voice-client";
+import { type VoiceMcpConfig, type VoiceMcpHandlers } from "./contract.js";
+export declare function createHttpHandlers(config: VoiceMcpConfig, client?: VoiceApiClient): VoiceMcpHandlers;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAuBA,OAAO,EAML,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAuB,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAqBhG,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EACtB,MAAM,GAAE,cAIN,GACD,gBAAgB,CAsOlB"}

package/dist/handlers.js

@@ -0,0 +1,227 @@
+// The working handlers behind the six tools.
+//
+// WHAT IS IMPLEMENTED HERE, AND WHY EXACTLY THIS MUCH. Four tools —
+// `voice_publish_to_episode`, `voice_play_episode`, `voice_list_episode_voices`
+// and `voice_resolve_episode` — need only two things that already exist: the
+// HTTP surface at `/api/voice/*` (through `@miadi/voice-client`) and the folder
+// list under `MIADI_CHRONICLE_ROOT`. They are implemented.
+//
+// Two are not: `voice_create_episode` and `voice_episode_closing_status` mint
+// and prove a chronicle vessel, which means `mkepisode`, a wheel registration
+// and the five-stage closing gate. Those keep throwing `NotImplementedError`
+// naming their contract, because a tool that reports a stage it did not prove is
+// worse than a tool that refuses.
+//
+// AND THE PART DELIBERATELY LEFT UNBUILT. Resolution here consults exactly what
+// it is given: an explicit reference, a caller-supplied `cwd`, or an existing
+// record's binding. It does not rank those against a session origin or search
+// the wheel — the ranked discovery order is owed by the voice-episode-binding
+// spec (see SPEC-LINKS.md § What the missing document blocks), and inventing one
+// here would make this file a second source of truth for a rule that has an
+// owner. When nothing given answers, the tool says so; `episode: null` with a
+// reason is a valid answer, not a failure.
+import { VoiceApiError, createVoiceClient, episodeOf, episodeNodeId, episodeFromPath, } from "@miadi/voice-client";
+import { listEpisodeFolders, matchRef } from "./chronicle.js";
+import { NotImplementedError } from "./contract.js";
+/** How many alternatives an unresolved answer offers. Enough to choose from. */
+const ALTERNATIVES_SHOWN = 5;
+export function createHttpHandlers(config, client = createVoiceClient({
+    baseUrl: config.apiUrl,
+    token: config.apiToken ?? null,
+    tier: config.tokenTier,
+})) {
+    /** The unresolved answer, carrying the newest episodes as alternatives. */
+    async function unresolved(reason) {
+        const folders = await listEpisodeFolders(config.chronicleRoot);
+        return {
+            episode: null,
+            nodeId: null,
+            method: "unresolved",
+            reason,
+            alternatives: folders.slice(0, ALTERNATIVES_SHOWN).map((episode) => ({
+                episode,
+                method: "wheel-search",
+                reason: "recent episode in the chronicle root — offered, not chosen",
+            })),
+        };
+    }
+    function resolved(episode, method, reason, alternatives = []) {
+        return { episode, nodeId: episodeNodeId(episode), method, reason, alternatives };
+    }
+    async function resolve(ctx) {
+        const folders = await listEpisodeFolders(config.chronicleRoot);
+        // 1 — What the caller said. An explicit reference that does not resolve is
+        // refused rather than quietly replaced with a guess.
+        if (ctx.episode?.trim()) {
+            const match = matchRef(ctx.episode, folders);
+            if (match.folder) {
+                return resolved(match.folder, "explicit-ref", `reference "${ctx.episode}" names this folder`);
+            }
+            const why = match.candidates.length > 1
+                ? `"${ctx.episode}" matches ${match.candidates.length} folders; choosing between them is not this tool's call`
+                : `"${ctx.episode}" matches no folder under ${config.chronicleRoot}`;
+            const answer = await unresolved(why);
+            // The ambiguous candidates ARE the alternatives worth showing. When there
+            // are none, the recent episodes `unresolved()` offers stay — a caller who
+            // named a folder that does not exist still needs somewhere to look.
+            return match.candidates.length > 0
+                ? {
+                    ...answer,
+                    alternatives: match.candidates.map((episode) => ({
+                        episode,
+                        method: "explicit-ref",
+                        reason: `also matches "${ctx.episode}"`,
+                    })),
+                }
+                : answer;
+        }
+        // 2 — What an existing record already says about itself.
+        if (ctx.messageId) {
+            const record = await client.message(ctx.messageId);
+            if (!record)
+                return unresolved(`no voice record ${ctx.messageId}`);
+            const reading = episodeOf(record);
+            if (reading.episode) {
+                return resolved(reading.episode, "voice-record-binding", reading.binding === "declared"
+                    ? `record ${ctx.messageId} declares this episode`
+                    : `record ${ctx.messageId} names this episode in its path`);
+            }
+            return unresolved(`record ${ctx.messageId} carries no episode binding`);
+        }
+        // 3 — Where the caller is standing, when it said where that is.
+        if (ctx.cwd) {
+            const fromPath = episodeFromPath(ctx.cwd);
+            if (fromPath && folders.includes(fromPath)) {
+                return resolved(fromPath, "cwd", `working directory is inside ${fromPath}`);
+            }
+            return unresolved(`working directory ${ctx.cwd} is not inside an episode folder`);
+        }
+        return unresolved("no episode reference, message id or working directory was given, and the ranked " +
+            "discovery order is owed by the voice-episode-binding spec — this tool will not guess one");
+    }
+    /** A ledger record as something playable, or the reason it is not. */
+    function playable(message) {
+        const url = client.audioUrl(message);
+        if (!url) {
+            return {
+                messageId: message.id,
+                reason: "record carries no audio_file — legal for the non-TTS integration messages, which are text-only",
+            };
+        }
+        const reading = episodeOf(message);
+        return {
+            messageId: message.id,
+            url,
+            ...(config.audioRoot && message.audio_file
+                ? { path: `${config.audioRoot.replace(/\/$/, "")}/${message.audio_file}` }
+                : {}),
+            contentType: "audio/mpeg",
+            persona: message.persona,
+            lang: message.lang,
+            timestamp: message.timestamp,
+            text: message.text,
+            listened: message.listened,
+            // The record-level binding, mapped onto the resolution vocabulary: a
+            // declared binding was written with the record; a path binding was read
+            // off the directory the publisher was standing in.
+            binding: reading.binding === "declared"
+                ? "voice-record-binding"
+                : reading.binding === "path"
+                    ? "cwd"
+                    : "unresolved",
+        };
+    }
+    function split(messages) {
+        const voices = [];
+        const unplayable = [];
+        for (const m of messages) {
+            const p = playable(m);
+            if ("url" in p)
+                voices.push(p);
+            else
+                unplayable.push(p);
+        }
+        return { voices, unplayable };
+    }
+    return {
+        async playEpisode(input) {
+            const resolution = await resolve({ episode: input.episode });
+            if (!resolution.episode)
+                return { resolution, voices: [], unplayable: [] };
+            const bound = await client.episodeVoices(resolution.episode);
+            // Newest first: "play me what we said" means the latest, not the oldest.
+            const ordered = [...bound].reverse();
+            const limited = input.limit ? ordered.slice(0, input.limit) : ordered;
+            const { voices, unplayable } = split(limited);
+            return { resolution, voices, unplayable };
+        },
+        async resolveEpisode(input) {
+            return resolve({ episode: input.episode, cwd: input.cwd, messageId: input.messageId });
+        },
+        async publishToEpisode(input) {
+            const resolution = await resolve({ episode: input.episode });
+            // An episode was named and did not resolve: refuse. Publishing it unbound
+            // would produce exactly the record this whole surface exists to stop
+            // producing — audio nobody can address afterwards.
+            if (input.episode && !resolution.episode) {
+                throw new Error(`refusing to publish: ${resolution.reason}. ` +
+                    `Publish without an episode to leave the voice unbound deliberately, or name one that exists.`);
+            }
+            let message;
+            try {
+                message = await client.publish({
+                    text: input.text,
+                    ...(resolution.episode ? { episode: resolution.episode } : {}),
+                    ...(input.persona ? { persona: input.persona } : {}),
+                    ...(input.lang ? { lang: input.lang } : {}),
+                    source: input.source ?? "agent",
+                    ...(input.origin ? { origin: input.origin } : {}),
+                });
+            }
+            catch (e) {
+                // The tier failure is the one worth restating at the tool boundary: an
+                // agent reading a raw 401 has no way to know which variable to set.
+                if (e instanceof VoiceApiError && e.status === 401)
+                    throw new Error(e.message);
+                throw e;
+            }
+            const p = playable(message);
+            if (!("url" in p)) {
+                throw new Error(`published ${message.id} but it has no playable audio: ${p.reason}. ` +
+                    `The record is in the ledger; the producer is what to look at.`);
+            }
+            return { message, resolution, playable: p };
+        },
+        async listEpisodeVoices(input) {
+            const resolution = await resolve({ episode: input.episode });
+            if (!resolution.episode)
+                return { resolution, total: 0, voices: [] };
+            const bound = await client.episodeVoices(resolution.episode);
+            const needle = input.query?.toLowerCase();
+            const filtered = bound.filter((m) => {
+                if (needle && !m.text.toLowerCase().includes(needle))
+                    return false;
+                if (input.persona && m.persona !== input.persona)
+                    return false;
+                if (input.lang && m.lang !== input.lang)
+                    return false;
+                if (input.listened !== undefined && m.listened !== input.listened)
+                    return false;
+                return true;
+            });
+            const ordered = [...filtered].reverse();
+            const limited = input.limit ? ordered.slice(0, input.limit) : ordered;
+            // `total` counts the matches, not the page: a caller that asked for 10 of
+            // 40 needs to know there are 40.
+            return { resolution, total: filtered.length, voices: split(limited).voices };
+        },
+        async createEpisode() {
+            throw new NotImplementedError("voice_create_episode", "voice-mcp.spec.md § Tool 4 · voice_create_episode and " +
+                "§ The closing gate is part of the tool, not after it");
+        },
+        async episodeClosingStatus() {
+            throw new NotImplementedError("voice_episode_closing_status", "voice-mcp.spec.md § Tool 6 · voice_episode_closing_status");
+        },
+    };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * @miadi/voice-mcp — the MCP server that lets an agent play, find, publish and
+ * mint episode-bound voice.
+ *
+ * The one sentence this package exists to satisfy, from William, 2026-08-04:
+ *   "What I want is actually to be capable to play the voice-audio created for
+ *    episodes."
+ *
+ * STATE. Four tools work: publish, play, list, resolve. Two still refuse and
+ * name their contract — `voice_create_episode` and `voice_episode_closing_status`
+ * mint and prove a chronicle vessel, and a tool that reports a closing stage it
+ * did not prove is worse than one that declines. See `handlers.ts`.
+ *
+ * ARCHITECTURE. This server is a *front*, not a second implementation. Audio
+ * bytes, the KV ledger and the Edge-TTS producer live behind the Miadi server
+ * (systemd unit `miadi-server`, port 3335 — verified live 2026-08-04), which
+ * holds the KV credentials. This process reaches them over HTTP through
+ * `@miadi/voice-client`, and reads the chronicle folders directly. `VoiceMessage`
+ * keeps exactly one definition in the workspace: `@miadi/voice`'s.
+ *
+ * Specifications: see `SPEC-LINKS.md` beside this package.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type VoiceMcpHandlers } from "./contract.js";
+export * from "./types.js";
+export { createScaffoldHandlers, loadConfig, NotImplementedError, type VoiceMcpConfig, type VoiceMcpHandlers, } from "./contract.js";
+export { createHttpHandlers } from "./handlers.js";
+export { listEpisodeFolders, matchRef, episodePath, isEpisodeFolder } from "./chronicle.js";
+/**
+ * Build the server with its six tools registered. Handlers are injected so the
+ * implementation can change without touching registration, and so tests can
+ * substitute one — `createScaffoldHandlers()` gives a surface that refuses
+ * everything, which is what a contract test wants.
+ */
+export declare function createServer(handlers?: VoiceMcpHandlers): McpServer;
+export declare function main(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAIvB,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,UAAU,EACV,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAmC5F;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,GAAE,gBAAmD,GAC5D,SAAS,CAiLX;AAID,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAiB1C"}

package/dist/index.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * @miadi/voice-mcp — the MCP server that lets an agent play, find, publish and
+ * mint episode-bound voice.
+ *
+ * The one sentence this package exists to satisfy, from William, 2026-08-04:
+ *   "What I want is actually to be capable to play the voice-audio created for
+ *    episodes."
+ *
+ * STATE. Four tools work: publish, play, list, resolve. Two still refuse and
+ * name their contract — `voice_create_episode` and `voice_episode_closing_status`
+ * mint and prove a chronicle vessel, and a tool that reports a closing stage it
+ * did not prove is worse than one that declines. See `handlers.ts`.
+ *
+ * ARCHITECTURE. This server is a *front*, not a second implementation. Audio
+ * bytes, the KV ledger and the Edge-TTS producer live behind the Miadi server
+ * (systemd unit `miadi-server`, port 3335 — verified live 2026-08-04), which
+ * holds the KV credentials. This process reaches them over HTTP through
+ * `@miadi/voice-client`, and reads the chronicle folders directly. `VoiceMessage`
+ * keeps exactly one definition in the workspace: `@miadi/voice`'s.
+ *
+ * Specifications: see `SPEC-LINKS.md` beside this package.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig, } from "./contract.js";
+import { createHttpHandlers } from "./handlers.js";
+export * from "./types.js";
+export { createScaffoldHandlers, loadConfig, NotImplementedError, } from "./contract.js";
+export { createHttpHandlers } from "./handlers.js";
+export { listEpisodeFolders, matchRef, episodePath, isEpisodeFolder } from "./chronicle.js";
+const NAME = "@miadi/voice-mcp";
+const VERSION = "0.1.0";
+// ── Shared schema fragments ─────────────────────────────────────────────────
+const episodeRefSchema = z
+    .string()
+    .describe("Episode reference. Accepts the folder name (2026-07-27-episode-300-from-shadow-to-song), " +
+    "the wheel node id (chronicle:<folder-name>), or the ep<NNN> number form of the " +
+    "notation owned by the episode-addressing spec. A number matching two folders " +
+    "resolves to neither and returns both. Omitted, the tool answers from what it was " +
+    "given (cwd, message id) and says plainly when that is nothing.");
+const langSchema = z.enum(["fr", "en"]).describe("Spoken language.");
+const personaSchema = z
+    .string()
+    .describe("Assembly persona id. Unknown personas are refused by the voice layer.");
+// ── Server construction ─────────────────────────────────────────────────────
+function ok(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function refused(e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return { isError: true, content: [{ type: "text", text: message }] };
+}
+/**
+ * Build the server with its six tools registered. Handlers are injected so the
+ * implementation can change without touching registration, and so tests can
+ * substitute one — `createScaffoldHandlers()` gives a surface that refuses
+ * everything, which is what a contract test wants.
+ */
+export function createServer(handlers = createHttpHandlers(loadConfig())) {
+    const server = new McpServer({ name: NAME, version: VERSION }, { capabilities: { tools: {} } });
+    // ── 1 · Play ──────────────────────────────────────────────────────────────
+    server.registerTool("voice_play_episode", {
+        title: "Play an episode's voice",
+        description: "Resolve an episode to its bound voice audio and return playable references — " +
+            "a streamable URL per voice, plus the on-disk path when the local audio store " +
+            "is active. Omit `episode` to play the episode adequate to the caller's context.",
+        inputSchema: {
+            episode: episodeRefSchema.optional(),
+            limit: z.number().int().positive().max(200).optional()
+                .describe("Maximum voices to return, newest first."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await handlers.playEpisode(args));
+        }
+        catch (e) {
+            return refused(e);
+        }
+    });
+    // ── 2 · Find the adequate episode ────────────────────────────────────────
+    server.registerTool("voice_resolve_episode", {
+        title: "Find the adequate episode",
+        description: "Answer which episode the caller is working inside, from an explicit reference, " +
+            "an existing voice record, the session's declared origin, or the working " +
+            "directory. Always returns the reason and the alternatives considered, and may " +
+            "answer that no episode is adequate — which is a valid answer, not a failure.",
+        inputSchema: {
+            episode: episodeRefSchema.optional(),
+            cwd: z.string().optional().describe("Absolute working directory of the agent."),
+            sessionId: z.string().optional().describe("Agent session id, when one exists."),
+            messageId: z.string().optional()
+                .describe("Resolve from an existing voice record rather than from context."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await handlers.resolveEpisode(args));
+        }
+        catch (e) {
+            return refused(e);
+        }
+    });
+    // ── 3 · Publish voice bound to an episode ────────────────────────────────
+    server.registerTool("voice_publish_to_episode", {
+        title: "Publish voice bound to an episode",
+        description: "Produce spoken audio that is addressable from its episode from the moment it " +
+            "exists. The binding is written with the record, never inferred afterwards.",
+        inputSchema: {
+            text: z.string().min(1).describe("Text to speak."),
+            episode: episodeRefSchema.optional(),
+            persona: personaSchema.optional(),
+            lang: langSchema.optional(),
+            source: z.string().optional()
+                .describe("Classification carried into the ledger record's `source` field."),
+            origin: z.record(z.string(), z.unknown()).optional()
+                .describe("The publisher's return address (user, host, multiplexer, session, pane). " +
+                "Server-owned fields are stamped by the voice layer and cannot be supplied."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await handlers.publishToEpisode(args));
+        }
+        catch (e) {
+            return refused(e);
+        }
+    });
+    // ── 4 · Create the episode when none fits ────────────────────────────────
+    server.registerTool("voice_create_episode", {
+        title: "Create a Chronicle episode vessel",
+        description: "Mint a new episode when no existing one is adequate, via mkepisode against the " +
+            "Chronicle wheel. Returns every one of the five closing stages with its proof — " +
+            "created, committed, pushed, registered, receipt-verified — and the exact " +
+            "commands owed for the stages this tool does not itself perform. Creation is " +
+            "not closure, and this tool never reports a later word than it proved.",
+        inputSchema: {
+            number: z.number().int().positive()
+                .describe("Episode number. Must be free; mkepisode refuses one in use."),
+            title: z.string().min(1).describe("Episode title; becomes the folder slug."),
+            goal: z.string().min(1).describe("The desired result this episode advances."),
+            references: z.array(z.string().min(1)).min(1)
+                .describe("Provenance locators as owner/repo#n, ordered. Required and repeatable; " +
+                "the first becomes the card's source_issue."),
+            firstVoice: z
+                .object({
+                text: z.string().min(1),
+                persona: personaSchema.optional(),
+                lang: langSchema.optional(),
+            })
+                .optional()
+                .describe("Voice to publish into the vessel the moment it exists."),
+        },
+    }, async (args) => {
+        try {
+            return ok(await handlers.createEpisode(args));
+        }
+        catch (e) {
+            return refused(e);
+        }
+    });
+    // ── 5 · List / search an episode's voices ────────────────────────────────
+    server.registerTool("voice_list_episode_voices", {
+        title: "List an episode's voices",
+        description: "Enumerate the voices bound to an episode, filtered by persona, language, " +
+            "listened state, or a substring of the spoken text.",
+        inputSchema: {
+            episode: episodeRefSchema.optional(),
+            query: z.string().optional().describe("Substring match over the spoken text."),
+            persona: personaSchema.optional(),
+            lang: langSchema.optional(),
+            listened: z.boolean().optional(),
+            limit: z.number().int().positive().max(200).optional(),
+        },
+    }, async (args) => {
+        try {
+            return ok(await handlers.listEpisodeVoices(args));
+        }
+        catch (e) {
+            return refused(e);
+        }
+    });
+    // ── 6 · Prove the closing gate ───────────────────────────────────────────
+    server.registerTool("voice_episode_closing_status", {
+        title: "Prove an episode's five closing stages",
+        description: "Read-only. Re-run each of the five proofs — created, committed, pushed, " +
+            "registered, receipt-verified — and report what each command actually said, " +
+            "plus any drift shape found and the commands owed to redeem it.",
+        inputSchema: {
+            episode: episodeRefSchema,
+        },
+    }, async (args) => {
+        try {
+            return ok(await handlers.episodeClosingStatus(args));
+        }
+        catch (e) {
+            return refused(e);
+        }
+    });
+    return server;
+}
+// ── Entry point ─────────────────────────────────────────────────────────────
+export async function main() {
+    const config = loadConfig();
+    // stderr: stdout belongs to the MCP transport, and one stray line there
+    // corrupts the JSON-RPC stream.
+    //
+    // The tier is printed because a reader-tier credential makes every publish
+    // answer 401 while every read keeps working — the failure that looks like a
+    // broken tool and is a one-variable fix.
+    console.error(`${NAME} ${VERSION} — api=${config.apiUrl} token=${config.tokenTier} ` +
+        `chronicle=${config.chronicleRoot}` +
+        (config.tokenTier === "writer"
+            ? ""
+            : ` ⚠ publishing needs MIADI_API_TOKEN_WRITER; reads work without it`));
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+}
+const invokedDirectly = typeof process !== "undefined" &&
+    Array.isArray(process.argv) &&
+    process.argv[1] !== undefined &&
+    /voice-mcp[\\/](?:dist|src)[\\/]index\.(?:js|ts)$/.test(process.argv[1]);
+if (invokedDirectly) {
+    main().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,165 @@
+import type { VoiceLang, VoiceMessage } from "@miadi/voice";
+export type { VoiceLang, VoiceMessage };
+/**
+ * The chronicle folder name — the primary key everywhere. Shaped
+ * `YYYY-MM-DD-episode-NNN-slug`. Verified 2026-08-04: 146 folders of this shape
+ * under `/srv/miadi/episodes/miadi-chronicle`, and the medicine wheel keys its
+ * card `chronicle:<folder-name>`.
+ */
+export type EpisodeFolderName = string;
+/** The wheel node id: `chronicle:<EpisodeFolderName>`. */
+export type EpisodeNodeId = string;
+/**
+ * A reference an agent may hand a tool. The `ep<NNN>[.<II>][/<segment>]`
+ * notation is owned by the addressing spec — this type only carries it.
+ *
+ * @see [episode-addressing spec § The Address Grammar · Notation]
+ */
+export type EpisodeRef = string;
+/** How an episode was arrived at. Ranked resolution belongs to the binding spec. */
+export type EpisodeResolutionMethod = "explicit-ref" | "voice-record-binding" | "session-origin" | "cwd" | "wheel-search" | "unresolved";
+/**
+ * The answer to "which episode is this?" — always carrying *why*, and always
+ * able to say it does not know.
+ *
+ * The order the resolvers are consulted, and the confidence each yields, are
+ * governed by [voice-episode-binding spec § Discovery resolution order]. This
+ * package consumes that order; it does not define one.
+ */
+export interface EpisodeResolution {
+    /** `null` when nothing adequate was found — a valid, expected answer. */
+    episode: EpisodeFolderName | null;
+    nodeId: EpisodeNodeId | null;
+    method: EpisodeResolutionMethod;
+    /** Human-readable account of what was matched. Never omitted. */
+    reason: string;
+    /** Candidates considered but not chosen, best-first. */
+    alternatives: Array<{
+        episode: EpisodeFolderName;
+        method: EpisodeResolutionMethod;
+        reason: string;
+    }>;
+}
+/**
+ * One playable voice. `url` is the streamable address served by the Miadi
+ * server (`GET /api/voice/audio/<key>` — verified 2026-08-04 returning 200
+ * `audio/mpeg`). `path` is the on-disk location when the local audio store is
+ * the active driver, offered so a caller on the same host can play it directly.
+ *
+ * @see [voice-episode-binding spec § Playback path]
+ */
+export interface PlayableVoice {
+    messageId: string;
+    url: string;
+    path?: string;
+    contentType: string;
+    persona: string;
+    lang: VoiceLang;
+    timestamp: string;
+    /** The spoken text. Present on every record in the live ledger. */
+    text: string;
+    listened: boolean;
+    /** How this voice came to belong to this episode. */
+    binding: EpisodeResolutionMethod;
+}
+export interface PlayEpisodeResult {
+    resolution: EpisodeResolution;
+    voices: PlayableVoice[];
+    /** Voices found for the episode but not playable, each with the reason. */
+    unplayable: Array<{
+        messageId: string;
+        reason: string;
+    }>;
+}
+/**
+ * Producing a voice already bound to an episode. Binding is established at
+ * publish time rather than inferred later — the whole point of the tool.
+ *
+ * @see [voice-episode-binding spec § Enforcement decision table]
+ */
+export interface PublishToEpisodeInput {
+    text: string;
+    episode?: EpisodeRef;
+    persona?: string;
+    lang?: VoiceLang;
+    /** Free-form classification carried into the ledger record's `source`. */
+    source?: string;
+    /**
+     * The publisher's return address, passed through untouched to the voice
+     * layer, which stamps the server-owned fields itself. Shape and the
+     * self-declared/server attestation rule are owned by `@miadi/voice`.
+     */
+    origin?: Record<string, unknown>;
+}
+export interface PublishToEpisodeResult {
+    message: VoiceMessage;
+    resolution: EpisodeResolution;
+    /** The address the voice can be played from immediately. */
+    playable: PlayableVoice;
+}
+export interface ListEpisodeVoicesInput {
+    episode?: EpisodeRef;
+    /** Substring match over the record's spoken text. */
+    query?: string;
+    persona?: string;
+    lang?: VoiceLang;
+    listened?: boolean;
+    limit?: number;
+}
+export interface ListEpisodeVoicesResult {
+    resolution: EpisodeResolution;
+    total: number;
+    voices: PlayableVoice[];
+}
+/**
+ * The five stages of a Chronicle episode, each proven separately. `mkepisode`
+ * exits 0 whether registration succeeded, skipped, or failed, so the gate
+ * belongs to the caller. This type exists so an MCP tool can never report a
+ * later word than the stage it proved.
+ *
+ * @see [voice-mcp spec § The closing gate is part of the tool, not after it]
+ * @see /etc/claude-code/skills/chronicle-episode-closing/SKILL.md
+ */
+export type ClosingStage = "created" | "committed" | "pushed" | "registered" | "receipt-verified";
+export interface ClosingStageProof {
+    stage: ClosingStage;
+    /** `owed` is a first-class state — the honest word for "not proven yet". */
+    state: "proven" | "owed" | "failed";
+    /** The command run, verbatim, so a human can re-run it. */
+    probe: string;
+    /** What that command actually said. Never a summary of what it should say. */
+    observed: string;
+}
+export interface CreateEpisodeInput {
+    /** Positive integer, must be free — `mkepisode` refuses a number in use. */
+    number: number;
+    title: string;
+    /** The desired result this episode advances. */
+    goal: string;
+    /** Ordered provenance locators, `owner/repo#n`. Required, repeatable. */
+    references: string[];
+    /** Voice to publish into the vessel the moment it exists. */
+    firstVoice?: {
+        text: string;
+        persona?: string;
+        lang?: VoiceLang;
+    };
+}
+export interface CreateEpisodeResult {
+    episode: EpisodeFolderName;
+    nodeId: EpisodeNodeId;
+    path: string;
+    /** Every stage, with its proof. Stages the tool cannot perform read `owed`. */
+    closing: ClosingStageProof[];
+    /** The exact commands a human runs to redeem each `owed` stage, in order. */
+    owedActions: string[];
+    firstVoice?: PublishToEpisodeResult;
+}
+export interface ClosingStatusResult {
+    episode: EpisodeFolderName;
+    closing: ClosingStageProof[];
+    /** Drift shape names as reported by the chronicle reconciler, when any. */
+    drift: string[];
+    owedActions: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+// Tool I/O shapes for @miadi/voice-mcp.
+//
+// These are the contract types the six tools speak. They are declared here so
+// the tool surface is readable and typed before any handler exists — the
+// scaffold's whole purpose. Every shape here is governed by a specification
+// section named in `SPEC-LINKS.md`; where a rule belongs to a sibling spec it is
+// cited, never restated, so there is exactly one source of truth for it.
+//
+// Canonical voice shapes (`VoiceMessage`, `VoiceLang`, persona identity) are
+// owned by `@miadi/voice` and imported, not re-declared.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,4EAA4E;AAC5E,iFAAiF;AACjF,yEAAyE;AACzE,EAAE;AACF,6EAA6E;AAC7E,yDAAyD"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@miadi/voice-mcp",
+  "version": "0.1.0",
+  "description": "MCP server fronting the Miadi voice layer with episode addressing \u2014 play, find, publish and mint episode-bound voice from an agent's tool surface.",
+  "license": "MIT",
+  "author": "Miadi",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "miadi-voice-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SPEC-LINKS.md"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p tsconfig.build.json",
+    "type-check": "../../node_modules/.bin/tsc -p tsconfig.build.json --noEmit",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@miadi/voice": "workspace:*",
+    "@miadi/voice-client": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "miadi",
+    "mcp",
+    "voice",
+    "tts",
+    "miadi-chronicle",
+    "episodic-memory"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/Miadi.git",
+    "directory": "packages/voice-mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}