@showly/mcp-server 0.1.0 → 0.3.0

package/README.md

@@ -6,37 +6,75 @@ you can preview and deploy a site directly from your terminal AI.
 ## Quickstart
 
 ```sh
-npx @showly/mcp-server install --to claude-code   # or --to codex
+npx @showly/mcp-server install --to codex --with-skill
+# or: npx @showly/mcp-server install --to claude-code --with-skill
 ```
 
 The installer writes the Showly MCP server block to `~/.claude.json`
-(or `~/.codex/config.toml`). No token to paste: the next time you call a Showly
+(or `~/.codex/config.toml`) and installs the reusable `showly-hosting` skill.
+The skill covers the whole lifecycle of a hosted site — listing and inspecting
+the sites you already have, creating one, updating it, sharing a private
+password-protected Preview, publishing it Live, rolling back, and connecting a
+custom domain. It supersedes the narrower `showly-publish` skill, which
+`install` removes from your skills directory when it finds it.
+
+No token to paste: the next time you call a Showly
 tool, your agent discovers Showly's OAuth authorization server from the
 endpoint and opens a browser tab for you to sign in and approve the scopes
 (standard MCP authorization).
 
 ## What you get
 
+`manifest.json` in this package is the authoritative list — the server
+derives `INVOKABLE_TOOLS` and `MCP_BLOCKED_TOOLS` from it, so read it
+rather than trusting a hand-kept summary. It currently ships 33 tools,
+grouped below by its own `kind` field.
+
 Read-only tools available to any token:
 
 - `list_projects`, `list_sites`, `get_site_context`, `list_templates`
 - `get_preview_status`, `get_deployment_logs`, `diagnose_deployment`
+- `list_deployments`, `list_site_versions`, `diff_site_versions`, `get_site_files`
+- `list_site_domains`, `request_download_url`
 
 Write tools that stage and materialise previews:
 
 - `create_change_plan` — turn a natural-language request into a plan
 - `apply_site_patch` — stage one or more file edits as a _changeset_
 - `create_preview` — build the changeset and return a real preview URL
+- `create_github_preview` — build a private preview from the latest commit on a connected GitHub branch (static targets; dynamic container builds fail before enqueue)
 - `retry_deployment` — re-run a failed preview build
 - `run_checks` — read the lint / typecheck / build status of a preview
 - `create_site_from_template` — bootstrap a new site from a template
+- `create_site_from_html` — create a site from inline HTML
+- `request_upload_url` — signed URL for a file too large to pass inline
+- `set_preview_access` — change who can open a preview URL
 - `request_publish` — open a publish approval (completed in the web UI)
 
-Production paths (`publish_site`, `rollback_deployment`) are deliberately
-not exposed via MCP at all — they don't appear in `tools/list`. The agent's
-path to production is `request_publish`, whose success response includes a
-`webApprovalUrl` deep link; the user opens that link to complete approval
-and step-up MFA in the Showly web UI.
+Write tools for custom domains (ADR-0015):
+
+- `add_custom_domain`, `verify_custom_domain`
+
+Write tools for version history and deletion:
+
+- `rollback_to_version` — restore a previous site version
+- `delete_preview`, `delete_site`
+
+Write tools for the guest trial flow:
+
+- `create_trial_site`, `claim_trial_site`
+
+`publish_site` is exposed through a narrower `publish:confirm` scope and never
+publishes on its first call: it returns a short-lived, deployment-bound token
+that the agent may echo only after the user confirms. Team and Enterprise
+workspaces use `request_publish` and its `webApprovalUrl` for second-person
+approval. Ordinary Live publishing does not require OTP/MFA. The legacy
+`rollback_deployment` path remains Web-only.
+
+Both publish paths require the human user bound to the MCP token to have a
+verified Showly account email. An `email_verification_required` result includes
+`webVerificationUrl`; the agent must direct the user there and must not report
+the site as live until verification succeeds and publishing is retried.
 
 ## Environment
 

package/dist/cli.d.ts

@@ -1,5 +1,30 @@
 #!/usr/bin/env node
-type Target = "claude-code" | "codex" | "stdout";
+export type Target = "claude-code" | "codex" | "stdout";
+/**
+ * The version of THIS copy of the package, read from the manifest that ships
+ * beside it. `manifest.test.ts` pins manifest.json, package.json,
+ * claude-code-skill and codex-plugin to one string, so this cannot print a
+ * version the package does not actually have.
+ *
+ * It is printed on every help screen and on every unknown-command error, and
+ * that is the whole point. When an agent runs `showly-mcp` from a stale npx
+ * cache and sees a command list that is missing what the docs told it to run,
+ * the most natural inference is "the docs are wrong" or "I misremembered the
+ * name" — because nothing on screen suggests a newer copy exists. A version
+ * string plus the `@latest` hint is the one signal that redirects that guess
+ * from "the instructions are wrong" to "my copy is old".
+ */
+export declare const CLI_VERSION: string;
+/** The commands this copy dispatches. Anything else is an error, never a no-op. */
+export declare const KNOWN_COMMANDS: readonly ["install", "login", "manifest"];
+export type KnownCommand = (typeof KNOWN_COMMANDS)[number];
+/**
+ * The sentence that turns "this tool cannot do that" into "this COPY cannot do
+ * that". Printed on unknown commands and on unknown flags, because both are
+ * reached by the same route: documentation written against a newer release
+ * than the one npx resolved.
+ */
+export declare const UPGRADE_HINT = "If you expected this, your copy is out of date \u2014 re-run with `npx @showly/mcp-server@latest`.";
 export declare function buildClaudeCodeSnippet(opts: {
     url: string;
     apiUrl?: string;
@@ -18,8 +43,272 @@ export type InstallResult = {
     snippet: string;
     wrote: boolean;
     alreadyConfigured: boolean;
+    skill: SkillInstallResult | null;
+};
+export type SkillInstallResult = {
+    path: string;
+    wrote: boolean;
+    alreadyConfigured: boolean;
+    /** Path of the superseded showly-publish skill this install removed, if any. */
+    removedLegacyPath: string | null;
+};
+export type InstallOptions = {
+    withSkill?: boolean;
 };
-export declare function performInstall(target: Target, env?: NodeJS.ProcessEnv): InstallResult;
+export declare function performInstall(target: Target, env?: NodeJS.ProcessEnv, options?: InstallOptions): InstallResult;
+export declare function performSkillInstall(target: Exclude<Target, "stdout">, env?: NodeJS.ProcessEnv): SkillInstallResult;
+/**
+ * The client_id this CLI starts device flows under.
+ *
+ * Deliberately NOT a first-party id (the API rejects those on /oauth/device
+ * precisely so nobody can wear the product's identity on a consent screen),
+ * and deliberately not registered: a device client_id is free text, so the
+ * consent page treats whatever name it carries as self-declared and asks the
+ * human to check the code echo instead.
+ */
+export declare const LOGIN_CLIENT_ID = "showly-mcp-cli";
+/** The env var name emitted into config snippets that must not hold a secret. */
+export declare const TOKEN_ENV_VAR = "SHOWLY_TOKEN";
+export type DeviceStart = {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+};
+export type DeviceToken = {
+    access_token: string;
+    scope: string;
+    expires_in?: number;
+};
+/**
+ * The exact text `login` prints while it waits. Pure, and pinned by a test,
+ * because this block is the entire user interface of headless sign-in — the
+ * docs quote it verbatim so the page and the binary cannot drift.
+ *
+ * Reading order is not cosmetic:
+ *   • The bare URL plus the separately-printed code comes FIRST, because that
+ *     is the pair that works when the human is on a phone or another machine —
+ *     which is the entire reason this flow exists. The one-click deep link is
+ *     offered second, for the case where the browser is on this box.
+ *   • The code is repeated three times on purpose. RFC 8628 §3.3.1's code echo
+ *     is the ONLY anti-phishing signal that survives an attacker-controlled
+ *     client_name (Storm-2372 phished 340+ M365 tenants on exactly this flow),
+ *     so the human has to be told what they will see and what to do if it
+ *     differs.
+ *   • The expiry is a wall-clock time, not a duration. A human who wanders off
+ *     to create an account and verify an email cannot subtract "15 minutes"
+ *     from a moment they have forgotten.
+ */
+export declare function buildLoginPrompt(input: {
+    verificationUri: string;
+    verificationUriComplete: string;
+    userCode: string;
+    expiresAt: Date;
+}): string;
+/** Claude Code reads a `headers` map on an http MCP server entry. */
+export declare function buildClaudeCodeAuthSnippet(opts: {
+    url: string;
+    token: string;
+}): Record<string, unknown>;
+export declare function buildCodexAuthSnippet(opts: {
+    url: string;
+    tokenEnvVar?: string;
+}): string;
+export type LoginDeps = {
+    fetchImpl?: typeof fetch;
+    /**
+     * Injectable wait. Takes the cancellation signal too, so the real one can
+     * return the instant Ctrl+C arrives instead of finishing a five-second nap
+     * first — a cancel the user has to wait out does not read as a cancel.
+     */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Injectable clock (ms). Lets the poll deadline be tested without waiting. */
+    now?: () => number;
+    /** stderr sink. Keeps stdout clean for --print-token. */
+    log?: (line: string) => void;
+    /**
+     * Cancellation from outside — Ctrl+C, in production (see createCancelScope).
+     *
+     * Without it there was no way out of this command but killing the process,
+     * which is a poor deal for the human who is already stuck: `login` blocks for
+     * a quarter of an hour by design, and the whole reason a reader reaches it is
+     * that something else (their editor's browser window) failed to appear.
+     */
+    signal?: AbortSignal;
+    /**
+     * Per-request deadline override, in ms. Production uses the constants below;
+     * the tests use a tiny value so a hung server can be exercised in
+     * milliseconds rather than in the fifteen seconds a real one gets.
+     */
+    requestTimeoutMs?: number;
+};
+/**
+ * How long ONE HTTP request may take before it is abandoned.
+ *
+ * Neither fetch had any bound at all, and both are inside the flow whose entire
+ * job is to unstick a human: a TCP connection that opens and then goes quiet
+ * (a captive portal, a proxy that swallows the response, a machine suspended
+ * mid-poll) leaves `login` hanging with no output and no deadline — the same
+ * silent wait, one layer down, that this command exists to replace.
+ *
+ * The start POST is short because nothing has been printed yet: until it
+ * returns there is no code, no URL, and nothing on screen, so the reader cannot
+ * tell a slow network from a dead one. A poll gets longer, because by then the
+ * prompt is on screen and the loop can absorb a slow answer without the reader
+ * seeing anything at all.
+ */
+export declare const START_REQUEST_TIMEOUT_MS = 15000;
+export declare const POLL_REQUEST_TIMEOUT_MS = 30000;
+/** Thrown when the human cancels; the CLI exits 130 rather than 1 on it. */
+export declare class LoginCancelledError extends Error {
+    constructor();
+}
+/**
+ * Wire Ctrl+C (and SIGTERM) to an AbortSignal the login flow watches.
+ *
+ * Registering a SIGINT listener also SUPPRESSES Node's default "die now", which
+ * is the point: the flow gets to unwind, say what happened, and exit with the
+ * conventional 130 instead of leaving the reader guessing whether anything was
+ * half-written. Exported so the wiring itself is testable — `main` is not.
+ */
+export type SignalTarget = {
+    on(event: string, listener: () => void): unknown;
+    off(event: string, listener: () => void): unknown;
+};
+export declare function createCancelScope(target?: SignalTarget): {
+    signal: AbortSignal;
+    release: () => void;
+};
+/**
+ * How far PAST the expiry we were handed at start the poll keeps going.
+ *
+ * `expires_in` from POST /oauth/device is a floor, not a deadline: when a
+ * signed-in human lands on the consent page the server pushes expires_at out
+ * (see DEVICE_LOOKUP_EXTENSION_MS), so a client that stopped at the advertised
+ * expiry would hang up on the human mid-approval. It is still bounded — the
+ * server caps a device flow at 30 minutes from creation whatever happens — so
+ * one absolute cap past the advertised expiry is comfortably beyond any answer
+ * that could still become a token, and stopping there is what keeps a deploy
+ * that stops resolving dead rows from turning this loop into a permanent 300
+ * requests/min against the token endpoint.
+ */
+export declare const SERVER_EXTENSION_ALLOWANCE_MS: number;
+export declare function startDeviceFlow(apiUrl: string, deps?: LoginDeps): Promise<DeviceStart>;
+/**
+ * Poll /oauth/token until the human decides, per RFC 8628 §3.4-3.5.
+ *
+ * Every terminal answer is turned into a sentence a human can act on. The
+ * server sends `error_description` for exactly this reason, so we prefer it
+ * over anything we could invent, and fall back only when an older deploy
+ * sends the bare code.
+ *
+ * `expiresAt` is the client-side backstop, not the contract: the server's own
+ * `expired_token` / `invalid_grant` is what normally ends the loop, and this
+ * only fires when no answer ever arrives at all. It sits a full
+ * SERVER_EXTENSION_ALLOWANCE_MS past the advertised expiry so an arrival
+ * extension is never cut short.
+ */
+export declare function pollForDeviceToken(input: {
+    apiUrl: string;
+    deviceCode: string;
+    intervalSec: number;
+    expiresAt: Date;
+}, deps?: LoginDeps): Promise<DeviceToken>;
+export type LoginResult = {
+    target: Target;
+    token: string;
+    scope: string;
+    expiresAt: Date | null;
+    path: string | null;
+    wrote: boolean;
+    snippet: string;
+};
+/**
+ * Run the whole headless sign-in and put the credential where the host will
+ * find it.
+ *
+ * No secret is ever accepted on argv — there is no `--token` flag, and the
+ * only credential this command handles is the one it just fetched. Anything
+ * pasted from /app/admin/mcp-tokens goes in through the environment
+ * (SHOWLY_TOKEN) or the host config by hand, so it stays out of shell history
+ * and out of every `ps` listing on the machine.
+ */
+export declare function performLogin(opts: {
+    target: Target;
+    env?: NodeJS.ProcessEnv;
+}, deps?: LoginDeps): Promise<LoginResult>;
+/**
+ * The env var names a host config tells its client to read the credential
+ * from: Codex's `bearer_token_env_var = "NAME"`, and the `${NAME}` placeholder
+ * in the pasteable snippet.
+ *
+ * Deliberately derived FROM the config text rather than hardcoded, because the
+ * bug this closes was a config and an output that disagreed. Whatever a future
+ * host schema calls its indirection, the name it references is what the human
+ * has to be handed a value for.
+ */
+export declare function envVarsReferencedBy(configText: string): string[];
+export type LoginOutputLine = {
+    stream: "out" | "err";
+    line: string;
+};
+/**
+ * Everything `login` says after the token lands. Pure, so the one property
+ * that matters can be tested: a human who ran this command ends up CONNECTED.
+ *
+ * `--to codex` used to break that. It writes `bearer_token_env_var =
+ * "SHOWLY_TOKEN"` — Codex reads the credential from the environment, never
+ * from the file — and then printed `Connected. Wrote <path>` and dropped the
+ * token on the floor. Nothing on the machine ever set SHOWLY_TOKEN, so every
+ * tool call went out with no Authorization header and 401'd, after the human
+ * had already spent their one approval; recovering meant a second device flow
+ * and a second approval, which is the dead end this whole command exists to
+ * remove. `--to stdout` had the same hole with a sentence over it ("re-run
+ * with --print-token"), which is also a second approval.
+ *
+ * So the value is supplied here, once, on stderr — the only place it can go
+ * without landing in a file. The config keeps the env indirection, which is
+ * what makes it safe to commit; stdout keeps carrying only the snippet (or,
+ * under --print-token, only the token) so both remain pipeable.
+ */
+export declare function buildLoginOutput(result: LoginResult, opts?: {
+    printToken?: boolean;
+}): LoginOutputLine[];
+export type ParsedCommandArgs = {
+    ok: true;
+    help: boolean;
+    flags: Set<string>;
+    values: Map<string, string>;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Strict argv parse for one command: every token must be a flag this command
+ * declares, a value for a flag that takes one, or `--help`.
+ *
+ * Bare positionals are rejected too, for the same reason flags are: `install
+ * claude-code` (no `--to`) is a plausible typo whose only old outcome was a
+ * usage error about the missing `--to`, and `manifest extra` simply printed the
+ * manifest as if the word were not there.
+ */
+export declare function parseCommandArgs(command: KnownCommand, rest: string[]): ParsedCommandArgs;
+/** stdout/stderr sinks, injected so the dispatcher is testable in-process. */
+export type CliIo = {
+    out: (line: string) => void;
+    err: (line: string) => void;
+};
+/**
+ * The whole command dispatcher, as a function that RETURNS its exit code.
+ *
+ * It used to be a `main` that assigned `process.exitCode` and was neither
+ * exported nor reachable from a test, which is why nothing noticed that the
+ * failure paths through it were not failures at all. The code is the contract
+ * here — the strings around it are not — so it is what a caller gets back.
+ */
+export declare function runCli(argv: string[], io?: CliIo, env?: NodeJS.ProcessEnv): Promise<number>;
 /**
  * True when this module is the program entrypoint.
  *
@@ -35,4 +324,3 @@ export declare function performInstall(target: Target, env?: NodeJS.ProcessEnv):
  * exercised from an in-process test runner otherwise).
  */
 export declare function isMainModule(argv1: string | undefined, metaUrl: string): boolean;
-export {};