@overcrow/mcp 0.0.0 → 0.1.0

package/dist/tools/common.js

@@ -0,0 +1,122 @@
+// Helpers shared by the tools: results with structured content and a text
+// copy, errors the model can act on, the confinement of each request, and
+// project data marked as data.
+import { CliError } from "../cli.js";
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { ConfinementError } from "../confine.js";
+import { NpmError } from "../npm.js";
+import { RunError } from "../run.js";
+import { SetupError } from "../session.js";
+import { bound, DATA_NOTICE } from "../text.js";
+/** Most characters a text result carries; Claude Code moves larger results to a file. */
+export const MAX_RESULT_CHARS = 40_000;
+/**
+ * A successful result: a one-line summary for people, then the structured
+ * content as JSON (clients that ignore `structuredContent` still get it).
+ * Results that carry project content are marked as data.
+ */
+export function ok(structured, summary, options = {}) {
+    const redact = (text) => (options.redactor ? options.redactor.text(text) : text);
+    const structuredContent = options.redactor
+        ? redactDeep(structured, options.redactor)
+        : structured;
+    const json = JSON.stringify(structuredContent);
+    const body = options.data
+        ? `${DATA_NOTICE}\n<data>\n${json.replaceAll("</data>", "<\\/data>")}\n</data>`
+        : json;
+    return {
+        content: [
+            { type: "text", text: bound(`${redact(summary)}\n\n${body}`, MAX_RESULT_CHARS) },
+            ...(options.extra ?? []),
+        ],
+        structuredContent,
+    };
+}
+/** Replaces the user's paths in every string of a JSON value. */
+function redactDeep(value, redactor) {
+    if (typeof value === "string")
+        return redactor.text(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactDeep(item, redactor));
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactDeep(item, redactor)]));
+    }
+    return value;
+}
+/** A failure the model can correct: what went wrong and what to do. */
+export function fail(message, redactor) {
+    return {
+        content: [{ type: "text", text: bound(redactor ? redactor.text(message) : message, 4000) }],
+        isError: true,
+    };
+}
+/** Turns the expected errors into tool failures; anything else is rethrown. */
+export function failure(error, redactor) {
+    if (error instanceof ConfinementError ||
+        error instanceof SetupError ||
+        error instanceof NpmError ||
+        error instanceof RunError) {
+        return fail(error.message, redactor);
+    }
+    if (error instanceof CliError) {
+        const detail = error.stderr
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .slice(0, 8)
+            .join("\n");
+        return fail(`${error.message}${detail ? `\n${DATA_NOTICE}\n${detail}` : ""}`, redactor);
+    }
+    throw error;
+}
+export const TOOLS_MISSING = "The creator tools (the widget CLI and its test runtime) are not installed on this computer yet: run the setup tool first. It downloads them once (about 15 MB) and checks them.";
+/**
+ * Runs `handler` with the project folders of this request. When the
+ * client's roots are needed and not known yet, returns the input request
+ * that asks for them; the client then retries the call.
+ */
+export async function withRoots(env, ctx, handler) {
+    const answer = await env.session.roots(ctx, env.server);
+    if ("input" in answer)
+        return answer.input;
+    if ("error" in answer)
+        return fail(answer.error);
+    const redactor = env.session.redactor(answer.confinement);
+    try {
+        return await handler(answer.confinement, redactor);
+    }
+    catch (error) {
+        return failure(error, redactor);
+    }
+}
+/** Sends a progress notification when the client asked for them. */
+export function progress(ctx) {
+    const token = ctx.mcpReq._meta
+        ?.progressToken;
+    if (token === undefined)
+        return undefined;
+    return (done, total, message) => {
+        ctx.mcpReq
+            .notify({
+            method: "notifications/progress",
+            params: { progressToken: token, progress: done, total, ...(message ? { message } : {}) },
+        })
+            .catch(() => undefined);
+    };
+}
+/** Annotations, spelled out for every tool (no default is relied on). */
+export const READ_ONLY = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+/** A widget folder inside the project: it must hold a manifest.json. */
+export async function widgetDirectory(confinement, directory) {
+    const target = await confinement.resolve(directory, "directory");
+    const manifest = await lstat(join(target, "manifest.json")).catch(() => undefined);
+    if (!manifest?.isFile()) {
+        throw new ConfinementError(`${directory} is not a widget folder: it has no manifest.json.`);
+    }
+    return target;
+}

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,178 @@
+// 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 { 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 >.";
+    }
+    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 });
+    }));
+}