@cinefiller/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 CineFiller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This licence covers the agent skills, the plugin manifest and the MCP stdio
+bridge only. The CineFiller platform, its hosted API and its models are
+proprietary and are not licensed by this file.

package/README.md

@@ -0,0 +1,89 @@
+# @cinefiller/mcp-server
+
+The Cinefiller MCP server for AI agents — the same Cinefiller API, speaking
+your agent's protocol. A Claude Code session can take a one-paragraph brief
+to a reviewed storyboard: director treatments to choose from, review gates a
+human approves, every asset landing on your project's CDN and in your
+project workspace automatically.
+
+This package is a thin stdio bridge: it speaks MCP over stdio locally and
+forwards to the hosted Cinefiller MCP endpoint
+(`https://www.cinefiller.com/mcp`) with your program API key. Same API key,
+same credits, same projects as the REST API.
+
+> **Status: API v1 preview.** The full v1 tool surface — the marketing-video
+> group (project, import, concepts, storyboard, gates, jobs, assets) and the M3
+> production tools (`generate_shot`, `assemble_cut`, `verify_cut`, now wired to
+> the render façade in the backend) — is exposed through this bridge. Schemas
+> are frozen (additive-only); public access to the hosted endpoint ships as the
+> MCP server comes online.
+
+## Install (Claude Code)
+
+```bash
+claude mcp add cinefiller -- npx @cinefiller/mcp-server
+```
+
+Set your key first (or pass it inline with `--env`):
+
+```bash
+export CINEFILLER_API_KEY=cf_live_sk_...
+# or:
+claude mcp add cinefiller --env CINEFILLER_API_KEY=cf_live_sk_... -- npx @cinefiller/mcp-server
+```
+
+Or with a plain `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cinefiller": {
+      "command": "npx",
+      "args": ["@cinefiller/mcp-server"],
+      "env": { "CINEFILLER_API_KEY": "cf_live_sk_..." }
+    }
+  }
+}
+```
+
+Advanced clients that speak streamable HTTP directly can skip the bridge:
+
+```bash
+claude mcp add --transport http cinefiller https://www.cinefiller.com/mcp \
+  --header "Authorization: Bearer cf_live_sk_..."
+```
+
+## Configuration
+
+| Env var | Required | Meaning |
+|---|---|---|
+| `CINEFILLER_API_KEY` | yes | Your program key (`cf_live_sk_…`), minted in the developer dashboard — the same key used for the REST API. |
+| `CINEFILLER_MCP_URL` | no | Endpoint override (default `https://www.cinefiller.com/mcp`). Point at `http://localhost:4050/mcp` for a local backend. |
+| `CINEFILLER_PROJECT_ID` | no | Default project for tools that omit `project_id`; an explicit tool argument always wins. |
+
+## What the tools are
+
+The marketing-video pipeline with human review gates:
+`create_project` / `import_source` → `generate_concepts` →
+(human approves `concept_select`) → `generate_storyboard` →
+(human approves `storyboard_approval`) → M3 production. Plus
+`gate_status` / `gate_wait` / `gate_respond`, `get_job_status`,
+`list_assets`, `export_asset`, `project_status`.
+
+Every tool maps 1:1 to a REST endpoint under
+`www.cinefiller.com/api/public/v1` — same auth, same rate limits, same
+credit meter, same error codes. Full contract:
+`docs/CINEFILLER_MCP_INTERFACE.html` in the main repo.
+
+## Publishing (maintainers)
+
+This package is delivered publish-ready but **not published by CI or
+agents** — publishing is a maintainer step:
+
+```bash
+cd mcp-server-npm
+npm pack                       # inspect the tarball
+npm publish --access public    # requires npm org access to @cinefiller
+```
+
+No build step; the bin script is dependency-free (Node ≥ 18).

package/bin/cinefiller-mcp.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * @cinefiller/mcp-server — stdio ↔ streamable-HTTP bridge.
+ *
+ * Speaks MCP over stdio locally (what `claude mcp add cinefiller -- npx
+ * @cinefiller/mcp-server` launches) and forwards every JSON-RPC message to
+ * the hosted Cinefiller MCP endpoint with the partner's program API key as
+ * the Bearer token — the same cf_live_sk_ key used for the REST API.
+ *
+ * Environment:
+ *   CINEFILLER_API_KEY     required — your program key (cf_live_sk_…)
+ *   CINEFILLER_MCP_URL     optional — defaults to
+ *                          https://www.cinefiller.com/mcp
+ *   CINEFILLER_PROJECT_ID  optional — default project for tools that omit
+ *                          project_id (sent as X-Cinefiller-Project)
+ *
+ * No dependencies: Node >= 18 (global fetch + web streams).
+ */
+
+import { createInterface } from "node:readline";
+import process from "node:process";
+
+/**
+ * An `.mcp.json` `${VAR}` reference whose variable is unset does NOT arrive as
+ * undefined — Claude Code passes the *literal* text `${VAR}` through. A plain
+ * falsy check therefore sees a non-empty string and lets an unconfigured key
+ * reach the server, which answers 401 "Invalid API key" and sends the user
+ * hunting for a bad key rather than a missing one. Treat an unexpanded
+ * placeholder as unset so the guidance below still fires.
+ */
+const isUnset = (v) => !v || /^\$\{[A-Za-z_][A-Za-z0-9_]*(:-.*)?\}$/.test(v);
+const envOr = (name, fallback) =>
+  isUnset(process.env[name]) ? fallback : process.env[name];
+
+const MCP_URL = envOr("CINEFILLER_MCP_URL", "https://www.cinefiller.com/mcp");
+const API_KEY = envOr("CINEFILLER_API_KEY", undefined);
+const PROJECT_ID = envOr("CINEFILLER_PROJECT_ID", undefined);
+
+if (!API_KEY) {
+  process.stderr.write(
+    "[cinefiller-mcp] CINEFILLER_API_KEY is not set.\n" +
+    "Create a key in the Cinefiller developer dashboard, then either:\n" +
+    "  export CINEFILLER_API_KEY=cf_live_sk_...            # plugin / .mcp.json\n" +
+    '  claude mcp add cinefiller --env CINEFILLER_API_KEY=cf_live_sk_... -- npx @cinefiller/mcp-server\n'
+  );
+  process.exit(1);
+}
+
+let sessionId = null;        // mcp-session-id echoed after initialize
+let protocolVersion = null;  // recorded from the initialize result
+
+function writeMessage(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+function errorResponse(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+/** Parse an SSE body, emitting each `data:` JSON payload to stdout. */
+async function pumpSSE(response) {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    // SSE allows \r\n line endings (sse-starlette uses them) — normalize.
+    buffer = buffer.split("\r\n").join("\n");
+    let sep;
+    while ((sep = buffer.indexOf("\n\n")) !== -1) {
+      const rawEvent = buffer.slice(0, sep);
+      buffer = buffer.slice(sep + 2);
+      const dataLines = rawEvent
+        .split("\n")
+        .filter((l) => l.startsWith("data:"))
+        .map((l) => l.slice(5).trimStart());
+      if (!dataLines.length) continue;
+      try {
+        handleServerMessage(JSON.parse(dataLines.join("\n")));
+      } catch (e) {
+        process.stderr.write(`[cinefiller-mcp] bad SSE payload: ${e}\n`);
+      }
+    }
+  }
+}
+
+function handleServerMessage(msg) {
+  // Record the negotiated protocol version from the initialize result so
+  // subsequent HTTP requests carry the MCP-Protocol-Version header.
+  if (msg && msg.result && msg.result.protocolVersion) {
+    protocolVersion = msg.result.protocolVersion;
+  }
+  writeMessage(msg);
+}
+
+async function forward(message) {
+  const headers = {
+    "content-type": "application/json",
+    accept: "application/json, text/event-stream",
+    authorization: `Bearer ${API_KEY}`,
+  };
+  if (sessionId) headers["mcp-session-id"] = sessionId;
+  if (protocolVersion) headers["mcp-protocol-version"] = protocolVersion;
+  if (PROJECT_ID) headers["x-cinefiller-project"] = PROJECT_ID;
+
+  let response;
+  try {
+    response = await fetch(MCP_URL, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(message),
+    });
+  } catch (e) {
+    if (message.id !== undefined) {
+      writeMessage(errorResponse(
+        message.id, -32001, `cinefiller endpoint unreachable: ${e.message}`));
+    } else {
+      process.stderr.write(`[cinefiller-mcp] send failed: ${e.message}\n`);
+    }
+    return;
+  }
+
+  const sid = response.headers.get("mcp-session-id");
+  if (sid) sessionId = sid;
+
+  if (response.status === 202) return; // notification accepted, no body
+
+  const contentType = (response.headers.get("content-type") || "").split(";")[0];
+
+  if (!response.ok && contentType !== "application/json" && contentType !== "text/event-stream") {
+    const text = await response.text();
+    if (message.id !== undefined) {
+      writeMessage(errorResponse(
+        message.id, -32000, `HTTP ${response.status} from ${MCP_URL}: ${text.slice(0, 500)}`));
+    } else {
+      process.stderr.write(`[cinefiller-mcp] HTTP ${response.status}: ${text.slice(0, 500)}\n`);
+    }
+    return;
+  }
+
+  if (contentType === "text/event-stream") {
+    await pumpSSE(response);
+    return;
+  }
+
+  const text = await response.text();
+  if (!text.trim()) return;
+  try {
+    handleServerMessage(JSON.parse(text));
+  } catch (e) {
+    if (message.id !== undefined) {
+      writeMessage(errorResponse(
+        message.id, -32700, `unparseable response from ${MCP_URL}: ${e.message}`));
+    }
+  }
+}
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+const inflight = new Set();
+
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let message;
+  try {
+    message = JSON.parse(trimmed);
+  } catch (e) {
+    process.stderr.write(`[cinefiller-mcp] ignoring unparseable input line\n`);
+    return;
+  }
+  const task = forward(message).finally(() => inflight.delete(task));
+  inflight.add(task);
+});
+
+rl.on("close", async () => {
+  await Promise.allSettled([...inflight]);
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@cinefiller/mcp-server",
+  "version": "0.1.0",
+  "description": "Cinefiller MCP server — a stdio bridge to the hosted Cinefiller API (www.cinefiller.com/mcp). Same API key, same credits, same projects as the REST API.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "cinefiller-mcp-server": "bin/cinefiller-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cinefiller",
+    "video-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cinefiller/cinefiller.git",
+    "directory": "mcp-server-npm"
+  }
+}