@docwhispr/mcp-server 0.0.0-stage → 0.1.3

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @docwhispr/mcp-server
+
+Thin client for **docwhispr** cloud curriculum compiler (HiliFlow).
+
+## One-time setup (paste from Settings)
+
+```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).
+
+## CLI
+
+```bash
+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
+```
+
+| Command | Credits |
+| --- | ---: |
+| `configure` | 0 |
+| `plan` | 0 |
+| `compile` | 1 |
+| `credits` / `status` | 0 |
+
+Auth: `HILIFLOW_API_KEY` env **or** credentials file from `configure`.
+
+`402` = out of credits · `409` = another job already generating.
+
+## MCP stdio
+
+After `configure --cursor-mcp`, or manually:
+
+```json
+{
+  "mcpServers": {
+    "docwhispr": {
+      "command": "npx",
+      "args": ["-y", "@docwhispr/mcp-server"],
+      "env": {
+        "HILIFLOW_API_BASE": "https://docwhispr.fly.dev",
+        "HILIFLOW_WEB_BASE": "https://docwhispr.com"
+      }
+    }
+  }
+}
+```
+
+| 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
+
+| Plan | Episodes / month |
+| --- | ---: |
+| free | 5 |
+| pro | 50 |
+| pro_plus | 100 |

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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * HiliFlow / docwhispr entry:
+ *   - CLI:  npx @docwhispr/mcp-server plan|compile|credits|status …
+ *   - MCP:  npx @docwhispr/mcp-server   (stdio, via Cursor mcp.json)
+ *
+ * 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 { 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 {
+        content: [
+            {
+                type: "text",
+                text: typeof payload === "string" ? payload : JSON.stringify(payload, null, 2)
+            }
+        ]
+    };
+}
+const server = new McpServer({
+    name: "hiliflow",
+    version: "0.1.1"
+});
+server.tool("hiliflow_credits", {
+    plan: z.enum(["free", "pro", "pro_plus"]).optional()
+}, async ({ plan }) => {
+    const q = plan ? `?plan=${encodeURIComponent(plan)}` : "";
+    const data = await api(`/api/mcp/credits${q}`);
+    return textResult(data);
+});
+server.tool("hiliflow_plan_curriculum", {
+    pdfPath: z
+        .string()
+        .describe("Absolute path to a local PDF on the machine running the MCP server"),
+    pageMin: z.number().int().min(1),
+    pageMax: z.number().int().min(1),
+    includeTopics: z
+        .array(z.string())
+        .optional()
+        .describe('e.g. ["EXTEST","INTEST"]'),
+    backgroundPolicy: z
+        .enum(["none", "necessary_only", "all_in_section"])
+        .optional()
+        .default("necessary_only"),
+    pageNumbering: z.enum(["auto", "pdf", "book"]).optional().default("auto"),
+    userPrompt: z.string().optional(),
+    maxPagesPerJob: z.number().int().min(1).max(20).optional().default(10),
+    title: z.string().optional()
+}, async (args) => {
+    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).",
+        plan
+    });
+});
+server.tool("hiliflow_compile_episode", {
+    pdfPath: z.string(),
+    pageMin: z.number().int().min(1),
+    pageMax: z.number().int().min(1),
+    includeTopics: z.array(z.string()).optional(),
+    backgroundPolicy: z
+        .enum(["none", "necessary_only", "all_in_section"])
+        .optional()
+        .default("necessary_only"),
+    pageNumbering: z.enum(["auto", "pdf", "book"]).optional().default("auto"),
+    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) => {
+    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
+    });
+    return textResult({
+        ...result,
+        note: "1 episode credit charged. Poll hiliflow_job_status until status=succeeded."
+    });
+});
+server.tool("hiliflow_compile_series", {
+    pdfPath: z.string(),
+    pageMin: z.number().int().min(1),
+    pageMax: z.number().int().min(1),
+    includeTopics: z.array(z.string()).optional(),
+    backgroundPolicy: z
+        .enum(["none", "necessary_only", "all_in_section"])
+        .optional()
+        .default("necessary_only"),
+    pageNumbering: z.enum(["auto", "pdf", "book"]).optional().default("auto"),
+    userPrompt: z.string().optional(),
+    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 = buildTeachingScope(args);
+    const result = await api("/api/series/create", {
+        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,
+            contentLanguage: args.contentLanguage ?? "en",
+            ...(args.characterId ? { characterId: args.characterId } : {}),
+            plan: args.plan ?? "free",
+            extractDocName: true,
+            highlight: true
+        }
+    });
+    return textResult({
+        ...result,
+        studioUrls: (result.jobs || []).map((j) => ({
+            jobId: j.id,
+            title: j.title,
+            studioUrl: `${getWebBase()}/app/projects/${j.id}`
+        })),
+        note: `${result.totalEpisodes} episode credit(s) charged.`
+    });
+});
+server.tool("hiliflow_job_status", {
+    jobId: z.string()
+}, 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);
+});
+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,6 +1,57 @@
-{
-  "name": "@docwhispr/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@docwhispr/mcp-server",
+  "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"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "docwhispr",
+    "hiliflow",
+    "curriculum",
+    "whiteboard",
+    "pdf"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhenjun-avatar/docwhispr.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://docwhispr.com",
+  "bugs": {
+    "url": "https://github.com/zhenjun-avatar/docwhispr/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}