plyo-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * Plyo MCP server — the flagship agent integration.
+ *
+ * Setup (Claude Code):  claude mcp add plyo -e PLYO_TOKEN=plyo_... -- npx plyo-mcp
+ * Then just say "save my work" or "publish this".
+ *
+ * Deliberately a thin client: real state lives in the Plyo API and in the
+ * project's real git repo. Every tool returns text an agent can act on, and
+ * errors pass through the API's {code, message, hint} shape.
+ */
+import { execFile } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const run = promisify(execFile);
+const API_URL = process.env.PLYO_API_URL ?? "https://api.plyo.dev";
+const TOKEN = process.env.PLYO_TOKEN ?? "";
+const REMOTE_NAME = "plyo";
+async function api(path, init = {}) {
+    const res = await fetch(`${API_URL}${path}`, {
+        ...init,
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${TOKEN}`,
+            ...(init.headers ?? {}),
+        },
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        throw new Error(`${body.message ?? `API error ${res.status}`}${body.hint ? `\nHint: ${body.hint}` : ""}`);
+    }
+    return body;
+}
+async function git(args, cwd = process.cwd()) {
+    const { stdout } = await run("git", args, { cwd });
+    return stdout.trim();
+}
+async function readLink(cwd = process.cwd()) {
+    try {
+        return JSON.parse(await readFile(join(cwd, ".plyo", "project.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function requireLink() {
+    const link = await readLink();
+    if (!link) {
+        throw new Error("This folder isn't linked to a Plyo project yet. Use link_project (existing project) or create_project (new one) first.");
+    }
+    return link;
+}
+function remoteUrl(slug) {
+    const host = new URL(API_URL).host;
+    const proto = API_URL.startsWith("http://") ? "http" : "https";
+    return `${proto}://ai:${TOKEN}@${host}/git/${slug}.git`;
+}
+async function ensureRemote(slug) {
+    try {
+        await git(["rev-parse", "--git-dir"]);
+    }
+    catch {
+        await git(["init", "-b", "main"]);
+    }
+    const url = remoteUrl(slug);
+    try {
+        await git(["remote", "set-url", REMOTE_NAME, url]);
+    }
+    catch {
+        await git(["remote", "add", REMOTE_NAME, url]);
+    }
+}
+async function writeLink(link) {
+    await mkdir(join(process.cwd(), ".plyo"), { recursive: true });
+    await writeFile(join(process.cwd(), ".plyo", "project.json"), JSON.stringify(link, null, 2));
+    // Keep the credentialed remote out of the project's own history.
+    try {
+        const ignorePath = join(process.cwd(), ".gitignore");
+        const current = await readFile(ignorePath, "utf8").catch(() => "");
+        if (!current.includes(".plyo/")) {
+            await writeFile(ignorePath, `${current.trimEnd()}\n.plyo/\n`.trimStart());
+        }
+    }
+    catch {
+        /* best effort */
+    }
+}
+/**
+ * Push to a branch, handling the first-push case: a brand-new project's
+ * remote holds only the empty "Project created" commit, which an existing
+ * local history can't fast-forward onto. That one case is safe to replace.
+ */
+async function pushBranch(branch) {
+    try {
+        await git(["push", REMOTE_NAME, `HEAD:${branch}`]);
+        return;
+    }
+    catch (err) {
+        if (!/fetch first|non-fast-forward|rejected/i.test(String(err)))
+            throw err;
+        await git(["fetch", REMOTE_NAME, branch]);
+        const commitCount = await git(["rev-list", "--count", "FETCH_HEAD"]);
+        const tree = await git(["ls-tree", "FETCH_HEAD"]);
+        if (commitCount === "1" && tree === "") {
+            await git(["push", "--force", REMOTE_NAME, `HEAD:${branch}`]);
+            return;
+        }
+        throw new Error(`The project already has saved work that this folder doesn't have. Bring it in first with: git pull ${REMOTE_NAME} ${branch} --rebase — then save again. (Never force-push; the user's timeline lives there.)`);
+    }
+}
+function text(s) {
+    return { content: [{ type: "text", text: s }] };
+}
+const server = new McpServer({ name: "plyo", version: "0.1.0" });
+server.tool("list_projects", "List the user's Plyo projects (name, slug, live URL).", {}, async () => {
+    const data = await api("/v1/projects");
+    if (!data.projects.length)
+        return text("No projects yet. create_project starts one.");
+    return text(data.projects.map((p) => `${p.name} (slug: ${p.slug}) — ${p.liveUrl}`).join("\n"));
+});
+server.tool("create_project", "Create a new Plyo project and link the current folder to it. Existing files stay untouched; use save_checkpoint afterwards to store them.", { name: z.string().describe("Human-friendly project name, e.g. 'Sunrise Yoga'") }, async ({ name }) => {
+    const project = await api("/v1/projects", { method: "POST", body: JSON.stringify({ name }) });
+    await ensureRemote(project.slug);
+    await writeLink({ projectId: project.id, slug: project.slug });
+    return text(`Project "${name}" created and linked to this folder.\nSlug: ${project.slug}\nWill publish at: ${project.liveUrl}\nNext: save_checkpoint to store the current files.`);
+});
+server.tool("link_project", "Link the current folder to an existing Plyo project by slug.", { slug: z.string().describe("The project slug, from list_projects") }, async ({ slug }) => {
+    const project = await api(`/v1/projects/${slug}`);
+    await ensureRemote(project.slug);
+    await writeLink({ projectId: project.id, slug: project.slug });
+    return text(`Linked this folder to "${slug}". save_checkpoint now saves to its timeline.`);
+});
+server.tool("save_checkpoint", "Save the current state of the project as a checkpoint on the user's Plyo timeline. Call this after completing a piece of work.", {
+    note: z
+        .string()
+        .describe("One plain-English sentence describing what changed, written for a non-technical user, e.g. 'Added a pricing page with three plans'"),
+}, async ({ note }) => {
+    const link = await requireLink();
+    await ensureRemote(link.slug);
+    await git(["add", "-A"]);
+    try {
+        await git(["commit", "-m", note]);
+    }
+    catch (err) {
+        const msg = String(err);
+        if (!/nothing to commit/i.test(msg))
+            throw err;
+    }
+    // Save into the current draft when one is checked out, else to live.
+    const currentBranch = await git(["rev-parse", "--abbrev-ref", "HEAD"]).catch(() => "main");
+    const target = currentBranch.startsWith("draft/") ? currentBranch : "live";
+    await pushBranch(target);
+    return text(`Checkpoint saved: "${note}". It's on the user's timeline and can be restored anytime.`);
+});
+server.tool("start_draft", "Start a Draft — a safe copy of the project to try changes without touching the live version. Switches this folder to the draft.", { name: z.string().describe("What this draft tries, e.g. 'Trying a new pricing page'") }, async ({ name }) => {
+    const link = await requireLink();
+    const data = await api(`/v1/projects/${link.slug}/drafts`, { method: "POST", body: JSON.stringify({ name }) });
+    const branch = data.hint.match(/"([^"]+)"/)?.[1];
+    if (branch) {
+        await git(["fetch", REMOTE_NAME, branch]);
+        await git(["checkout", "-B", branch, `${REMOTE_NAME}/${branch}`]);
+    }
+    return text(`Draft "${name}" started; this folder now works in the draft. save_checkpoint saves into it. Preview: ${data.draft.previewUrl}. Apply it with the dashboard or POST /v1/drafts/${data.draft.id}/apply.`);
+});
+server.tool("publish", "Publish the project's latest checkpoint to its live URL. Waits for the result; on failure, returns a plain-English cause plus a fix you can act on.", {}, async () => {
+    const link = await requireLink();
+    const pub = await api(`/v1/projects/${link.slug}/publish`, { method: "POST", body: "{}" });
+    for (let i = 0; i < 120; i++) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const build = await api(`/v1/builds/${pub.build.id}`);
+        if (build.status === "ready") {
+            return text(`Published. The site is live at ${pub.liveUrl}`);
+        }
+        if (build.status === "failed" || build.status === "needs_server") {
+            return text(`Publish failed: ${build.error_plain}\n\nFix it like this:\n${build.error_fix_prompt}`);
+        }
+    }
+    return text(`The build is taking unusually long. Check later with get_build_error.`);
+});
+server.tool("get_build_error", "Get the most recent build's status, and if it failed, the plain-English error and the fix guidance.", {}, async () => {
+    const link = await requireLink();
+    const timeline = await api(`/v1/projects/${link.slug}/checkpoints`);
+    if (!timeline.checkpoints.length)
+        return text("No checkpoints yet, so no builds either.");
+    // The events feed carries build outcomes; simplest reliable source is the
+    // project's latest publish attempt via /v1/projects/:slug.
+    const project = await api(`/v1/projects/${link.slug}`);
+    return text(project.isLive
+        ? `The site is live at ${project.liveUrl}. If a later publish failed, re-run publish to see the error.`
+        : "The project isn't live yet. Run publish to build it — any failure comes back with a plain-English cause and a fix.");
+});
+server.tool("get_timeline", "Show the project's recent checkpoints (the timeline) with what changed in each.", {}, async () => {
+    const link = await requireLink();
+    const data = await api(`/v1/projects/${link.slug}/checkpoints`);
+    if (!data.checkpoints.length)
+        return text("No checkpoints yet. save_checkpoint creates the first one.");
+    return text(data.checkpoints
+        .slice(0, 15)
+        .map((c) => `${c.createdAt} — ${c.note} (${c.source}) [${c.id}]`)
+        .join("\n"));
+});
+server.tool("restore", "Restore the project to an earlier checkpoint. Never destructive: a new checkpoint is created and everything stays on the timeline.", { checkpointId: z.string().describe("Checkpoint id from get_timeline") }, async ({ checkpointId }) => {
+    const link = await requireLink();
+    const data = await api(`/v1/projects/${link.slug}/restore`, { method: "POST", body: JSON.stringify({ checkpointId }) });
+    await git(["fetch", REMOTE_NAME, "live"]);
+    await git(["checkout", "-B", "main", `${REMOTE_NAME}/live`]).catch(() => "");
+    return text(`${data.checkpoint.note}. Nothing was deleted — the timeline keeps every version.`);
+});
+if (!TOKEN) {
+    console.error("PLYO_TOKEN is not set. Create an AI key in the dashboard (Settings → AI keys) and set PLYO_TOKEN.");
+    process.exit(1);
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "plyo-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Plyo — Undo and Publish for everything your AI builds. Save checkpoints, publish, restore.",
+  "type": "module",
+  "bin": {
+    "plyo-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "plyo",
+    "claude",
+    "deploy",
+    "version-control"
+  ],
+  "homepage": "https://plyo.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/plyo/plyo"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.2"
+  }
+}