@nexdoc/mcp-server 0.1.0 → 0.2.1

package/README.md

@@ -28,18 +28,69 @@ Model Context Protocol server for [NexDoc Design](https://www.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`
+`create_design`, `update_design`, `check_run`, `refresh_preview`, `wait_for_run`, `notify_run_email`, `list_runs`, `export_design`, `publish_design`, `unpublish_design`, `list_formats`, `get_balance`
+
+`create_design` / `update_design` accept `notify_email: true` to email the account owner when the run finishes. `notify_run_email` does the same for a run that already started; if that run is already done, the tool returns a `warning` and no email is sent.
 
 ## Develop
 
 ```bash
+cd integrations/mcp-server
 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)
+HTTP locally:
+
+```bash
+NXD_API_KEY=nxd_test_... NXD_API_URL=http://127.0.0.1:8082 \
+  node dist/index.js --http --port 8084
+```
+
+## Release an update (npm + hosted MCP)
+
+`npx -y @nexdoc/mcp-server` pulls from npm. The Railway `mcp` service builds from this folder’s Dockerfile — redeploy it after merging so `https://mcp.nexdoc.design` matches the published package.
+
+```bash
+cd integrations/mcp-server
+
+# 1. Edit src/ (e.g. tools.ts), then bump the version
+#    patch  0.1.0 → 0.1.1   tool copy / bugfix
+#    minor  0.1.x → 0.2.0   new tool or behavior
+npm version patch --no-git-tag-version   # or: npm version minor --no-git-tag-version
+
+# 2. Build (also runs automatically via prepublishOnly)
+npm run build
+
+# 3. Smoke-check the built binary
+node dist/index.js --help 2>/dev/null || true
+grep -n "list_runs\|oldest first" dist/tools.js   # confirm your change landed
+
+# 4. Publish — run this in your own interactive terminal (not a headless agent).
+#    Passkey / WebAuthn accounts cannot use --otp. npm opens a browser (or prints
+#    an auth URL); approve with Touch ID / Face ID / security key, then publish finishes.
+npm whoami
+npm publish --access public
+
+# 5. Verify
+npm view @nexdoc/mcp-server version
+npx -y @nexdoc/mcp-server@latest --help 2>/dev/null || true
+
+# 6. Redeploy the hosted HTTP service so OAuth clients get the same tools
+#    (Railway project → mcp service → Deploy, or your usual compose/redeploy path)
+```
 
-## TODO
+### Passkey publish notes
 
-- [ ] **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`.
+- **Do the publish step yourself** in Terminal / iTerm. Agents and non-TTY shells get `EOTP` and cannot complete WebAuthn.
+- If the CLI only prints an auth URL (no browser), open that URL, complete the passkey prompt, wait for success, then re-run `npm publish --access public` in the same shell if needed.
+- Prefer npm CLI **≥ 11** (`npm -v`). Older CLIs expect TOTP `--otp` and fail on passkey-only accounts.
+- For CI later: create a **granular access token** (or Trusted Publisher) on [npmjs.com](https://www.npmjs.com) while signed in with your passkey; do not put classic forever-tokens in git.
+
+After publish, clients that pin no version (`npx -y @nexdoc/mcp-server`) pick up the new release on the next cold start. Restart Cursor / Claude Desktop if a long-lived stdio process is still on the old build.
+
+
+Install: `npx -y @nexdoc/mcp-server`
+
+Docs: [../../docs/agents/mcp.md](../../docs/agents/mcp.md)

package/dist/client.d.ts

@@ -12,6 +12,7 @@ export type RunCreated = {
     run_id: string;
     status: string;
     created_at: string;
+    notify_email?: boolean;
 };
 export type RunStatus = {
     run_id: string;
@@ -37,6 +38,7 @@ export declare function createRunJson(jobId: string, body: {
         file_id: string;
     }>;
     webhook_url?: string;
+    notify_email?: boolean;
 }): Promise<RunCreated>;
 export declare function createRunMultipart(jobId: string, opts: {
     format?: string;
@@ -44,6 +46,7 @@ export declare function createRunMultipart(jobId: string, opts: {
     content?: string;
     contentPath?: string;
     assetPaths?: string[];
+    notify_email?: boolean;
 }): Promise<RunCreated>;
 export declare function getRun(jobId: string, runId: string): Promise<RunStatus>;
 export declare function listRuns(jobId: string): Promise<{
@@ -54,6 +57,7 @@ export declare function exportDesign(jobId: string, format: "pdf" | "html", runI
 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 requestRunEmail(jobId: string, runId: string): Promise<Record<string, unknown>>;
 export declare function getBalance(): Promise<Record<string, unknown>>;
 export declare function waitForRun(jobId: string, runId: string, opts?: {
     timeoutSec?: number;

package/dist/client.js

@@ -79,6 +79,8 @@ export async function createRunMultipart(jobId, opts) {
                         : "application/octet-stream";
         form.append("files", new Blob([buf], { type }), name);
     }
+    if (opts.notify_email)
+        form.set("notify_email", "true");
     return request("POST", `/v1/jobs/${jobId}/runs`, { form });
 }
 export async function getRun(jobId, runId) {
@@ -103,6 +105,9 @@ export async function unpublishDesign(jobId) {
 export async function getPreviewLink(jobId) {
     return request("GET", `/v1/jobs/${jobId}/viewer/session`);
 }
+export async function requestRunEmail(jobId, runId) {
+    return request("POST", `/v1/jobs/${jobId}/runs/${runId}/notify-email`, { json: {} });
+}
 export async function getBalance() {
     return request("GET", "/v1/credits");
 }

package/dist/tools.js

@@ -43,6 +43,10 @@ export function registerTools(server) {
             .optional()
             .describe("If true, poll until terminal status before returning"),
         timeout_sec: z.number().optional().describe("Wait timeout seconds (default 900)"),
+        notify_email: z
+            .boolean()
+            .optional()
+            .describe("If true, email the account owner when the run finishes (completed, failed, or cancelled). Use when you cannot poll for the full duration."),
     }, async (args) => {
         try {
             let jobId = args.job_id;
@@ -58,11 +62,13 @@ export function registerTools(server) {
                     content: args.content,
                     contentPath: args.content_path,
                     assetPaths: args.asset_paths,
+                    notify_email: args.notify_email,
                 })
                 : await api.createRunJson(jobId, {
                     format: args.format,
                     instructions: args.instructions,
                     content: args.content ?? "",
+                    notify_email: args.notify_email,
                 });
             if (args.wait) {
                 const final = await api.waitForRun(jobId, created.run_id, {
@@ -70,7 +76,13 @@ export function registerTools(server) {
                 });
                 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 });
+            return ok({
+                job_id: jobId,
+                run_id: created.run_id,
+                status: created.status,
+                created_at: created.created_at,
+                notify_email: created.notify_email ?? false,
+            });
         }
         catch (err) {
             return fail(err);
@@ -83,12 +95,17 @@ export function registerTools(server) {
         content: z.string().optional(),
         wait: z.boolean().optional(),
         timeout_sec: z.number().optional(),
+        notify_email: z
+            .boolean()
+            .optional()
+            .describe("If true, email the account owner when the run finishes. Use when you cannot poll for the full duration."),
     }, async (args) => {
         try {
             const created = await api.createRunJson(args.job_id, {
                 format: args.format,
                 instructions: args.instructions,
                 content: args.content ?? "",
+                notify_email: args.notify_email,
             });
             if (args.wait) {
                 const final = await api.waitForRun(args.job_id, created.run_id, {
@@ -121,6 +138,17 @@ export function registerTools(server) {
             return fail(err);
         }
     });
+    server.tool("notify_run_email", "Request an email when an in-progress run finishes (completed, failed, or cancelled). Emails the authenticated account. If the run is already terminal, returns a warning and does not send.", {
+        job_id: z.string(),
+        run_id: z.string(),
+    }, async (args) => {
+        try {
+            return ok(await api.requestRunEmail(args.job_id, args.run_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(),
@@ -137,7 +165,7 @@ export function registerTools(server) {
             return fail(err);
         }
     });
-    server.tool("list_runs", "List runs for a job (newest first).", { job_id: z.string() }, async (args) => {
+    server.tool("list_runs", "List runs for a job (oldest first; the last entry is the latest run).", { job_id: z.string() }, async (args) => {
         try {
             return ok(await api.listRuns(args.job_id));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexdoc/mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "NexDoc Design MCP server — create, update, export, and publish designs via API key (stdio) or OAuth (HTTP).",
   "type": "module",
   "bin": {