@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/catalog/claude/manifest.js

@@ -0,0 +1,134 @@
+import { createHash } from "node:crypto";
+import { isSafePackagePath, PLUGIN_MANIFEST_LIMITS } from "@capybara-hq/plugin-sdk";
+import { contentDigest, PluginPackageError } from "../plugin-package.js";
+import { printable } from "./report.js";
+/**
+ * Lenient reading of Claude Code's plugin files (`.claude-plugin/plugin.json`, `.mcp.json`,
+ * `hooks/hooks.json`; format: spec Appendix A, re-checked against the Claude Code plugins
+ * reference on 2026-10-26). Claude's format is open-ended and keeps gaining fields, so there is no
+ * schema: every value is type-checked where it is used, and a wrong type is a report item, never
+ * an exception (spec §8.1).
+ */
+/** Claude Code's plugin manifest. */
+export const CLAUDE_PLUGIN_FILE = ".claude-plugin/plugin.json";
+/**
+ * Component fields a marketplace entry may carry (stored in `ClaudeEntryOverlay.components`). The
+ * first six are the ones Claude's `strict` rule appends or rejects; the rest apply only to a plugin
+ * without its own `plugin.json` (the entry is then the manifest).
+ */
+export const CLAUDE_STRICT_COMPONENT_KEYS = [
+    "skills",
+    "commands",
+    "agents",
+    "hooks",
+    "outputStyles",
+    "themes",
+];
+export const CLAUDE_COMPONENT_KEYS = [
+    ...CLAUDE_STRICT_COMPONENT_KEYS,
+    "mcpServers",
+    "lspServers",
+    "userConfig",
+    "channels",
+    "monitors",
+    "workflows",
+    "experimental",
+    "settings",
+];
+export const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** JSON with object keys sorted (code unit order) at every level. */
+const canonicalJson = (v) => Array.isArray(v)
+    ? `[${v.map(canonicalJson).join(",")}]`
+    : isObj(v)
+        ? `{${Object.keys(v)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonicalJson(v[k])}`)
+            .join(",")}}`
+        : (JSON.stringify(v) ?? "null");
+/**
+ * The content digest of a Claude Code plugin (Decision 5, Review Focus 5): {@link contentDigest}
+ * of the files as read, never of the translated tree, so it does not depend on the translator.
+ * When the marketplace entry carries component fields, they decide what is imported (Claude's
+ * `strict` rule), so `strict` and the components (canonical JSON) are folded in: an entry-only
+ * change at the same version is other content (`+git.<sha12>` / `+sha256.<12>`), not
+ * `catalog.version_exists`. An entry without components gives the files' own digest, the same as
+ * a direct git import of the plugin. Entry display fields (description, author) are listing data
+ * and are not folded in, as for a Capybara marketplace.
+ *
+ * Phase D (spec §8.3): `translatorRevision` (the translation's, set only when the tree has a
+ * command, a manual-only or a forked skill, whose translation phase D changed) is folded in last,
+ * so re-importing such a plugin at an already imported version records `+sha256.<12>` with the
+ * new skills, while every other plugin keeps its digest.
+ */
+export function claudeContentDigest(files, overlay, translatorRevision) {
+    let digest = contentDigest(files);
+    if (overlay !== undefined && Object.keys(overlay.components).length > 0) {
+        const entry = canonicalJson({ strict: overlay.strict, components: overlay.components });
+        digest = createHash("sha256").update(`${digest}\0claude-entry\0${entry}`).digest("hex");
+    }
+    if (translatorRevision === undefined)
+        return digest;
+    return createHash("sha256")
+        .update(`${digest}\0claude-translator\0${translatorRevision}`)
+        .digest("hex");
+}
+export const decodeUtf8 = (data) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(data);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Reads a JSON file with the plugin manifest's size cap; never throws. */
+export function readJsonFile(data) {
+    const max = PLUGIN_MANIFEST_LIMITS.manifestChars;
+    if (data.byteLength > max * 4)
+        return { problem: `larger than ${max} characters` };
+    const text = decodeUtf8(data);
+    if (text === undefined)
+        return { problem: "not valid UTF-8 text" };
+    if (text.length > max)
+        return { problem: `larger than ${max} characters` };
+    try {
+        return { value: JSON.parse(text.startsWith("") ? text.slice(1) : text) };
+    }
+    catch {
+        return { problem: "not valid JSON" };
+    }
+}
+/** Cuts a string to `max` code points (trimmed). */
+export const cut = (s, max) => [...s.trim()].slice(0, max).join("");
+/** A short, printable rendering of an untrusted key for the report (see {@link printable}). */
+export const showName = (s) => cut(printable(s), 200) || "?";
+/**
+ * Resolves a component path of a Claude manifest (`./x`, or `.` / `./` for the root where
+ * `allowRoot`) to a path relative to the plugin root (`""` is the root). A non-string, a path
+ * without `./` or the root where it is not allowed is a `{ problem }` (the caller reports it); a
+ * path that leaves the root, or is not a safe relative path at all, refuses the import naming it
+ * (spec §8.1: paths stay inside the root).
+ */
+export function componentPath(p, where, allowRoot = false) {
+    if (typeof p !== "string")
+        return { problem: "must be a path string" };
+    if (allowRoot && (p === "." || p === "./"))
+        return { rel: "" };
+    const leaves = p.startsWith("/") || p.split(/[/\\]/).includes("..");
+    if (!leaves && !p.startsWith("./")) {
+        return { problem: `path ${JSON.stringify(showName(p))} must start with "./"` };
+    }
+    const rest = p.slice(2).replace(/\/+$/, "");
+    if (!leaves && rest === "") {
+        return allowRoot
+            ? { rel: "" }
+            : { problem: `path ${JSON.stringify(showName(p))} must not be the plugin root` };
+    }
+    if (leaves || !isSafePackagePath(rest)) {
+        throw new PluginPackageError("catalog.invalid_manifest", [
+            `${where}: path ${JSON.stringify(showName(p))} leaves the plugin root or is not a safe relative path`,
+        ]);
+    }
+    return { rel: rest };
+}
+/** A string or an array as a list (anything else is `null`). */
+export const asList = (v) => Array.isArray(v) ? v : v === undefined ? [] : typeof v === "string" || isObj(v) ? [v] : null;

package/dist/catalog/claude/marketplace.d.ts

@@ -0,0 +1,35 @@
+import { type MarketplaceManifest } from "@capybara-hq/plugin-sdk";
+import { type ClaudeEntryOverlay } from "./manifest.js";
+export { CLAUDE_PLUGIN_FILE } from "./manifest.js";
+/**
+ * Claude Code's `.claude-plugin/marketplace.json` (spec §5.1, Appendix A; re-checked against the
+ * Claude Code marketplace reference on 2026-10-26) read as a Capybara marketplace: each entry
+ * becomes a {@link MarketplaceEntry} with a Capybara source, and its component fields and `strict`
+ * flag go to a {@link ClaudeEntryOverlay} that the import applies. Claude validates each entry on
+ * its own, so an entry Capybara cannot store is skipped with a reason, never fails the marketplace.
+ */
+/** Claude Code's marketplace manifest in a git repository. */
+export declare const CLAUDE_MARKETPLACE_FILE = ".claude-plugin/marketplace.json";
+/** Why an entry of a marketplace could not be stored (shown on the marketplace). */
+export type MarketplaceSkipReason = "claude_npm_unpinned" | "claude_source_unsupported" | "invalid_name" | "invalid_entry";
+/** Result of {@link parseClaudeMarketplace}. */
+export interface ClaudeMarketplace {
+    manifest: MarketplaceManifest;
+    /** Entry name -> overlay. */
+    overlays: Map<string, ClaudeEntryOverlay>;
+    skipped: {
+        name: string;
+        reason: MarketplaceSkipReason;
+    }[];
+}
+/**
+ * Parses a Claude Code `marketplace.json` value. A top level that is not an object, or has no
+ * `name` or `plugins` array, is `{ errors }`; each entry that cannot be stored is in `skipped`.
+ * The produced manifest passes `parseMarketplaceManifest` (a root path entry is `{ path: "." }`,
+ * as for a single-plugin repository).
+ */
+export declare function parseClaudeMarketplace(json: unknown, o: {
+    allowInsecureLoopback: boolean;
+}): ClaudeMarketplace | {
+    errors: string[];
+};

package/dist/catalog/claude/marketplace.js

@@ -0,0 +1,194 @@
+import { CATALOG_ITEM_NAME_RE, isSafePackagePath, parseMarketplaceManifest, SEMVER_VERSION_RE, } from "@capybara-hq/plugin-sdk";
+import { expandGitUrl } from "../git-source.js";
+import { CLAUDE_COMPONENT_KEYS, cut, isObj, showName, } from "./manifest.js";
+export { CLAUDE_PLUGIN_FILE } from "./manifest.js";
+/**
+ * Claude Code's `.claude-plugin/marketplace.json` (spec §5.1, Appendix A; re-checked against the
+ * Claude Code marketplace reference on 2026-10-26) read as a Capybara marketplace: each entry
+ * becomes a {@link MarketplaceEntry} with a Capybara source, and its component fields and `strict`
+ * flag go to a {@link ClaudeEntryOverlay} that the import applies. Claude validates each entry on
+ * its own, so an entry Capybara cannot store is skipped with a reason, never fails the marketplace.
+ */
+/** Claude Code's marketplace manifest in a git repository. */
+export const CLAUDE_MARKETPLACE_FILE = ".claude-plugin/marketplace.json";
+const SHA_RE = /^[0-9a-f]{40}$/;
+const HTTPS_RE = /^https:\/\/\S+$/;
+const LOOPBACK_RE = /^http:\/\/(?:127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|\[::1\])(?::\d{1,5})?(?:\/\S*)?$/;
+const SUMMARY_MAX = 280;
+/** Most entries read; the rest are one skipped row. */
+const MAX_ENTRIES = 5000;
+/** `./a/b/`, `a/b` -> `a/b`; `.`, `./` -> `.`; null when it leaves the repository. */
+function repoRelative(p) {
+    const rest = p.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (rest === "" || rest === ".")
+        return ".";
+    return isSafePackagePath(rest) ? rest : null;
+}
+function mapSource(raw, pluginRoot, loopback) {
+    if (typeof raw === "string") {
+        // A bare name resolves under metadata.pluginRoot; anything else needs "./" (or is ".").
+        const bare = raw !== "." && !raw.startsWith("./") && !raw.includes("/");
+        if (bare && pluginRoot === null)
+            return { skip: "invalid_entry" };
+        if (!bare && raw !== "." && !raw.startsWith("./"))
+            return { skip: "invalid_entry" };
+        const rel = repoRelative(bare ? `${pluginRoot}/${raw}` : raw);
+        if (rel === null)
+            return { skip: "invalid_entry" };
+        return { source: { path: rel === "." ? "." : `./${rel}` } };
+    }
+    if (!isObj(raw) || typeof raw.source !== "string")
+        return { skip: "invalid_entry" };
+    const okUrl = (u) => HTTPS_RE.test(u) || (loopback && LOOPBACK_RE.test(u));
+    const pin = () => {
+        const out = {};
+        if (raw.ref !== undefined) {
+            if (typeof raw.ref !== "string" || raw.ref === "" || raw.ref.length > 256)
+                return null;
+            out.ref = raw.ref;
+        }
+        if (raw.sha !== undefined) {
+            if (typeof raw.sha !== "string" || !SHA_RE.test(raw.sha))
+                return null;
+            out.commit = raw.sha;
+        }
+        return out;
+    };
+    switch (raw.source) {
+        case "github": {
+            if (typeof raw.repo !== "string")
+                return { skip: "invalid_entry" };
+            const url = expandGitUrl(raw.repo);
+            const p = pin();
+            if (url === raw.repo || p === null)
+                return { skip: "invalid_entry" };
+            return { source: { git: { url, ...p } } };
+        }
+        case "url":
+        case "git-subdir": {
+            if (typeof raw.url !== "string" || raw.url === "")
+                return { skip: "invalid_entry" };
+            const url = raw.source === "git-subdir" ? expandGitUrl(raw.url) : raw.url;
+            if (!okUrl(url))
+                return { skip: "claude_source_unsupported" };
+            const p = pin();
+            if (p === null)
+                return { skip: "invalid_entry" };
+            if (raw.source === "url")
+                return { source: { git: { url, ...p } } };
+            if (typeof raw.path !== "string")
+                return { skip: "invalid_entry" };
+            const path = repoRelative(raw.path);
+            if (path === null)
+                return { skip: "invalid_entry" };
+            return { source: { git: { url, path, ...p } } };
+        }
+        case "npm":
+            return { skip: "claude_npm_unpinned" };
+        default:
+            // archive (a zip; Capybara reads tgz archives only), command, and anything newer
+            return { skip: "claude_source_unsupported" };
+    }
+}
+/**
+ * Parses a Claude Code `marketplace.json` value. A top level that is not an object, or has no
+ * `name` or `plugins` array, is `{ errors }`; each entry that cannot be stored is in `skipped`.
+ * The produced manifest passes `parseMarketplaceManifest` (a root path entry is `{ path: "." }`,
+ * as for a single-plugin repository).
+ */
+export function parseClaudeMarketplace(json, o) {
+    if (!isObj(json))
+        return { errors: ["marketplace.json must be a JSON object"] };
+    const errors = [];
+    const name = typeof json.name === "string" ? cut(json.name, 100) : "";
+    if (name === "")
+        errors.push("name is required");
+    if (!Array.isArray(json.plugins))
+        errors.push("plugins must be an array");
+    if (errors.length > 0)
+        return { errors };
+    const metadata = isObj(json.metadata) ? json.metadata : {};
+    const rootRaw = typeof metadata.pluginRoot === "string" ? metadata.pluginRoot : null;
+    const pluginRoot = rootRaw === null ? null : repoRelative(rootRaw);
+    const ownerName = isObj(json.owner) && typeof json.owner.name === "string"
+        ? cut(json.owner.name, 100) || undefined
+        : undefined;
+    const descRaw = typeof json.description === "string" ? json.description : metadata.description;
+    const description = typeof descRaw === "string" ? cut(descRaw, 1024) : "";
+    const plugins = [];
+    const overlays = new Map();
+    const skipped = [];
+    const all = json.plugins;
+    all.slice(0, MAX_ENTRIES).forEach((raw, i) => {
+        if (!isObj(raw) || typeof raw.name !== "string" || raw.name === "") {
+            skipped.push({ name: `plugins[${i}]`, reason: "invalid_entry" });
+            return;
+        }
+        const en = raw.name;
+        if (!CATALOG_ITEM_NAME_RE.test(en)) {
+            skipped.push({ name: showName(en), reason: "invalid_name" });
+            return;
+        }
+        if (overlays.has(en)) {
+            skipped.push({ name: en, reason: "invalid_entry" });
+            return;
+        }
+        const mapped = mapSource(raw.source, pluginRoot, o.allowInsecureLoopback);
+        if ("skip" in mapped) {
+            skipped.push({ name: en, reason: mapped.skip });
+            return;
+        }
+        const summary = typeof raw.description === "string" && cut(raw.description, SUMMARY_MAX) !== ""
+            ? cut(raw.description, SUMMARY_MAX)
+            : `Claude Code plugin ${en}`;
+        const entry = {
+            name: en,
+            summary: { en: summary },
+            ...(typeof raw.version === "string" &&
+                SEMVER_VERSION_RE.test(raw.version) &&
+                raw.version.length <= 256 && { version: raw.version }),
+            ...(typeof raw.homepage === "string" &&
+                HTTPS_RE.test(raw.homepage) &&
+                raw.homepage.length <= 2000 && { homepage: raw.homepage }),
+            source: mapped.source,
+        };
+        // Each entry is checked on its own (a root path stands in as "./x": the SDK has no root form).
+        const probe = parseMarketplaceManifest({
+            schemaVersion: 1,
+            name: "probe",
+            plugins: [
+                "path" in entry.source && entry.source.path === "."
+                    ? { ...entry, source: { path: "./x" } }
+                    : entry,
+            ],
+        }, { allowInsecureLoopback: o.allowInsecureLoopback });
+        if ("errors" in probe) {
+            skipped.push({ name: en, reason: "invalid_entry" });
+            return;
+        }
+        const components = {};
+        for (const k of CLAUDE_COMPONENT_KEYS)
+            if (raw[k] !== undefined)
+                components[k] = raw[k];
+        const author = isObj(raw.author) && typeof raw.author.name === "string" ? cut(raw.author.name, 100) : "";
+        const publisher = author !== "" ? author : ownerName;
+        plugins.push(entry);
+        overlays.set(en, {
+            strict: raw.strict !== false,
+            components,
+            ...(publisher !== undefined && { publisher }),
+        });
+    });
+    if (all.length > MAX_ENTRIES) {
+        // one row for the rest, so the cut is visible on the marketplace
+        skipped.push({ name: `plugins[${MAX_ENTRIES}…${all.length - 1}]`, reason: "invalid_entry" });
+    }
+    const manifest = {
+        schemaVersion: 1,
+        name,
+        ...(ownerName !== undefined && { owner: { name: ownerName } }),
+        ...(description !== "" && { description }),
+        plugins,
+    };
+    return { manifest, overlays, skipped };
+}

package/dist/catalog/claude/mcp.d.ts

@@ -0,0 +1,33 @@
+import { type ConnectorTemplateFile } from "@capybara-hq/plugin-sdk";
+import { type TranslationItem } from "./report.js";
+/**
+ * Claude Code MCP servers -> connector templates for `connector-mcp` (spec §8.3). Only remote
+ * Streamable HTTP servers translate (`type` `http` / `streamable-http`, or a `url` without a type);
+ * `sse`, `ws`, stdio and `.mcpb` / `.dxt` bundles are reported as unsupported transports. `${VAR}`
+ * in headers become the auth fields an org fills at install; nothing secret is ever copied into a
+ * template, and every generated file passes `parseConnectorTemplateFile`.
+ */
+/** The connector extension and kind the generated templates target. */
+export declare const CLAUDE_MCP_CONNECTOR: {
+    readonly plugin: "connector-mcp";
+    readonly connector: "mcp";
+};
+/** Directory of the generated template files in the translated tree. */
+export declare const GENERATED_CONNECTORS_DIR = ".capybara-generated/connectors";
+/** Options of {@link mcpServerTemplates}. */
+export interface McpTemplateOptions {
+    /** Where each server was declared (path relative to the plugin root), for the report. */
+    paths?: ReadonlyMap<string, string>;
+    /** Accept `http://` loopback URLs (tests; `marketplaces.allowInsecureLoopback`). */
+    allowInsecureLoopback?: boolean;
+}
+/**
+ * Translates a merged map of Claude MCP servers (name -> config, later declarations already
+ * applied) into connector template files keyed by template id, plus the report items. `plugin` is
+ * the Claude plugin's name (used in the template description). At most
+ * `PLUGIN_MANIFEST_LIMITS.connectorTemplates` templates; the rest are "too many servers".
+ */
+export declare function mcpServerTemplates(servers: ReadonlyMap<string, unknown> | Record<string, unknown>, plugin: string, opts?: McpTemplateOptions): {
+    files: Map<string, ConnectorTemplateFile>;
+    items: TranslationItem[];
+};

package/dist/catalog/claude/mcp.js

@@ -0,0 +1,226 @@
+import { CATALOG_ITEM_NAME_RE, PLUGIN_MANIFEST_LIMITS, parseConnectorTemplateFile, } from "@capybara-hq/plugin-sdk";
+import { credentialQueryParams } from "../../tools/endpoint.js";
+import { cut, isObj, showName } from "./manifest.js";
+import { item } from "./report.js";
+/**
+ * Claude Code MCP servers -> connector templates for `connector-mcp` (spec §8.3). Only remote
+ * Streamable HTTP servers translate (`type` `http` / `streamable-http`, or a `url` without a type);
+ * `sse`, `ws`, stdio and `.mcpb` / `.dxt` bundles are reported as unsupported transports. `${VAR}`
+ * in headers become the auth fields an org fills at install; nothing secret is ever copied into a
+ * template, and every generated file passes `parseConnectorTemplateFile`.
+ */
+/** The connector extension and kind the generated templates target. */
+export const CLAUDE_MCP_CONNECTOR = { plugin: "connector-mcp", connector: "mcp" };
+/** Directory of the generated template files in the translated tree. */
+export const GENERATED_CONNECTORS_DIR = ".capybara-generated/connectors";
+const VAR_RE = /\$\{([^}:]+)(?::-([^}]*))?\}/g;
+const WHOLE_VAR_RE = /^\$\{([^}:]+)\}$/;
+const BEARER_VAR_RE = /^Bearer \$\{([^}:]+)\}$/;
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+/** `My Server` -> `my-server`; empty -> `mcp`; at most 64 characters, a valid template id. */
+function slug(name) {
+    const s = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60)
+        .replace(/-+$/, "");
+    return s === "" ? "mcp" : s;
+}
+const transportOf = (cfg) => {
+    const t = cfg.type;
+    if (typeof t === "string")
+        return t;
+    if (typeof cfg.url === "string")
+        return null;
+    if (cfg.command !== undefined)
+        return "stdio";
+    return "unknown";
+};
+/**
+ * Translates a merged map of Claude MCP servers (name -> config, later declarations already
+ * applied) into connector template files keyed by template id, plus the report items. `plugin` is
+ * the Claude plugin's name (used in the template description). At most
+ * `PLUGIN_MANIFEST_LIMITS.connectorTemplates` templates; the rest are "too many servers".
+ */
+export function mcpServerTemplates(servers, plugin, opts = {}) {
+    const files = new Map();
+    const items = [];
+    const entries = servers instanceof Map ? [...servers] : Object.entries(servers);
+    for (const [rawName, cfg] of entries) {
+        const name = showName(rawName);
+        const path = opts.paths?.get(rawName);
+        const at = path !== undefined ? { path } : {};
+        const invalid = (reason) => items.push(item("mcp_invalid", "mcpServer", name, { ...at, detail: { reason } }));
+        if (!isObj(cfg)) {
+            invalid("the server configuration is not an object");
+            continue;
+        }
+        const transport = transportOf(cfg);
+        if (transport !== null && transport !== "http" && transport !== "streamable-http") {
+            items.push(item("mcp_unsupported_transport", "mcpServer", name, {
+                ...at,
+                detail: { transport: showName(transport) },
+            }));
+            continue;
+        }
+        if (typeof cfg.url !== "string" || cfg.url === "") {
+            invalid("url must be a string");
+            continue;
+        }
+        if (files.size >= PLUGIN_MANIFEST_LIMITS.connectorTemplates) {
+            invalid("too many servers");
+            continue;
+        }
+        const pending = [];
+        if (transport === null)
+            pending.push(item("mcp_type_assumed", "mcpServer", name, at));
+        // URL: ${VAR:-default} takes the default and makes url editable; a bare ${VAR} cannot be valid.
+        let editable = false;
+        let bare = undefined;
+        const url = cfg.url.replace(VAR_RE, (_m, v, def) => {
+            if (def === undefined) {
+                bare ??= v;
+                return "";
+            }
+            editable = true;
+            pending.push(item("mcp_url_variable", "mcpServer", name, {
+                ...at,
+                detail: { variable: showName(v), default: showName(def) },
+            }));
+            return def;
+        });
+        if (bare !== undefined) {
+            items.push(item("mcp_url_variable", "mcpServer", name, {
+                ...at,
+                detail: { variable: showName(bare) },
+            }));
+            continue;
+        }
+        let parsedUrl;
+        try {
+            parsedUrl = new URL(url);
+        }
+        catch {
+            parsedUrl = undefined;
+        }
+        const urlOk = parsedUrl !== undefined &&
+            (parsedUrl.protocol === "https:" ||
+                (opts.allowInsecureLoopback === true &&
+                    parsedUrl.protocol === "http:" &&
+                    LOOPBACK.has(parsedUrl.hostname)));
+        if (!urlOk) {
+            invalid("url must be an https URL");
+            continue;
+        }
+        // the endpoint is visible to every connector user: no credential may ride in the URL
+        const u = parsedUrl;
+        if (u.username !== "" || u.password !== "") {
+            invalid("the url must not contain a user name or password");
+            continue;
+        }
+        const secretParams = credentialQueryParams(u);
+        if (secretParams.length > 0) {
+            invalid(`the url query parameter ${secretParams.map((k) => JSON.stringify(showName(k))).join(", ")} looks like a credential`);
+            continue;
+        }
+        // Headers: literal ones stay in the endpoint preset; ${VAR} ones become the auth fields.
+        const literal = {};
+        const vars = [];
+        let problem;
+        if (cfg.headers !== undefined) {
+            if (!isObj(cfg.headers))
+                problem = "headers must be an object";
+            else {
+                for (const [h, v] of Object.entries(cfg.headers)) {
+                    if (h === "__proto__") {
+                        problem = "the header name __proto__ is not allowed";
+                        break;
+                    }
+                    if (typeof v !== "string") {
+                        problem = `header ${showName(h)} must be a string`;
+                        break;
+                    }
+                    const bearer = BEARER_VAR_RE.exec(v);
+                    const whole = WHOLE_VAR_RE.exec(v);
+                    if (bearer && h.toLowerCase() === "authorization") {
+                        vars.push({ header: h, variable: bearer[1], bearer: true });
+                    }
+                    else if (whole) {
+                        vars.push({ header: h, variable: whole[1], bearer: false });
+                    }
+                    else if (v.includes("${")) {
+                        problem = `header ${showName(h)} mixes text and a variable`;
+                        break;
+                    }
+                    else
+                        literal[h] = v;
+                }
+            }
+        }
+        if (problem === undefined && cfg.headersHelper !== undefined) {
+            problem = "headersHelper runs a command to produce headers";
+        }
+        const oauth = cfg.oauth !== undefined;
+        if (problem === undefined && oauth && vars.length > 0) {
+            problem = "the server declares both oauth and credential headers";
+        }
+        if (problem !== undefined) {
+            invalid(problem);
+            continue;
+        }
+        let auth;
+        const first = vars[0];
+        if (oauth) {
+            auth = { type: "oauth_code", ownership: "personal", discovery: "mcp", client: "dcr" };
+        }
+        else if (first === undefined) {
+            auth = { type: "none" };
+            pending.push(item("mcp_auth_none", "mcpServer", name, at));
+        }
+        else if (vars.length === 1 && first.bearer) {
+            auth = { type: "bearer", ownership: "personal" };
+        }
+        else if (vars.length === 1) {
+            auth = { type: "api_key", ownership: "personal", in: "header", name: first.header };
+        }
+        else {
+            auth = { type: "headers", ownership: "personal", names: vars.map((v) => v.header) };
+        }
+        for (const v of vars) {
+            pending.push(item("mcp_header_variable", "mcpServer", name, {
+                ...at,
+                detail: { header: showName(v.header), variable: showName(v.variable) },
+            }));
+        }
+        const file = {
+            displayName: { zh: cut(name, 100), en: cut(name, 100) },
+            description: cut(`Remote MCP server ${name} from Claude Code plugin ${plugin}`, 1024),
+            template: {
+                plugin: CLAUDE_MCP_CONNECTOR.plugin,
+                connector: CLAUDE_MCP_CONNECTOR.connector,
+                endpoint: { url, ...(Object.keys(literal).length > 0 && { headers: literal }) },
+                ...(editable && { editableEndpoint: ["url"] }),
+                auth,
+            },
+        };
+        const parsed = parseConnectorTemplateFile(file);
+        if ("errors" in parsed) {
+            invalid(parsed.errors[0] ?? "the generated template is not valid");
+            continue;
+        }
+        let id = slug(rawName);
+        for (let n = 2; files.has(id); n++)
+            id = `${slug(rawName).slice(0, 60)}-${n}`;
+        if (!CATALOG_ITEM_NAME_RE.test(id)) {
+            invalid("no valid template id");
+            continue;
+        }
+        files.set(id, parsed);
+        items.push(item("mcp_template", "mcpServer", name, {
+            path: `${GENERATED_CONNECTORS_DIR}/${id}.json`,
+            detail: { template: id, auth: String(auth.type) },
+        }), ...pending);
+    }
+    return { files, items };
+}