@gritsenko/cta-mcp 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @gritsenko/cta-mcp
+
+An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) stdio server
+that exposes the headless playable-ad packer to agents and IDEs. It wraps
+[`@gritsenko/cta-pack`](https://www.npmjs.com/package/@gritsenko/cta-pack) — the
+same engine behind the [PlayableTools](https://tools.gritsenko.biz/) `/publish`
+page — so an agent can pack an already-built HTML5 playable into per-network
+builds and get a machine-readable validation report. No browser, no clicks.
+
+## Install & register
+
+Register the stdio server in your MCP client (Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "cta": { "command": "npx", "args": ["-y", "@gritsenko/cta-mcp"] }
+  }
+}
+```
+
+Or install it and point at the binary:
+
+```sh
+npm install -g @gritsenko/cta-mcp
+```
+
+```json
+{ "mcpServers": { "cta": { "command": "cta-mcp" } } }
+```
+
+## Tools
+
+- `list_networks()` → `[{ id, output, maxBytes, notes }]`
+- `pack_playable({ source, networks?, outDir?, options?, validate? })` → `{ builds, report }`
+- `validate_build({ source, networks? })` → `report`
+
+`source` is a filesystem path **or** base64-encoded HTML, so an agent can pack a
+build inline or from disk. `pack_playable` validates by default.
+
+## License
+
+MIT

package/dist/server.d.ts

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

package/dist/server.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// cta-mcp — MCP server exposing the headless playable packer over stdio.
+// Thin wrapper over @gritsenko/cta-pack (the Node adapter). Three tools:
+//   list_networks() · pack_playable({...}) · validate_build({...})
+import { stat } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getNetworks, pack, runPack, validateBuild, bundleFromBase64Html, } from "@gritsenko/cta-pack";
+const optionsSchema = z
+    .object({
+    name: z.string().optional(),
+    suffix: z.string().optional(),
+    storeUrls: z
+        .object({ android: z.string().optional(), ios: z.string().optional() })
+        .optional(),
+    compress: z.enum(["none", "imba"]).optional(),
+    imbaEncoding: z.enum(["base64", "base122"]).optional(),
+})
+    .optional();
+function json(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function fail(error) {
+    return {
+        content: [
+            { type: "text", text: error instanceof Error ? error.message : String(error) },
+        ],
+        isError: true,
+    };
+}
+async function isPath(source) {
+    try {
+        await stat(source);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function looksBase64(value) {
+    const t = value.trim();
+    return t.length >= 8 && t.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(t);
+}
+function looksHtml(value) {
+    return /<\s*(?:!doctype|html|head|body|div|script|canvas|meta|section|main|a\b|img)/i.test(value);
+}
+/**
+ * Resolve `source` (an existing filesystem path OR base64-encoded HTML) with strict
+ * validation, so arbitrary non-base64 strings are rejected instead of silently
+ * decoded into garbage.
+ */
+async function resolveSource(source) {
+    if (await isPath(source)) {
+        return { kind: "path", path: source };
+    }
+    if (looksHtml(source)) {
+        throw new Error("`source` looks like raw HTML; pass it base64-encoded, or a filesystem path.");
+    }
+    if (!looksBase64(source)) {
+        throw new Error("`source` is neither an existing path nor base64-encoded HTML.");
+    }
+    const bundle = bundleFromBase64Html(source);
+    if (!looksHtml(bundle.entryHtml)) {
+        throw new Error("Decoded base64 `source` does not look like HTML.");
+    }
+    return { kind: "bundle", bundle };
+}
+function buildsFromReport(report) {
+    return report.networks.map((n) => ({
+        network: n.id,
+        path: n.path,
+        sizeBytes: n.sizeBytes,
+        format: n.output,
+    }));
+}
+const server = new McpServer({ name: "cta-mcp", version: "0.1.0" });
+server.registerTool("list_networks", {
+    title: "List networks",
+    description: "List the supported ad networks with output type, max size and notes.",
+    inputSchema: {},
+}, async () => {
+    const networks = getNetworks().map((n) => ({
+        id: n.id,
+        output: n.output,
+        maxBytes: n.constraints.maxBytes,
+        notes: n.notes,
+    }));
+    return json(networks);
+});
+server.registerTool("pack_playable", {
+    title: "Pack playable",
+    description: "Pack a playable for one or more ad networks and write the builds. `source` is a path " +
+        "(folder with index.html, or a single .html) OR base64-encoded HTML. Returns builds + report.",
+    inputSchema: {
+        source: z.string().describe("Filesystem path OR base64-encoded HTML."),
+        networks: z.array(z.string()).optional().describe("Network ids/names; omit for all."),
+        outDir: z.string().optional().describe("Output directory (default: ./builds)."),
+        validate: z.boolean().optional().describe("Run validation (default: true)."),
+        options: optionsSchema,
+    },
+}, async ({ source, networks, outDir, validate, options }) => {
+    try {
+        const out = outDir ?? "builds";
+        const doValidate = validate ?? true;
+        const opts = (options ?? {});
+        const resolved = await resolveSource(source);
+        const report = resolved.kind === "path"
+            ? await pack({ source: resolved.path, networks, out, validate: doValidate, options: opts })
+            : await runPack(resolved.bundle, {
+                networks,
+                out,
+                validate: doValidate,
+                options: { name: "Playable", ...opts },
+            });
+        return json({ builds: buildsFromReport(report), report });
+    }
+    catch (error) {
+        return fail(error);
+    }
+});
+server.registerTool("validate_build", {
+    title: "Validate build",
+    description: "Validate a playable for one or more networks WITHOUT writing builds. `source` is a path " +
+        "or base64-encoded HTML. Returns the report.",
+    inputSchema: {
+        source: z.string().describe("Filesystem path OR base64-encoded HTML."),
+        networks: z.array(z.string()).optional().describe("Network ids/names; omit for all."),
+        options: optionsSchema,
+    },
+}, async ({ source, networks, options }) => {
+    try {
+        const opts = (options ?? {});
+        const resolved = await resolveSource(source);
+        const report = resolved.kind === "path"
+            ? await validateBuild({ source: resolved.path, networks, options: opts })
+            : await runPack(resolved.bundle, {
+                networks,
+                validate: true,
+                options: { name: "Playable", ...opts },
+            });
+        return json(report);
+    }
+    catch (error) {
+        return fail(error);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logs; stdout is the MCP channel.
+    console.error("cta-mcp ready (stdio): list_networks, pack_playable, validate_build");
+}
+main().catch((error) => {
+    console.error(`cta-mcp fatal: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@gritsenko/cta-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing the headless playable packer (list_networks / pack_playable / validate_build).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/server.js",
+  "bin": {
+    "cta-mcp": "./dist/server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@gritsenko/cta-pack": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.13",
+    "typescript": "~5.8.3"
+  }
+}