patchxnote-agent 0.2.7 → 0.2.9

package/README.md

@@ -9,7 +9,32 @@ PatchXNote Agent is the local AI assistant connector for PatchXNote. It lets an
 Give this one-line prompt to a local-command-capable AI assistant:
 
 ```text
-Connect PatchXNote Agent by following the public guide at https://patchx2025.feishu.cn/wiki/PnVRwYT7IirFPckairGcWPnHnCd: run npx -y patchxnote-agent@latest mcp config, add the printed MCP JSON config to this AI assistant, then guide me through npx -y patchxnote-agent@latest login in the editor terminal. Do not ask me to paste OTP codes, access tokens, or refresh tokens into chat. GitHub repository: https://github.com/ZsTs119/patchxnote-agent
+Connect PatchXNote Agent by following the public guide at https://patchx2025.feishu.cn/wiki/PnVRwYT7IirFPckairGcWPnHnCd: run npx -y patchxnote-agent@latest setup --client <my-client>, keep MCP config secret-free, and guide me through login in the same runtime that will launch the MCP server. Do not ask me to paste OTP codes, access tokens, or refresh tokens into chat. GitHub repository: https://github.com/ZsTs119/patchxnote-agent
+```
+
+Run setup for a supported local client:
+
+```sh
+npx -y patchxnote-agent@latest setup --client cursor
+npx -y patchxnote-agent@latest setup --client vscode
+npx -y patchxnote-agent@latest setup --client codex
+```
+
+PatchXNote Agent currently exposes two login surfaces and two MCP service shapes:
+
+| Mode | Entry | Use when |
+| --- | --- | --- |
+| Browser MCP login | `npx -y patchxnote-agent@latest mcp login` | Recommended for desktop editors and local MCP hosts. |
+| Terminal CLI login | `npx -y patchxnote-agent@latest login` | Terminal-only users, headless runtimes, or the legacy local Agent path. |
+| Local MCP service | `npx -y patchxnote-agent@latest mcp serve` | VS Code, Cursor, Codex, Claude Desktop, Windsurf, Trae, Qoder, WorkBuddy, and other stdio MCP clients. |
+| Hosted remote MCP gateway | `https://ws-lab.patch-x.cn/patchnote-test-api/mcp` | Feishu Aily, Doubao Work Partner, Tencent Agent Development Platform, enterprise WorkBuddy, and other platform clients that cannot run local commands. |
+
+Log in with browser OAuth, then check or clear the MCP login state:
+
+```sh
+npx -y patchxnote-agent@latest mcp login
+npx -y patchxnote-agent@latest mcp status
+npx -y patchxnote-agent@latest mcp logout --local-only
 ```
 
 Print the generic MCP config manually:
@@ -24,12 +49,18 @@ The generated config uses this universal local stdio MCP command:
 npx -y patchxnote-agent@latest mcp serve
 ```
 
-Log in from the editor terminal:
+The older terminal Agent login remains available for legacy local CLI/MCP fallback:
 
 ```sh
 npx -y patchxnote-agent@latest login
 ```
 
+`setup` reuses the same `mcp login` browser OAuth flow. The GoServer website owns phone OTP input; the local Agent owns the loopback callback, token exchange, secure storage, and stdio bridge. `mcp serve` never opens a browser during editor startup. It stores credentials in the OS-native keychain and keeps MCP config free of phone numbers, OTP codes, access tokens, refresh tokens, webhook secrets, and base URL by default.
+
+P0 local client IDs: `vscode`, `cursor`, `codex`, `claude-code`, `claude-desktop`, `windsurf`, `trae`, `qoder`, `workbuddy`.
+
+Platform clients such as Feishu Aily, Doubao Work Partner, Tencent Agent Development Platform, and enterprise WorkBuddy need the hosted remote MCP gateway plus platform-console acceptance; local `npx` setup is for desktop and terminal clients.
+
 If a client rejects `npx` or times out during first binary download, run the stable absolute-path fallback:
 
 ```sh

package/bin/patchxnote-agent.js

@@ -29,10 +29,18 @@ async function main(argv) {
     await runLogin(parsed);
     return;
   }
+  if (parsed.command === "setup") {
+    await runSetup(parsed);
+    return;
+  }
   if (parsed.command === "mcp" && parsed.subcommand === "config") {
     printUniversalMCPConfig();
     return;
   }
+  if (parsed.command === "mcp" && ["login", "status", "logout"].includes(parsed.subcommand)) {
+    await runMCPSubcommand(parsed);
+    return;
+  }
   if (parsed.command === "mcp" && parsed.subcommand === "serve") {
     await runMCPServe(parsed);
     return;
@@ -74,6 +82,14 @@ async function runLogin(parsed) {
   process.exitCode = code;
 }
 
+async function runSetup(parsed) {
+  const plan = await ensureBinary(parsed.options, { stderr: process.stderr });
+  const code = await spawnAndWait(plan.install_path, ["setup", ...parsed.passthroughArgs], {
+    stdio: "inherit"
+  });
+  process.exitCode = code;
+}
+
 async function runMCPServe(parsed) {
   const plan = await ensureBinary(parsed.options, { stderr: process.stderr });
   const code = await spawnAndWait(plan.install_path, ["mcp", "serve", ...parsed.passthroughArgs], {
@@ -83,6 +99,14 @@ async function runMCPServe(parsed) {
   process.exitCode = code;
 }
 
+async function runMCPSubcommand(parsed) {
+  const plan = await ensureBinary(parsed.options, { stderr: process.stderr });
+  const code = await spawnAndWait(plan.install_path, ["mcp", parsed.subcommand, ...parsed.passthroughArgs], {
+    stdio: "inherit"
+  });
+  process.exitCode = code;
+}
+
 function createInstallPlan(command, options = {}) {
   const target = resolveTarget(options.platform || process.platform, options.arch || process.arch);
   const installDir = options.installDir || defaultInstallDir(process.platform);
@@ -371,13 +395,21 @@ function parseArgs(argv) {
     const launcher = parseLauncherOptions(rest, { allowPassthrough: true, rejectPrintConfig: true });
     return { command, options: launcher.options, passthroughArgs: launcher.passthroughArgs };
   }
+  if (command === "setup") {
+    const launcher = parseLauncherOptions(rest, {
+      allowPassthrough: true,
+      passThroughDryRun: true,
+      passThroughPrintConfig: true
+    });
+    return { command, options: launcher.options, passthroughArgs: launcher.passthroughArgs };
+  }
   if (command === "mcp") {
     const [subcommand, ...subcommandArgs] = rest;
-    if (!["serve", "config"].includes(subcommand)) {
+    if (!["serve", "config", "login", "status", "logout"].includes(subcommand)) {
       throw new Error(mcpUsage());
     }
     const launcher = parseLauncherOptions(subcommandArgs, {
-      allowPassthrough: subcommand === "serve",
+      allowPassthrough: subcommand !== "config",
       rejectPrintConfig: true
     });
     return { command, subcommand, options: launcher.options, passthroughArgs: launcher.passthroughArgs };
@@ -432,8 +464,16 @@ function parseLauncherOptions(rest, settings = {}) {
         }
         throw new Error(`unknown option ${arg}`);
       case "--dry-run":
+        if (settings.passThroughDryRun) {
+          passthroughArgs.push(arg);
+          break;
+        }
         throw new Error("--dry-run is only valid for install/update/uninstall");
       case "--print-config":
+        if (settings.passThroughPrintConfig) {
+          passthroughArgs.push(arg);
+          break;
+        }
         if (settings.rejectPrintConfig) {
           throw new Error("--print-config is not valid for this command");
         }
@@ -629,11 +669,11 @@ function verifyChecksum(binary, assetName, checksumsText) {
 }
 
 function usage() {
-  return "usage: patchxnote-agent <install|update|uninstall|login|mcp> [options]";
+  return "usage: patchxnote-agent <install|update|uninstall|login|setup|mcp> [options]";
 }
 
 function mcpUsage() {
-  return "usage: patchxnote-agent mcp <serve|config> [options]";
+  return "usage: patchxnote-agent mcp <serve|config|login|status|logout> [options]";
 }
 
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchxnote-agent",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Installer wrapper for the PatchXNote Agent CLI and local MCP server.",
   "repository": {
     "type": "git",