@docwhispr/mcp-server 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,75 @@
-# 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 MCP 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
+
+## Setup
+
+1. Sign in at [docwhispr.com](https://docwhispr.com), create an API key:
+
+```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"}'
+```
+
+Save the returned `apiKey` (`hl_live_…`) once.
+
+2. Cursor `mcp.json` (or Claude Desktop MCP config):
+
+```json
+{
+  "mcpServers": {
+    "docwhispr": {
+      "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"
+      }
+    }
+  }
+}
+```
+
+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 |
+
+## Monthly credits (same pool as web Generate)
+
+| Plan | Episodes / month |
+| --- | ---: |
+| free | 5 |
+| pro | 50 |
+| pro_plus | 100 |

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * HiliFlow MCP server (stdio).
+ *
+ * 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
+ */
+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;
+}
+function textResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof payload === "string" ? payload : JSON.stringify(payload, null, 2)
+            }
+        ]
+    };
+}
+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"
+});
+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) => {
+    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
+        }
+    });
+    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"),
+    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
+        }
+    });
+    const jobId = String(job.id || "");
+    return textResult({
+        job,
+        studioUrl: jobId ? `${WEB_BASE}/app/projects/${jobId}` : null,
+        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"),
+    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 result = await api("/api/series/create", {
+        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,
+            contentLanguage: args.contentLanguage ?? "en",
+            plan: args.plan ?? "free",
+            extractDocName: true,
+            highlight: true
+        }
+    });
+    return textResult({
+        ...result,
+        studioUrls: (result.jobs || []).map((j) => ({
+            jobId: j.id,
+            title: j.title,
+            studioUrl: `${WEB_BASE}/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}`
+    });
+});
+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/package.json

@@ -1,6 +1,55 @@
-{
-  "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.0",
+  "description": "docwhispr MCP server — plan curriculum, compile whiteboard lesson videos, open interactive studio",
+  "type": "module",
+  "bin": {
+    "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"
+  }
+}