@nexdoc/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @nexdoc/mcp-server
+
+Model Context Protocol server for [NexDoc Design](https://www.nexdoc.design).
+
+## Transports
+
+| Mode | Command | Auth |
+|------|---------|------|
+| **stdio** (default) | `npx -y @nexdoc/mcp-server` | `NXD_API_KEY` |
+| **HTTP** | `npx -y @nexdoc/mcp-server --http --port 8084` | `Authorization: Bearer` (OAuth `nxd_at_…` or API key) |
+
+## Claude Desktop / Cursor (stdio)
+
+```json
+{
+  "mcpServers": {
+    "nexdoc": {
+      "command": "npx",
+      "args": ["-y", "@nexdoc/mcp-server"],
+      "env": {
+        "NXD_API_KEY": "nxd_live_...",
+        "NXD_API_URL": "https://api.nexdoc.design"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+`create_design`, `update_design`, `check_run`, `refresh_preview`, `wait_for_run`, `list_runs`, `export_design`, `publish_design`, `unpublish_design`, `list_formats`, `get_balance`
+
+## Develop
+
+```bash
+npm install
+npm run build
+NXD_API_KEY=nxd_test_... NXD_API_URL=http://127.0.0.1:8082 node dist/index.js
+```
+
+Docs: [../../docs/agents/mcp.md](../../docs/agents/mcp.md)
+
+## TODO
+
+- [ ] **Publish `@nexdoc/mcp-server` to npm** after MCP stdio + HTTP tests pass (Inspector, compose `mcp` service, OAuth discovery). Until then, clients should run from this repo (`node dist/index.js` or Docker), not `npx -y @nexdoc/mcp-server`.

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+export declare class ApiError extends Error {
+    status: number;
+    detail: string;
+    constructor(status: number, detail: string);
+}
+export type Job = {
+    job_id: string;
+    name: string;
+};
+export type RunCreated = {
+    job_id: string;
+    run_id: string;
+    status: string;
+    created_at: string;
+};
+export type RunStatus = {
+    run_id: string;
+    job_id?: string;
+    status: string;
+    charge_usd?: number;
+    viewer_url?: string;
+    commit_hash?: string;
+    error?: string;
+    log_tail?: string;
+};
+export declare function createJob(name: string): Promise<Job>;
+export declare function listJobs(): Promise<{
+    data: Job[];
+}>;
+export declare function createRunJson(jobId: string, body: {
+    format?: string;
+    instructions?: string;
+    content?: string;
+    files?: string[];
+    assets?: Array<{
+        name: string;
+        file_id: string;
+    }>;
+    webhook_url?: string;
+}): Promise<RunCreated>;
+export declare function createRunMultipart(jobId: string, opts: {
+    format?: string;
+    instructions?: string;
+    content?: string;
+    contentPath?: string;
+    assetPaths?: string[];
+}): Promise<RunCreated>;
+export declare function getRun(jobId: string, runId: string): Promise<RunStatus>;
+export declare function listRuns(jobId: string): Promise<{
+    job_id: string;
+    data: RunStatus[];
+}>;
+export declare function exportDesign(jobId: string, format: "pdf" | "html", runId?: string): Promise<Record<string, unknown>>;
+export declare function publishDesign(jobId: string, runId?: string): Promise<Record<string, unknown>>;
+export declare function unpublishDesign(jobId: string): Promise<Record<string, unknown>>;
+export declare function getPreviewLink(jobId: string): Promise<Record<string, unknown>>;
+export declare function getBalance(): Promise<Record<string, unknown>>;
+export declare function waitForRun(jobId: string, runId: string, opts?: {
+    timeoutSec?: number;
+    intervalSec?: number;
+}): Promise<RunStatus>;

package/dist/client.js

@@ -0,0 +1,121 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { getApiBase, getBearer } from "./context.js";
+export class ApiError extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(detail);
+        this.status = status;
+        this.detail = detail;
+        this.name = "ApiError";
+    }
+}
+async function request(method, apiPath, init = {}) {
+    const headers = new Headers();
+    headers.set("Authorization", `Bearer ${getBearer()}`);
+    let body;
+    if (init.form) {
+        body = init.form;
+    }
+    else if (init.json !== undefined) {
+        headers.set("Content-Type", "application/json");
+        body = JSON.stringify(init.json);
+    }
+    const res = await fetch(`${getApiBase()}${apiPath}`, { method, headers, body });
+    const text = await res.text();
+    let parsed = null;
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = { detail: text };
+        }
+    }
+    if (!res.ok) {
+        const detail = typeof parsed === "object" && parsed && "detail" in parsed
+            ? String(parsed.detail)
+            : res.statusText;
+        throw new ApiError(res.status, detail);
+    }
+    return parsed;
+}
+export async function createJob(name) {
+    return request("POST", "/v1/jobs", { json: { name } });
+}
+export async function listJobs() {
+    return request("GET", "/v1/jobs");
+}
+export async function createRunJson(jobId, body) {
+    return request("POST", `/v1/jobs/${jobId}/runs`, { json: body });
+}
+export async function createRunMultipart(jobId, opts) {
+    const form = new FormData();
+    if (opts.format)
+        form.set("format", opts.format);
+    if (opts.instructions)
+        form.set("instructions", opts.instructions);
+    if (opts.contentPath) {
+        const buf = await readFile(opts.contentPath);
+        const name = path.basename(opts.contentPath);
+        form.append("content", new Blob([buf]), name);
+    }
+    else if (opts.content !== undefined) {
+        form.set("content", opts.content);
+    }
+    for (const assetPath of opts.assetPaths || []) {
+        const buf = await readFile(assetPath);
+        const name = path.basename(assetPath);
+        const lower = name.toLowerCase();
+        const type = lower.endsWith(".png")
+            ? "image/png"
+            : lower.endsWith(".jpg") || lower.endsWith(".jpeg")
+                ? "image/jpeg"
+                : lower.endsWith(".gif")
+                    ? "image/gif"
+                    : lower.endsWith(".pdf")
+                        ? "application/pdf"
+                        : "application/octet-stream";
+        form.append("files", new Blob([buf], { type }), name);
+    }
+    return request("POST", `/v1/jobs/${jobId}/runs`, { form });
+}
+export async function getRun(jobId, runId) {
+    return request("GET", `/v1/jobs/${jobId}/runs/${runId}`);
+}
+export async function listRuns(jobId) {
+    return request("GET", `/v1/jobs/${jobId}/runs`);
+}
+export async function exportDesign(jobId, format, runId) {
+    return request("POST", `/v1/jobs/${jobId}/export`, {
+        json: { format, run_id: runId ?? null },
+    });
+}
+export async function publishDesign(jobId, runId) {
+    return request("POST", `/v1/jobs/${jobId}/publish`, {
+        json: { run_id: runId ?? null },
+    });
+}
+export async function unpublishDesign(jobId) {
+    return request("POST", `/v1/jobs/${jobId}/unpublish`, { json: {} });
+}
+export async function getPreviewLink(jobId) {
+    return request("GET", `/v1/jobs/${jobId}/viewer/session`);
+}
+export async function getBalance() {
+    return request("GET", "/v1/credits");
+}
+export async function waitForRun(jobId, runId, opts = {}) {
+    const timeoutSec = opts.timeoutSec ?? 900;
+    const intervalSec = opts.intervalSec ?? 5;
+    const deadline = Date.now() + timeoutSec * 1000;
+    let last = null;
+    while (Date.now() < deadline) {
+        last = await getRun(jobId, runId);
+        if (["completed", "failed", "cancelled"].includes(last.status))
+            return last;
+        await new Promise((r) => setTimeout(r, intervalSec * 1000));
+    }
+    throw new Error(`Timed out after ${timeoutSec}s waiting for ${runId} (last status: ${last?.status ?? "unknown"})`);
+}

package/dist/context.d.ts

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export type RequestAuth = {
+    bearer: string;
+};
+export declare const authStore: AsyncLocalStorage<RequestAuth>;
+export declare function getBearer(): string;
+export declare function getApiBase(): string;

package/dist/context.js

@@ -0,0 +1,14 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const authStore = new AsyncLocalStorage();
+export function getBearer() {
+    const fromStore = authStore.getStore()?.bearer;
+    if (fromStore)
+        return fromStore;
+    const envKey = process.env.NXD_API_KEY?.trim();
+    if (envKey)
+        return envKey;
+    throw new Error("No auth token. Set NXD_API_KEY for stdio mode, or send Authorization: Bearer for HTTP mode.");
+}
+export function getApiBase() {
+    return (process.env.NXD_API_URL || "https://api.nexdoc.design").replace(/\/$/, "");
+}

package/dist/formats.d.ts

@@ -0,0 +1,6 @@
+export type FormatInfo = {
+    slug: string;
+    family: string;
+    when: string;
+};
+export declare const FORMATS: FormatInfo[];

package/dist/formats.js

@@ -0,0 +1,39 @@
+export const FORMATS = [
+    { slug: "landing-page", family: "web", when: "Marketing / product homepage" },
+    { slug: "link-in-bio", family: "web", when: "Compact link hub" },
+    { slug: "portfolio", family: "web", when: "Personal or studio portfolio" },
+    { slug: "lookbook", family: "web", when: "Visual product/collection story" },
+    { slug: "slide-deck", family: "slides", when: "General presentation (Reveal.js)" },
+    { slug: "presentation", family: "slides", when: "Alias of slide-deck" },
+    { slug: "pitch-deck", family: "slides", when: "Fundraising / sales narrative" },
+    { slug: "report", family: "print", when: "Multi-page narrative with figures" },
+    { slug: "proposal", family: "print", when: "Business proposal" },
+    { slug: "case-study", family: "print", when: "Case study document" },
+    { slug: "whitepaper", family: "print", when: "Long-form whitepaper" },
+    { slug: "invoice", family: "print", when: "Structured invoice" },
+    { slug: "receipt", family: "print", when: "Receipt" },
+    { slug: "resume", family: "print", when: "Resume" },
+    { slug: "cv", family: "print", when: "CV" },
+    { slug: "cover-letter", family: "print", when: "Cover letter" },
+    { slug: "contract", family: "print", when: "Contract" },
+    { slug: "nda", family: "print", when: "NDA" },
+    { slug: "certificate", family: "print", when: "Certificate / award" },
+    { slug: "brochure", family: "print", when: "Brochure" },
+    { slug: "menu", family: "print", when: "Menu" },
+    { slug: "business-card", family: "fixed-canvas", when: "Contact card" },
+    { slug: "social-card", family: "fixed-canvas", when: "Social share card" },
+    { slug: "og-image", family: "fixed-canvas", when: "Open Graph image" },
+    { slug: "banner", family: "fixed-canvas", when: "Banner" },
+    { slug: "poster", family: "fixed-canvas", when: "Poster" },
+    { slug: "invitation", family: "fixed-canvas", when: "Invitation" },
+    { slug: "ticket", family: "fixed-canvas", when: "Ticket" },
+    { slug: "boarding-pass", family: "fixed-canvas", when: "Boarding pass" },
+    { slug: "coupon", family: "fixed-canvas", when: "Coupon" },
+    { slug: "voucher", family: "fixed-canvas", when: "Voucher" },
+    { slug: "email-newsletter", family: "other", when: "HTML email layout" },
+    { slug: "infographic", family: "other", when: "Infographic" },
+    { slug: "timeline", family: "other", when: "Timeline" },
+    { slug: "roadmap", family: "other", when: "Roadmap" },
+    { slug: "org-chart", family: "other", when: "Org chart" },
+    { slug: "dashboard", family: "other", when: "Dashboard layout" },
+];

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { authStore } from "./context.js";
+import { getApiBase } from "./context.js";
+import { createServer } from "./server.js";
+function parseArgs(argv) {
+    const http = argv.includes("--http");
+    const portIdx = argv.indexOf("--port");
+    const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : Number(process.env.PORT || 8084);
+    return { http, port: Number.isFinite(port) ? port : 8084 };
+}
+async function runStdio() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("NexDoc MCP server running on stdio");
+}
+async function runHttp(port) {
+    const app = express();
+    app.use(express.json({ limit: "4mb" }));
+    const apiBase = getApiBase();
+    const resourceMetadata = {
+        resource: process.env.NXD_MCP_RESOURCE_URL || `http://127.0.0.1:${port}`,
+        authorization_servers: [apiBase],
+        scopes_supported: ["files:rw", "jobs:rw", "runs:rw"],
+        bearer_methods_supported: ["header"],
+    };
+    app.get("/.well-known/oauth-protected-resource", (_req, res) => {
+        res.json(resourceMetadata);
+    });
+    app.get("/health", (_req, res) => {
+        res.json({ ok: true, transport: "http", api: apiBase });
+    });
+    app.all("/mcp", async (req, res) => {
+        const auth = req.header("authorization") || "";
+        const bearer = auth.toLowerCase().startsWith("bearer ") ? auth.slice(7).trim() : "";
+        if (!bearer && !process.env.NXD_API_KEY) {
+            res.status(401).json({
+                error: "unauthorized",
+                detail: "Authorization: Bearer <nxd_at_... or nxd_live_...> required",
+            });
+            return;
+        }
+        const token = bearer || process.env.NXD_API_KEY.trim();
+        await authStore.run({ bearer: token }, async () => {
+            const server = createServer();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        });
+    });
+    app.listen(port, () => {
+        console.error(`NexDoc MCP HTTP server on :${port} (API ${apiBase})`);
+    });
+}
+async function main() {
+    const { http, port } = parseArgs(process.argv.slice(2));
+    if (http) {
+        await runHttp(port);
+    }
+    else {
+        await runStdio();
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "nexdoc-design",
+        version: "0.1.0",
+    });
+    registerTools(server);
+    return server;
+}

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTools(server: McpServer): void;

package/dist/tools.js

@@ -0,0 +1,179 @@
+import { z } from "zod";
+import * as api from "./client.js";
+import { FORMATS } from "./formats.js";
+function ok(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function fail(err) {
+    const message = err instanceof api.ApiError
+        ? `API ${err.status}: ${err.detail}`
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+export function registerTools(server) {
+    server.tool("list_formats", "List supported NexDoc Design format slugs with selection guidance.", {}, async () => ok({ formats: FORMATS }));
+    server.tool("get_balance", "Get the authenticated org wallet summary (USD balances, auto-topup, past_due).", {}, async () => {
+        try {
+            return ok(await api.getBalance());
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("create_design", "Create a job (or reuse job_id) and start a generative run. Prefer asset_paths in stdio mode. After completion, return viewer_url and offer export (pdf/html) — do not publish unless the user asks.", {
+        name: z.string().optional().describe("Job name when creating a new job"),
+        job_id: z.string().optional().describe("Existing job id to reuse"),
+        format: z.string().describe("Format slug, e.g. landing-page, report, business-card"),
+        instructions: z.string().describe("Design direction / edit notes"),
+        content: z.string().optional().describe("Source copy (markdown/text)"),
+        content_path: z.string().optional().describe("Local path to content file (stdio)"),
+        asset_paths: z
+            .array(z.string())
+            .optional()
+            .describe("Local asset file paths to upload (stdio)"),
+        wait: z
+            .boolean()
+            .optional()
+            .describe("If true, poll until terminal status before returning"),
+        timeout_sec: z.number().optional().describe("Wait timeout seconds (default 900)"),
+    }, async (args) => {
+        try {
+            let jobId = args.job_id;
+            if (!jobId) {
+                const job = await api.createJob(args.name || `Design ${args.format}`);
+                jobId = job.job_id;
+            }
+            const useMultipart = Boolean(args.content_path || (args.asset_paths && args.asset_paths.length));
+            const created = useMultipart
+                ? await api.createRunMultipart(jobId, {
+                    format: args.format,
+                    instructions: args.instructions,
+                    content: args.content,
+                    contentPath: args.content_path,
+                    assetPaths: args.asset_paths,
+                })
+                : await api.createRunJson(jobId, {
+                    format: args.format,
+                    instructions: args.instructions,
+                    content: args.content ?? "",
+                });
+            if (args.wait) {
+                const final = await api.waitForRun(jobId, created.run_id, {
+                    timeoutSec: args.timeout_sec,
+                });
+                return ok({ job_id: jobId, run: final });
+            }
+            return ok({ job_id: jobId, run_id: created.run_id, status: created.status, created_at: created.created_at });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("update_design", "Start an update run on an existing job with edit instructions (diff-style).", {
+        job_id: z.string(),
+        format: z.string().describe("Keep the same format unless changing medium"),
+        instructions: z.string().describe("Edit instructions against the current design"),
+        content: z.string().optional(),
+        wait: z.boolean().optional(),
+        timeout_sec: z.number().optional(),
+    }, async (args) => {
+        try {
+            const created = await api.createRunJson(args.job_id, {
+                format: args.format,
+                instructions: args.instructions,
+                content: args.content ?? "",
+            });
+            if (args.wait) {
+                const final = await api.waitForRun(args.job_id, created.run_id, {
+                    timeoutSec: args.timeout_sec,
+                });
+                return ok({ ...created, run: final });
+            }
+            return ok(created);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("check_run", "Fetch current status for a run (status, charge_usd, viewer_url, error). viewer_url is freshly minted — call this (or refresh_preview) if the user says the preview link expired.", {
+        job_id: z.string(),
+        run_id: z.string(),
+    }, async (args) => {
+        try {
+            return ok(await api.getRun(args.job_id, args.run_id));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("refresh_preview", "Mint a fresh viewer_url for a job. Use when the user says the preview link expired or 401s.", { job_id: z.string() }, async (args) => {
+        try {
+            return ok(await api.getPreviewLink(args.job_id));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("wait_for_run", "Poll a run until completed, failed, or cancelled (or timeout).", {
+        job_id: z.string(),
+        run_id: z.string(),
+        timeout_sec: z.number().optional(),
+        interval_sec: z.number().optional(),
+    }, async (args) => {
+        try {
+            return ok(await api.waitForRun(args.job_id, args.run_id, {
+                timeoutSec: args.timeout_sec,
+                intervalSec: args.interval_sec,
+            }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("list_runs", "List runs for a job (newest first).", { job_id: z.string() }, async (args) => {
+        try {
+            return ok(await api.listRuns(args.job_id));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("export_design", "Export a job as pdf or html (ZIP) and return a short-lived download_url. Prefer pdf for print/slides/cards; html for web landing pages. This is the standard download step — do not publish unless the user asks.", {
+        job_id: z.string(),
+        format: z.enum(["pdf", "html"]),
+        run_id: z.string().optional(),
+    }, async (args) => {
+        try {
+            return ok(await api.exportDesign(args.job_id, args.format, args.run_id));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("publish_design", "Publish a job to a public URL. ONLY call this when the user explicitly asks to publish or make the design public — never as a default step after create/export.", {
+        job_id: z.string(),
+        run_id: z.string().optional(),
+    }, async (args) => {
+        try {
+            return ok(await api.publishDesign(args.job_id, args.run_id));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("unpublish_design", "Unpublish a job's public site. Only when the user asks to take a published design down.", { job_id: z.string() }, async (args) => {
+        try {
+            return ok(await api.unpublishDesign(args.job_id));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@nexdoc/mcp-server",
+  "version": "0.1.0",
+  "description": "NexDoc Design MCP server — create, update, export, and publish designs via API key (stdio) or OAuth (HTTP).",
+  "type": "module",
+  "bin": {
+    "nexdoc-mcp-server": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nexdocai/nxd-design.git",
+    "directory": "integrations/mcp-server"
+  },
+  "homepage": "https://github.com/nexdocai/nxd-design/tree/main/integrations/mcp-server",
+  "bugs": {
+    "url": "https://github.com/nexdocai/nxd-design/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "nexdoc",
+    "design"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "express": "^4.21.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "license": "MIT"
+}