mcplane 0.1.0 → 0.3.0

package/README.md

@@ -7,6 +7,8 @@ npx mcplane init --url https://mcp.example.com/mcp
 npx mcplane preflight
 ```
 
+No terminal handy? Paste your URL at [reviewtimes.fyi/check](https://reviewtimes.fyi/check).
+
 ```
 ✗ DNS does not advertise Encrypted ClientHello [ChatGPT]
     example.com has ech= in its HTTPS record
@@ -44,7 +46,7 @@ Cursor, VS Code and others: add a stdio server with command `npx` and args `["-y
 
 Then run the **onboard** prompt (`/mcp__mcplane__onboard` in Claude Code). The agent creates `mcplane.json` and reads your code. It writes the listing copy and the review test cases (ChatGPT wants exactly 5 positive and 3 negative), runs preflight and fixes what it can. The **ship** prompt takes it from there: check, pack, publish, and a short list of what's left for you.
 
-Tools: `preflight`, `drift`, `pack`, `publish`, `record_submission`, `record_decision`, `submission_status`, `install_links`, `pull_listings`, `init`, `fleet`. Every tool takes an optional `project` folder, so one mcplane serves all your apps. Annotations are honest: `publish` and `record_*` are marked open-world, and `publish` does nothing without `confirm: true`.
+Tools: `preflight`, `drift`, `pack`, `publish`, `record_submission`, `record_decision`, `submission_status`, `install_links`, `listings`, `init`, `fleet`. Every tool takes an optional `project` folder, so one mcplane serves all your apps. Annotations are honest: `publish` and `record_*` are marked open-world, and `publish` does nothing without `confirm: true`.
 
 ## Many apps
 
@@ -53,10 +55,11 @@ npx mcplane fleet --root ~/Projects
 ```
 
 ```
-✓ Review Times             preflight clean · live on chatgpt
-✗ Invoice Bot              2 blocking · waiting on claude-connectors
-✗ Weather Pro              1 store update needed
-    chatgpt: Tools changed since the live version (v1.2.0) on 2026-09-02: added forecast_hourly
+✓ Review Times             preflight clean · listed on mcp-registry, glama, chatgpt
+✗ Invoice Bot              2 blocking · waiting on claude-connectors · listed on mcp-registry
+✗ Weather Pro              1 store update needed · listed on mcp-registry, claude-connectors · 1 listing fix
+    chatgpt: Hints changed: send_alert
+    claude-connectors: listing doesn't show: forecast_hourly (ask the review team to resync)
 
 3 projects, 2 need attention.
 ```
@@ -67,13 +70,14 @@ npx mcplane fleet --root ~/Projects
 
 | Store | How mcplane gets you there | Keeping it current |
 |---|---|---|
-| Official MCP Registry | **Publishes**: writes `server.json`, runs `mcp-publisher`, signs in with GitHub OIDC in Actions. GitHub's MCP Registry (VS Code), PulseMCP and MCP.Directory read from it | Versions can't change: bump, or a prerelease like `1.2.0-1` for listing-only edits. mcplane checks what's already published |
+| Official MCP Registry | **Publishes**: writes `server.json`, runs `mcp-publisher`, signs in with GitHub OIDC in Actions. Glama and PulseMCP import from it; GitHub's MCP gallery (VS Code) syncs it after a one-time manual onboarding | Versions can't change: bump, or a prerelease like `1.2.0-1` for listing-only edits. mcplane checks what's already published |
 | Grok plugins | **Publishes**: opens the pull request to `xai-org/plugin-marketplace`, validated with xAI's own scripts | Opens a pin-bump PR when xAI's daily bump lags |
 | ChatGPT | **Prepares** `chatgpt-app-submission.json` for the portal's import: listing, tools, hint justifications, 5+3 tests | Tool changes roll out after OpenAI's automated checks. Listing text and hint justifications need a new version, and drift says when |
 | Claude connectors | **Prepares** every field of the directory form | Tool changes are live on deploy; listing edits (tool names included) are reviewed |
 | Claude plugins | **Prepares** and checks the plugin repo | The portal tracks your branch; drift tells you a new version is waiting for review |
 | Cursor | **Prepares** and checks the plugin repo | Pinned to the commit first added; drift flags when you've moved on |
 | Muse | **Prepares** the form | Flags changes |
+| awesome-remote-mcp-servers | The three-line entry with your Glama connector badge and auth marker, ready for the PR | |
 | Cline, Glama, LobeHub, Smithery, Docker, awesome-mcp-servers | The prefilled issue, `glama.json`, CLI command or entry | |
 | mcp.so, MCP Market, mcpservers.org, cursor.directory | `mcplane pack directories`: one sheet with every value to paste | |
 
@@ -83,14 +87,41 @@ npx mcplane fleet --root ~/Projects
 
 Checks come from real rejections, most of them ours:
 
-- **Server**: `initialize`, `tools/list` and `ping` work. Unknown methods return `-32601` (OpenAI's tool scan probes `server/discover` and gives up on a crash). The URL works with a trailing slash. CORS preflight answers. Automated clients aren't blocked by a bot filter. A TLS 1.2 client connects. DNS doesn't advertise Encrypted ClientHello, which review proxies reset without a trace in your logs.
+- **Server**: `initialize`, `tools/list` and `ping` work. An OAuth server that initializes without a token also lists its tools without one (the half-way state leaves a new ChatGPT connector stuck on "no actions available"). Unknown methods return `-32601` (OpenAI's tool scan probes `server/discover` and gives up on a crash). The URL works with a trailing slash. CORS preflight answers. Automated clients aren't blocked by a bot filter. A TLS 1.2 client connects. DNS doesn't advertise Encrypted ClientHello, which review proxies reset without a trace in your logs.
 - **OAuth**: unauthenticated calls get `401` with `resource_metadata`. Protected-resource and authorization-server metadata resolve, and PKCE S256 is supported. With `--register`, Dynamic Client Registration is tested, including the `cursor://` and other native redirect schemes that locked out every desktop client for us.
 - **Tools**: every tool has a title and explicit `readOnlyHint`, `destructiveHint` and `openWorldHint`, and the hints are consistent. Tools declare `outputSchema`. Descriptions don't instruct the model. Writes aren't authorised by a token passed through the chat (Anthropic rejected exactly that). Hints follow OpenAI's current definitions: `openWorldHint` for anything that reaches the public internet (read-only web search included), `destructiveHint` for messages that can't be unsent. No catch-all request tools, no tool names over 64 characters, no sensitive inputs, no upgrade or pricing copy.
-- **Listing**: the icon is a square PNG of at least 512px behind a direct link, and `/favicon.ico` resolves. The privacy policy covers collection, retention and user controls. Support is a web page. Name, subtitle, one-liner, description and starter prompts fit each store's limits. The ChatGPT domain challenge is served.
+- **Listing**: the icon is a square PNG of at least 512px behind a direct link, and `/favicon.ico` resolves. The privacy policy covers collection, retention and user controls. Support is a web page. Name, subtitle, one-liner, description and starter prompts fit each store's limits. Every test case uses tools the live server actually has. The ChatGPT domain challenge is served.
 - **Plugin repo**: public, on GitHub, with `.claude-plugin/plugin.json`, and no root `SKILL.md` shadowing the plugin's skills. Grok plugins come from an organisation.
 
 `--json` for machines; exit code 1 when something blocks.
 
+Preflight also lists what no script can see and that has still cost real submissions. For example: a reviewer account a stranger can actually use (not your Google login, email already confirmed, no 2FA), and a safe target for write tools so reviewers don't post to a real timeline.
+
+## Where you're listed
+
+```sh
+mcplane listings
+```
+
+```
+✗ Official MCP Registry        listed
+    latest is v1.0.0, mcplane.json says v1.0.1
+✓ Glama                        listed  (Imported from the registry. Claim it with glama.json so the score badge is yours.)
+✗ Claude connectors            listed  (tier: community)
+    listing doesn't show: forecast_hourly (ask the review team to resync)
+· Cursor Marketplace           missing
+? ChatGPT                      unknown  (OpenAI's directory can't be read automatically. Open your plugin page and compare.)
+```
+
+A form that returned 200 is a claim; the public record is the result. `listings` reads every store with an open record and compares it with your live server and `mcplane.json`:
+- MCP Registry: versions, status, endpoint.
+- Claude: the connectors directory feed, including the tool inventory synced at submission, which you can't edit yourself; and the community plugin mirror.
+- Cursor and Grok.
+- Glama's registry import.
+- Both awesome lists and Docker's catalog.
+
+Coverage decays quietly, so run it on a schedule (`--ci` exits 1 on a mismatch). `fleet` runs it for every project.
+
 ## Keeping listings current
 
 Every store calls your live server, so fixes reach users on their own. What doesn't: listing text, tool names in Claude's listing, ChatGPT's hint justifications, registry versions and plugins pinned to a commit. Each store has different rules for these. When you record a submission, mcplane snapshots what the store is reviewing. `mcplane drift` compares your live server and `mcplane.json` against that snapshot and tells you what each store needs.
@@ -115,7 +146,7 @@ Like fastlane's lanes: named workflows in `mcplane.json`.
 }
 ```
 
-`mcplane release` runs the steps in order and stops at the first failure. A `?` step may fail without stopping the lane. `handoff:` steps are listed at the end as your to-do. `check` and `release` are built in.
+`mcplane release` runs the steps in order and stops at the first failure. A `?` step may fail without stopping the lane. `handoff:` steps are listed at the end as your to-do. `check`, `watch` and `release` are built in.
 
 ## CI
 
@@ -132,6 +163,21 @@ jobs:
           command: check   # preflight + drift --ci
 ```
 
+And weekly, to catch listings that went stale:
+
+```yaml
+on:
+  schedule: [{ cron: '0 9 * * 1' }]
+jobs:
+  listings:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: stevysmith/mcplane@v0
+        with:
+          command: watch   # listings --ci + drift --ci
+```
+
 Publishing to the MCP Registry from CI needs no secrets for `io.github.*` names:
 
 ```yaml
@@ -166,7 +212,7 @@ decided <store> <outcome>     approved | rejected | withdrawn
 status                        Your submissions, days waited, each store's typical wait
 drift [--ci]                  What each store needs since it last saw your server
 baseline <store>              Mark an existing live listing as the drift baseline
-pull                          Compare live public listings with mcplane.json
+listings [--ci]               Where you're listed, and whether what went live matches
 try                           Install links for every client, for you and your testers
 fleet [--root <dir>]          Every project at a glance (--quick, --json, --ci)
 fleet run <command...>        Run a command in every project
@@ -176,6 +222,17 @@ mcp                           Run as an MCP server over stdio
 
 Servers behind sign-in: pass `--token` or set `MCPLANE_TOKEN` so tool checks can run.
 
+## Use the checks in your own code
+
+`mcplane/core` runs anywhere with `fetch` (Workers, Deno, Bun, Node):
+
+```ts
+import { draftManifest, preflight } from 'mcplane/core';
+const report = await preflight(await draftManifest('https://mcp.example.com/mcp'));
+```
+
+It's what powers [reviewtimes.fyi/check](https://reviewtimes.fyi/check). The TLS 1.2 handshake needs a raw socket, so only the CLI runs that one.
+
 ## mcplane.json
 
 One file describes your server and its listings. [`schema.json`](schema.json) gives editors completion and validation; `mcplane init` adds the `$schema` line. [`examples/mcplane.json`](examples/mcplane.json) is a complete one, from [Review Times](https://reviewtimes.fyi)' own ChatGPT and Claude submissions.
@@ -186,7 +243,7 @@ One file describes your server and its listings. [`schema.json`](schema.json) gi
 |---|---|
 | `precheck` | `preflight` |
 | `deliver` + metadata in the repo | `mcplane.json`, `pack`, `publish` |
-| `download_metadata` | `pull` |
+| `download_metadata` | `listings`: reads what went live back and diffs it |
 | `pilot` (TestFlight testers) | `try`: install links for every client |
 | Fastfile lanes | `lanes` |
 | `fastlane init` | `init`, and the **onboard** prompt that writes the listing for you |

package/dist/checks/auth.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OAuth checks, from Stacktree's ChatGPT rounds. Read-only by default:
+ * registering a client writes to your authorization server, so that only
+ * happens with --register.
+ */
+import type { Check } from '../types.js';
+export declare function authChecks(url: string, opts?: {
+    register?: boolean;
+}): Promise<Check[]>;

package/dist/checks/listing.d.ts

@@ -0,0 +1,4 @@
+import type { Check, Manifest, StoreId, Tool } from '../types.js';
+export declare function listingChecks(m: Manifest, tools: Tool[], stores: StoreId[]): Promise<Check[]>;
+/** Rules for plugin repositories (Claude plugins, Cursor, Grok). */
+export declare function repoChecks(m: Manifest, stores: StoreId[]): Promise<Check[]>;

package/dist/checks/listing.js

@@ -106,6 +106,15 @@ export async function listingChecks(m, tools, stores) {
     if (has(stores, 'claude-connectors', 'claude-plugins'))
         len(m.oneLiner, 200, 'listing.one-liner', 'One-liner', ['claude-connectors', 'claude-plugins']);
     len(m.description, 2000, 'listing.description', 'Description', []);
+    // Test cases must name tools the server actually has; descriptions drift away from live servers.
+    const named = [...new Set((m.tests?.positive ?? []).flatMap((t) => t.tools))];
+    if (tools.length && named.length) {
+        const live = new Set(tools.map((t) => t.name));
+        const unknown = named.filter((n) => !live.has(n));
+        checks.push(unknown.length
+            ? { id: 'listing.test-tools', level: 'fail', title: 'Test cases use tools the server has', detail: unknown.join(', '), fix: 'Reviewers run your test cases against the live server. Update the tests, and check the description doesn’t promise tools you no longer expose.' }
+            : { id: 'listing.test-tools', level: 'pass', title: 'Test cases use tools the server has' });
+    }
     // ChatGPT domain verification
     if (has(stores, 'chatgpt')) {
         const ch = await get(`${origin}/.well-known/openai-apps-challenge`);

package/dist/checks/server.d.ts

@@ -0,0 +1,8 @@
+import type { Check, Tool } from '../types.js';
+/** Connects the way a store's scanner does and returns the tool list for the other checks. */
+/** A check that needs a raw socket, which only some runtimes have. Node passes the TLS 1.2 check in. */
+export type SocketCheck = (url: string) => Promise<Check>;
+export declare function serverChecks(url: string, auth: 'none' | 'oauth', token?: string, extra?: SocketCheck[]): Promise<{
+    checks: Check[];
+    tools: Tool[];
+}>;

package/dist/checks/server.js

@@ -1,8 +1,6 @@
-import { connect } from 'node:tls';
 import { McpClient } from '../mcp-client.js';
 const BROWSER_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36';
-/** Connects the way a store's scanner does and returns the tool list for the other checks. */
-export async function serverChecks(url, auth, token) {
+export async function serverChecks(url, auth, token, extra = []) {
     const checks = [];
     const bearer = token ? { authorization: `Bearer ${token}` } : {};
     const client = new McpClient(url, bearer);
@@ -37,9 +35,28 @@ export async function serverChecks(url, auth, token) {
         const info = init.body?.result?.serverInfo;
         checks.push({ id: 'server.initialize', level: 'pass', title: 'initialize succeeds', detail: info ? `${info.name ?? ''} ${info.version ?? ''}`.trim() : undefined });
     }
-    if (auth === 'none' || (token && init.status < 300)) {
+    // An OAuth server that answers initialize without a token should list its tools the same way. One that
+    // initializes but then refuses tools/list leaves ChatGPT's new connector stuck on "no actions available":
+    // ChatGPT reads the list before signing in; Claude and Cursor sign in first, so they never show it.
+    if (auth === 'oauth' && !token && init.status < 300) {
+        const peek = await client.request('tools/list').catch(() => null);
+        const peekTools = (peek?.body?.result?.tools ?? []);
+        checks.push(peekTools.length
+            ? { id: 'server.public-tools', level: 'pass', title: 'tools/list answers without a token, like initialize' }
+            : {
+                id: 'server.public-tools',
+                level: 'warn',
+                title: 'tools/list answers without a token, like initialize',
+                detail: `initialize works unsigned, tools/list gave HTTP ${peek?.status ?? 'error'} with ${peekTools.length} tools`,
+                fix: 'Either return 401 for everything until sign-in, or list tools without a token and gate execution. The half-way state froze one team’s ChatGPT connector at "no actions available" until they deleted and recreated it.',
+                stores: ['chatgpt'],
+            });
+        if (peekTools.length)
+            tools = peekTools;
+    }
+    if (auth === 'none' || (token && init.status < 300) || tools.length) {
         const list = await client.request('tools/list').catch(() => null);
-        tools = list?.body?.result?.tools ?? [];
+        tools = list?.body?.result?.tools?.length ? list.body.result.tools : tools;
         checks.push(tools.length
             ? { id: 'server.tools', level: 'pass', title: 'tools/list returns tools', detail: tools.map((t) => t.name).join(', ') }
             : { id: 'server.tools', level: 'fail', title: 'tools/list returns tools', detail: `HTTP ${list?.status ?? 'error'}`, fix: 'Stores scan tools/list; with no tools there is nothing to list.' });
@@ -109,26 +126,11 @@ export async function serverChecks(url, auth, token) {
             fix: 'A firewall or bot rule is returning 403 to non-browser clients. Store scanners and reviewers are automated; allow them on the MCP path.',
         });
     }
-    checks.push(await tls12Check(url));
+    for (const c of extra)
+        checks.push(await c(url));
     checks.push(await echCheck(url));
     return { checks, tools };
 }
-/** Some review networks only speak TLS 1.2. */
-function tls12Check(url) {
-    const host = new URL(url).hostname;
-    return new Promise((resolve) => {
-        const sock = connect({ host, port: 443, servername: host, maxVersion: 'TLSv1.2', timeout: 8000 }, () => {
-            sock.end();
-            resolve({ id: 'server.tls12', level: 'pass', title: 'A TLS 1.2 client can connect' });
-        });
-        const bad = (why) => resolve({ id: 'server.tls12', level: 'warn', title: 'A TLS 1.2 client can connect', detail: why, fix: 'Allow TLS 1.2; some corporate and review proxies cannot do TLS 1.3.' });
-        sock.on('error', (e) => bad(e.message));
-        sock.on('timeout', () => {
-            sock.destroy();
-            bad('timed out');
-        });
-    });
-}
 /** Encrypted ClientHello in DNS makes TLS-inspecting proxies reset the connection. */
 async function echCheck(url) {
     const host = new URL(url).hostname;

package/dist/checks/tls.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from '../types.js';
+/** Some review networks only speak TLS 1.2. */
+export declare function tls12Check(url: string): Promise<Check>;

package/dist/checks/tls.js

@@ -0,0 +1,17 @@
+import { connect } from 'node:tls';
+/** Some review networks only speak TLS 1.2. */
+export function tls12Check(url) {
+    const host = new URL(url).hostname;
+    return new Promise((resolve) => {
+        const sock = connect({ host, port: 443, servername: host, maxVersion: 'TLSv1.2', timeout: 8000 }, () => {
+            sock.end();
+            resolve({ id: 'server.tls12', level: 'pass', title: 'A TLS 1.2 client can connect' });
+        });
+        const bad = (why) => resolve({ id: 'server.tls12', level: 'warn', title: 'A TLS 1.2 client can connect', detail: why, fix: 'Allow TLS 1.2; some corporate and review proxies cannot do TLS 1.3.' });
+        sock.on('error', (e) => bad(e.message));
+        sock.on('timeout', () => {
+            sock.destroy();
+            bad('timed out');
+        });
+    });
+}

package/dist/checks/tools.d.ts

@@ -0,0 +1,2 @@
+import type { Check, Tool } from '../types.js';
+export declare function toolChecks(tools: Tool[]): Check[];

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { writeFile, access } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
-import { MANIFEST_FILE, draftManifest, loadManifest } from './manifest.js';
+import { MANIFEST_FILE, draftManifest, loadManifest, storesOf } from './manifest.js';
 import { VERSION } from './version.js';
 import { preflight } from './preflight.js';
 import { printPreflight } from './report.js';
@@ -10,7 +10,8 @@ import { recordDecision, recordSubmitted, status } from './submissions.js';
 import { chatgptPack, claudePack, directoriesPack, simplePack, writePack } from './packs.js';
 import { drift, printDrift, takeSnapshot } from './drift.js';
 import { publish } from './publish.js';
-import { lanes, pull, runLane, tryLinks } from './extras.js';
+import { lanes, runLane, tryLinks } from './extras.js';
+import { listings, printListings } from './listings.js';
 import { fleet, fleetRun, printFleet } from './fleet.js';
 const HELP = `mcplane: fastlane for MCP servers
 
@@ -34,8 +35,8 @@ Usage
   mcplane baseline <store> [--version x.y.z]   Record a listing that's already live as the drift baseline
   mcplane publish <store> [--yes]     Publish where the store allows it (mcp-registry, grok); dry run without --yes
   mcplane try                         Install links for every client, for you and your testers
-  mcplane pull                        Compare your live public listings with mcplane.json
-  mcplane lanes                       List lanes; run one with "mcplane <lane>" (built in: check, release)
+  mcplane listings [--store <id>]...  Where you're listed, and whether what went live matches your server (--ci)
+  mcplane lanes                       List lanes; run one with "mcplane <lane>" (built in: check, watch, release)
   mcplane fleet [--root <dir>]        Every project under a folder: blockers, store updates needed, reviews waiting
       --quick                         Skip the live checks; just submissions
   mcplane fleet run <command...>      Run any mcplane command in every project (e.g. fleet run publish mcp-registry --yes)
@@ -215,7 +216,7 @@ async function main() {
             console.log(JSON.stringify(rows, null, 2));
         else
             printFleet(rows);
-        if (values.ci && rows.some((r) => r.error || r.blocking || r.driftActions?.length))
+        if (values.ci && rows.some((r) => r.error || r.blocking || r.driftActions?.length || r.listingIssues?.length))
             process.exitCode = 1;
         return;
     }
@@ -225,24 +226,16 @@ async function main() {
             console.log(`${t.client.padEnd(22)} ${t.how}`);
         return;
     }
-    if (cmd === 'pull') {
+    if (cmd === 'listings' || cmd === 'pull') {
         const m = await loadManifest();
-        const diffs = await pull(m);
-        if (values.json) {
-            console.log(JSON.stringify(diffs, null, 2));
-            return;
-        }
-        for (const d of diffs) {
-            if (!d.found)
-                console.log(`${d.store}: not listed yet.`);
-            else if (!d.fields.length)
-                console.log(`${d.store}: matches mcplane.json.`);
-            else {
-                console.log(`${d.store}: live listing differs${d.url ? ` (${d.url})` : ''}`);
-                for (const f of d.fields)
-                    console.log(`  ${f.field}\n    live:  ${f.live.slice(0, 160)}\n    yours: ${f.yours.slice(0, 160)}`);
-            }
-        }
+        const stores = (values.store?.length ? values.store : storesOf(m));
+        const rows = await listings(m, stores, { token: values.token ?? process.env.MCPLANE_TOKEN });
+        if (values.json)
+            console.log(JSON.stringify(rows, null, 2));
+        else
+            printListings(rows);
+        if (values.ci && rows.some((r) => r.issues.length))
+            process.exitCode = 1;
         return;
     }
     const m = await loadManifest().catch(() => null);

package/dist/core.d.ts

@@ -0,0 +1,18 @@
+import type { SocketCheck } from './checks/server.js';
+import type { Check, Manifest, StoreId } from './types.js';
+export interface PreflightResult {
+    checks: Check[];
+    reminders: string[];
+    stores: StoreId[];
+}
+/** Runtime-neutral: fetch only. Node adds socket checks (TLS 1.2) through extraChecks; see preflight-node. */
+export declare function preflight(m: Manifest, opts?: {
+    stores?: StoreId[];
+    register?: boolean;
+    token?: string;
+    extraChecks?: SocketCheck[];
+}): Promise<PreflightResult>;
+export { draftManifest, storesOf, SCHEMA_URL } from './draft.js';
+export { toolChecks } from './checks/tools.js';
+export { STORE_NAMES } from './types.js';
+export type { Check, Level, Manifest, StoreId, Tool } from './types.js';

package/dist/core.js

@@ -0,0 +1,52 @@
+/**
+ * mcplane's checks for any runtime with fetch (Workers, Deno, browsers' servers).
+ * Import from "mcplane/core".
+ */
+import { authChecks } from './checks/auth.js';
+import { listingChecks, repoChecks } from './checks/listing.js';
+import { serverChecks } from './checks/server.js';
+import { toolChecks } from './checks/tools.js';
+import { storesOf } from './draft.js';
+/** Things no script can see, which have still cost real submissions. */
+function reminders(m, stores) {
+    const r = [];
+    if (m.server.auth === 'oauth') {
+        r.push('Give reviewers a demo account a stranger can use: email and password (not your Google or SSO login), email already confirmed, no 2FA or SMS, seeded with data for every test case. Re-check the seed right before submitting.');
+        r.push('Sign in through your OAuth flow once as a brand-new user. A blank post-sign-in redirect stranded a ChatGPT reviewer between registration and consent.');
+    }
+    if (stores.some((s) => s === 'chatgpt' || s === 'claude-connectors')) {
+        r.push('If a tool writes somewhere public (posts, sends, publishes), give reviewers a safe target: a sandbox account or a "playground" option that validates and then discards. Reviewers test writes; they shouldn’t post to a real timeline.');
+    }
+    if (stores.includes('chatgpt')) {
+        r.push('ChatGPT needs a demo video recorded in developer mode that shows the tools your test cases use. Re-record it whenever tools change.');
+        r.push('After "Submit for Review" the ChatGPT portal shows nothing for about 20 seconds. Confirm the status on the plugins list, not the button.');
+        r.push('Tool-annotation justifications are cut at 200 characters without warning.');
+        r.push('ChatGPT allows one version in review at a time. To change a submission, Cancel Review and resubmit the same draft.');
+    }
+    if (stores.includes('claude-connectors') || stores.includes('claude-plugins')) {
+        if (stores.includes('claude-connectors'))
+            r.push('Claude connectors are submitted from an organisation’s admin settings (claude.ai/directory/manage), so you need admin rights in a paid org. The tool list is synced from your server when you submit; it is not an editable field.');
+        if (stores.includes('claude-plugins'))
+            r.push('Run "claude plugin validate --strict" in the plugin repo; the portal validates every commit on the branch it tracks.');
+        r.push('Claude: "Passed review" is not the same as listed. Check claude.ai/directory for your listing after approval; with the new portal you choose when to publish.');
+    }
+    return r;
+}
+/** Runtime-neutral: fetch only. Node adds socket checks (TLS 1.2) through extraChecks; see preflight-node. */
+export async function preflight(m, opts = {}) {
+    const stores = opts.stores?.length ? opts.stores : storesOf(m);
+    const auth = m.server.auth ?? 'none';
+    const server = await serverChecks(m.server.url, auth, opts.token, opts.extraChecks);
+    const [authC, listing, repo] = await Promise.all([
+        auth === 'oauth' ? authChecks(m.server.url, { register: opts.register }) : Promise.resolve([]),
+        listingChecks(m, server.tools, stores),
+        repoChecks(m, stores),
+    ]);
+    const all = [...server.checks, ...authC, ...toolChecks(server.tools), ...listing, ...repo];
+    // Keep checks that apply to every store or to one we're submitting to.
+    const checks = all.filter((c) => !c.stores?.length || c.stores.some((s) => stores.includes(s)));
+    return { checks, reminders: reminders(m, stores), stores };
+}
+export { draftManifest, storesOf, SCHEMA_URL } from './draft.js';
+export { toolChecks } from './checks/tools.js';
+export { STORE_NAMES } from './types.js';

package/dist/draft.d.ts

@@ -0,0 +1,5 @@
+import { type Manifest, type StoreId } from './types.js';
+export declare const SCHEMA_URL = "https://unpkg.com/mcplane/schema.json";
+export declare function storesOf(m: Manifest): StoreId[];
+/** A starting manifest from what the live server and its domain reveal. */
+export declare function draftManifest(url: string): Promise<Manifest>;

package/dist/draft.js

@@ -0,0 +1,55 @@
+/** Runtime-neutral pieces of the manifest: fetch only, no filesystem. */
+import { McpClient } from './mcp-client.js';
+import { STORE_NAMES } from './types.js';
+export const SCHEMA_URL = 'https://unpkg.com/mcplane/schema.json';
+export function storesOf(m) {
+    return m.stores?.length ? m.stores : Object.keys(STORE_NAMES);
+}
+/** A starting manifest from what the live server and its domain reveal. */
+export async function draftManifest(url) {
+    const client = new McpClient(url);
+    const init = await client.initialize().catch(() => null);
+    const auth = init?.status === 401 ? 'oauth' : 'none';
+    const info = init?.body?.result?.serverInfo ?? {};
+    const host = new URL(url).hostname;
+    const labels = host.split('.');
+    // api.example.com and mcp.example.com usually keep their pages on example.com.
+    const origins = [`https://${host}`, ...(labels.length > 2 ? [`https://${labels.slice(1).join('.')}`] : [])];
+    const origin = origins[origins.length - 1];
+    const found = async (p) => {
+        for (const o of origins) {
+            const r = await fetch(o + p, { method: 'GET', redirect: 'follow' }).catch(() => null);
+            if (r?.ok && !(r.headers.get('content-type') ?? '').includes('json'))
+                return o + p;
+        }
+        return undefined;
+    };
+    const first = async (...paths) => {
+        for (const p of paths) {
+            const hit = await found(p);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    const [privacy, support, terms, docs, icon] = await Promise.all([
+        first('/privacy', '/privacy-policy', '/legal/privacy'),
+        first('/support', '/contact', '/help'),
+        first('/terms', '/terms-of-service', '/legal/terms'),
+        first('/llms.txt', '/docs'),
+        first('/icon-512.png', '/icon.png', '/apple-touch-icon.png'),
+    ]);
+    return {
+        $schema: SCHEMA_URL,
+        name: String(info.name ?? new URL(url).hostname.split('.')[0]),
+        title: String(info.title ?? info.name ?? ''),
+        subtitle: '',
+        oneLiner: '',
+        description: '',
+        server: { url, auth },
+        author: { name: '', url: origin },
+        links: { website: origin, support, privacy, terms, docs },
+        icon,
+        stores: ['mcp-registry', 'chatgpt', 'claude-connectors', 'cursor', 'muse'],
+    };
+}

package/dist/drift.d.ts

@@ -0,0 +1,57 @@
+import { type Manifest, type StoreId, type Tool } from './types.js';
+interface ToolShape {
+    name: string;
+    title?: string;
+    description?: string;
+    hints: {
+        readOnly?: boolean;
+        destructive?: boolean;
+        openWorld?: boolean;
+    };
+    input: string;
+    output: string;
+}
+export interface Snapshot {
+    store: StoreId;
+    takenOn: string;
+    version?: string;
+    state: 'submitted' | 'live';
+    tools: ToolShape[];
+    listing: Record<string, string | undefined>;
+    repoSha?: string;
+}
+export interface DriftItem {
+    store: StoreId;
+    level: 'action' | 'info';
+    what: string;
+    todo: string;
+}
+export declare function liveTools(m: Manifest, token?: string): Promise<Tool[]>;
+/** HEAD of the plugin repository on GitHub, when there is one. */
+export declare function repoHead(repository?: string): Promise<string | undefined>;
+export declare function takeSnapshot(m: Manifest, store: StoreId, opts: {
+    version?: string;
+    state: Snapshot['state'];
+    token?: string;
+}, dir?: string): Promise<Snapshot>;
+export declare function markLive(store: StoreId, dir?: string): Promise<void>;
+/** What changed between a snapshot and now, as plain descriptions. */
+export declare function diffTools(before: ToolShape[], now: ToolShape[]): {
+    added: string[];
+    removed: string[];
+    changed: {
+        tool: string;
+        fields: string[];
+    }[];
+};
+export declare function drift(m: Manifest, stores: StoreId[], opts?: {
+    token?: string;
+}, dir?: string): Promise<{
+    items: DriftItem[];
+    missing: StoreId[];
+}>;
+export declare function printDrift(r: {
+    items: DriftItem[];
+    missing: StoreId[];
+}): void;
+export {};

package/dist/extras.d.ts

@@ -0,0 +1,13 @@
+import type { Manifest } from './types.js';
+export declare const DEFAULT_LANES: Record<string, string[]>;
+export declare function lanes(m: Manifest): Record<string, string[]>;
+/**
+ * Runs a lane step by step. A step that fails stops the lane unless it starts
+ * with "?" (optional). "handoff:" steps are what only a person can do: policy
+ * statements, the final submit. They're collected and shown at the end.
+ */
+export declare function runLane(name: string, steps: string[], passthrough: string[]): number;
+export declare function tryLinks(m: Manifest): {
+    client: string;
+    how: string;
+}[];