@overcrow/mcp 0.0.0-stage → 0.1.0

package/dist/tools/setup.js

@@ -0,0 +1,146 @@
+// status and setup: what is ready, and the one tool that downloads.
+import { z } from "zod";
+import { findNpmCli } from "../npm.js";
+import { DESCRIPTIONS } from "../texts.js";
+import { VERSION } from "../version.js";
+import { fail, failure, ok, progress, READ_ONLY, withRoots } from "./common.js";
+const NODE_MINIMUM = [22, 18];
+function nodeOk(version = process.versions.node) {
+    const [major = 0, minor = 0] = version.split(".").map(Number);
+    return (major > NODE_MINIMUM[0] ||
+        (major === NODE_MINIMUM[0] && minor >= NODE_MINIMUM[1]));
+}
+export function registerSetupTools(env) {
+    const { server, session } = env;
+    server.registerTool("status", {
+        title: "Status",
+        description: DESCRIPTIONS.status,
+        inputSchema: z.strictObject({}),
+        outputSchema: z.object({
+            server: z.string(),
+            node: z.object({ version: z.string(), ok: z.boolean() }),
+            npm: z.boolean(),
+            platform: z.object({
+                supported: z.boolean(),
+                name: z.string().nullable(),
+                message: z.string().nullable(),
+            }),
+            release: z.string().nullable(),
+            sdk: z.string(),
+            typescript: z.string(),
+            tools: z.object({
+                installed: z.boolean(),
+                cli: z.string().nullable(),
+                folder: z.string().nullable(),
+            }),
+            projectFolders: z.array(z.string()),
+            projectProblem: z.string().nullable(),
+            next: z.string(),
+        }),
+        annotations: { title: "Status", ...READ_ONLY },
+    }, async (_args, ctx) => {
+        const platform = session.platform;
+        const tools = await session.installedTools().catch(() => undefined);
+        const answer = await session.roots(ctx, server);
+        if ("input" in answer)
+            return answer.input;
+        const confinement = "confinement" in answer ? answer.confinement : undefined;
+        const redactor = session.redactor(confinement);
+        const release = session.options.pin.release;
+        let next;
+        if (!("platform" in platform))
+            next = platform.unsupported;
+        else if (!nodeOk())
+            next = `Node.js ${process.versions.node} is too old: install Node.js 22.18 or later.`;
+        else if (!release)
+            next =
+                "This version of @overcrow/mcp is not tied to a published OverCrow release yet: update it.";
+        else if (!tools)
+            next = "Run setup to install the creator tools.";
+        else if ("error" in answer)
+            next = answer.error;
+        else
+            next = "Ready. Create a widget with create_widget, or check an existing one with check.";
+        return ok({
+            server: `@overcrow/mcp ${VERSION}`,
+            node: { version: process.versions.node, ok: nodeOk() },
+            npm: findNpmCli() !== undefined,
+            platform: {
+                supported: "platform" in platform,
+                name: "platform" in platform ? platform.platform : null,
+                message: "unsupported" in platform ? platform.unsupported : null,
+            },
+            release,
+            sdk: session.options.pin.npm.sdk.version,
+            typescript: session.options.pin.npm.typescript.version,
+            tools: {
+                installed: tools !== undefined,
+                cli: tools ? tools.cliVersion : null,
+                folder: tools ? tools.directory : null,
+            },
+            projectFolders: confinement ? confinement.roots.map((root) => root.path) : [],
+            projectProblem: "error" in answer ? answer.error : null,
+            next,
+        }, next, { redactor });
+    });
+    server.registerTool("setup", {
+        title: "Install the creator tools",
+        description: DESCRIPTIONS.setup,
+        inputSchema: z.strictObject({
+            zipPath: z
+                .string()
+                .min(1)
+                .max(1024)
+                .optional()
+                .describe("A local copy of the creator tools ZIP, inside the project, for offline use. It must be the exact pinned file."),
+        }),
+        outputSchema: z.object({
+            release: z.string(),
+            platform: z.string(),
+            cli: z.string(),
+            folder: z.string(),
+            source: z.enum(["cache", "local", "download"]),
+            seconds: z.number(),
+        }),
+        annotations: {
+            title: "Install the creator tools",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ zipPath }, ctx) => {
+        const started = Date.now();
+        const report = progress(ctx);
+        const run = async (localZip, redactor = session.redactor()) => {
+            try {
+                const { tools, source } = await session.setup(localZip, report
+                    ? (done, total) => report(done, total, "Downloading the creator tools")
+                    : undefined, ctx.mcpReq.signal);
+                const summary = source === "cache"
+                    ? `The creator tools of OverCrow ${tools.release} are already installed and intact.`
+                    : `Installed the creator tools of OverCrow ${tools.release} (CLI ${tools.cliVersion}) after checking every file.`;
+                return ok({
+                    release: tools.release,
+                    platform: tools.platform,
+                    cli: tools.cliVersion,
+                    folder: tools.directory,
+                    source,
+                    seconds: Math.round((Date.now() - started) / 100) / 10,
+                }, summary, { redactor });
+            }
+            catch (error) {
+                return failure(error, redactor);
+            }
+        };
+        if (zipPath === undefined)
+            return run(undefined);
+        // A local ZIP is read only inside the project folders.
+        return withRoots(env, ctx, async (confinement, redactor) => {
+            if (!zipPath.toLowerCase().endsWith(".zip"))
+                return fail("zipPath must name a .zip file.");
+            const file = await confinement.resolve(zipPath, "file");
+            return run(file, redactor);
+        });
+    });
+}

package/dist/tools/submission.js

@@ -0,0 +1,369 @@
+// prepare_submission: everything the OverCrow creator space asks for, checked
+// on the project; the ZIP of the sources written to dist/ once nothing
+// fails; and the texts the creator space asks for, listed for the assistant
+// to draft with the user. Nothing is sent: the user sends the ZIP and the
+// texts in the creator space.
+import { join } from "node:path";
+import { z } from "zod";
+import { auditWidget } from "../audit/index.js";
+import { readWidget } from "../audit/project.js";
+import { Cli } from "../cli.js";
+import { limit } from "../content.js";
+import { sourcesFingerprint } from "../fingerprint.js";
+import { ID_FORMS, idProblem, isPlaceholderId, WIDGET_ID } from "../ids.js";
+import { selectSources, writeSourcesZip } from "../sources.js";
+import { cleanLine } from "../text.js";
+import { DESCRIPTIONS } from "../texts.js";
+import { ok, widgetDirectory, withRoots } from "./common.js";
+const DIRECTORY = z
+    .string()
+    .min(1)
+    .max(1024)
+    .describe("The widget folder (it holds manifest.json), relative to the project folder.");
+const VERSION = /^\d+\.\d+\.\d+$/;
+const MAX_LISTED_INCLUDED = 200;
+const MAX_LISTED_EXCLUDED = 100;
+export const SEND = "The user sends the ZIP and these texts in the OverCrow creator space on overcrow.playervox.com.";
+const KIB = 1024;
+const kib = (bytes) => `${Math.max(1, Math.round(bytes / KIB))} KiB`;
+const size = (bytes) => bytes >= KIB * KIB && bytes % (KIB * KIB) === 0
+    ? `${bytes / (KIB * KIB)} MiB`
+    : bytes >= KIB
+        ? `${Math.ceil(bytes / KIB)} KiB`
+        : `${bytes} bytes`;
+export function registerSubmissionTool(env) {
+    const { server, session } = env;
+    server.registerTool("prepare_submission", {
+        title: "Prepare the submission",
+        description: DESCRIPTIONS.prepare_submission,
+        inputSchema: z.strictObject({ directory: DIRECTORY }),
+        outputSchema: z.object({
+            directory: z.string(),
+            id: z.string().nullable(),
+            version: z.string().nullable(),
+            ready: z.boolean(),
+            checklist: z.array(z.object({
+                item: z.string(),
+                status: z.enum(["pass", "fail", "todo"]),
+                detail: z.string(),
+            })),
+            sources: z.object({
+                zip: z.string().nullable(),
+                bytes: z.number().nullable(),
+                sha256: z.string().nullable(),
+                files: z.number(),
+                included: z.array(z.object({ path: z.string(), bytes: z.number() })),
+                excluded: z.array(z.object({ path: z.string(), reason: z.string() })),
+                omitted: z.number(),
+            }),
+            texts: z.array(z.object({
+                kind: z.enum(["permission", "privacy-policy", "release-notes", "description"]),
+                subject: z.string(),
+                current: z.string().nullable(),
+                ask: z.string(),
+            })),
+            next: z.string(),
+            notes: z.array(z.string()),
+        }),
+        annotations: {
+            title: "Prepare the submission",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ directory }, ctx) => withRoots(env, ctx, async (confinement, redactor) => {
+        const target = await widgetDirectory(confinement, directory);
+        const tools = await session.installedTools();
+        const project = await readWidget(target);
+        const audit = await auditWidget(target);
+        const manifest = project.manifest ?? {};
+        const listing = project.listing;
+        const files = new Map(project.files.map((file) => [file.path, file]));
+        const checklist = [];
+        // 1. The ID.
+        const id = audit.id ?? "";
+        const idIssue = idProblem(id) ??
+            (isPlaceholderId(id) ? `The ID ${id} is a placeholder: use ${ID_FORMS}.` : undefined);
+        checklist.push({
+            item: "Widget ID",
+            status: idIssue ? "fail" : "pass",
+            detail: idIssue ?? `${id}: final. Keep it for every version; it can never be reused.`,
+        });
+        // 2. check and the static admission, with the creator tools.
+        let review = [];
+        if (tools) {
+            const cli = new Cli(tools);
+            const check = await cli.check(target, ctx.mcpReq.signal);
+            const errors = check.diagnostics.filter((d) => d.severity === "error").length;
+            const warnings = check.diagnostics.length - errors;
+            checklist.push({
+                item: "check: no error, no warning",
+                status: errors + warnings === 0 ? "pass" : "fail",
+                detail: errors + warnings === 0
+                    ? "Clean."
+                    : `${errors} error(s), ${warnings} warning(s): the creator space refuses warnings too.`,
+            });
+            const report = await cli.admit(target, ctx.mcpReq.signal);
+            const diagnostics = Array.isArray(report.diagnostics)
+                ? report.diagnostics
+                : [];
+            // The listing is filled in the creator space: listing.json is optional.
+            const noListing = diagnostics.some((d) => d.code === "admission.listing_missing");
+            const others = diagnostics.filter((d) => d.code !== "admission.listing_missing");
+            const admitted = (report.admitted === true || noListing) && others.length === 0;
+            review = Array.isArray(report.review) ? report.review : [];
+            checklist.push({
+                item: "Static admission (overcrow-widget admit)",
+                status: admitted ? "pass" : "fail",
+                detail: admitted
+                    ? noListing
+                        ? "Admitted. There is no listing.json: the listing is filled in the creator space, which can also import a listing.json placed next to manifest.json."
+                        : "Admitted, with its listing.json."
+                    : others
+                        .slice(0, 8)
+                        .map((d) => `${cleanLine(String(d.code ?? ""), 48)}: ${cleanLine(String(d.message ?? ""), 200)}`)
+                        .join("; ") || "Refused.",
+            });
+        }
+        else {
+            checklist.push({
+                item: "check and static admission",
+                status: "fail",
+                detail: "Run setup first: they need the creator tools.",
+            });
+        }
+        // 3. The tests, the audit, the preview, the texts and the licence.
+        const lastTest = session.lastTests.get(target);
+        const unchanged = lastTest !== undefined && lastTest.fingerprint === (await sourcesFingerprint(target));
+        const passedRun = unchanged && lastTest.complete && lastTest.failed === 0 && lastTest.passed > 0
+            ? lastTest
+            : undefined;
+        checklist.push({
+            item: "Tests pass",
+            status: passedRun ? "pass" : "fail",
+            detail: passedRun
+                ? `All ${passedRun.passed} scenarios passed at ${passedRun.at.toISOString().slice(11, 16)} UTC, and no source changed since.`
+                : lastTest && !unchanged
+                    ? "The sources changed since the last test run: run test again."
+                    : "Run test (every scenario, not one): each must pass with its reference images.",
+        });
+        const high = audit.findings.filter((finding) => finding.severity === "high" && finding.rule !== "reserved-id");
+        checklist.push({
+            item: "Audit: no high finding",
+            status: high.length === 0 ? "pass" : "fail",
+            detail: high.length === 0
+                ? `Security ${audit.scores.security}/100, lightness ${audit.scores.lightness}/100.`
+                : high
+                    .map((f) => f.message)
+                    .slice(0, 5)
+                    .join(" "),
+        });
+        checklist.push(previewItem(listing, files));
+        checklist.push(languagesItem(manifest, files));
+        checklist.push({
+            item: "LICENSE",
+            status: files.has("LICENSE") ? "pass" : "fail",
+            detail: files.has("LICENSE")
+                ? "Any licence is accepted, including all rights reserved: choose the same one in the creator space."
+                : "There is no LICENSE file: add the text of your licence (any licence is accepted, including all rights reserved).",
+        });
+        // 4. What the creator space asks when sending: the texts to draft.
+        const permissions = review.length > 0
+            ? review.map(describeReview)
+            : audit.authority.filter((line) => !line.startsWith("Nothing:"));
+        const origins = networkOrigins(manifest);
+        checklist.push({
+            item: "Each permission justified",
+            status: permissions.length === 0 ? "pass" : "todo",
+            detail: permissions.length === 0
+                ? "The widget asks for no permission: nothing to justify."
+                : `${permissions.length} permission(s): the creator space asks why the widget needs each one. Draft one or two sentences for each (texts).`,
+        });
+        checklist.push({
+            item: "Privacy policy",
+            status: origins.length === 0 ? "pass" : "todo",
+            detail: origins.length === 0
+                ? "Not needed: the widget uses no network."
+                : `The widget contacts ${origins.join(", ")}: the creator space asks for the address of a privacy policy.`,
+        });
+        checklist.push({
+            item: "Release notes in English and French",
+            status: "todo",
+            detail: "Shown to players with the update: draft them (texts).",
+        });
+        const texts = textsToWrite(permissions, origins, listing);
+        // 5. The ZIP of the sources, once nothing above fails.
+        const selection = await selectSources(target);
+        const blocked = checklist.some((entry) => entry.status === "fail");
+        let written;
+        let zipProblem = selection.problem;
+        const version = VERSION.test(audit.version ?? "") ? audit.version : "";
+        if (!blocked && !zipProblem && WIDGET_ID.test(id) && version) {
+            const dist = await confinement.resolve(join(target, "dist"), "new-directory");
+            const result = await writeSourcesZip(target, selection.included, dist, `${id}-${version}-sources.zip`).catch((error) => ({
+                problem: `The ZIP could not be written to dist/ (${cleanLine(String(error.code ?? error.message), 80)}).`,
+            }));
+            if ("problem" in result)
+                zipProblem = result.problem;
+            else
+                written = result;
+        }
+        checklist.push({
+            item: "Sources ZIP",
+            status: written ? "pass" : "fail",
+            detail: written
+                ? `${confinement.display(written.path)}: ${selection.included.length} files, ${kib(written.bytes)}. The sources stay private: only PlayerVox reviewers read them, and players get the package built from them.`
+                : (zipProblem ?? "Not written yet: fix the failed items above first."),
+        });
+        const ready = checklist.every((entry) => entry.status !== "fail");
+        const included = selection.included.slice(0, MAX_LISTED_INCLUDED);
+        const excluded = selection.excluded.slice(0, MAX_LISTED_EXCLUDED);
+        const failed = checklist.filter((entry) => entry.status === "fail").length;
+        return ok({
+            directory: confinement.display(target),
+            id: audit.id,
+            version: audit.version,
+            ready,
+            checklist,
+            sources: {
+                zip: written ? confinement.display(written.path) : null,
+                bytes: written?.bytes ?? null,
+                sha256: written?.sha256 ?? null,
+                files: selection.included.length,
+                included,
+                excluded,
+                omitted: selection.included.length -
+                    included.length +
+                    (selection.excluded.length - excluded.length),
+            },
+            texts,
+            next: ready
+                ? `Draft each text of texts with the user, then show them the checklist, the ZIP and the drafts. ${SEND}`
+                : "Fix the failed items with the user, then run prepare_submission again.",
+            notes: [
+                `This tool sends, signs and publishes nothing. ${SEND}`,
+                "For an update, the creator space asks only about the permissions this version adds.",
+            ],
+        }, ready
+            ? `Ready: ${confinement.display(written?.path ?? target)} (${selection.included.length} files). ${texts.length} text(s) to draft with the user.`
+            : `Not ready: ${failed} item(s) to fix.`, { data: true, redactor });
+    }));
+}
+function previewItem(listing, files) {
+    const path = typeof listing?.preview === "string" ? cleanLine(listing.preview, 256) : "assets/preview.png";
+    const file = files.get(path);
+    if (!file) {
+        return {
+            item: "Preview",
+            status: "fail",
+            detail: `There is no ${path}: use_preview copies a reference image of a test scenario there (a 4:3 PNG rendered at 150 %, 256 KiB at most).`,
+        };
+    }
+    if (!file.image)
+        return { item: "Preview", status: "fail", detail: `${path} is not a PNG.` };
+    if (file.bytes > limit("MAX_PREVIEW_BYTES")) {
+        return {
+            item: "Preview",
+            status: "fail",
+            detail: `${path} weighs ${kib(file.bytes)}: a preview may weigh 256 KiB at most.`,
+        };
+    }
+    const { width, height } = file.image;
+    const fourByThree = Math.abs(width * 3 - height * 4) <= Math.max(width, height) * 0.01;
+    return {
+        item: "Preview",
+        status: "pass",
+        detail: `${path}, ${width}×${height}, ${kib(file.bytes)}${fourByThree ? "" : ": not 4:3, so it is shown in a 4:3 box"}. It is also the listing's preview in the creator space.`,
+    };
+}
+function languagesItem(manifest, files) {
+    const name = (manifest.name ?? {});
+    const en = typeof name.en === "string" ? name.en.trim() : "";
+    const fr = typeof name.fr === "string" ? name.fr.trim() : "";
+    const locales = ["en", "fr"].filter((locale) => files.has(`locales/${locale}.json`));
+    const problems = [
+        en && fr ? null : "manifest.json needs a name in English (en) and in French (fr)",
+        locales.length === 1
+            ? `locales/${locales[0] === "en" ? "fr" : "en"}.json is missing: give the interface texts in both languages`
+            : null,
+    ].filter((problem) => problem !== null);
+    return {
+        item: "Texts in English and French",
+        status: problems.length === 0 ? "pass" : "fail",
+        detail: problems.length > 0
+            ? `${problems.join("; ")}.`
+            : `Name "${cleanLine(en, 64)}" / "${cleanLine(fr, 64)}"; ${locales.length === 2 ? "interface texts in locales/en.json and locales/fr.json" : "no locales (the view uses no t())"}. Check that the French is a real translation.`,
+    };
+}
+function networkOrigins(manifest) {
+    const permissions = (manifest.permissions ?? {});
+    const rules = Array.isArray(permissions.network)
+        ? permissions.network
+        : [];
+    const origins = rules
+        .map((rule) => (typeof rule.origin === "string" ? cleanLine(rule.origin, 200) : ""))
+        .filter((origin) => origin !== "");
+    return [...new Set(origins)].slice(0, 16);
+}
+function textsToWrite(permissions, origins, listing) {
+    const texts = permissions.map((permission) => ({
+        kind: "permission",
+        subject: permission,
+        current: null,
+        ask: "Why the widget needs this permission, in one or two plain sentences, for the reviewer.",
+    }));
+    if (origins.length > 0) {
+        texts.push({
+            kind: "privacy-policy",
+            subject: origins.join(", "),
+            current: null,
+            ask: "The address of a privacy policy that says what the widget sends to these servers and why. Ask the user for it, never invent one; if they have none, offer to draft its text for them to publish.",
+        });
+    }
+    for (const [locale, language] of [
+        ["en", "English"],
+        ["fr", "French"],
+    ]) {
+        texts.push({
+            kind: "release-notes",
+            subject: locale,
+            current: null,
+            ask: `What changes for players in this version, in ${language}: short and plain, no marketing.`,
+        });
+    }
+    const localizations = Array.isArray(listing?.localizations)
+        ? listing.localizations
+        : [];
+    for (const [locale, language] of [
+        ["en", "English"],
+        ["fr", "French"],
+    ]) {
+        const found = localizations.find((entry) => entry.locale === locale);
+        texts.push({
+            kind: "description",
+            subject: locale,
+            current: typeof found?.description === "string" ? cleanLine(found.description, 600) : null,
+            ask: `What the widget shows or does, in ${language}, 500 characters at most: the first two lines appear on the catalog card. Say what it contacts if it uses the network.`,
+        });
+    }
+    return texts;
+}
+function describeReview(item) {
+    switch (item.kind) {
+        case "capability":
+            return `Capability ${cleanLine(String(item.name), 64)}${item.sensitive ? " (sensitive)" : ""}${item.account ? `, needs a ${cleanLine(String(item.account), 32)} account` : ""}.`;
+        case "network":
+            return `Network: ${cleanLine(String(item.method), 8)} ${cleanLine(String(item.origin), 200)}${cleanLine(String(item.path), 300)}, responses up to ${size(Number(item.maxResponseBytes))}.`;
+        case "clipboardWrite":
+            return "Clipboard: writes text when the user acts.";
+        case "storage":
+            return item.processLifetime
+                ? "Storage, kept only while OverCrow runs."
+                : "Storage on this computer.";
+        case "gameEvent":
+            return `Game event ${cleanLine(String(item.name), 64)}.`;
+        default:
+            return cleanLine(JSON.stringify(item), 200);
+    }
+}

package/dist/version.js

@@ -0,0 +1,3 @@
+// The package version; scripts/build.mjs refuses a build where it differs
+// from package.json.
+export const VERSION = "0.1.0";