@zegazone_mcp/mcp 2.0.0

package/README.md

@@ -0,0 +1,123 @@
+# @zegazone_mcp/mcp
+
+MCP wrapper over `POST /functions/v1/thirdparty-v1`.
+
+## Quick start
+
+```bash
+npx @zegazone_mcp/mcp --pair
+```
+
+One-time OAuth pairing stores credentials in `~/.zegazone-mcp/credentials.json`. Access tokens refresh automatically — you never handle tokens manually.
+
+## MCP client config
+
+**Claude Desktop / Cursor:**
+
+```json
+{
+  "mcpServers": {
+    "zegazone": {
+      "command": "npx",
+      "args": ["@zegazone_mcp/mcp"]
+    }
+  }
+}
+```
+
+Set `ZEGA_API_BASE=https://api.zegaphone.com` in env if needed (defaults apply for production).
+
+## What this server does
+
+- Exposes stable MCP tools (`collections_delete`, `media_move`, etc.) mapped to API `op` values.
+- Keeps API as source of truth.
+- Applies safety defaults for destructive operations (`dry_run` when neither `confirm` nor `dry_run` is provided).
+- Adds `idempotency_key` automatically to mutating operations when absent.
+
+## Tool mapping
+
+Examples:
+
+- `operations_list` -> `operations.list`
+- `collections_delete` -> `collections.delete`
+- `media_delete` -> `media.delete`
+- `media_move` -> `media.move`
+- `media_reorder` -> `media.reorder`
+
+Also includes generic `thirdparty_call` for forward compatibility.
+
+## Configuration
+
+Copy `.env.example` to `.env.local`. You need `ZEGA_API_BASE` plus **either** a one-time OAuth pairing **or** a static access token.
+
+**OAuth (recommended):** stores refresh + access metadata in `~/.zegazone-mcp/credentials.json`. The server refreshes access tokens automatically.
+
+```bash
+export ZEGA_API_BASE=https://api.zegaphone.com
+npx @zegazone_mcp/mcp --pair
+```
+
+**Legacy:** set `ZEGA_ACCESS_TOKEN` to a short-lived JWT (see `supabase/docs/OPENCLAW_ZEGAZONE.md`).
+
+Optional: `ZEGA_APP_BASE` (defaults to `https://www.zegazone.com`), `ZEGA_OAUTH_CLIENT_ID`, `ZEGA_CREDENTIALS_PATH`, `ZEGA_DEFAULT_DRY_RUN`, `ZEGA_TIMEOUT_MS`.
+
+## Local development
+
+Clone the repo and work from `supabase/mcp-zegazone-thirdparty/`:
+
+```bash
+npm install
+npm run dev
+```
+
+PowerShell helper:
+
+```powershell
+./scripts/run-local.ps1
+```
+
+## Build / run
+
+```bash
+npm run build
+npm start
+```
+
+Check version:
+
+```bash
+npx @zegazone_mcp/mcp --version
+```
+
+## Smoke tests
+
+```bash
+npm run smoke
+```
+
+Smoke tests call the backing API directly and validate read + destructive dry-run paths. Use `ZEGA_ACCESS_TOKEN` or a credential file whose `access_token` is still valid (fresh pairing).
+
+## Hosted deployment (container)
+
+```bash
+docker build -t zegazone-mcp .
+docker run --rm \
+  -e ZEGA_API_BASE=https://api.zegaphone.com \
+  -e ZEGA_ACCESS_TOKEN=<token> \
+  -e ZEGA_DEFAULT_DRY_RUN=true \
+  zegazone-mcp
+```
+
+Mount a credential file instead of `ZEGA_ACCESS_TOKEN` if you use pairing on the host:
+
+```bash
+docker run --rm \
+  -v "$HOME/.zegazone-mcp:/root/.zegazone-mcp:ro" \
+  -e ZEGA_API_BASE=https://api.zegaphone.com \
+  -e ZEGA_DEFAULT_DRY_RUN=true \
+  zegazone-mcp
+```
+
+## npm
+
+Published as [`@zegazone_mcp/mcp`](https://www.npmjs.com/package/@zegazone_mcp/mcp).

package/dist/api.js

@@ -0,0 +1,159 @@
+import { STATUS_CODES } from "node:http";
+import { DESTRUCTIVE_OPS, MUTATING_OPS } from "./ops.js";
+function jsonReplacerForApiErrors(_key, value) {
+    if (value instanceof Error) {
+        return { name: value.name, message: value.message };
+    }
+    return value;
+}
+/** API / gateway `error` fields may be strings or structured objects — never rely on String(obj). */
+function coerceApiErrorField(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (value == null)
+        return "api_error";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "api_error";
+    }
+}
+/**
+ * Thrown on non-2xx API responses so MCP hosts see a real `Error#message` (plain objects become "[object Object]").
+ */
+export class ThirdPartyRequestError extends Error {
+    payload;
+    constructor(payload) {
+        super(ThirdPartyRequestError.formatMessage(payload));
+        this.name = "ThirdPartyRequestError";
+        this.payload = payload;
+    }
+    static formatMessage(p) {
+        const phrase = STATUS_CODES[p.status] ?? "";
+        const headline = phrase ? `HTTP ${p.status} ${phrase}` : `HTTP ${p.status}`;
+        const summary = {
+            status: p.status,
+            error: p.error,
+        };
+        if (p.detail !== undefined)
+            summary.detail = p.detail;
+        if (p.field !== undefined)
+            summary.field = p.field;
+        if (p.need !== undefined)
+            summary.need = p.need;
+        if (p.raw !== undefined)
+            summary.raw = p.raw;
+        let body;
+        try {
+            body = JSON.stringify(summary, jsonReplacerForApiErrors, 2);
+        }
+        catch {
+            body = JSON.stringify({ status: p.status, error: p.error }, jsonReplacerForApiErrors, 2);
+        }
+        return `${headline}\n\n${body}`;
+    }
+}
+export function ensureDestructiveSafety(op, payload, defaultDryRun) {
+    if (!DESTRUCTIVE_OPS.has(op))
+        return payload;
+    const hasConfirm = payload.confirm === true;
+    const hasDryRun = payload.dry_run === true;
+    if (hasConfirm || hasDryRun)
+        return payload;
+    return {
+        ...payload,
+        dry_run: defaultDryRun,
+    };
+}
+export function ensureIdempotency(op, payload) {
+    if (!MUTATING_OPS.has(op))
+        return payload;
+    if (typeof payload.idempotency_key === "string" && payload.idempotency_key.trim()) {
+        return payload;
+    }
+    return {
+        ...payload,
+        idempotency_key: `mcp-${op}-${Date.now()}`,
+    };
+}
+async function callThirdPartyOnce(config, accessToken, op, args) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+    try {
+        const body = JSON.stringify({
+            op,
+            ...args,
+        });
+        const res = await fetch(`${config.apiBase}/functions/v1/thirdparty-v1`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body,
+            signal: controller.signal,
+        });
+        const parsed = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const detail = typeof parsed.detail === "string"
+                ? parsed.detail
+                : typeof parsed.message === "string"
+                    ? parsed.message
+                    : undefined;
+            const errorObj = {
+                error: coerceApiErrorField(parsed.error ?? "api_error"),
+                detail,
+                field: typeof parsed.field === "string" ? parsed.field : undefined,
+                need: parsed.need ?? undefined,
+                status: res.status,
+                raw: parsed,
+            };
+            return { ok: false, error: errorObj };
+        }
+        return { ok: true, data: parsed };
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        throw new ThirdPartyRequestError({
+            error: "transport_error",
+            detail: message,
+            status: 502,
+            raw: e,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function callThirdParty(config, op, args) {
+    let token = await config.getAccessToken();
+    let attempt = await callThirdPartyOnce(config, token, op, args);
+    if (!attempt.ok && attempt.error.status === 401) {
+        // The server rejected our token. The cached access_token may be structurally unexpired
+        // but signature-invalid (e.g. server-side JWT_SECRET rotated). Bypass every cache and
+        // run the OAuth refresh grant unconditionally.
+        let refreshed = null;
+        try {
+            refreshed = await config.forceRefreshAccessToken();
+        }
+        catch (e) {
+            // If we cannot refresh (legacy ZEGA_ACCESS_TOKEN mode, or refresh_token revoked),
+            // surface the original 401 with the refresh failure attached as context.
+            const refreshMsg = e instanceof Error ? e.message : String(e);
+            throw new ThirdPartyRequestError({
+                ...attempt.error,
+                detail: attempt.error.detail
+                    ? `${attempt.error.detail} (token refresh also failed: ${refreshMsg})`
+                    : `token refresh failed: ${refreshMsg}`,
+            });
+        }
+        attempt = await callThirdPartyOnce(config, refreshed, op, args);
+    }
+    if (!attempt.ok) {
+        throw new ThirdPartyRequestError(attempt.error);
+    }
+    return attempt.data;
+}

package/dist/config.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import { createAccessTokenHandle } from "./token-provider.js";
+import { defaultCredentialsPath } from "./token-store.js";
+function readBool(input, fallback) {
+    if (!input)
+        return fallback;
+    const v = input.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+function hasRefreshInFileSync(credentialsPath) {
+    try {
+        const raw = fs.readFileSync(credentialsPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.refresh_token === "string" && parsed.refresh_token.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function loadConfig() {
+    const apiBase = (process.env.ZEGA_API_BASE ?? "").trim().replace(/\/+$/, "");
+    if (!apiBase) {
+        throw new Error("Missing ZEGA_API_BASE");
+    }
+    const credentialsPath = defaultCredentialsPath();
+    const legacyAccessToken = (process.env.ZEGA_ACCESS_TOKEN ?? "").trim() || null;
+    const timeoutMsRaw = Number(process.env.ZEGA_TIMEOUT_MS ?? "30000");
+    const timeoutMs = Number.isFinite(timeoutMsRaw) && timeoutMsRaw > 0 ? timeoutMsRaw : 30000;
+    const fileHasRefresh = hasRefreshInFileSync(credentialsPath);
+    if (!fileHasRefresh && !legacyAccessToken) {
+        throw new Error(`Missing credentials. Run: npm run oauth-pair (saves ${credentialsPath}) or set ZEGA_ACCESS_TOKEN.`);
+    }
+    const handle = createAccessTokenHandle({
+        apiBase,
+        credentialsPath,
+        legacyAccessToken,
+        timeoutMs,
+    });
+    return {
+        apiBase,
+        defaultDryRun: readBool(process.env.ZEGA_DEFAULT_DRY_RUN, true),
+        timeoutMs,
+        getAccessToken: handle.getAccessToken,
+        forceRefreshAccessToken: handle.forceRefreshAccessToken,
+        invalidateAccessTokenCache: handle.invalidateMemory,
+    };
+}

package/dist/credentials-types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(moduleDir, "..");
+function readVersion() {
+    const pkg = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+    return pkg.version ?? "0.0.0";
+}
+async function runPair() {
+    const script = path.join(packageRoot, "scripts", "oauth-pair.mjs");
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [script], {
+            stdio: "inherit",
+            env: process.env,
+        });
+        child.on("close", (code) => resolve(code ?? 1));
+        child.on("error", () => resolve(1));
+    });
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--version")) {
+        console.log(readVersion());
+        process.exit(0);
+    }
+    if (args.includes("--pair")) {
+        process.exit(await runPair());
+    }
+    const config = await loadConfig();
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.stack ?? err.message : String(err);
+    console.error(`[zegazone-mcp] startup failed: ${message}`);
+    process.exit(1);
+});

package/dist/oauth-client.js

@@ -0,0 +1,67 @@
+export async function exchangeAuthorizationCode(params) {
+    const body = JSON.stringify({
+        grant_type: "authorization_code",
+        client_id: params.clientId,
+        code: params.code,
+        redirect_uri: params.redirectUri,
+        code_verifier: params.codeVerifier,
+    });
+    return postToken(params.apiBase, body, params.timeoutMs);
+}
+export async function refreshWithStoredRefresh(params) {
+    const body = JSON.stringify({
+        grant_type: "refresh_token",
+        client_id: params.clientId,
+        refresh_token: params.refreshToken,
+    });
+    return postToken(params.apiBase, body, params.timeoutMs);
+}
+function toStoredCredentials(clientId, tokens) {
+    const access_expires_at_ms = Date.now() + Math.max(0, tokens.expires_in) * 1000;
+    return {
+        version: 1,
+        client_id: clientId,
+        refresh_token: tokens.refresh_token,
+        access_token: tokens.access_token,
+        access_expires_at_ms,
+    };
+}
+export async function refreshAndPersist(params) {
+    const tokens = await refreshWithStoredRefresh({
+        apiBase: params.apiBase,
+        clientId: params.previous.client_id,
+        refreshToken: params.previous.refresh_token,
+        timeoutMs: params.timeoutMs,
+    });
+    const next = toStoredCredentials(params.previous.client_id, tokens);
+    await params.writeStoredCredentials(params.credentialsPath, next);
+    return next;
+}
+async function postToken(apiBase, body, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${apiBase}/functions/v1/thirdparty-oauth-token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            signal: controller.signal,
+        });
+        const parsed = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const err = String(parsed.error ?? "token_error");
+            const detail = typeof parsed.detail === "string" ? parsed.detail : JSON.stringify(parsed);
+            throw new Error(`OAuth token endpoint failed (${res.status}): ${err} — ${detail}`);
+        }
+        const access_token = typeof parsed.access_token === "string" ? parsed.access_token : "";
+        const refresh_token = typeof parsed.refresh_token === "string" ? parsed.refresh_token : "";
+        const expires_in = typeof parsed.expires_in === "number" ? parsed.expires_in : 3600;
+        if (!access_token || !refresh_token) {
+            throw new Error("OAuth token response missing access_token or refresh_token");
+        }
+        return { access_token, refresh_token, expires_in };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/ops.js

@@ -0,0 +1,100 @@
+export const OP_TOOL_MAP = {
+    ping: "ping",
+    schema_get: "schema.get",
+    operations_list: "operations.list",
+    operation_describe: "operation.describe",
+    ui_state_get: "ui.state.get",
+    ui_state_set: "ui.state.set",
+    collections_list: "collections.list",
+    collections_batch_get: "collections.batch.get",
+    collections_export: "collections.export",
+    collections_create: "collections.create",
+    collections_update: "collections.update",
+    collections_delete: "collections.delete",
+    collections_restore: "collections.restore",
+    collections_reorder: "collections.reorder",
+    collections_archive: "collections.archive",
+    collections_unarchive: "collections.unarchive",
+    collections_like: "collections.like",
+    collections_unlike: "collections.unlike",
+    collections_liked_list: "collections.liked.list",
+    collections_search: "collections.search",
+    collections_browse: "collections.browse",
+    collections_stats_get: "collections.stats.get",
+    collections_share_url: "collections.share_url",
+    collections_publish: "collections.publish",
+    collections_unpublish: "collections.unpublish",
+    aliases_list: "aliases.list",
+    aliases_follow: "aliases.follow",
+    aliases_unfollow: "aliases.unfollow",
+    aliases_following_list: "aliases.following.list",
+    profile_get: "profile.get",
+    profile_update: "profile.update",
+    collaborators_list: "collaborators.list",
+    collaborators_invite: "collaborators.invite",
+    collaborators_revoke: "collaborators.revoke",
+    collaborators_invites_list: "collaborators.invites.list",
+    collaborators_invites_received: "collaborators.invites.received",
+    collaborators_invite_accept: "collaborators.invite.accept",
+    collaborators_invite_decline: "collaborators.invite.decline",
+    media_list: "media.list",
+    media_search: "media.search",
+    media_batch_list: "media.batch.list",
+    media_download: "media.download",
+    media_create: "media.create",
+    media_update: "media.update",
+    media_describe: "media.describe",
+    media_replace: "media.replace",
+    media_delete: "media.delete",
+    media_restore: "media.restore",
+    media_move: "media.move",
+    media_copy: "media.copy",
+    media_reorder: "media.reorder",
+    media_archive: "media.archive",
+    media_unarchive: "media.unarchive",
+    media_text_note_add: "media.text_note.add",
+    media_text_note_get: "media.text_note.get",
+    media_text_note_update: "media.text_note.update",
+    media_text_note_delete: "media.text_note.delete",
+};
+export const DESTRUCTIVE_OPS = new Set([
+    "collections.delete",
+    "collections.restore",
+    "media.delete",
+    "media.restore",
+    "media.text_note.delete",
+]);
+export const MUTATING_OPS = new Set([
+    "ui.state.set",
+    "collections.create",
+    "collections.update",
+    "collections.delete",
+    "collections.restore",
+    "collections.reorder",
+    "collections.archive",
+    "collections.unarchive",
+    "collections.like",
+    "collections.unlike",
+    "collections.publish",
+    "collections.unpublish",
+    "aliases.follow",
+    "aliases.unfollow",
+    "profile.update",
+    "collaborators.invite",
+    "collaborators.revoke",
+    "collaborators.invite.accept",
+    "collaborators.invite.decline",
+    "media.create",
+    "media.update",
+    "media.replace",
+    "media.delete",
+    "media.restore",
+    "media.move",
+    "media.copy",
+    "media.reorder",
+    "media.archive",
+    "media.unarchive",
+    "media.text_note.add",
+    "media.text_note.update",
+    "media.text_note.delete",
+]);