@docwhispr/mcp-server 0.1.0 → 0.1.3

package/README.md

@@ -1,25 +1,48 @@
 # @docwhispr/mcp-server
 
-Thin MCP client for **docwhispr** cloud curriculum compiler (HiliFlow).
+Thin client for **docwhispr** cloud curriculum compiler (HiliFlow).
 
-- Free: `hiliflow_plan_curriculum` (topic scope + multi-episode blueprint)
-- Metered: `hiliflow_compile_episode` / `hiliflow_compile_series` (charges from the same monthly video pool as the web app)
-- Upsell: `hiliflow_open_studio` → hosted interactive player URL
+## One-time setup (paste from Settings)
 
-## Setup
+```bash
+npx -y @docwhispr/mcp-server configure --key "hl_live_…"
+# optional, Cursor only:
+# npx -y @docwhispr/mcp-server configure --key "hl_live_…" --cursor-mcp
+```
+
+Saves `~/.docwhispr/credentials.json`. CLI and any MCP host that runs this package will read it automatically. `--cursor-mcp` only updates `~/.cursor/mcp.json` (still **without** embedding the key).
 
-1. Sign in at [docwhispr.com](https://docwhispr.com), create an API key:
+## CLI
 
 ```bash
-curl -X POST "$HILIFLOW_API_BASE/api/mcp/keys" \
-  -H "Authorization: Bearer <session_jwt>" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"Cursor MCP","plan":"free"}'
+npx -y @docwhispr/mcp-server plan \
+  --pdf "/path/to/book.pdf" \
+  --pages 602-604 \
+  --topics EXTEST,INTEST
+
+npx -y @docwhispr/mcp-server compile \
+  --pdf "/path/to/book.pdf" \
+  --pages 602-604 \
+  --topics EXTEST,INTEST \
+  --lang zh \
+  --character chr_pixel_voxel \
+  --wait
 ```
 
-Save the returned `apiKey` (`hl_live_…`) once.
+| Command | Credits |
+| --- | ---: |
+| `configure` | 0 |
+| `plan` | 0 |
+| `compile` | 1 |
+| `credits` / `status` | 0 |
+
+Auth: `HILIFLOW_API_KEY` env **or** credentials file from `configure`.
 
-2. Cursor `mcp.json` (or Claude Desktop MCP config):
+`402` = out of credits · `409` = another job already generating.
+
+## MCP stdio
+
+After `configure --cursor-mcp`, or manually:
 
 ```json
 {
@@ -28,7 +51,6 @@ Save the returned `apiKey` (`hl_live_…`) once.
       "command": "npx",
       "args": ["-y", "@docwhispr/mcp-server"],
       "env": {
-        "HILIFLOW_API_KEY": "hl_live_…",
         "HILIFLOW_API_BASE": "https://docwhispr.fly.dev",
         "HILIFLOW_WEB_BASE": "https://docwhispr.com"
       }
@@ -37,36 +59,16 @@ Save the returned `apiKey` (`hl_live_…`) once.
 }
 ```
 
-Local monorepo:
-
-```json
-{
-  "mcpServers": {
-    "docwhispr": {
-      "command": "npx",
-      "args": ["tsx", "packages/mcp-server/src/index.ts"],
-      "cwd": "<repo-root>",
-      "env": {
-        "HILIFLOW_API_KEY": "hl_live_…",
-        "HILIFLOW_API_BASE": "http://127.0.0.1:8080"
-      }
-    }
-  }
-}
-```
-
-## Tools
-
-| Tool | Credits | Purpose |
-| --- | ---: | --- |
-| `hiliflow_credits` | 0 | Balance / monthly allowance |
-| `hiliflow_plan_curriculum` | 0 | Book↔PDF resolve, keep/drop topics, episode split |
-| `hiliflow_compile_episode` | 1 | Single project job |
-| `hiliflow_compile_series` | N | Multi-episode split & enqueue |
-| `hiliflow_job_status` | 0 | Poll job |
-| `hiliflow_open_studio` | 0 | Hosted interactive studio URL |
+| Tool | Credits |
+| --- | ---: |
+| `hiliflow_credits` | 0 |
+| `hiliflow_plan_curriculum` | 0 |
+| `hiliflow_compile_episode` | 1 |
+| `hiliflow_compile_series` | N |
+| `hiliflow_job_status` | 0 |
+| `hiliflow_open_studio` | 0 |
 
-## Monthly credits (same pool as web Generate)
+## Monthly credits
 
 | Plan | Episodes / month |
 | --- | ---: |

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function run(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,139 @@
+/**
+ * CLI handlers for configure / plan / compile / credits / status.
+ * Invoked from index.ts when argv includes a subcommand.
+ */
+import { api, compileEpisode, ensureCursorMcpConfig, getWebBase, jobStatus, parsePages, parseTopics, planCurriculum, saveCredentials } from "./lib.js";
+function usage(exitCode = 1) {
+    console.error(`Usage:
+  npx @docwhispr/mcp-server configure --key hl_live_… [--cursor-mcp]
+  npx @docwhispr/mcp-server plan    --pdf <path> --pages <min>-<max> [--topics a,b] [--title ...]
+  npx @docwhispr/mcp-server compile --pdf <path> --pages <min>-<max> [--topics a,b] [--lang zh]
+                                    [--character chr_pixel_voxel] [--title ...] [--plan free|pro|pro_plus]
+                                    [--wait] [--poll-ms 20000]
+  npx @docwhispr/mcp-server credits [--plan free|pro|pro_plus]
+  npx @docwhispr/mcp-server status  --job <id>
+
+Auth: HILIFLOW_API_KEY env, or ~/.docwhispr/credentials.json from \`configure\`
+`);
+    process.exit(exitCode);
+}
+function flag(args, name) {
+    const i = args.indexOf(name);
+    if (i < 0)
+        return undefined;
+    return args[i + 1];
+}
+function has(args, name) {
+    return args.includes(name);
+}
+async function sleep(ms) {
+    await new Promise((r) => setTimeout(r, ms));
+}
+async function waitForJob(jobId, pollMs) {
+    for (;;) {
+        const job = await jobStatus(jobId, "cli");
+        const status = String(job.status || "");
+        const progress = job.progressMessage ? ` · ${job.progressMessage}` : "";
+        console.error(`[status] ${status}${progress}`);
+        if (status === "succeeded" || status === "failed" || status === "error") {
+            return job;
+        }
+        await sleep(pollMs);
+    }
+}
+export async function run(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help")
+        usage(0);
+    try {
+        if (cmd === "configure") {
+            const key = flag(rest, "--key");
+            if (!key)
+                usage();
+            const path = saveCredentials({ apiKey: key });
+            const out = {
+                credentialsPath: path,
+                note: "API key saved. plan/compile/MCP will read it automatically."
+            };
+            if (has(rest, "--cursor-mcp")) {
+                out.cursorMcpPath = ensureCursorMcpConfig();
+                out.cursorNote =
+                    "Cursor mcp.json updated (no key embedded). Restart MCP docwhispr in Cursor.";
+            }
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (cmd === "credits") {
+            const plan = flag(rest, "--plan");
+            const q = plan ? `?plan=${encodeURIComponent(plan)}` : "";
+            const data = await api(`/api/mcp/credits${q}`, {}, "cli");
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        if (cmd === "status") {
+            const jobId = flag(rest, "--job");
+            if (!jobId)
+                usage();
+            console.log(JSON.stringify(await jobStatus(jobId, "cli"), null, 2));
+            return;
+        }
+        if (cmd === "plan" || cmd === "compile") {
+            const pdf = flag(rest, "--pdf");
+            const pages = flag(rest, "--pages");
+            if (!pdf || !pages)
+                usage();
+            const { pageMin, pageMax } = parsePages(pages);
+            const includeTopics = parseTopics(flag(rest, "--topics"));
+            const title = flag(rest, "--title");
+            const common = {
+                pdfPath: pdf,
+                pageMin,
+                pageMax,
+                includeTopics,
+                title,
+                client: "cli"
+            };
+            if (cmd === "plan") {
+                const plan = await planCurriculum(common);
+                console.log(JSON.stringify({
+                    note: "Free curriculum preview. Confirm, then run compile.",
+                    plan
+                }, null, 2));
+                return;
+            }
+            const result = await compileEpisode({
+                ...common,
+                contentLanguage: flag(rest, "--lang") || "en",
+                characterId: flag(rest, "--character") || undefined,
+                plan: flag(rest, "--plan") ||
+                    "free"
+            });
+            const jobId = String(result.job?.id || "");
+            console.log(JSON.stringify({ ...result, note: "1 episode credit charged." }, null, 2));
+            if (has(rest, "--wait") && jobId) {
+                const pollMs = Number(flag(rest, "--poll-ms") || 20000);
+                const finalJob = await waitForJob(jobId, Number.isFinite(pollMs) ? pollMs : 20000);
+                console.log(JSON.stringify({
+                    job: finalJob,
+                    studioUrl: `${getWebBase()}/app/projects/${jobId}`
+                }, null, 2));
+                if (String(finalJob.status) !== "succeeded")
+                    process.exit(2);
+            }
+            return;
+        }
+        usage();
+    }
+    catch (err) {
+        const status = err.status;
+        const message = err instanceof Error ? err.message : String(err);
+        if (status === 402) {
+            console.error("Insufficient credits (402). Upgrade plan or wait for monthly refresh.");
+        }
+        else if (status === 409) {
+            console.error("Another video is already generating (409). Wait or stop the running job.");
+        }
+        console.error(message);
+        process.exit(1);
+    }
+}

package/dist/index.js

@@ -1,61 +1,33 @@
 #!/usr/bin/env node
 /**
- * HiliFlow MCP server (stdio).
+ * HiliFlow / docwhispr entry:
+ *   - CLI:  npx @docwhispr/mcp-server plan|compile|credits|status …
+ *   - MCP:  npx @docwhispr/mcp-server   (stdio, via Cursor mcp.json)
  *
- * Env:
- *   HILIFLOW_API_KEY     — required (hl_live_…)
- *   HILIFLOW_API_BASE    — optional, default https://docwhispr.fly.dev
- *   HILIFLOW_WEB_BASE    — optional studio host, default https://docwhispr.com
+ * Auth (first match wins):
+ *   HILIFLOW_API_KEY env, or ~/.docwhispr/credentials.json from `configure`
+ * Optional:
+ *   HILIFLOW_API_BASE / HILIFLOW_WEB_BASE
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
-const API_BASE = (process.env.HILIFLOW_API_BASE ||
-    process.env.DOCWHISPR_API_BASE ||
-    process.env.NEXT_PUBLIC_VIDEO_WORKER_BASE_URL ||
-    "https://docwhispr.fly.dev").replace(/\/$/, "");
-const WEB_BASE = (process.env.HILIFLOW_WEB_BASE ||
-    process.env.DOCWHISPR_WEB_BASE ||
-    process.env.NEXT_PUBLIC_APP_URL ||
-    "https://docwhispr.com").replace(/\/$/, "");
-function requireApiKey() {
-    const key = (process.env.HILIFLOW_API_KEY || "").trim();
-    if (!key) {
-        throw new Error("HILIFLOW_API_KEY is required. Create one via POST /api/mcp/keys (signed-in browser session), then set it in MCP env.");
-    }
-    return key;
-}
-async function api(path, init = {}) {
-    const key = requireApiKey();
-    const headers = {
-        Authorization: `Bearer ${key}`,
-        "X-HiliFlow-Client": "mcp",
-        Accept: "application/json",
-        ...init.headers
-    };
-    let body = init.body;
-    if (init.json !== undefined) {
-        headers["Content-Type"] = "application/json";
-        body = JSON.stringify(init.json);
-    }
-    const res = await fetch(`${API_BASE}${path}`, { ...init, headers, body });
-    const text = await res.text();
-    let data = null;
-    try {
-        data = text ? JSON.parse(text) : null;
-    }
-    catch {
-        data = { raw: text };
-    }
-    if (!res.ok) {
-        const detail = typeof data === "object" && data && "detail" in data
-            ? String(data.detail)
-            : text || res.statusText;
-        throw new Error(`HiliFlow API ${res.status}: ${detail}`);
-    }
-    return data;
+import { api, buildTeachingScope, compileEpisode, fileNameOf, fileToBase64, getWebBase, jobStatus, planCurriculum, sha256HexOfFile } from "./lib.js";
+const CLI_COMMANDS = new Set([
+    "configure",
+    "plan",
+    "compile",
+    "credits",
+    "status",
+    "help",
+    "-h",
+    "--help"
+]);
+const maybeCmd = process.argv[2];
+if (maybeCmd && CLI_COMMANDS.has(maybeCmd)) {
+    const { run } = await import("./cli.js");
+    await run(process.argv.slice(2));
+    process.exit(0);
 }
 function textResult(payload) {
     return {
@@ -67,29 +39,9 @@ function textResult(payload) {
         ]
     };
 }
-function fileToBase64(filePath) {
-    const abs = resolve(filePath);
-    return readFileSync(abs).toString("base64");
-}
-async function sha256HexOfFile(filePath) {
-    const { createHash } = await import("node:crypto");
-    const buf = readFileSync(resolve(filePath));
-    return createHash("sha256").update(buf).digest("hex");
-}
-const teachingScopeSchema = z
-    .object({
-    include_topics: z.array(z.string()).optional(),
-    exclude_topics: z.array(z.string()).optional(),
-    background_policy: z
-        .enum(["none", "necessary_only", "all_in_section"])
-        .optional(),
-    page_numbering: z.enum(["auto", "pdf", "book"]).optional(),
-    user_prompt: z.string().optional()
-})
-    .optional();
 const server = new McpServer({
     name: "hiliflow",
-    version: "0.1.0"
+    version: "0.1.1"
 });
 server.tool("hiliflow_credits", {
     plan: z.enum(["free", "pro", "pro_plus"]).optional()
@@ -117,31 +69,16 @@ server.tool("hiliflow_plan_curriculum", {
     maxPagesPerJob: z.number().int().min(1).max(20).optional().default(10),
     title: z.string().optional()
 }, async (args) => {
-    const contentHash = await sha256HexOfFile(args.pdfPath);
-    const contentBase64 = fileToBase64(args.pdfPath);
-    const teachingScope = {
-        include_topics: args.includeTopics ?? [],
-        background_policy: args.backgroundPolicy ?? "necessary_only",
-        page_numbering: args.pageNumbering ?? "auto",
-        user_prompt: args.userPrompt ||
-            (args.includeTopics?.length
-                ? `Focus on: ${args.includeTopics.join(", ")}`
-                : "")
-    };
-    const plan = await api("/api/series/plan", {
-        method: "POST",
-        json: {
-            fileName: resolve(args.pdfPath).split(/[/\\]/).pop(),
-            pageMin: args.pageMin,
-            pageMax: args.pageMax,
-            contentHash,
-            contentBase64,
-            sourceType: "pdf",
-            title: args.title,
-            teachingScope,
-            maxPagesPerJob: args.maxPagesPerJob ?? 10,
-            extractDocName: true
-        }
+    void args.pageNumbering; // always auto in teachingScope
+    const plan = await planCurriculum({
+        pdfPath: args.pdfPath,
+        pageMin: args.pageMin,
+        pageMax: args.pageMax,
+        includeTopics: args.includeTopics,
+        backgroundPolicy: args.backgroundPolicy,
+        userPrompt: args.userPrompt,
+        maxPagesPerJob: args.maxPagesPerJob,
+        title: args.title
     });
     return textResult({
         note: "Free curriculum preview. Confirm with the user, then call hiliflow_compile_series (or hiliflow_compile_episode for a single job).",
@@ -161,37 +98,27 @@ server.tool("hiliflow_compile_episode", {
     userPrompt: z.string().optional(),
     title: z.string().optional(),
     contentLanguage: z.string().optional().default("en"),
+    characterId: z
+        .string()
+        .optional()
+        .describe('e.g. "chr_pixel_voxel" for Voxel teacher'),
     plan: z.enum(["free", "pro", "pro_plus"]).optional().default("free")
 }, async (args) => {
-    const contentHash = await sha256HexOfFile(args.pdfPath);
-    const contentBase64 = fileToBase64(args.pdfPath);
-    const teachingScope = {
-        include_topics: args.includeTopics ?? [],
-        background_policy: args.backgroundPolicy ?? "necessary_only",
-        page_numbering: args.pageNumbering ?? "auto",
-        user_prompt: args.userPrompt || ""
-    };
-    const job = await api("/api/jobs", {
-        method: "POST",
-        json: {
-            fileName: resolve(args.pdfPath).split(/[/\\]/).pop(),
-            pageMin: args.pageMin,
-            pageMax: args.pageMax,
-            contentHash,
-            contentBase64,
-            sourceType: "pdf",
-            title: args.title,
-            teachingScope,
-            contentLanguage: args.contentLanguage ?? "en",
-            plan: args.plan ?? "free",
-            extractDocName: true,
-            highlight: true
-        }
+    void args.pageNumbering;
+    const result = await compileEpisode({
+        pdfPath: args.pdfPath,
+        pageMin: args.pageMin,
+        pageMax: args.pageMax,
+        includeTopics: args.includeTopics,
+        backgroundPolicy: args.backgroundPolicy,
+        userPrompt: args.userPrompt,
+        title: args.title,
+        contentLanguage: args.contentLanguage,
+        characterId: args.characterId,
+        plan: args.plan
     });
-    const jobId = String(job.id || "");
     return textResult({
-        job,
-        studioUrl: jobId ? `${WEB_BASE}/app/projects/${jobId}` : null,
+        ...result,
         note: "1 episode credit charged. Poll hiliflow_job_status until status=succeeded."
     });
 });
@@ -209,20 +136,20 @@ server.tool("hiliflow_compile_series", {
     maxPagesPerJob: z.number().int().min(1).max(20).optional().default(10),
     title: z.string().optional(),
     contentLanguage: z.string().optional().default("en"),
+    characterId: z
+        .string()
+        .optional()
+        .describe('e.g. "chr_pixel_voxel" for Voxel teacher'),
     plan: z.enum(["free", "pro", "pro_plus"]).optional().default("free")
 }, async (args) => {
+    void args.pageNumbering;
     const contentHash = await sha256HexOfFile(args.pdfPath);
     const contentBase64 = fileToBase64(args.pdfPath);
-    const teachingScope = {
-        include_topics: args.includeTopics ?? [],
-        background_policy: args.backgroundPolicy ?? "necessary_only",
-        page_numbering: args.pageNumbering ?? "auto",
-        user_prompt: args.userPrompt || ""
-    };
+    const teachingScope = buildTeachingScope(args);
     const result = await api("/api/series/create", {
         method: "POST",
         json: {
-            fileName: resolve(args.pdfPath).split(/[/\\]/).pop(),
+            fileName: fileNameOf(args.pdfPath),
             pageMin: args.pageMin,
             pageMax: args.pageMax,
             contentHash,
@@ -232,6 +159,7 @@ server.tool("hiliflow_compile_series", {
             teachingScope,
             maxPagesPerJob: args.maxPagesPerJob ?? 10,
             contentLanguage: args.contentLanguage ?? "en",
+            ...(args.characterId ? { characterId: args.characterId } : {}),
             plan: args.plan ?? "free",
             extractDocName: true,
             highlight: true
@@ -242,27 +170,19 @@ server.tool("hiliflow_compile_series", {
         studioUrls: (result.jobs || []).map((j) => ({
             jobId: j.id,
             title: j.title,
-            studioUrl: `${WEB_BASE}/app/projects/${j.id}`
+            studioUrl: `${getWebBase()}/app/projects/${j.id}`
         })),
         note: `${result.totalEpisodes} episode credit(s) charged.`
     });
 });
 server.tool("hiliflow_job_status", {
     jobId: z.string()
-}, async ({ jobId }) => {
-    const job = await api(`/api/jobs/${jobId}`);
-    return textResult({
-        ...job,
-        studioUrl: `${WEB_BASE}/app/projects/${jobId}`
-    });
-});
+}, async ({ jobId }) => textResult(await jobStatus(jobId)));
 server.tool("hiliflow_open_studio", {
     jobId: z.string()
 }, async ({ jobId }) => {
     const data = await api(`/api/mcp/studio/${jobId}`);
     return textResult(data);
 });
-// silence unused schema warning in some bundlers
-void teachingScopeSchema;
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/lib.d.ts

@@ -0,0 +1,70 @@
+export type StoredCredentials = {
+    apiKey?: string;
+    apiBase?: string;
+    webBase?: string;
+    updatedAt?: string;
+};
+export declare function credentialsDir(): string;
+export declare function credentialsPath(): string;
+export declare function readCredentials(): StoredCredentials;
+/** Persist API key for CLI/MCP (env still wins when set). */
+export declare function saveCredentials(input: {
+    apiKey: string;
+    apiBase?: string;
+    webBase?: string;
+}): string;
+/** Ensure Cursor user MCP config points at docwhispr without embedding the key. */
+export declare function ensureCursorMcpConfig(): string;
+export declare function getApiBase(): string;
+export declare function getWebBase(): string;
+/** @deprecated use getApiBase() — kept for call sites that import API_BASE */
+export declare const API_BASE: string;
+/** @deprecated use getWebBase() — kept for call sites that import WEB_BASE */
+export declare const WEB_BASE: string;
+export declare function requireApiKey(): string;
+export declare function api<T>(path: string, init?: RequestInit & {
+    json?: unknown;
+}, client?: string): Promise<T>;
+export declare function fileToBase64(filePath: string): string;
+export declare function sha256HexOfFile(filePath: string): Promise<string>;
+export declare function fileNameOf(filePath: string): string;
+export type TeachingScopeInput = {
+    includeTopics?: string[];
+    backgroundPolicy?: "none" | "necessary_only" | "all_in_section";
+    userPrompt?: string;
+};
+export declare function buildTeachingScope(input: TeachingScopeInput): {
+    include_topics: string[];
+    background_policy: "none" | "necessary_only" | "all_in_section";
+    page_numbering: "auto";
+    user_prompt: string;
+};
+export type PlanArgs = {
+    pdfPath: string;
+    pageMin: number;
+    pageMax: number;
+    includeTopics?: string[];
+    backgroundPolicy?: "none" | "necessary_only" | "all_in_section";
+    userPrompt?: string;
+    maxPagesPerJob?: number;
+    title?: string;
+    client?: string;
+};
+export declare function planCurriculum(args: PlanArgs): Promise<unknown>;
+export type CompileArgs = PlanArgs & {
+    contentLanguage?: string;
+    characterId?: string;
+    plan?: "free" | "pro" | "pro_plus";
+};
+export declare function compileEpisode(args: CompileArgs): Promise<{
+    job: Record<string, unknown>;
+    studioUrl: string | null;
+}>;
+export declare function jobStatus(jobId: string, client?: string): Promise<Record<string, unknown> & {
+    studioUrl: string;
+}>;
+export declare function parsePages(raw: string): {
+    pageMin: number;
+    pageMax: number;
+};
+export declare function parseTopics(raw: string | undefined): string[] | undefined;

package/dist/lib.js

@@ -0,0 +1,237 @@
+/**
+ * Shared HiliFlow / docwhispr API helpers for MCP tools and CLI.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function credentialsDir() {
+    return join(homedir(), ".docwhispr");
+}
+export function credentialsPath() {
+    return join(credentialsDir(), "credentials.json");
+}
+export function readCredentials() {
+    try {
+        const raw = readFileSync(credentialsPath(), "utf8");
+        const data = JSON.parse(raw);
+        return data && typeof data === "object" ? data : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Persist API key for CLI/MCP (env still wins when set). */
+export function saveCredentials(input) {
+    const key = input.apiKey.trim();
+    if (!key.startsWith("hl_live_")) {
+        throw new Error('API key must start with "hl_live_"');
+    }
+    const prev = readCredentials();
+    const dir = credentialsDir();
+    mkdirSync(dir, { recursive: true });
+    const path = credentialsPath();
+    const payload = {
+        apiKey: key,
+        apiBase: (input.apiBase ||
+            prev.apiBase ||
+            "https://docwhispr.fly.dev").replace(/\/$/, ""),
+        webBase: (input.webBase ||
+            prev.webBase ||
+            "https://docwhispr.com").replace(/\/$/, ""),
+        updatedAt: new Date().toISOString()
+    };
+    writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600
+    });
+    return path;
+}
+/** Ensure Cursor user MCP config points at docwhispr without embedding the key. */
+export function ensureCursorMcpConfig() {
+    const cursorDir = join(homedir(), ".cursor");
+    mkdirSync(cursorDir, { recursive: true });
+    const path = join(cursorDir, "mcp.json");
+    let root = { mcpServers: {} };
+    if (existsSync(path)) {
+        try {
+            root = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            root = { mcpServers: {} };
+        }
+    }
+    if (!root.mcpServers || typeof root.mcpServers !== "object") {
+        root.mcpServers = {};
+    }
+    root.mcpServers.docwhispr = {
+        command: "npx",
+        args: ["-y", "@docwhispr/mcp-server"],
+        env: {
+            HILIFLOW_API_BASE: getApiBase(),
+            HILIFLOW_WEB_BASE: getWebBase()
+        }
+    };
+    writeFileSync(path, `${JSON.stringify(root, null, 2)}\n`, "utf8");
+    return path;
+}
+export function getApiBase() {
+    return (process.env.HILIFLOW_API_BASE ||
+        process.env.DOCWHISPR_API_BASE ||
+        process.env.NEXT_PUBLIC_VIDEO_WORKER_BASE_URL ||
+        readCredentials().apiBase ||
+        "https://docwhispr.fly.dev").replace(/\/$/, "");
+}
+export function getWebBase() {
+    return (process.env.HILIFLOW_WEB_BASE ||
+        process.env.DOCWHISPR_WEB_BASE ||
+        process.env.NEXT_PUBLIC_APP_URL ||
+        readCredentials().webBase ||
+        "https://docwhispr.com").replace(/\/$/, "");
+}
+/** @deprecated use getApiBase() — kept for call sites that import API_BASE */
+export const API_BASE = getApiBase();
+/** @deprecated use getWebBase() — kept for call sites that import WEB_BASE */
+export const WEB_BASE = getWebBase();
+export function requireApiKey() {
+    const fromEnv = (process.env.HILIFLOW_API_KEY ||
+        process.env.DOCWHISPR_API_KEY ||
+        "").trim();
+    if (fromEnv)
+        return fromEnv;
+    const fromFile = (readCredentials().apiKey || "").trim();
+    if (fromFile)
+        return fromFile;
+    throw new Error(`No API key found. Run: npx @docwhispr/mcp-server configure --key hl_live_…\n` +
+        `Or set HILIFLOW_API_KEY / write ${credentialsPath()}`);
+}
+export async function api(path, init = {}, client = "mcp") {
+    const key = requireApiKey();
+    const headers = {
+        Authorization: `Bearer ${key}`,
+        "X-HiliFlow-Client": client,
+        Accept: "application/json",
+        ...init.headers
+    };
+    let body = init.body;
+    if (init.json !== undefined) {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify(init.json);
+    }
+    const res = await fetch(`${getApiBase()}${path}`, { ...init, headers, body });
+    const text = await res.text();
+    let data = null;
+    try {
+        data = text ? JSON.parse(text) : null;
+    }
+    catch {
+        data = { raw: text };
+    }
+    if (!res.ok) {
+        const detail = typeof data === "object" && data && "detail" in data
+            ? String(data.detail)
+            : text || res.statusText;
+        const err = new Error(`HiliFlow API ${res.status}: ${detail}`);
+        err.status = res.status;
+        throw err;
+    }
+    return data;
+}
+export function fileToBase64(filePath) {
+    return readFileSync(resolve(filePath)).toString("base64");
+}
+export async function sha256HexOfFile(filePath) {
+    const buf = readFileSync(resolve(filePath));
+    return createHash("sha256").update(buf).digest("hex");
+}
+export function fileNameOf(filePath) {
+    return resolve(filePath).split(/[/\\]/).pop() || "document.pdf";
+}
+export function buildTeachingScope(input) {
+    const topics = input.includeTopics ?? [];
+    return {
+        include_topics: topics,
+        background_policy: input.backgroundPolicy ?? "necessary_only",
+        page_numbering: "auto",
+        user_prompt: input.userPrompt ||
+            (topics.length ? `Focus on: ${topics.join(", ")}` : "")
+    };
+}
+export async function planCurriculum(args) {
+    const contentHash = await sha256HexOfFile(args.pdfPath);
+    const contentBase64 = fileToBase64(args.pdfPath);
+    const teachingScope = buildTeachingScope(args);
+    return api("/api/series/plan", {
+        method: "POST",
+        json: {
+            fileName: fileNameOf(args.pdfPath),
+            pageMin: args.pageMin,
+            pageMax: args.pageMax,
+            contentHash,
+            contentBase64,
+            sourceType: "pdf",
+            title: args.title,
+            teachingScope,
+            maxPagesPerJob: args.maxPagesPerJob ?? 10,
+            extractDocName: true
+        }
+    }, args.client ?? "mcp");
+}
+export async function compileEpisode(args) {
+    const contentHash = await sha256HexOfFile(args.pdfPath);
+    const contentBase64 = fileToBase64(args.pdfPath);
+    const teachingScope = buildTeachingScope(args);
+    const job = await api("/api/jobs", {
+        method: "POST",
+        json: {
+            fileName: fileNameOf(args.pdfPath),
+            pageMin: args.pageMin,
+            pageMax: args.pageMax,
+            contentHash,
+            contentBase64,
+            sourceType: "pdf",
+            title: args.title,
+            teachingScope,
+            contentLanguage: args.contentLanguage ?? "en",
+            ...(args.characterId ? { characterId: args.characterId } : {}),
+            plan: args.plan ?? "free",
+            extractDocName: true,
+            highlight: true
+        }
+    }, args.client ?? "mcp");
+    const jobId = String(job.id || "");
+    return {
+        job,
+        studioUrl: jobId ? `${getWebBase()}/app/projects/${jobId}` : null
+    };
+}
+export async function jobStatus(jobId, client = "mcp") {
+    const job = await api(`/api/jobs/${jobId}`, {}, client);
+    return {
+        ...job,
+        studioUrl: `${getWebBase()}/app/projects/${jobId}`
+    };
+}
+export function parsePages(raw) {
+    const m = String(raw || "")
+        .trim()
+        .match(/^(\d+)\s*[-–—:]\s*(\d+)$/);
+    if (!m) {
+        throw new Error(`Invalid --pages value "${raw}". Use e.g. 602-604`);
+    }
+    const pageMin = Number(m[1]);
+    const pageMax = Number(m[2]);
+    if (!(pageMin >= 1 && pageMax >= pageMin)) {
+        throw new Error(`Invalid page range ${pageMin}-${pageMax}`);
+    }
+    return { pageMin, pageMax };
+}
+export function parseTopics(raw) {
+    if (!raw?.trim())
+        return undefined;
+    const parts = raw
+        .split(/[,;，；\n]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return parts.length ? parts : undefined;
+}

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@docwhispr/mcp-server",
-  "version": "0.1.0",
-  "description": "docwhispr MCP server — plan curriculum, compile whiteboard lesson videos, open interactive studio",
+  "version": "0.1.3",
+  "description": "docwhispr MCP server + CLI — plan curriculum, compile whiteboard lesson videos, open interactive studio",
   "type": "module",
   "bin": {
+    "mcp-server": "dist/index.js",
+    "docwhispr": "dist/index.js",
     "docwhispr-mcp": "dist/index.js",
     "hiliflow-mcp": "dist/index.js"
   },