@overcrow/mcp 0.0.0 → 0.1.1

package/dist/tools/docs.js

@@ -0,0 +1,196 @@
+// explain_permission, explain_error, search_docs, read_doc and read_example:
+// answers from the documentation and examples shipped in the package.
+import { z } from "zod";
+import { docPages, projectFile, projects } from "../content.js";
+import { explainError, explainPermission, permissionNames, readDoc, searchDocs, similarCodes, } from "../knowledge.js";
+import { bound } from "../text.js";
+import { DESCRIPTIONS } from "../texts.js";
+import { fail, MAX_RESULT_CHARS, ok, READ_ONLY } from "./common.js";
+const LOCALE = z
+    .enum(["en", "fr"])
+    .default("en")
+    .describe("Language of the documentation: en or fr.");
+export function registerDocTools(env) {
+    const { server } = env;
+    server.registerTool("explain_permission", {
+        title: "Explain a permission",
+        description: DESCRIPTIONS.explain_permission,
+        inputSchema: z.strictObject({
+            name: z
+                .string()
+                .min(1)
+                .max(64)
+                .describe("network, storage, clipboardWrite, gameEvents, or a capability such as media.read."),
+            locale: LOCALE,
+        }),
+        outputSchema: z.object({
+            name: z.string(),
+            kind: z.enum(["permission", "capability"]),
+            meaning: z.string(),
+            withSensitiveCapability: z.string().nullable(),
+            services: z.array(z.object({ service: z.string(), when: z.string() })),
+            sensitive: z.boolean().nullable(),
+            account: z.string().nullable(),
+            advice: z.string(),
+            docs: z.string(),
+        }),
+        annotations: { title: "Explain a permission", ...READ_ONLY },
+    }, async ({ name, locale }) => {
+        const info = explainPermission(name, locale);
+        if (!info)
+            return fail(`Unknown permission or capability: ${name.slice(0, 64)}. Known: ${permissionNames().join(", ")}.`);
+        return ok({ ...info }, `${info.name}: ${info.meaning}`);
+    });
+    server.registerTool("explain_error", {
+        title: "Explain an error code",
+        description: DESCRIPTIONS.explain_error,
+        inputSchema: z.strictObject({
+            code: z
+                .string()
+                .regex(/^[a-z_]+(\.[a-z_]+)?$/)
+                .max(64)
+                .describe("A diagnostic code (view.unknown_attribute) or a service error code (permission_denied)."),
+            locale: LOCALE,
+        }),
+        outputSchema: z.object({
+            code: z.string(),
+            kind: z.enum(["diagnostic", "service", "domain"]),
+            meaning: z.string(),
+            page: z.string(),
+            url: z.string(),
+        }),
+        annotations: { title: "Explain an error code", ...READ_ONLY },
+    }, async ({ code, locale }) => {
+        const info = explainError(code, locale);
+        if (!info) {
+            const similar = similarCodes(code);
+            return fail(`Unknown code ${code}.${similar.length ? ` Close codes: ${similar.join(", ")}.` : " Use search_docs."}`);
+        }
+        return ok({ ...info }, `${info.code}: ${info.meaning}`);
+    });
+    server.registerTool("search_docs", {
+        title: "Search the documentation",
+        description: DESCRIPTIONS.search_docs,
+        inputSchema: z.strictObject({
+            query: z.string().min(1).max(200),
+            locale: LOCALE,
+            limit: z.number().int().min(1).max(10).default(5),
+        }),
+        outputSchema: z.object({
+            results: z.array(z.object({
+                slug: z.string(),
+                page: z.string(),
+                section: z.string(),
+                url: z.string(),
+                resource: z.string(),
+                snippet: z.string(),
+                score: z.number(),
+            })),
+        }),
+        annotations: { title: "Search the documentation", ...READ_ONLY },
+    }, async ({ query, locale, limit }) => {
+        const results = searchDocs(query, locale, limit);
+        return ok({ results }, results.length === 0
+            ? "No match: try other words, or read_doc with a page slug."
+            : `${results.length} section(s) found; read one with read_doc.`);
+    });
+    server.registerTool("read_doc", {
+        title: "Read the documentation",
+        description: DESCRIPTIONS.read_doc,
+        inputSchema: z.strictObject({
+            slug: z
+                .string()
+                .max(64)
+                .describe('Page slug, such as "guide", "manifest", "services", "limits"; "index" for the overview.'),
+            section: z
+                .string()
+                .max(200)
+                .optional()
+                .describe("A heading of the page, to read only that section."),
+            locale: LOCALE,
+        }),
+        outputSchema: z.object({
+            slug: z.string(),
+            title: z.string(),
+            url: z.string(),
+            headings: z.array(z.string()),
+            markdown: z.string().nullable(),
+            pages: z.array(z.object({ slug: z.string(), title: z.string(), group: z.string() })),
+        }),
+        annotations: { title: "Read the documentation", ...READ_ONLY },
+    }, async ({ slug, section, locale }) => {
+        const pageSlug = slug === "index" ? "" : slug;
+        const pages = docPages().map((page) => ({
+            slug: page.slug || "index",
+            title: page.titles[locale] ?? page.slug,
+            group: page.group,
+        }));
+        const doc = readDoc(pageSlug, locale, section);
+        if (!doc)
+            return fail(`No page ${slug.slice(0, 64)}. Pages: ${pages.map((page) => page.slug).join(", ")}.`);
+        const markdown = doc.markdown === null ? null : bound(doc.markdown, MAX_RESULT_CHARS - 4000);
+        return ok({ slug, title: doc.title, url: doc.url, headings: doc.headings, markdown, pages }, doc.markdown === null
+            ? `No section "${section}" in ${doc.title}: see headings.`
+            : `${doc.title} (${doc.url})`);
+    });
+    server.registerTool("read_example", {
+        title: "Read an example",
+        description: DESCRIPTIONS.read_example,
+        inputSchema: z.strictObject({
+            name: z
+                .string()
+                .max(64)
+                .optional()
+                .describe("A reference widget (warframe-market, clock…), a template (counter…) or a documentation example (weather, countdown)."),
+            file: z
+                .string()
+                .max(256)
+                .optional()
+                .describe("A file of that project, such as logic.ts or manifest.json."),
+        }),
+        outputSchema: z.object({
+            projects: z.array(z.object({
+                name: z.string(),
+                kind: z.string(),
+                title: z.string().nullable(),
+                id: z.string().nullable(),
+            })),
+            files: z.array(z.string()),
+            file: z.string().nullable(),
+            text: z.string().nullable(),
+            resource: z.string().nullable(),
+        }),
+        annotations: { title: "Read an example", ...READ_ONLY },
+    }, async ({ name, file }) => {
+        const all = projects().filter((project) => project.name !== "shared");
+        const list = all.map((project) => ({
+            name: project.name,
+            kind: project.kind === "templates"
+                ? "template"
+                : project.source === "docs"
+                    ? "documentation example"
+                    : "reference widget",
+            title: project.title ?? null,
+            id: project.id ?? null,
+        }));
+        if (!name) {
+            return ok({ projects: list, files: [], file: null, text: null, resource: null }, `${list.length} projects; read one with name.`);
+        }
+        const project = all.find((candidate) => candidate.name === name);
+        if (!project)
+            return fail(`No example named ${name}. Names: ${all.map((p) => p.name).join(", ")}.`);
+        if (!file) {
+            return ok({ projects: [], files: project.files, file: null, text: null, resource: null }, `${name}: ${project.files.length} files${project.images.length ? ` (and ${project.images.length} images, not included)` : ""}.`);
+        }
+        const text = projectFile(project.kind, project.name, file);
+        if (text === undefined)
+            return fail(`${name} has no text file ${file.slice(0, 256)}. Files: ${project.files.join(", ")}.`);
+        return ok({
+            projects: [],
+            files: [],
+            file,
+            text: bound(text, MAX_RESULT_CHARS - 4000),
+            resource: `overcrow://${project.kind}/${project.name}/${file}`,
+        }, `${name}/${file}`, { data: true });
+    });
+}

package/dist/tools/preview.js

@@ -0,0 +1,87 @@
+// use_preview: the marketplace preview of a widget is a PNG under assets/,
+// usually rendered by a test scenario at 150 %. An assistant's file tools
+// write text, not images: this copies one reference image into
+// assets/preview.png, inside the widget, and never overwrites a file.
+import { constants } from "node:fs";
+import { copyFile, lstat, mkdir, open } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { DESCRIPTIONS } from "../texts.js";
+import { fail, ok, widgetDirectory, withRoots } from "./common.js";
+const NAME = z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/);
+const MAX_PREVIEW_BYTES = 256 * 1024;
+async function pngSize(path) {
+    const handle = await open(path, "r");
+    try {
+        const header = Buffer.alloc(24);
+        const { bytesRead } = await handle.read(header, 0, 24, 0);
+        if (bytesRead < 24 ||
+            header.readUInt32BE(0) !== 0x89504e47 ||
+            header.toString("latin1", 12, 16) !== "IHDR") {
+            return null;
+        }
+        return { width: header.readUInt32BE(16), height: header.readUInt32BE(20) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function registerPreviewTool(env) {
+    env.server.registerTool("use_preview", {
+        title: "Use an image as the preview",
+        description: DESCRIPTIONS.use_preview,
+        inputSchema: z.strictObject({
+            directory: z
+                .string()
+                .min(1)
+                .max(1024)
+                .describe("The widget folder, relative to the project folder."),
+            scenario: NAME.describe("The scenario whose reference image to use (tests/reference/<scenario>/)."),
+            image: NAME.describe("The image name, without .png."),
+        }),
+        outputSchema: z.object({
+            directory: z.string(),
+            preview: z.string(),
+            bytes: z.number(),
+            width: z.number(),
+            height: z.number(),
+            fourByThree: z.boolean(),
+            next: z.string(),
+        }),
+        annotations: {
+            title: "Use an image as the preview",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ directory, scenario, image }, ctx) => withRoots(env, ctx, async (confinement, redactor) => {
+        const target = await widgetDirectory(confinement, directory);
+        const source = await confinement.resolve(join(target, "tests", "reference", scenario, `${image}.png`), "file");
+        const info = await lstat(source);
+        if (info.size > MAX_PREVIEW_BYTES) {
+            return fail(`That image is ${Math.round(info.size / 1024)} KiB: a preview may be 256 KiB at most.`);
+        }
+        const size = await pngSize(source);
+        if (!size)
+            return fail("That file is not a PNG image.");
+        // The destination folder must stay inside the project (no link out).
+        const assets = await confinement.resolve(join(target, "assets"), "new-directory");
+        const destination = join(assets, "preview.png");
+        if (await lstat(destination).catch(() => undefined)) {
+            return fail("assets/preview.png already exists: this tool never replaces a file. Keep it, or delete it yourself first.");
+        }
+        await mkdir(assets, { recursive: true });
+        await copyFile(source, destination, constants.COPYFILE_EXCL);
+        const fourByThree = Math.abs(size.width * 3 - size.height * 4) <= Math.max(size.width, size.height) * 0.01;
+        return ok({
+            directory: confinement.display(target),
+            preview: "assets/preview.png",
+            bytes: info.size,
+            width: size.width,
+            height: size.height,
+            fourByThree,
+            next: `Run check, package and prepare_submission. If the widget has a listing.json, add "preview": "assets/preview.png" to it.${fourByThree ? "" : " The image is not 4:3: the catalog shows it in a 4:3 box."}`,
+        }, `Copied ${scenario}/${image}.png to assets/preview.png (${size.width}×${size.height}, ${Math.round(info.size / 1024)} KiB).`, { redactor });
+    }));
+}

package/dist/tools/project.js

@@ -0,0 +1,183 @@
+// list_templates, create_widget and install_sdk: starting a widget project.
+import { readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { z } from "zod";
+import { Cli } from "../cli.js";
+import { projects } from "../content.js";
+import { installPackages } from "../npm.js";
+import { codePoint, hiddenCharacter } from "../hidden.js";
+import { cleanLine } from "../text.js";
+import { DESCRIPTIONS, TEMPLATE_SUMMARIES } from "../texts.js";
+import { ID_FORMS, idProblem, isPlaceholderId } from "../ids.js";
+import { fail, ok, READ_ONLY, TOOLS_MISSING, withRoots } from "./common.js";
+const TEMPLATES = ["blank", "counter", "list", "chart"];
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the point is to refuse them
+const REFUSED_IN_NAME = /[\u0000-\u001f\u007f<>]/;
+export function nameProblem(name) {
+    if (name !== name.trim() ||
+        name.length === 0 ||
+        [...name].length > 48 ||
+        REFUSED_IN_NAME.test(name)) {
+        return "The name must be 1 to 48 characters, without spaces at either end, control characters, < or >.";
+    }
+    const hidden = hiddenCharacter(name);
+    if (hidden) {
+        return `The name holds a hidden character, ${codePoint(hidden.code)}, at position ${hidden.position}: remove it.`;
+    }
+    return undefined;
+}
+async function listFiles(directory) {
+    const out = [];
+    const walk = async (current) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (entry.isFile())
+                out.push(relative(directory, path).split(sep).join("/"));
+        }
+    };
+    await walk(directory);
+    return out.sort();
+}
+export function registerProjectTools(env) {
+    const { server, session } = env;
+    server.registerTool("list_templates", {
+        title: "List templates",
+        description: DESCRIPTIONS.list_templates,
+        inputSchema: z.strictObject({}),
+        outputSchema: z.object({
+            templates: z.array(z.object({
+                name: z.string(),
+                summary: z.string(),
+                files: z.array(z.string()),
+                resource: z.string(),
+            })),
+        }),
+        annotations: { title: "List templates", ...READ_ONLY },
+    }, async () => {
+        const shared = projects("templates").find((project) => project.name === "shared")?.files ?? [];
+        const templates = TEMPLATES.map((name) => {
+            const project = projects("templates").find((candidate) => candidate.name === name);
+            return {
+                name,
+                summary: TEMPLATE_SUMMARIES[name] ?? "",
+                files: [
+                    ...(project?.files ?? []),
+                    ...shared.map((file) => (file === "gitignore" ? ".gitignore" : file)),
+                ].sort(),
+                resource: `overcrow://templates/${name}/logic.ts`,
+            };
+        });
+        return ok({ templates }, `${templates.length} templates: ${templates.map((t) => `${t.name} (${t.summary})`).join("; ")}`);
+    });
+    server.registerTool("create_widget", {
+        title: "Create a widget",
+        description: DESCRIPTIONS.create_widget,
+        inputSchema: z.strictObject({
+            directory: z
+                .string()
+                .min(1)
+                .max(1024)
+                .describe("A new folder, relative to the project folder."),
+            template: z.enum(TEMPLATES).default("blank"),
+            id: z
+                .string()
+                .min(3)
+                .max(128)
+                .describe("The widget's ID, final: <handle>.<name> with the user's publisher handle in the OverCrow creator space (such as nova.lol-timers), or a reverse domain the user can verify (such as gg.nova.lol-timers). Never com.playervox.*."),
+            name: z
+                .string()
+                .min(1)
+                .max(48)
+                .describe("The widget's name shown to users, 1 to 48 characters."),
+        }),
+        outputSchema: z.object({
+            directory: z.string(),
+            template: z.string(),
+            id: z.string(),
+            files: z.array(z.string()),
+            warnings: z.array(z.string()),
+            next: z.string(),
+        }),
+        annotations: {
+            title: "Create a widget",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ directory, template, id, name }, ctx) => withRoots(env, ctx, async (confinement, redactor) => {
+        const problem = idProblem(id) ?? nameProblem(name);
+        if (problem)
+            return fail(problem);
+        const tools = await session.installedTools();
+        if (!tools)
+            return fail(TOOLS_MISSING);
+        const target = await confinement.resolve(directory, "new-directory");
+        const existing = await readdir(target).catch(() => []);
+        if (existing.length > 0)
+            return fail(`${directory} already exists and is not empty: create_widget never overwrites files. Choose a new folder.`);
+        const result = await new Cli(tools).init(target, template, id, name, confinement.roots[0]?.path ?? target);
+        if (!result.ok) {
+            const reason = cleanLine(result.stderr.split("\n").find((line) => line.trim() !== "") ?? `exit ${result.code}`);
+            return fail(`The widget could not be created: ${reason}`, redactor);
+        }
+        const warnings = isPlaceholderId(id)
+            ? [`The ID ${id} is a placeholder: before submitting, replace it with ${ID_FORMS}.`]
+            : [];
+        return ok({
+            directory: confinement.display(target),
+            template,
+            id,
+            files: await listFiles(target),
+            warnings,
+            next: "Ask the user before installing packages, then run install_sdk with confirm: true, then check.",
+        }, `Created ${confinement.display(target)} from the ${template} template.`, { redactor });
+    }));
+    server.registerTool("install_sdk", {
+        title: "Install the SDK",
+        description: DESCRIPTIONS.install_sdk,
+        inputSchema: z.strictObject({
+            directory: z
+                .string()
+                .min(1)
+                .max(1024)
+                .describe("The widget folder, relative to the project folder."),
+            confirm: z
+                .literal(true)
+                .describe("Must be true: the user agreed to download the packages from npm."),
+        }),
+        outputSchema: z.object({
+            directory: z.string(),
+            installed: z.array(z.object({
+                name: z.string(),
+                version: z.string().nullable(),
+                integrityMatches: z.boolean(),
+            })),
+            next: z.string(),
+        }),
+        annotations: {
+            title: "Install the SDK",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ directory }, ctx) => withRoots(env, ctx, async (confinement, redactor) => {
+        const target = await confinement.resolve(directory, "directory");
+        const pins = session.options.pin.npm;
+        const cliSdk = session.cliSdkVersion;
+        if (cliSdk && cliSdk !== pins.sdk.version) {
+            return fail(`The installed CLI uses @overcrow/sdk ${cliSdk} but this server pins ${pins.sdk.version}: update @overcrow/mcp.`);
+        }
+        const checks = await installPackages(target, pins, ctx.mcpReq.signal);
+        // Exactly the advertised fields: clients check the output schema strictly.
+        const installed = checks.map(({ name, version, integrityMatches }) => ({
+            name,
+            version,
+            integrityMatches,
+        }));
+        return ok({ directory: confinement.display(target), installed, next: "Run check." }, `Installed @overcrow/sdk ${pins.sdk.version} and TypeScript ${pins.typescript.version}; their integrity matches the published packages.`, { redactor });
+    }));
+}

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);
+        });
+    });
+}