@imgcli/mcp 0.0.0-stage → 0.1.1

package/dist/access.js

@@ -0,0 +1,60 @@
+import { PUBLIC_ORIGIN } from "./catalog-schema.js";
+const ACCESS_TTL_MS = 15 * 60_000;
+export class McpToolError extends Error {
+}
+export function serviceOrigin(value = process.env.IMGCLI_MCP_ORIGIN) {
+    if (!value || value === PUBLIC_ORIGIN)
+        return PUBLIC_ORIGIN;
+    const local = /^http:\/\/(?:127\.0\.0\.1|\[::1\]):\d{1,5}$/;
+    if (!local.test(value))
+        throw new Error("IMGCLI_MCP_ORIGIN must be the Imgcli site or a local test server.");
+    return new URL(value).origin;
+}
+export function createAccessCheck(origin, key) {
+    let expiresAt = 0;
+    let pending;
+    async function verify() {
+        if (!key || key === "YOUR_KEY") {
+            throw new McpToolError("Set IMGCLI_MCP_API_KEY to an MCP key from https://imgcli.com/account.");
+        }
+        let response;
+        try {
+            response = await fetch(new URL("/api/mcp/access", origin), {
+                headers: { Authorization: `Bearer ${key}` },
+                signal: AbortSignal.timeout(5000),
+                redirect: "error",
+            });
+        }
+        catch {
+            throw new McpToolError("Could not reach Imgcli to verify your key. Check your connection and retry.");
+        }
+        const result = await response.json().catch(() => null);
+        if (response.status === 401) {
+            throw new McpToolError("This key is invalid or revoked. Create an MCP key at https://imgcli.com/account.");
+        }
+        if (response.status === 403) {
+            throw new McpToolError("Use an MCP key. Create one under API keys at https://imgcli.com/account.");
+        }
+        if (response.status === 429) {
+            throw new McpToolError("Imgcli is rate limiting key checks. Wait a minute and retry.");
+        }
+        if (!response.ok ||
+            !result ||
+            typeof result !== "object" ||
+            !("status" in result) ||
+            result.status !== "allowed" ||
+            !("scope" in result) ||
+            result.scope !== "mcp") {
+            throw new McpToolError("Imgcli could not verify your key. Try again shortly.");
+        }
+        expiresAt = Date.now() + ACCESS_TTL_MS;
+    }
+    return async () => {
+        if (Date.now() < expiresAt)
+            return;
+        pending ??= verify().finally(() => {
+            pending = undefined;
+        });
+        await pending;
+    };
+}

package/dist/catalog-schema.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const CATALOG_SCHEMA_VERSION = 1;
+export const PUBLIC_ORIGIN = "https://imgcli.com";
+const slug = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+const count = z.number().int().positive();
+const sourceHash = z.string().regex(/^[a-f0-9]{12}$/);
+const target = z
+    .string()
+    .regex(/^(?:components\/imgcli|lib)\/[a-zA-Z0-9_/-]+\.(?:ts|tsx)$/);
+const measurement = z.object({
+    sourceHash,
+    width: count,
+    height: count,
+    fps: count,
+    durationInFrames: count,
+    settle: z.object({
+        base: z.number(),
+        baseWords: z.number(),
+        perWord: z.number(),
+    }),
+    copy: z
+        .object({
+        prop: z.string(),
+        pxPerChar: z.number().positive(),
+        maxChars: count,
+    })
+        .optional(),
+});
+const prop = z.object({
+    name: z.string(),
+    type: z.string(),
+    required: z.boolean(),
+    defaultExpression: z.string().optional(),
+});
+export const componentSchema = z.object({
+    slug,
+    title: z.string(),
+    description: z.string(),
+    category: slug,
+    tier: z.literal("free"),
+    aliases: z.array(slug),
+    docsPath: z.string().regex(/^\/docs(?:\/[a-z0-9-]+)*$/),
+    notes: z.string().optional(),
+    exportName: z.string().regex(/^[A-Z][a-zA-Z0-9]*$/),
+    target,
+    importPath: z.string().regex(/^@\/components\/imgcli\/[a-z0-9-]+$/),
+    files: z.array(target).nonempty(),
+    dependencies: z.array(z.string()),
+    registryDependencies: z.array(z.string()),
+    props: z.array(prop).nonempty(),
+    preview: z
+        .object({
+        width: count,
+        height: count,
+        fps: count,
+        durationInFrames: count,
+        controls: z.record(z.string(), z.object({
+            type: z.string(),
+            label: z.string(),
+            default: z.union([z.string(), z.number(), z.boolean()]),
+            min: z.number().optional(),
+            max: z.number().optional(),
+            step: z.number().optional(),
+            options: z.array(z.string()).optional(),
+        })),
+        example: z.string().optional(),
+    })
+        .optional(),
+    sourceHash,
+    installHash: z.string().regex(/^[a-f0-9]{16}$/),
+    measurement: measurement.optional(),
+});
+export const catalogSchema = z
+    .object({
+    schemaVersion: z.literal(CATALOG_SCHEMA_VERSION),
+    revision: z.string().regex(/^[a-f0-9]{16}$/),
+    components: z.array(componentSchema).nonempty(),
+})
+    .superRefine(({ components }, ctx) => {
+    const names = new Set();
+    for (const component of components) {
+        for (const name of [component.slug, ...component.aliases]) {
+            if (names.has(name))
+                ctx.addIssue({ code: "custom", message: `Duplicate name: ${name}` });
+            names.add(name);
+        }
+        if (!component.files.includes(component.target)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Missing entry file: ${component.slug}`,
+            });
+        }
+        if (component.measurement &&
+            component.measurement.sourceHash !== component.sourceHash) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Stale measurement: ${component.slug}`,
+            });
+        }
+    }
+});
+export function catalogRevision(components) {
+    return createHash("sha256")
+        .update(JSON.stringify(components))
+        .digest("hex")
+        .slice(0, 16);
+}
+export function parseCatalog(data) {
+    const catalog = catalogSchema.parse(data);
+    if (catalogRevision(catalog.components) !== catalog.revision) {
+        throw new Error("Catalog contents do not match their revision.");
+    }
+    return catalog;
+}

package/dist/catalog.js

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { PUBLIC_ORIGIN, parseCatalog, } from "./catalog-schema.js";
+const REFRESH_MS = 5 * 60_000;
+const RETRY_MS = 30_000;
+const bundled = new URL("../catalog.json", import.meta.url);
+export function createCatalogReader(origin, cacheRoot = path.join(homedir(), ".cache", "imgcli-mcp")) {
+    const cacheDir = path.join(cacheRoot, new URL(origin).host.replace(/[^a-zA-Z0-9.-]/g, "_"));
+    const cache = path.join(cacheDir, "catalog-v1.json");
+    let current;
+    let pending;
+    async function refresh() {
+        try {
+            const response = await fetch(new URL("/api/mcp/catalog", origin), {
+                signal: AbortSignal.timeout(5000),
+                redirect: "error",
+            });
+            if (!response.ok)
+                throw new Error("Directory unavailable");
+            const catalog = parseCatalog(await response.json());
+            const tmp = path.join(cacheDir, `${randomUUID()}.tmp`);
+            try {
+                await mkdir(cacheDir, { recursive: true, mode: 0o700 });
+                await writeFile(tmp, JSON.stringify(catalog), {
+                    flag: "wx",
+                    mode: 0o600,
+                });
+                await rename(tmp, cache);
+            }
+            catch {
+                await rm(tmp, { force: true }).catch(() => { });
+            }
+            return {
+                catalog,
+                from: "live",
+                expiresAt: Date.now() + REFRESH_MS,
+            };
+        }
+        catch {
+            const cached = current?.from !== "bundled" && current?.catalog
+                ? current.catalog
+                : await readFile(cache, "utf8")
+                    .then((s) => parseCatalog(JSON.parse(s)))
+                    .catch(() => null);
+            const catalog = cached ?? parseCatalog(JSON.parse(await readFile(bundled, "utf8")));
+            return {
+                catalog,
+                from: cached ? "cache" : "bundled",
+                expiresAt: Date.now() + RETRY_MS,
+            };
+        }
+    }
+    return async () => {
+        if (current && Date.now() < current.expiresAt)
+            return current;
+        pending ??= refresh().finally(() => {
+            pending = undefined;
+        });
+        current = await pending;
+        return current;
+    };
+}
+const normalize = (value) => value
+    .trim()
+    .toLowerCase()
+    .replace(/^@(?:imgcli|snapcn)\//, "")
+    .replace(/[\s_]+/g, "-");
+export function findComponent(catalog, name) {
+    const slug = normalize(name);
+    return catalog.components.find((item) => item.slug === slug ||
+        normalize(item.title) === slug ||
+        item.aliases.includes(slug));
+}
+export function summarize(item) {
+    return {
+        slug: item.slug,
+        title: item.title,
+        category: item.category,
+        tier: item.tier,
+        description: item.description,
+        fps: item.preview?.fps ?? null,
+        durationInFrames: item.preview?.durationInFrames ?? null,
+        notes: item.notes,
+        docs: new URL(item.docsPath, PUBLIC_ORIGIN).href,
+        install: `npx shadcn@latest add ${PUBLIC_ORIGIN}/r/${item.slug}.json`,
+    };
+}
+const STOP_WORDS = new Set("a an and at by for from i in into is it me my of on or that the to using want with".split(" "));
+const tokens = (text) => new Set(text
+    .toLowerCase()
+    .match(/[\p{L}\p{N}]+/gu)
+    ?.filter((token) => token.length > 1 && !STOP_WORDS.has(token)));
+export function searchComponents(catalog, input) {
+    const { query, category, vibe, tier, max_frames, limit } = input;
+    const candidates = catalog.components.filter((item) => (!category || item.category === normalize(category)) &&
+        (!tier || item.tier === tier) &&
+        (max_frames === undefined ||
+            (item.preview !== undefined &&
+                item.preview.durationInFrames <= max_frames)));
+    const terms = tokens(query);
+    const mood = tokens(vibe ?? "");
+    const matches = candidates
+        .map((item) => {
+        const name = tokens(`${item.slug} ${item.title}`);
+        const description = tokens(item.description);
+        let score = normalize(query) === item.slug ? 20 : 0;
+        for (const term of terms) {
+            if (name.has(term))
+                score += 5;
+            if (description.has(term))
+                score += 2;
+        }
+        for (const term of mood) {
+            if (name.has(term) || description.has(term))
+                score++;
+        }
+        return { item, score };
+    })
+        .filter(({ score }) => (!query.trim() && !mood.size) || score > 0)
+        .sort((a, b) => b.score - a.score || a.item.slug.localeCompare(b.item.slug, "en"));
+    if (matches.length) {
+        return {
+            matches: matches.slice(0, limit).map(({ item }) => summarize(item)),
+            categories: !query.trim()
+                ? [...new Set(candidates.map(({ category }) => category))].sort()
+                : undefined,
+        };
+    }
+    const alternatives = [
+        "text-reveal",
+        "punch-lines",
+        "screen-recording",
+    ].flatMap((slug) => {
+        const item = candidates.find((entry) => entry.slug === slug);
+        return item ? [summarize(item)] : [];
+    });
+    return {
+        matches: [],
+        message: "No free components matched. Try another term or relax the filters.",
+        alternatives,
+    };
+}

package/dist/index.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createAccessCheck, McpToolError, serviceOrigin } from "./access.js";
+import { createCatalogReader, findComponent, searchComponents, summarize, } from "./catalog.js";
+import { PUBLIC_ORIGIN } from "./catalog-schema.js";
+import { RULES } from "./rules.js";
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const text = (value) => ({ type: "text", text: value });
+const success = (value) => ({
+    content: [text(JSON.stringify(value))],
+    structuredContent: value,
+});
+async function main() {
+    const server = new McpServer({ name: "imgcli", version });
+    const origin = serviceOrigin();
+    const checkAccess = createAccessCheck(origin, process.env.IMGCLI_MCP_API_KEY);
+    const readCatalog = createCatalogReader(origin);
+    const verified = async (fn) => {
+        try {
+            await checkAccess();
+            return success(await fn());
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    text(error instanceof McpToolError
+                        ? error.message
+                        : "Imgcli could not load the tool data. Retry the call or reinstall the MCP package."),
+                ],
+            };
+        }
+    };
+    const annotations = { readOnlyHint: true };
+    server.registerTool("imgcli_search_components", {
+        description: "Find free Imgcli Remotion components by scene intent. An empty query lists available categories and components.",
+        annotations,
+        inputSchema: {
+            query: z.string().max(500),
+            category: z.string().max(80).optional(),
+            vibe: z.string().max(160).optional(),
+            tier: z.enum(["free", "pro"]).optional(),
+            max_frames: z.number().int().positive().optional(),
+            limit: z.number().int().min(1).max(12).default(5),
+        },
+    }, (input) => verified(async () => {
+        const { catalog, from } = await readCatalog();
+        return {
+            revision: catalog.revision,
+            source: from,
+            ...searchComponents(catalog, input),
+        };
+    }));
+    server.registerTool("imgcli_component", {
+        description: "Read a component's actual TypeScript props, preview defaults, dependencies, and shadcn installation target.",
+        annotations,
+        inputSchema: { name: z.string().trim().min(1).max(120) },
+    }, ({ name }) => verified(async () => {
+        const { catalog, from } = await readCatalog();
+        const item = findComponent(catalog, name);
+        if (!item)
+            throw new McpToolError("This component is absent from the free catalog. Use imgcli_search_components to find an available component.");
+        return {
+            revision: catalog.revision,
+            source: from,
+            ...summarize(item),
+            aliases: item.aliases,
+            import: `import { ${item.exportName} } from "${item.importPath}";`,
+            target: item.target,
+            files: item.files,
+            dependencies: item.dependencies,
+            registryDependencies: item.registryDependencies,
+            props: item.props,
+            preview: item.preview ?? null,
+            measurement: item.measurement ?? null,
+            sourceCode: `${PUBLIC_ORIGIN}/r/${item.slug}.json`,
+        };
+    }));
+    server.registerTool("imgcli_rules", {
+        description: "Get Imgcli's motion, design, shot structure, and render rules for Remotion scenes.",
+        annotations,
+        inputSchema: {
+            topic: z
+                .enum(["all", "motion", "design", "anatomy", "anti-patterns"])
+                .default("all"),
+        },
+    }, ({ topic }) => verified(async () => ({
+        rules: topic === "all" ? RULES : { [topic]: RULES[topic] },
+    })));
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    console.error(error instanceof Error && error.message.startsWith("IMGCLI_MCP_ORIGIN")
+        ? error.message
+        : "Imgcli MCP could not start.");
+    process.exitCode = 1;
+});

package/dist/rules.js

@@ -0,0 +1,22 @@
+export const RULES = {
+    motion: [
+        "Drive animation with useCurrentFrame() and useVideoConfig() so frames render correctly on their own.",
+        "Reserve enough frames for the motion to settle. Inspect the beginning, the midpoint and the final pose in a real render.",
+        "When scaling type, pivot on its measured baseline. Check the rendered frames for position jumps and avoid will-change on animated text.",
+    ],
+    design: [
+        "Set foreground and background together so text stays readable. Use concrete colors and explicit font families inside the composition.",
+        "Reuse the component's theme props and let users override copy, colors and media. Check the result with their actual text and aspect ratio.",
+        "Use staticFile() for project media in public/. Use a persistent HTTPS URL for remote media you expect a renderer to load.",
+    ],
+    anatomy: [
+        "Start each shot with one job: introduce the subject, show an action, reveal the result, or give the viewer a next step.",
+        "Check the real component props and installation target before writing an import. Keep the composition clock consistent across the shots.",
+        "Budget frames for both holds and motion. Subtract overlap when clips share a transition.",
+    ],
+    "anti-patterns": [
+        "Avoid wall-clock time, randomness and browser-driven keyframes for render timing.",
+        "Avoid website CSS variables in Remotion unless the composition supplies them explicitly.",
+        "Avoid judging a render from the live browser player alone. Inspect rendered frames with the final media and copy.",
+    ],
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@imgcli/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Imgcli's local MCP server for Remotion components",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imgcli/mcp.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "imgcli-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "catalog.json",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:update": "npm run build && node scripts/test-update.mjs",
+    "prepack": "npm run build && node scripts/check-catalog.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^5",
+    "vitest": "^4.1.9"
+  }
+}