@showly/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @showly/mcp-server
+
+Connect Claude Code or Codex to the [Showly](https://showly.ai) MCP server, so
+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
+```
+
+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
+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
+
+Read-only tools available to any token:
+
+- `list_projects`, `list_sites`, `get_site_context`, `list_templates`
+- `get_preview_status`, `get_deployment_logs`, `diagnose_deployment`
+
+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
+- `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
+- `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.
+
+## Environment
+
+| Variable         | Default                 | What it controls       |
+| ---------------- | ----------------------- | ---------------------- |
+| `SHOWLY_MCP_URL` | `https://mcp.showly.ai` | MCP transport endpoint |
+| `SHOWLY_API_URL` | `https://api.showly.ai` | OAuth + API base       |
+
+## Without an installer
+
+If your agent isn't supported by the installer, run:
+
+```sh
+npx @showly/mcp-server install --to stdout
+```
+
+and paste the snippet into the agent's configuration manually. The manifest
+that drives both targets is also accessible programmatically:
+
+```ts
+import { manifest } from "@showly/mcp-server";
+console.log(manifest.tools.map((t) => t.name));
+```
+
+## Troubleshooting
+
+**Codex doesn't list the showly tools.** Older Codex CLI versions only reach
+remote (streamable HTTP) MCP servers when the rmcp client is enabled. Either
+update Codex, or add to `~/.codex/config.toml`:
+
+```toml
+[features]
+experimental_use_rmcp_client = true
+```
+
+(Current Codex versions need no flag — a bare `url` under
+`[mcp_servers.showly]` is the whole config.)
+
+## License
+
+Proprietary — © Showly. This package is distributed for use with the Showly
+hosting service; it is not open source. See https://showly.ai/terms.

package/dist/cli.d.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+type Target = "claude-code" | "codex" | "stdout";
+export declare function buildClaudeCodeSnippet(opts: {
+    url: string;
+    apiUrl?: string;
+}): Record<string, unknown>;
+export declare function buildCodexSnippet(opts: {
+    url: string;
+    apiUrl?: string;
+}): string;
+export declare function resolveUrls(env?: NodeJS.ProcessEnv): {
+    url: string;
+    apiUrl: string;
+};
+export type InstallResult = {
+    target: Target;
+    path: string | null;
+    snippet: string;
+    wrote: boolean;
+    alreadyConfigured: boolean;
+};
+export declare function performInstall(target: Target, env?: NodeJS.ProcessEnv): InstallResult;
+/**
+ * True when this module is the program entrypoint.
+ *
+ * Must handle the `npm bin` case: an installed package exposes the CLI as
+ * `node_modules/.bin/showly-mcp`, a symlink to `dist/cli.js`. Node sets
+ * `process.argv[1]` to the symlink path (`…/.bin/showly-mcp`), while
+ * `import.meta.url` is the real `…/dist/cli.js`. The old guard compared the
+ * two strings (and looked for a `cli.js` suffix on argv[1]) so it silently
+ * failed through the symlink — `showly-mcp <cmd>` exited 0 with no output.
+ *
+ * Resolve argv[1] to its real path before comparing, so the symlink and the
+ * target reconcile. Exported for unit testing (the bin path can't be
+ * exercised from an in-process test runner otherwise).
+ */
+export declare function isMainModule(argv1: string | undefined, metaUrl: string): boolean;
+export {};

package/dist/cli.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// packages/showly-mcp-server/src/cli.ts — install helper.
+//
+// Usage:
+//   showly-mcp install --to claude-code     # writes ~/.claude.json
+//   showly-mcp install --to codex           # writes ~/.codex/config.toml
+//   showly-mcp install --to stdout          # prints the snippet for manual paste
+//   showly-mcp manifest                     # prints manifest.json
+//   showly-mcp --help
+//
+// The CLI only writes the MCP server config block — it doesn't touch network.
+// The agent discovers OAuth from the server and runs the browser sign-in on
+// first use (standard MCP authorization).
+import { readFileSync, mkdirSync, writeFileSync, existsSync, realpathSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+import { loadManifest } from "./index.js";
+function usage() {
+    return [
+        "Showly MCP server installer",
+        "",
+        "Usage:",
+        "  showly-mcp install --to <claude-code|codex|stdout>",
+        "  showly-mcp manifest",
+        "",
+        "Environment overrides:",
+        "  SHOWLY_MCP_URL    full URL to your MCP endpoint (default https://mcp.showly.ai)",
+        "  SHOWLY_API_URL    full URL to your API (default https://api.showly.ai)",
+    ].join("\n");
+}
+// The MCP server config is intentionally MINIMAL: just the transport + URL.
+// OAuth is NOT configured inline — a standards-compliant MCP client (Claude
+// Code / Codex) discovers it from the server: it connects, gets 401 +
+// WWW-Authenticate, fetches the server's protected-resource metadata, then the
+// authorization-server metadata, dynamically registers, and runs
+// authorization_code + PKCE in the browser. There is no client-readable
+// `oauth` field in the host config schema, so emitting one (as a prior version
+// did) was a no-op that misled rather than helped. `apiUrl` is retained in the
+// signature for the stdout help text + the device-flow fallback docs.
+export function buildClaudeCodeSnippet(opts) {
+    return {
+        mcpServers: {
+            showly: {
+                type: "http",
+                url: opts.url,
+            },
+        },
+    };
+}
+// Codex's HTTP MCP config schema has no `type` key — a bare `url` is what
+// selects the streamable-HTTP transport (stdio servers use `command` instead).
+// Codex's TOML deserialization rejects unknown keys, so emitting one risks
+// breaking the whole config file, not just our entry. Codex versions that
+// predate the rmcp client need `[features] experimental_use_rmcp_client =
+// true` on top — documented in the README rather than written here, so we
+// never inject a duplicate [features] table into a user's config.
+export function buildCodexSnippet(opts) {
+    return [
+        "# Added by @showly/mcp-server install",
+        "",
+        "[mcp_servers.showly]",
+        `url = "${opts.url}"`,
+        "",
+    ].join("\n");
+}
+export function resolveUrls(env = process.env) {
+    const manifest = loadManifest();
+    return {
+        url: env[manifest.mcp.endpoints.url_env] ?? manifest.mcp.endpoints.default_url,
+        apiUrl: env[manifest.mcp.endpoints.api_url_env] ?? "https://api.showly.ai",
+    };
+}
+export function performInstall(target, env = process.env) {
+    const { url, apiUrl } = resolveUrls(env);
+    if (target === "stdout") {
+        const obj = buildClaudeCodeSnippet({ url, apiUrl });
+        return {
+            target,
+            path: null,
+            snippet: "# claude-code (~/.claude.json):\n" +
+                JSON.stringify(obj, null, 2) +
+                "\n\n# codex (~/.codex/config.toml):\n" +
+                buildCodexSnippet({ url, apiUrl }),
+            wrote: false,
+            alreadyConfigured: false,
+        };
+    }
+    if (target === "claude-code") {
+        // User-scope MCP servers live in ~/.claude.json (top-level `mcpServers`),
+        // NOT ~/.claude/settings.json — Claude Code never reads mcpServers from
+        // settings.json, so a prior version of this installer wrote a block that
+        // was silently ignored.
+        const path = join(homedir(), ".claude.json");
+        const existing = existsSync(path)
+            ? safeReadJson(path)
+            : { mcpServers: {} };
+        const before = JSON.stringify(existing);
+        const snippet = buildClaudeCodeSnippet({ url, apiUrl });
+        const merged = {
+            ...existing,
+            mcpServers: {
+                ...(typeof existing.mcpServers === "object" && existing.mcpServers
+                    ? existing.mcpServers
+                    : {}),
+                showly: snippet.mcpServers.showly,
+            },
+        };
+        const after = JSON.stringify(merged);
+        if (before === after) {
+            return {
+                target,
+                path,
+                snippet: JSON.stringify(merged, null, 2),
+                wrote: false,
+                alreadyConfigured: true,
+            };
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
+        return {
+            target,
+            path,
+            snippet: JSON.stringify(merged, null, 2),
+            wrote: true,
+            alreadyConfigured: false,
+        };
+    }
+    // codex
+    const path = join(homedir(), ".codex", "config.toml");
+    const snippet = buildCodexSnippet({ url, apiUrl });
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (existing.includes("[mcp_servers.showly]")) {
+        return {
+            target,
+            path,
+            snippet,
+            wrote: false,
+            alreadyConfigured: true,
+        };
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, existing.length > 0 && !existing.endsWith("\n")
+        ? `${existing}\n${snippet}`
+        : `${existing}${snippet}`, "utf8");
+    return {
+        target,
+        path,
+        snippet,
+        wrote: true,
+        alreadyConfigured: false,
+    };
+}
+function safeReadJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function main(argv) {
+    const [cmd, ...rest] = argv.slice(2);
+    if (!cmd || cmd === "--help" || cmd === "-h") {
+        console.log(usage());
+        return;
+    }
+    if (cmd === "manifest") {
+        console.log(JSON.stringify(loadManifest(), null, 2));
+        return;
+    }
+    if (cmd === "install") {
+        const toIdx = rest.indexOf("--to");
+        if (toIdx === -1 || !rest[toIdx + 1]) {
+            console.error("install: --to <target> is required");
+            process.exitCode = 2;
+            console.error(usage());
+            return;
+        }
+        const target = rest[toIdx + 1];
+        if (!["claude-code", "codex", "stdout"].includes(target)) {
+            console.error(`install: unknown target "${target}"`);
+            process.exitCode = 2;
+            return;
+        }
+        const result = performInstall(target);
+        if (target === "stdout") {
+            console.log(result.snippet);
+        }
+        else if (result.alreadyConfigured) {
+            console.log(`Already configured at ${result.path}`);
+        }
+        else {
+            console.log(`Wrote ${result.path}`);
+            console.log("");
+            console.log("Next: open Claude Code / Codex and run any read tool (e.g. list_sites).");
+            console.log("The agent will pop a browser tab for you to authorize the connection.");
+        }
+        return;
+    }
+    console.error(`unknown command: ${cmd}`);
+    process.exitCode = 2;
+    console.error(usage());
+}
+/**
+ * True when this module is the program entrypoint.
+ *
+ * Must handle the `npm bin` case: an installed package exposes the CLI as
+ * `node_modules/.bin/showly-mcp`, a symlink to `dist/cli.js`. Node sets
+ * `process.argv[1]` to the symlink path (`…/.bin/showly-mcp`), while
+ * `import.meta.url` is the real `…/dist/cli.js`. The old guard compared the
+ * two strings (and looked for a `cli.js` suffix on argv[1]) so it silently
+ * failed through the symlink — `showly-mcp <cmd>` exited 0 with no output.
+ *
+ * Resolve argv[1] to its real path before comparing, so the symlink and the
+ * target reconcile. Exported for unit testing (the bin path can't be
+ * exercised from an in-process test runner otherwise).
+ */
+export function isMainModule(argv1, metaUrl) {
+    if (!argv1)
+        return false;
+    try {
+        return pathToFileURL(realpathSync(argv1)).href === metaUrl;
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule(process.argv[1], import.meta.url)) {
+    main(process.argv);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { SkillManifest, ToolManifestEntry } from "./manifest-types.js";
+export type { SkillManifest, ToolManifestEntry, ToolKind, } from "./manifest-types.js";
+export declare function loadManifest(): SkillManifest;
+/** Sync read of the manifest; throws if file missing or malformed. */
+export declare const manifest: SkillManifest;
+/** Tool names safe to call directly from an MCP-origin token. */
+export declare const INVOKABLE_TOOLS: readonly string[];
+/** Tool names that are intentionally blocked at the wrapper layer. */
+export declare const MCP_BLOCKED_TOOLS: readonly string[];
+export declare function getToolEntry(name: string): ToolManifestEntry | undefined;

package/dist/index.js

@@ -0,0 +1,34 @@
+// packages/showly-mcp-server/src/index.ts — programmatic API.
+//
+// Consumers (mostly tests + integration code) can do:
+//
+//   import { loadManifest, manifest, INVOKABLE_TOOLS } from "@showly/mcp-server";
+//
+// The Claude Code skill loader and the Codex plugin loader both
+// resolve manifest.json directly from their package.json fields; the
+// JS surface here is for programmatic clients (tests, integrators)
+// that want a typed view.
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+// We ship manifest.json at the package root, so from dist/index.js
+// it lives one level up.
+const MANIFEST_PATH = resolve(HERE, "..", "manifest.json");
+let cached = null;
+export function loadManifest() {
+    if (cached)
+        return cached;
+    const raw = readFileSync(MANIFEST_PATH, "utf8");
+    cached = JSON.parse(raw);
+    return cached;
+}
+/** Sync read of the manifest; throws if file missing or malformed. */
+export const manifest = loadManifest();
+/** Tool names safe to call directly from an MCP-origin token. */
+export const INVOKABLE_TOOLS = Object.freeze(manifest.tools.filter((t) => !t.mcp_origin_blocked).map((t) => t.name));
+/** Tool names that are intentionally blocked at the wrapper layer. */
+export const MCP_BLOCKED_TOOLS = Object.freeze(manifest.tools.filter((t) => t.mcp_origin_blocked).map((t) => t.name));
+export function getToolEntry(name) {
+    return manifest.tools.find((t) => t.name === name);
+}

package/dist/manifest-types.d.ts

@@ -0,0 +1,34 @@
+export type ToolKind = "read" | "write" | "production";
+export type ToolManifestEntry = {
+    name: string;
+    kind: ToolKind;
+    scopes: string[];
+    mcp_origin_blocked?: boolean;
+    note?: string;
+};
+export type SkillManifest = {
+    name: string;
+    displayName: string;
+    version: string;
+    description: string;
+    homepage: string;
+    publisher: string;
+    mcp: {
+        transport: "streamable-http" | "stdio";
+        auth: {
+            kind: "oauth" | "oauth-device-flow" | "api-token";
+            /** Scopes the client requests by default at consent time. */
+            default_scopes: string[];
+        };
+        endpoints: {
+            /** Env var that overrides the MCP server URL. */
+            url_env: string;
+            /** Default MCP server URL (the resource a client connects to). */
+            default_url: string;
+            /** Env var that overrides the API base (device-flow fallback + docs). */
+            api_url_env: string;
+        };
+    };
+    tools: ToolManifestEntry[];
+    quickstart: string[];
+};

package/dist/manifest-types.js

@@ -0,0 +1,6 @@
+// packages/showly-mcp-server/src/manifest-types.ts — shape of manifest.json.
+//
+// The manifest is the contract between the package and the host agent
+// (Claude Code, Codex, future plugins). Bumping a field requires a
+// minor version bump and a SDK release.
+export {};

package/manifest.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://showly.ai/schemas/skill-manifest-v1.json",
+  "name": "showly",
+  "displayName": "Showly",
+  "version": "0.1.0",
+  "description": "Deploy and manage Showly sites from inside Claude Code / Codex.",
+  "homepage": "https://showly.ai/docs/skills",
+  "publisher": "Showly",
+  "mcp": {
+    "transport": "streamable-http",
+    "auth": {
+      "kind": "oauth",
+      "default_scopes": [
+        "project:read",
+        "site:read",
+        "site:write",
+        "preview:read",
+        "preview:create",
+        "checks:run",
+        "publish:request",
+        "logs:read",
+        "template:read",
+        "template:create"
+      ]
+    },
+    "endpoints": {
+      "url_env": "SHOWLY_MCP_URL",
+      "default_url": "https://mcp.showly.ai",
+      "api_url_env": "SHOWLY_API_URL"
+    }
+  },
+  "tools": [
+    { "name": "list_projects", "kind": "read", "scopes": ["project:read"] },
+    { "name": "list_sites", "kind": "read", "scopes": ["site:read"] },
+    { "name": "get_site_context", "kind": "read", "scopes": ["site:read"] },
+    {
+      "name": "get_preview_status",
+      "kind": "read",
+      "scopes": ["preview:read"]
+    },
+    { "name": "get_deployment_logs", "kind": "read", "scopes": ["logs:read"] },
+    {
+      "name": "diagnose_deployment",
+      "kind": "read",
+      "scopes": ["logs:read"]
+    },
+    { "name": "list_templates", "kind": "read", "scopes": ["template:read"] },
+    { "name": "create_change_plan", "kind": "write", "scopes": ["site:read"] },
+    { "name": "apply_site_patch", "kind": "write", "scopes": ["site:write"] },
+    { "name": "create_preview", "kind": "write", "scopes": ["preview:create"] },
+    {
+      "name": "retry_deployment",
+      "kind": "write",
+      "scopes": ["preview:create"]
+    },
+    { "name": "run_checks", "kind": "write", "scopes": ["checks:run"] },
+    {
+      "name": "request_publish",
+      "kind": "write",
+      "scopes": ["publish:request"]
+    },
+    {
+      "name": "create_site_from_template",
+      "kind": "write",
+      "scopes": ["template:create", "site:write"]
+    },
+    {
+      "name": "publish_site",
+      "kind": "production",
+      "scopes": ["production:deploy"],
+      "mcp_origin_blocked": true,
+      "note": "Production-side deploy. MCP-origin calls are rejected; trigger from the web UI with step-up MFA + approval."
+    },
+    {
+      "name": "rollback_deployment",
+      "kind": "production",
+      "scopes": ["production:rollback"],
+      "mcp_origin_blocked": true,
+      "note": "Production-side rollback. Same constraint as publish_site."
+    }
+  ],
+  "quickstart": [
+    "Install: npx @showly/mcp-server install --to claude-code",
+    "Authorize: run any read tool — your agent opens the consent URL in your browser.",
+    "Demo: ask the agent to 'preview a one-line H1 change' on a site you own."
+  ]
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@showly/mcp-server",
+  "version": "0.1.0",
+  "description": "Connect Claude Code / Codex to the Showly MCP server — preview and deploy sites from your agent.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "showly-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "manifest.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:publish": "tsc -p tsconfig.json --declarationMap false",
+    "lint": "eslint .",
+    "test": "tsx --test \"src/**/*.test.ts\" \"src/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "rm -rf dist && pnpm run build:publish"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "mcp",
+    "mcp-server",
+    "showly",
+    "hosting",
+    "agent"
+  ],
+  "homepage": "https://showly.ai/docs/mcp",
+  "bugs": {
+    "url": "https://showly.ai/support"
+  },
+  "claude-code-skill": {
+    "name": "showly",
+    "version": "0.1.0",
+    "description": "Deploy and manage Showly sites from inside Claude Code.",
+    "mcp-server": {
+      "url-env": "SHOWLY_MCP_URL",
+      "default-url": "https://mcp.showly.ai",
+      "auth": "oauth",
+      "api-url-env": "SHOWLY_API_URL"
+    },
+    "tools-prefix": "showly",
+    "manifest": "manifest.json"
+  },
+  "codex-plugin": {
+    "name": "showly",
+    "version": "0.1.0",
+    "type": "mcp-server",
+    "manifest": "manifest.json"
+  },
+  "devDependencies": {
+    "@showly/eslint-config": "workspace:^",
+    "@types/node": "^25.9.1",
+    "eslint": "^9.18.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  }
+}