@overcrow/mcp 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valhallab SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,91 @@
-Placeholder of @overcrow/mcp, the OverCrow MCP server for widget creators: use 0.1.0 or later. Guide: https://overcrow.playervox.com/docs/en/mcp/
+# @overcrow/mcp
+
+An MCP server for creating [PlayerVox OverCrow](https://overcrow.playervox.com/)
+widgets with an AI assistant. Add it to Claude Code, Claude Desktop, Cursor,
+VS Code or Codex, and the assistant can create a widget, check it, test it,
+audit its security and lightness, package it and prepare its submission.
+
+You need Node.js 22.18 or later, nothing else: the server installs the
+OverCrow creator tools it needs by itself.
+
+```sh
+claude mcp add overcrow -- npx -y @overcrow/mcp
+```
+
+Guide, other clients and offline use:
+[overcrow.playervox.com/docs/en/mcp/](https://overcrow.playervox.com/docs/en/mcp/)
+([français](https://overcrow.playervox.com/docs/mcp/)).
+
+## Clients
+
+| Client | Setup |
+| --- | --- |
+| Claude Code | `claude mcp add overcrow -- npx -y @overcrow/mcp` |
+| Codex | `codex mcp add overcrow -- npx -y @overcrow/mcp` |
+| Cursor | [`.cursor/mcp.json`](https://github.com/Valhallab/playervox-overcrow-releases/blob/main/mcp/examples/cursor-mcp.json) |
+| VS Code | [`.vscode/mcp.json`](https://github.com/Valhallab/playervox-overcrow-releases/blob/main/mcp/examples/vscode-mcp.json), or `code --add-mcp '{"name":"overcrow","command":"npx","args":["-y","@overcrow/mcp"]}'` |
+| Claude Desktop | [`claude_desktop_config.json`](https://github.com/Valhallab/playervox-overcrow-releases/blob/main/mcp/examples/claude_desktop_config.json), with `--root` and your widgets folder |
+
+Options: `--root <folder>` (repeatable) names the folders the server may
+use; `--tools-zip <file>` gives a local copy of the creator tools ZIP.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `status` | What is ready, and what to do next |
+| `setup` | Downloads and checks the creator tools, once (the only download) |
+| `list_templates`, `create_widget` | Start a widget from a template, in a new folder |
+| `install_sdk` | `@overcrow/sdk` and TypeScript with npm, after your confirmation |
+| `check` | Every problem, with file, line, code and fix |
+| `test` | The test scenarios; differing images are shown |
+| `update_reference_images` | Replaces reference images, after your confirmation |
+| `use_preview` | Copies a reference image to `assets/preview.png`, the marketplace preview |
+| `package`, `inspect` | The `.ocpkg`, its size and what it may do |
+| `audit` | Security and lightness, scored out of 100, with fixes and examples |
+| `explain_permission`, `explain_error` | A permission or a code, in plain words |
+| `search_docs`, `read_doc`, `read_example` | The documentation and the reference widgets, offline |
+| `prepare_submission` | Everything the OverCrow creator space asks for, checked; the ZIP of the sources in `dist/`; the texts to draft with you |
+
+Resources: the documentation (`overcrow://docs/{en,fr}/…`), the manifest
+reference, the limits, the templates and the reference widgets. Prompts:
+`create_widget`, `audit_widget`, `prepare_submission`.
+
+## Security
+
+- The server works only in your project folders, through their real paths:
+  no system folder, no whole home folder, no link that leads out, no
+  hidden folder.
+- It runs the OverCrow widget CLI and npm, without a shell, with a minimal
+  environment (no token is passed on), time limits and bounded output. It
+  never runs a command chosen by the assistant.
+- It downloads only the creator tools ZIP of the OverCrow release this
+  version pins, from GitHub, and checks its size and SHA-256 and every file
+  in it before use. npm installs only `@overcrow/sdk` and TypeScript, with
+  install scripts disabled, and their integrity is checked against the
+  pinned published packages.
+- Replacing reference images and installing packages need an explicit
+  confirmation; the server deletes nothing in your project.
+- Text read from your files and from the tools is returned marked as data:
+  the server's instructions tell the assistant never to follow
+  instructions found in it.
+- No telemetry. Logs go to standard error, without your paths.
+- It never sends, signs or publishes anything: you send the sources ZIP
+  in the OverCrow creator space on overcrow.playervox.com.
+
+## Platforms
+
+Checking, testing and packaging run on Windows x64 and Linux x86-64. On
+other computers, the documentation, the explanations and the audit still
+work.
+
+## Dependencies
+
+Three packages, at exact versions frozen by `npm-shrinkwrap.json`:
+`@modelcontextprotocol/server` and `@modelcontextprotocol/core` (the
+official MCP SDK, Apache-2.0) and `zod` (MIT). No install script.
+
+## License
+
+MIT. Source:
+[github.com/Valhallab/playervox-overcrow-releases/tree/main/mcp](https://github.com/Valhallab/playervox-overcrow-releases/tree/main/mcp).

package/dist/audit/index.js

@@ -0,0 +1,103 @@
+// The audit of a widget: security (least authority, no secret, user data
+// kept) and lightness (CPU, memory, network, images), each scored out of
+// 100, with findings ranked by severity, each with a fix and an example
+// from a reference widget. Static: nothing of the widget runs.
+import { permissionsTable, projectFile } from "../content.js";
+import { readWidget } from "./project.js";
+import { runRules } from "./rules.js";
+const PENALTY = { high: 25, medium: 10, low: 3 };
+const ORDER = { high: 0, medium: 1, low: 2 };
+/** Finds an example's line in the embedded reference widgets. */
+export function resolveExample(example) {
+    const text = projectFile("examples", example.widget, example.file);
+    if (text === undefined)
+        return undefined;
+    const lines = text.split("\n");
+    const index = lines.findIndex((line) => line.includes(example.find));
+    if (index < 0)
+        return undefined;
+    return {
+        widget: example.widget,
+        file: example.file,
+        line: index + 1,
+        excerpt: lines.slice(index, index + 6).join("\n"),
+        resource: `overcrow://examples/${example.widget}/${example.file}`,
+    };
+}
+function score(findings, area) {
+    return Math.max(0, 100 - findings.filter((f) => f.area === area).reduce((sum, f) => sum + PENALTY[f.severity], 0));
+}
+function verdict(value) {
+    if (value >= 90)
+        return "good";
+    if (value >= 70)
+        return "fair";
+    return "needs work";
+}
+/** What the manifest lets the widget do, in plain words. */
+export function authoritySummary(manifest) {
+    const permissions = manifest?.permissions ?? {};
+    const table = permissionsTable();
+    const out = [];
+    const network = Array.isArray(permissions.network)
+        ? permissions.network
+        : [];
+    for (const rule of network) {
+        const bound = typeof rule.maxResponseBytes === "number"
+            ? `${Math.ceil(rule.maxResponseBytes / 1024)} KiB`
+            : "1 MiB (default)";
+        out.push(`Network: ${String(rule.method ?? "GET")} ${String(rule.origin ?? "")}${String(rule.path ?? "")}, responses up to ${bound}.`);
+    }
+    if (permissions.storage === true)
+        out.push(`Storage: ${table.permissions.storage?.en.meaning ?? "host-managed storage"}`);
+    if (permissions.clipboardWrite === true)
+        out.push(`Clipboard: ${table.permissions.clipboardWrite?.en.meaning ?? "text writes"}`);
+    const events = Array.isArray(permissions.gameEvents) ? permissions.gameEvents : [];
+    if (events.length > 0)
+        out.push(`Game events: ${events.join(", ")}.`);
+    const capabilities = Array.isArray(permissions.capabilities)
+        ? permissions.capabilities
+        : [];
+    for (const capability of capabilities) {
+        const info = table.capabilities[capability];
+        const flags = [
+            info?.sensitive ? "sensitive" : null,
+            info?.account ? `needs a ${info.account} account` : null,
+        ].filter(Boolean);
+        out.push(`${capability}${flags.length ? ` (${flags.join(", ")})` : ""}: ${info?.en.meaning ?? "unknown capability"}`);
+    }
+    if (out.length === 0)
+        out.push("Nothing: the widget asks for no permission and no capability.");
+    return out;
+}
+/** Audits the widget in `directory` (already confined). */
+export async function auditWidget(directory, extra = {}) {
+    const project = await readWidget(directory);
+    const findings = [...runRules(project), ...(extra.findings ?? [])].sort((a, b) => ORDER[a.severity] - ORDER[b.severity] || a.rule.localeCompare(b.rule));
+    const notes = [...(extra.notes ?? [])];
+    if (project.manifestError)
+        notes.push(`manifest.json could not be read (${project.manifestError}): the permission rules did not run.`);
+    if (!project.logic)
+        notes.push("No logic.ts or logic.js: the logic rules did not run.");
+    if (project.truncated)
+        notes.push("The folder is very large: the audit read only part of it.");
+    const security = score(findings, "security");
+    const lightness = score(findings, "lightness");
+    return {
+        id: typeof project.manifest?.id === "string" ? project.manifest.id : null,
+        version: typeof project.manifest?.version === "string" ? project.manifest.version : null,
+        scores: { security, lightness },
+        verdicts: { security: verdict(security), lightness: verdict(lightness) },
+        counts: {
+            high: findings.filter((f) => f.severity === "high").length,
+            medium: findings.filter((f) => f.severity === "medium").length,
+            low: findings.filter((f) => f.severity === "low").length,
+        },
+        findings: findings.map(({ example, ...finding }) => {
+            const resolved = example ? resolveExample(example) : undefined;
+            return resolved ? { ...finding, example: resolved } : finding;
+        }),
+        authority: authoritySummary(project.manifest),
+        notes,
+    };
+}

package/dist/audit/lexer.js

@@ -0,0 +1,417 @@
+// A small tokenizer of TypeScript and JavaScript for the static audit: it
+// separates code from comments, strings and template literals so that the
+// rules look at what the logic does, not at what its comments say. It never
+// evaluates anything. Precision is that of a lexer: the rules that use it
+// are worded as findings to check, not as proofs.
+const IDENTIFIER_START = /[A-Za-z_$À-￿]/;
+const IDENTIFIER_PART = /[A-Za-z0-9_$À-￿]/;
+const PUNCTUATION = [
+    "...",
+    "===",
+    "!==",
+    "**=",
+    "<<=",
+    ">>=",
+    ">>>",
+    "=>",
+    "==",
+    "!=",
+    "<=",
+    ">=",
+    "&&",
+    "||",
+    "??",
+    "?.",
+    "++",
+    "--",
+    "+=",
+    "-=",
+    "*=",
+    "/=",
+    "%=",
+    "&=",
+    "|=",
+    "^=",
+    "**",
+    "<<",
+    ">>",
+];
+/** After these, a `/` starts a regular expression rather than a division. */
+const REGEX_AFTER_KEYWORDS = new Set([
+    "return",
+    "typeof",
+    "instanceof",
+    "in",
+    "of",
+    "new",
+    "delete",
+    "void",
+    "throw",
+    "case",
+    "do",
+    "else",
+    "yield",
+    "await",
+]);
+export function tokenize(source) {
+    const tokens = [];
+    let i = 0;
+    let line = 1;
+    /** Brace depth at which each open template literal resumes. */
+    const templateStack = [];
+    let braceDepth = 0;
+    const regexAllowed = () => {
+        const previous = tokens.at(-1);
+        if (!previous)
+            return true;
+        if (previous.kind === "identifier")
+            return REGEX_AFTER_KEYWORDS.has(previous.value);
+        if (previous.kind === "number" || previous.kind === "string" || previous.kind === "regex")
+            return false;
+        if (previous.kind === "template")
+            return !previous.end;
+        return ![")", "]", "}"].includes(previous.value);
+    };
+    const readTemplateChunk = () => {
+        // `i` is just after the opening backtick or the closing brace of `${`.
+        const startLine = line;
+        let value = "";
+        while (i < source.length) {
+            const char = source[i];
+            if (char === "\\") {
+                value += source.slice(i, i + 2);
+                if (source[i + 1] === "\n")
+                    line += 1;
+                i += 2;
+                continue;
+            }
+            if (char === "`") {
+                i += 1;
+                tokens.push({ kind: "template", value, line: startLine, end: true });
+                return;
+            }
+            if (char === "$" && source[i + 1] === "{") {
+                i += 2;
+                tokens.push({ kind: "template", value, line: startLine, end: false });
+                templateStack.push(braceDepth);
+                braceDepth += 1;
+                return;
+            }
+            if (char === "\n")
+                line += 1;
+            value += char;
+            i += 1;
+        }
+        tokens.push({ kind: "template", value, line: startLine, end: true });
+    };
+    while (i < source.length) {
+        const char = source[i];
+        const next = source[i + 1];
+        if (char === "\n") {
+            line += 1;
+            i += 1;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            i += 1;
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            while (i < source.length && source[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            const end = source.indexOf("*/", i + 2);
+            const stop = end < 0 ? source.length : end + 2;
+            for (let j = i; j < stop; j += 1)
+                if (source[j] === "\n")
+                    line += 1;
+            i = stop;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            const startLine = line;
+            let value = "";
+            i += 1;
+            while (i < source.length && source[i] !== char && source[i] !== "\n") {
+                if (source[i] === "\\") {
+                    value += source.slice(i, i + 2);
+                    i += 2;
+                    continue;
+                }
+                value += source[i];
+                i += 1;
+            }
+            i += 1;
+            tokens.push({ kind: "string", value, line: startLine });
+            continue;
+        }
+        if (char === "`") {
+            i += 1;
+            readTemplateChunk();
+            continue;
+        }
+        if (char === "}" && templateStack.length > 0 && templateStack.at(-1) === braceDepth - 1) {
+            templateStack.pop();
+            braceDepth -= 1;
+            i += 1;
+            readTemplateChunk();
+            continue;
+        }
+        if (char === "/" && regexAllowed()) {
+            const startLine = line;
+            let value = "";
+            let inClass = false;
+            i += 1;
+            while (i < source.length && source[i] !== "\n") {
+                const c = source[i];
+                if (c === "\\") {
+                    value += source.slice(i, i + 2);
+                    i += 2;
+                    continue;
+                }
+                if (c === "[")
+                    inClass = true;
+                else if (c === "]")
+                    inClass = false;
+                else if (c === "/" && !inClass)
+                    break;
+                value += c;
+                i += 1;
+            }
+            i += 1;
+            while (i < source.length && /[a-z]/.test(source[i]))
+                i += 1;
+            tokens.push({ kind: "regex", value, line: startLine });
+            continue;
+        }
+        if (/[0-9]/.test(char) || (char === "." && /[0-9]/.test(next ?? ""))) {
+            let end = i + 1;
+            while (end < source.length && /[0-9A-Za-z_.]/.test(source[end]))
+                end += 1;
+            tokens.push({ kind: "number", value: source.slice(i, end), line });
+            i = end;
+            continue;
+        }
+        if (IDENTIFIER_START.test(char)) {
+            let end = i + 1;
+            while (end < source.length && IDENTIFIER_PART.test(source[end]))
+                end += 1;
+            tokens.push({ kind: "identifier", value: source.slice(i, end), line });
+            i = end;
+            continue;
+        }
+        const operator = PUNCTUATION.find((candidate) => source.startsWith(candidate, i));
+        const value = operator ?? char;
+        if (value === "{")
+            braceDepth += 1;
+        if (value === "}")
+            braceDepth = Math.max(0, braceDepth - 1);
+        tokens.push({ kind: "punctuation", value, line });
+        i += value.length;
+    }
+    return tokens;
+}
+/** The numeric value of a literal (`30_000`, `0x10`, `1e3`), or undefined. */
+export function numberValue(text) {
+    const value = Number(text.replaceAll("_", ""));
+    return Number.isFinite(value) ? value : undefined;
+}
+/** Index of the token that closes the bracket opened at `open`, or -1. */
+export function matching(tokens, open) {
+    const pairs = { "(": ")", "[": "]", "{": "}" };
+    const opener = tokens[open]?.value ?? "";
+    const closer = pairs[opener];
+    if (!closer)
+        return -1;
+    let depth = 0;
+    for (let index = open; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token.kind !== "punctuation")
+            continue;
+        if (token.value === opener)
+            depth += 1;
+        else if (token.value === closer) {
+            depth -= 1;
+            if (depth === 0)
+                return index;
+        }
+    }
+    return -1;
+}
+/**
+ * Indexes of calls of a dotted name: `timers.every(` for
+ * `["timers", "every"]`. Returns the index of the opening parenthesis.
+ */
+export function calls(tokens, path) {
+    const found = [];
+    outer: for (let index = 0; index + path.length * 2 - 1 < tokens.length; index += 1) {
+        for (let part = 0; part < path.length; part += 1) {
+            const token = tokens[index + part * 2];
+            if (token?.kind !== "identifier" || token.value !== path[part])
+                continue outer;
+            if (part < path.length - 1) {
+                const dot = tokens[index + part * 2 + 1];
+                if (dot?.value !== "." && dot?.value !== "?.")
+                    continue outer;
+            }
+        }
+        // Not the tail of a longer chain (`x.timers.every`).
+        const before = tokens[index - 1];
+        if (before?.value === "." || before?.value === "?.")
+            continue;
+        const open = tokens[index + path.length * 2 - 1];
+        if (open?.value === "(")
+            found.push(index + path.length * 2 - 1);
+    }
+    return found;
+}
+/** Splits the arguments of the call whose `(` is at `open` into token ranges. */
+export function callArguments(tokens, open) {
+    const close = matching(tokens, open);
+    if (close < 0)
+        return [];
+    const args = [];
+    let current = [];
+    let depth = 0;
+    for (let index = open + 1; index < close; index += 1) {
+        const token = tokens[index];
+        if (token.kind === "punctuation" && ["(", "[", "{"].includes(token.value))
+            depth += 1;
+        if (token.kind === "punctuation" && [")", "]", "}"].includes(token.value))
+            depth -= 1;
+        if (depth === 0 && token.kind === "punctuation" && token.value === ",") {
+            args.push(current);
+            current = [];
+            continue;
+        }
+        current.push(token);
+    }
+    if (current.length > 0)
+        args.push(current);
+    return args;
+}
+/** `const NAME = <number expression>` declarations of a file, evaluated when only literals are multiplied or added. */
+export function numericConstants(tokens) {
+    const constants = new Map();
+    for (let index = 0; index + 3 < tokens.length; index += 1) {
+        if (tokens[index]?.value !== "const" || tokens[index + 1]?.kind !== "identifier")
+            continue;
+        let cursor = index + 2;
+        // An optional type annotation: `const X: number = …`.
+        if (tokens[cursor]?.value === ":")
+            cursor += 2;
+        if (tokens[cursor]?.value !== "=")
+            continue;
+        const expression = [];
+        for (let j = cursor + 1; j < tokens.length; j += 1) {
+            const token = tokens[j];
+            if (token.value === ";" || token.line !== tokens[cursor].line)
+                break;
+            expression.push(token);
+        }
+        const value = evaluate(expression, constants);
+        if (value !== undefined)
+            constants.set(tokens[index + 1].value, value);
+    }
+    return constants;
+}
+/** Evaluates `a * b + c` made of number literals and known constants. */
+export function evaluate(expression, constants) {
+    if (expression.length === 0 || expression.length > 15)
+        return undefined;
+    let total = 0;
+    let product = 1;
+    let expectOperand = true;
+    for (const token of expression) {
+        if (expectOperand) {
+            const value = token.kind === "number"
+                ? numberValue(token.value)
+                : token.kind === "identifier"
+                    ? constants.get(token.value)
+                    : undefined;
+            if (value === undefined)
+                return undefined;
+            product *= value;
+            expectOperand = false;
+        }
+        else if (token.value === "*") {
+            expectOperand = true;
+        }
+        else if (token.value === "+") {
+            total += product;
+            product = 1;
+            expectOperand = true;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return expectOperand ? undefined : total + product;
+}
+/**
+ * Named functions of a file: `function f(`, `export function f(`,
+ * `const f = (…) =>`, `const f = function`, and methods `f(…) {`.
+ */
+export function functions(tokens) {
+    const out = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        let name;
+        let search = index;
+        if (token.value === "function" && tokens[index + 1]?.kind === "identifier") {
+            name = tokens[index + 1].value;
+            search = index + 2;
+        }
+        else if ((token.value === "const" || token.value === "let") &&
+            tokens[index + 1]?.kind === "identifier" &&
+            tokens[index + 2]?.value === "=") {
+            const after = tokens[index + 3];
+            if (after?.value === "(" ||
+                after?.value === "async" ||
+                after?.value === "function" ||
+                after?.kind === "identifier") {
+                name = tokens[index + 1].value;
+                search = index + 3;
+            }
+        }
+        if (!name)
+            continue;
+        // The body is the first `{` after the parameters (and `=>` for arrows).
+        let open = -1;
+        for (let j = search; j < Math.min(tokens.length, search + 400); j += 1) {
+            const candidate = tokens[j];
+            if (candidate.value === "(") {
+                const close = matching(tokens, j);
+                if (close < 0)
+                    break;
+                j = close;
+                continue;
+            }
+            if (candidate.value === ";")
+                break;
+            if (candidate.value === "{") {
+                open = j;
+                break;
+            }
+        }
+        if (open < 0)
+            continue;
+        const end = matching(tokens, open);
+        if (end < 0)
+            continue;
+        const exported = tokens[index - 1]?.value === "export" || tokens[index - 2]?.value === "export";
+        out.push({ name, exported, start: open, end });
+    }
+    return out;
+}
+/** The innermost named function whose body holds token `index`. */
+export function enclosing(ranges, index) {
+    let best;
+    for (const range of ranges) {
+        if (range.start < index && index < range.end && (!best || range.start > best.start))
+            best = range;
+    }
+    return best;
+}