mcplane 0.4.0 → 0.5.0

package/dist/publish.js

@@ -233,15 +233,24 @@ function prepared(m, store) {
         return { store, done: false, lines: [`smithery mcp publish ${m.server.url} -n @<your-org>/${m.name}`, 'Or at https://smithery.ai/new. If Smithery’s scan can’t get past your sign-in, serve /.well-known/mcp/server-card.json describing your tools.'] };
     }
     if (store === 'glama') {
+        const reg = registryName(m);
         const owner = gh?.owner ?? '<your-github-user>';
+        const domainNs = !reg.startsWith('io.github.');
+        const domain = reg.split('/')[0].split('.').reverse().join('.');
         return {
             store,
             done: false,
             lines: [
-                `Hosted servers: Glama imports a connector from the official registry at https://glama.ai/mcp/connectors/${registryName(m)}. Publish there first, then claim it.`,
-                `Code on GitHub: add ${gh ? `https://github.com/${gh.owner}/${gh.repo}` : 'the repo'} at https://glama.ai/mcp/servers ("Add MCP Server"); Glama checks license, security and health, and scores it.`,
-                'To claim either, commit glama.json at the repo root:',
-                JSON.stringify({ $schema: 'https://glama.ai/mcp/schemas/server.json', maintainers: [owner] }, null, 2),
+                `Hosted server: Glama imports it from the official registry as a connector, https://glama.ai/mcp/connectors/${reg}. Publish there first.`,
+                domainNs
+                    ? `To claim it: open that page, choose Claim ownership, sign in, and verify ${domain} with the token Glama shows, either as a TXT record at _glama-claim.${domain} or as https://${domain}/.well-known/glama.json ({"$schema":"https://glama.ai/mcp/schemas/connector.json","claim":"glama_claim_…"}). One verification covers every connector under the domain.`
+                    : `To claim it: open that page, choose Claim ownership and "Claim with GitHub" as ${reg.split('/')[0].slice('io.github.'.length)}. An organisation also needs the Glama GitHub App installed.`,
+                ...(gh
+                    ? [
+                        `Server code on GitHub is a separate listing: add https://github.com/${gh.owner}/${gh.repo} at https://glama.ai/mcp/servers ("Add MCP Server") and claim it with glama.json at the repo root:`,
+                        JSON.stringify({ $schema: 'https://glama.ai/mcp/schemas/server.json', maintainers: [owner] }, null, 2),
+                    ]
+                    : []),
                 'Both awesome lists require the Glama badge on each entry, so do this first.',
             ],
         };

package/dist/report.js

@@ -1,25 +1,41 @@
 import { STORE_NAMES } from './types.js';
 const tty = process.stdout.isTTY;
 const c = (code, s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : s);
-const MARK = { pass: c('32', '✓'), warn: c('33', '!'), fail: c('31', '✗'), skip: c('90', '-') };
-export function printPreflight(r, opts = {}) {
-    const fails = r.checks.filter((x) => x.level === 'fail');
-    const warns = r.checks.filter((x) => x.level === 'warn');
-    console.log(c('1', `Preflight for ${r.stores.map((s) => STORE_NAMES[s]).join(', ')}`));
-    console.log('');
-    for (const x of r.checks) {
-        if (x.level === 'pass' && !opts.verbose)
+const MARK = { pass: c('32', '✓'), warn: c('33', '!'), fail: c('31', '✗'), skip: c('90', '-'), info: c('36', 'i') };
+/** Readiness for the next MCP revision gets its own section, so it never reads as a store requirement. */
+const isReadiness = (x) => x.id.startsWith('readiness.');
+function printChecks(checks, verbose, indent = '') {
+    for (const x of checks) {
+        if (x.level === 'pass' && !verbose)
             continue;
         const where = x.stores?.length ? c('90', ` [${x.stores.map((s) => STORE_NAMES[s]).join(', ')}]`) : '';
-        console.log(`${MARK[x.level]} ${x.title}${where}`);
+        console.log(`${indent}${MARK[x.level]} ${x.title}${where}`);
         if (x.detail)
-            console.log(c('90', `    ${x.detail}`));
+            console.log(c('90', `${indent}    ${x.detail}`));
         if (x.fix && x.level !== 'pass')
-            console.log(`    ${x.fix}`);
+            console.log(`${indent}    ${x.fix}`);
     }
-    const passed = r.checks.length - fails.length - warns.length;
+}
+export function printPreflight(r, opts = {}) {
+    const fails = r.checks.filter((x) => x.level === 'fail');
+    const warns = r.checks.filter((x) => x.level === 'warn');
+    const notes = r.checks.filter((x) => x.level === 'info');
+    const main = r.checks.filter((x) => !isReadiness(x));
+    const ready = r.checks.filter(isReadiness);
+    console.log(c('1', `Preflight for ${r.stores.map((s) => STORE_NAMES[s]).join(', ')}`));
+    console.log('');
+    printChecks(main, opts.verbose);
+    const passed = main.filter((x) => x.level === 'pass').length;
     if (!opts.verbose && passed)
         console.log(c('32', `✓ ${passed} checks passed`) + c('90', ' (--verbose to list them)'));
+    if (ready.length) {
+        console.log('');
+        console.log(c('1', 'Readiness for MCP 2026-07-28') + c('90', ' (never blocking)'));
+        printChecks(ready, opts.verbose, '  ');
+        const ok = ready.filter((x) => x.level === 'pass').length;
+        if (!opts.verbose && ok)
+            console.log(`  ${c('32', `✓ ${ok} ready`)}`);
+    }
     if (r.reminders.length) {
         console.log('');
         console.log(c('1', 'Check these yourself'));
@@ -27,5 +43,6 @@ export function printPreflight(r, opts = {}) {
             console.log(`  • ${t}`);
     }
     console.log('');
-    console.log(fails.length ? c('31', `${fails.length} blocking, ${warns.length} to review.`) : warns.length ? c('33', `No blockers, ${warns.length} to review.`) : c('32', 'Ready to submit.'));
+    const noteLine = notes.length ? `, ${notes.length} note${notes.length === 1 ? '' : 's'}` : '';
+    console.log(fails.length ? c('31', `${fails.length} blocking, ${warns.length} to review${noteLine}.`) : warns.length ? c('33', `No blockers, ${warns.length} to review${noteLine}.`) : c('32', `Ready to submit${noteLine ? ` (${notes.length} note${notes.length === 1 ? '' : 's'})` : ''}.`));
 }

package/dist/skills.d.ts

@@ -0,0 +1,21 @@
+import type { ZipEntry } from './zip.js';
+export type FrontMatter = {
+    data: Record<string, unknown>;
+    body: string;
+} | {
+    error: string;
+};
+/**
+ * Reads SKILL.md front matter: the YAML a skill loader sees, for the subset skills use (plain,
+ * quoted and block scalars, nested maps and lists). A plain value holding ": " is an error, as in
+ * YAML itself, because strict loaders refuse the whole skill over it.
+ */
+export declare function frontMatter(raw: string): FrontMatter;
+export interface SkillBundle {
+    files: ZipEntry[];
+    names: string[];
+    problems: string[];
+    todo: string[];
+}
+/** Reads, checks and lays out skills for skills/<folder>/ in a plugin package. */
+export declare function bundleSkills(spec: string | string[] | undefined, dir: string, pluginName: string): Promise<SkillBundle>;

package/dist/skills.js

@@ -0,0 +1,180 @@
+/**
+ * Agent Skills for plugin packages: each skill is a folder with a SKILL.md, bundled under
+ * skills/<folder>/ with its scripts and references, executable bits kept. Checked against the
+ * Agent Skills spec (agentskills.io) and the skill rules in OpenAI's submission errors.
+ */
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { basename, join, relative, resolve, sep } from 'node:path';
+/** Front matter fields the Agent Skills spec defines. */
+const SPEC_FIELDS = new Set(['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools']);
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const DESCRIPTION_MAX = 1024;
+/** Noise and bulk that never belongs in a package. */
+const SKIPPED = new Set(['.DS_Store', 'Thumbs.db', 'node_modules', '.git']);
+function unquoteDouble(s) {
+    try {
+        return JSON.parse(s.replace(/\\'/g, "'").replace(/\\\n/g, ''));
+    }
+    catch {
+        return s.slice(1, -1);
+    }
+}
+/**
+ * Reads SKILL.md front matter: the YAML a skill loader sees, for the subset skills use (plain,
+ * quoted and block scalars, nested maps and lists). A plain value holding ": " is an error, as in
+ * YAML itself, because strict loaders refuse the whole skill over it.
+ */
+export function frontMatter(raw) {
+    const lines = raw.replace(/^/, '').replace(/\r\n/g, '\n').split('\n');
+    if (lines[0].trimEnd() !== '---')
+        return { error: 'SKILL.md must start with front matter between --- lines' };
+    const close = lines.findIndex((l, i) => i > 0 && /^(---|\.\.\.)\s*$/.test(l));
+    if (close < 0)
+        return { error: 'the front matter has no closing --- line' };
+    const fm = lines.slice(1, close);
+    const data = {};
+    for (let i = 0; i < fm.length; i++) {
+        const line = fm[i];
+        if (!line.trim() || /^\s*#/.test(line))
+            continue;
+        const m = /^([A-Za-z0-9_-]+)\s*:(?:[ \t]+(.*))?$/.exec(line);
+        if (!m)
+            return { error: `front matter line ${i + 2} isn't "key: value": ${line.trim().slice(0, 60)}` };
+        const key = m[1];
+        const value = (m[2] ?? '').trim();
+        const more = [];
+        while (i + 1 < fm.length && (fm[i + 1].trim() === '' || /^\s/.test(fm[i + 1])))
+            more.push(fm[++i]);
+        while (more.length && !more[more.length - 1].trim())
+            more.pop();
+        if (/^[|>][+-]?\d*(\s+#.*)?$/.test(value)) {
+            const indent = Math.min(...more.filter((l) => l.trim()).map((l) => l.length - l.trimStart().length));
+            const body = more.map((l) => l.slice(Number.isFinite(indent) ? indent : 0));
+            data[key] = value.startsWith('|') ? body.join('\n') : body.reduce((s, l) => (!l.trim() ? `${s}\n` : s && !s.endsWith('\n') ? `${s} ${l}` : `${s}${l}`), '');
+        }
+        else if (!value && more.length) {
+            const items = more.filter((l) => l.trim());
+            data[key] = items.every((l) => /^\s*-\s/.test(l))
+                ? items.map((l) => l.replace(/^\s*-\s+/, '').trim())
+                : Object.fromEntries(items.map((l) => /^\s*([^:]+):\s*(.*)$/.exec(l)).filter(Boolean).map((r) => [r[1].trim(), r[2].trim().replace(/^(["'])(.*)\1$/, '$2')]));
+        }
+        else if (value.startsWith('"')) {
+            data[key] = unquoteDouble([value, ...more.map((l) => l.trim())].join(' '));
+        }
+        else if (value.startsWith("'")) {
+            data[key] = [value, ...more.map((l) => l.trim())].join(' ').slice(1, -1).replace(/''/g, "'");
+        }
+        else {
+            const text = [value, ...more.map((l) => l.trim())].join(' ').replace(/\s+#.*$/, '');
+            if (/:\s/.test(text))
+                return { error: `"${key}" holds ": " without quotes, which YAML reads as a nested key; quote the value` };
+            data[key] = text;
+        }
+    }
+    return { data, body: lines.slice(close + 1).join('\n') };
+}
+async function walk(root, problems, skipped, at = root) {
+    const out = [];
+    for (const name of (await readdir(at)).sort()) {
+        const abs = join(at, name);
+        const inner = relative(root, abs).split(sep).join('/');
+        if (SKIPPED.has(name))
+            continue;
+        if (name.startsWith('.')) {
+            skipped.push(inner);
+            continue;
+        }
+        const st = await lstat(abs);
+        if (st.isSymbolicLink())
+            problems.push(`${basename(root)}/${inner} is a symbolic link; packages can't hold one (OpenAI ignores the skill). Copy the file in instead`);
+        else if (st.isDirectory())
+            out.push(...(await walk(root, problems, skipped, abs)));
+        else if (st.isFile())
+            out.push({ inner, abs, mode: st.mode & 0o111 ? 0o755 : 0o644 });
+    }
+    return out;
+}
+/** Skill folders from the manifest setting: one folder of skills, or a list of skill folders. Null when the folder isn't there. */
+async function skillDirs(spec, dir) {
+    if (Array.isArray(spec))
+        return spec.map((p) => resolve(dir, p));
+    const parent = resolve(dir, spec);
+    const names = await readdir(parent).catch(() => null);
+    if (!names)
+        return null;
+    const dirs = [];
+    for (const n of names.sort())
+        if (!n.startsWith('.') && !SKIPPED.has(n) && (await lstat(join(parent, n))).isDirectory())
+            dirs.push(join(parent, n));
+    return dirs;
+}
+/** Reads, checks and lays out skills for skills/<folder>/ in a plugin package. */
+export async function bundleSkills(spec, dir, pluginName) {
+    const out = { files: [], names: [], problems: [], todo: [] };
+    if (spec === undefined)
+        return out;
+    const dirs = await skillDirs(spec, dir);
+    if (!dirs) {
+        out.problems.push(`chatgpt.skills: ${spec} isn't a folder (paths are relative to mcplane.json)`);
+        return out;
+    }
+    if (!dirs.length && typeof spec === 'string')
+        out.todo.push(`chatgpt.skills: ${spec} holds no skill folders, so the package has no skills.`);
+    const seen = new Map();
+    for (const root of dirs) {
+        const folder = basename(root);
+        const where = `skills/${folder}`;
+        const st = await lstat(root).catch(() => null);
+        if (!st?.isDirectory()) {
+            out.problems.push(`${where}: ${relative(dir, root) || root} isn't a folder`);
+            continue;
+        }
+        const skipped = [];
+        const found = await walk(root, out.problems, skipped);
+        if (skipped.length)
+            out.todo.push(`Left out of ${where}: ${skipped.join(', ')} (hidden files never go in the package).`);
+        const md = found.find((f) => f.inner === 'SKILL.md');
+        if (!md) {
+            out.problems.push(`${where} has no SKILL.md`);
+            continue;
+        }
+        const raw = await readFile(md.abs, 'utf8');
+        const fm = frontMatter(raw);
+        if ('error' in fm) {
+            out.problems.push(`${where}/SKILL.md: ${fm.error}`);
+            continue;
+        }
+        const { name, description } = fm.data;
+        if (typeof name !== 'string' || !name.trim())
+            out.problems.push(`${where}/SKILL.md: "name" is required`);
+        else {
+            if (!NAME.test(name) || name.length > 64)
+                out.problems.push(`${where}/SKILL.md: name "${name}" must be lowercase letters, digits and single hyphens, at most 64 characters`);
+            if (name !== folder)
+                out.problems.push(`${where}/SKILL.md: name "${name}" doesn't match its folder "${folder}"; the Agent Skills spec requires a match, and strict clients skip the skill`);
+            if (`${pluginName}:${name}`.length > 64)
+                out.problems.push(`${where}: "${pluginName}:${name}" is over 64 characters, OpenAI's limit for a skill's full name`);
+            if (seen.has(name))
+                out.problems.push(`${where}: the name "${name}" is also used by ${seen.get(name)}`);
+            seen.set(name, where);
+            out.names.push(name);
+        }
+        if (typeof description !== 'string' || !description.trim())
+            out.problems.push(`${where}/SKILL.md: "description" is required`);
+        else if (description.trim().length > DESCRIPTION_MAX)
+            out.problems.push(`${where}/SKILL.md: the description is ${description.trim().length} characters; the limit is ${DESCRIPTION_MAX}`);
+        if (!fm.body.trim())
+            out.problems.push(`${where}/SKILL.md has no instructions after the front matter`);
+        const extra = Object.keys(fm.data).filter((k) => !SPEC_FIELDS.has(k));
+        if (extra.length)
+            out.todo.push(`${where}/SKILL.md: ${extra.map((k) => `"${k}"`).join(', ')} ${extra.length === 1 ? "isn't" : "aren't"} in the Agent Skills spec. OpenAI ignores unknown fields, but strict clients may refuse the skill.`);
+        const own = new Set(found.map((f) => f.inner));
+        for (const ref of new Set([...raw.matchAll(/\bscripts\/[A-Za-z0-9._/-]*[A-Za-z0-9_-]/g)].map((r) => r[0]))) {
+            if (!own.has(ref))
+                out.problems.push(`${where}/SKILL.md refers to ${ref}, which isn't in the skill's folder. Installed on its own, the skill can't run it`);
+        }
+        for (const f of found)
+            out.files.push({ path: `${where}/${f.inner}`, data: await readFile(f.abs), mode: f.mode });
+    }
+    return out;
+}

package/dist/submissions.js

@@ -17,6 +17,7 @@ const RT_SLUG = {
     'claude-plugins': 'claude-plugins',
     cursor: 'cursor',
     muse: 'muse',
+    'vercel-connect': 'vercel-connect',
 };
 const TRACKED_FROM_GITHUB = ['grok', 'docker'];
 export async function load(dir = process.cwd()) {
@@ -36,7 +37,7 @@ const today = () => new Date().toISOString().slice(0, 10);
 function listingRef(m, store, appId) {
     if (store === 'chatgpt')
         return appId;
-    if (store === 'claude-connectors' || store === 'muse')
+    if (store === 'claude-connectors' || store === 'muse' || store === 'vercel-connect')
         return m.server.url;
     if (store === 'claude-plugins' || store === 'cursor')
         return m.repository;

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-export type Level = 'pass' | 'warn' | 'fail' | 'skip';
+/** info: optional or advisory. It never blocks and isn't counted as something to review. */
+export type Level = 'pass' | 'warn' | 'fail' | 'skip' | 'info';
 export interface Check {
     id: string;
     level: Level;
@@ -10,7 +11,7 @@ export interface Check {
     /** The stores this matters for; empty means all. */
     stores?: StoreId[];
 }
-export type StoreId = 'mcp-registry' | 'chatgpt' | 'claude-connectors' | 'claude-plugins' | 'cursor' | 'grok' | 'docker' | 'muse' | 'smithery' | 'glama' | 'cline' | 'lobehub' | 'awesome-mcp-servers' | 'awesome-remote-mcp-servers';
+export type StoreId = 'mcp-registry' | 'chatgpt' | 'claude-connectors' | 'claude-plugins' | 'cursor' | 'grok' | 'docker' | 'muse' | 'smithery' | 'glama' | 'cline' | 'lobehub' | 'awesome-mcp-servers' | 'awesome-remote-mcp-servers' | 'vercel-connect';
 export declare const STORE_NAMES: Record<StoreId, string>;
 export interface Manifest {
     $schema?: string;
@@ -23,6 +24,11 @@ export interface Manifest {
     server: {
         url: string;
         auth?: 'none' | 'oauth';
+        /**
+         * Sign-in pages and identity-provider URLs your consent screen sends people to (e.g. https://accounts.example.com/sign-in).
+         * Preflight GETs them with the authorization endpoint to find bot challenges and 403s reviewers would hit.
+         */
+        signIn?: string[];
     };
     repository?: string;
     author?: {
@@ -36,6 +42,7 @@ export interface Manifest {
         terms?: string;
         docs?: string;
     };
+    /** A direct image URL. The ChatGPT package also takes a local path, relative to mcplane.json. */
     icon?: string;
     prompts?: string[];
     stores?: StoreId[];
@@ -54,7 +61,10 @@ export interface Manifest {
             prompt: string;
         }[];
     };
-    /** Hand-written ChatGPT hint justifications, per tool; they replace mcplane's drafts. */
+    /**
+     * @deprecated OpenAI no longer asks for hint justifications. Still accepted: the ChatGPT pack lists them
+     * as optional notes for an appeal if review flags a hint.
+     */
     justifications?: Record<string, {
         readOnly?: string;
         openWorld?: string;
@@ -77,9 +87,15 @@ export interface Manifest {
         /** #RRGGBB with 2:1 contrast against white; the dark one against #212121. */
         brandColor?: string;
         brandColorDark?: string;
-        /** Direct image URLs; default to "icon". */
+        /** Image URLs or local paths (relative to mcplane.json), bundled into the package. logo and composerIcon default to "icon". */
+        logo?: string;
         composerIcon?: string;
         logoDark?: string;
+        /**
+         * Agent Skills to bundle under skills/ in the package: a folder whose subfolders each hold a SKILL.md,
+         * or a list of skill folders. Paths are relative to mcplane.json.
+         */
+        skills?: string | string[];
         /** Reviewer-accessible video URL showing the main use cases (required for review). */
         demoVideo?: string;
         commerce?: boolean;
@@ -100,6 +116,23 @@ export interface Manifest {
         keywords?: string[];
         domains?: string[];
     };
+    /** Vercel Connect's Submit a Service form fields with no shared equivalent. */
+    vercelConnect?: {
+        /** Base URL of a REST API your users also call, listed as a second target. */
+        apiBase?: string;
+        /** Default scopes for the OAuth method. Defaults to the discovery document's scopes_supported. */
+        scopes?: string[];
+        /** Offer an API key connection method: where users create a key, and the header it's sent in. */
+        apiKey?: {
+            docs?: string;
+            header?: string;
+        };
+    };
+    /** The Claude Code plugin that ships this server, for "mcplane pack claude-eval". Read from the plugin repo when left out. */
+    claudePlugin?: {
+        name?: string;
+        server?: string;
+    };
     /** Named workflows, run with "mcplane <lane>": each step is a command line without "mcplane". */
     lanes?: Record<string, string[]>;
     /** How reviewers get in, for servers behind sign-in. Never put the password here; say where it lives. */

package/dist/types.js

@@ -13,4 +13,5 @@ export const STORE_NAMES = {
     lobehub: 'LobeHub Market',
     'awesome-mcp-servers': 'awesome-mcp-servers',
     'awesome-remote-mcp-servers': 'awesome-remote-mcp-servers',
+    'vercel-connect': 'Vercel Connect',
 };

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.4.0';
+export const VERSION = '0.5.0';

package/dist/video.d.ts

@@ -0,0 +1,58 @@
+/** One screencast frame: a JPEG relative to the work folder, and when it was shown (seconds). */
+export interface Frame {
+    file: string;
+    ts: number;
+}
+export interface Scene {
+    caption: string;
+    frames: Frame[];
+    /** When recording stopped; the last frame is held until then. */
+    end: number;
+}
+/** ffmpeg's concat-demuxer list: each frame held until the next one, the last until `end`. */
+export declare function concatList(frames: Frame[], end: number): string;
+/** How long a scene runs once assembled. */
+export declare function sceneSeconds(s: Scene): number;
+/**
+ * Escapes a value for a filter option inside an ffmpeg filtergraph. Two levels:
+ * the option value (\ ' :) and then the filtergraph itself (\ ' [ ] , ;).
+ */
+export declare function ffEscape(value: string): string;
+/**
+ * A caption as at most `maxLines` lines of about `width` characters. Control
+ * characters become spaces (drawtext would draw them as boxes); anything that
+ * doesn't fit ends in an ellipsis.
+ */
+export declare function wrapCaption(text: string, width?: number, maxLines?: number): string[];
+/** Width and height from a JPEG's start-of-frame marker. */
+export declare function jpegSize(b: Uint8Array): {
+    width: number;
+    height: number;
+} | null;
+/** Even dimensions (H.264 needs them) within the maximum, keeping the aspect ratio. */
+export declare function outputSize(width: number, height: number, maxWidth?: number, maxHeight?: number): {
+    width: number;
+    height: number;
+};
+export declare function findFfmpeg(path?: string): string | null;
+/** Text colours that read on a background, given as 0xRRGGBB: light on dark, dark on light. */
+export declare function inkFor(bg: string): {
+    text: string;
+    muted: string;
+};
+/**
+ * Builds the video in `work` (where the frames are) and writes it to `out`.
+ * Every part is encoded the same way so they join without re-encoding.
+ */
+export declare function buildVideo(o: {
+    scenes: Scene[];
+    title: string;
+    subtitle?: string;
+    out: string;
+    work: string;
+    ffmpeg: string;
+    size: {
+        width: number;
+        height: number;
+    };
+}): Promise<number>;