@actiondock/cli 2.0.1 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "ActionDock CLI facade for developing, testing, building, and exporting standalone Agent Actions and Skills",
   "type": "module",
   "bin": {

package/src/commands/config.ts

@@ -1,11 +1,15 @@
 import {
   createGlobalStorage,
   createStorage,
+  deleteRemoteConfig,
+  fetchRemoteConfig,
   filterWithFallbackInfo,
   isSecretConfigKey,
   loadProjectConfig,
   maskSecretValue,
   resolvePackageRoot,
+  resolveTarget,
+  setRemoteConfig,
   type ConfigItemDefinition,
 } from "@actiondock/core";
 import { Command } from "commander";
@@ -69,18 +73,17 @@ export function registerConfigCommands(program: Command): void {
             resolvedValue = itemDef.default;
             source = "default";
             status = "DEFAULT";
-          } else {
-            status = "MISSING";
           }
 
+          const displayValue = isSecret && resolvedValue !== undefined ? maskSecretValue(resolvedValue) : resolvedValue;
+
           return {
             key,
-            description: itemDef.description || "",
-            secret: isSecret,
-            default: itemDef.default,
+            value: displayValue,
             status,
             source,
-            value: isSecret && resolvedValue !== undefined ? maskSecretValue(resolvedValue) : resolvedValue,
+            secret: isSecret,
+            description: itemDef.description || "",
             required: itemDef.default === undefined,
           };
         });
@@ -141,16 +144,45 @@ export function registerConfigCommands(program: Command): void {
     .description("List configuration entries (Global & Project)")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-g, --global", "Show only global configurations")
+    .option("-p, --profile <name>", "Query config on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
     .option("--reveal, --show-secrets", "Reveal plain text values for secrets")
     .option("--no-fallback", "Disable fallback to full list when no items match intent")
     .option("--json", "Output as JSON")
-    .action((patterns, options) => {
+    .action(async (patterns, options) => {
       try {
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const shouldFallback = options.fallback !== false;
         const reveal = options.reveal || options.showSecrets;
 
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const res = await fetchRemoteConfig(target.serverUrl!, target.token, options.package);
+          if (options.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+          }
+          console.log(
+            `Config on remote server ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""}:\n`
+          );
+          const entries = Object.entries(res.values || {});
+          if (entries.length === 0) {
+            console.log("  (No config entries stored)");
+          } else {
+            for (const [k, v] of entries) {
+              console.log(`  ${k.padEnd(24)} = ${JSON.stringify(v)}`);
+            }
+          }
+          return;
+        }
+
         const globalStorage = createGlobalStorage();
         const globalConfig = globalStorage.listConfig();
 
@@ -246,10 +278,30 @@ export function registerConfigCommands(program: Command): void {
     .description("Get a configuration value")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-g, --global", "Get from global configuration only")
+    .option("-p, --profile <name>", "Query config on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("--reveal, --show-secrets", "Reveal plain text value for secret")
     .option("--json", "Output as JSON")
-    .action((key, options) => {
+    .action(async (key, options) => {
       try {
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const res = await fetchRemoteConfig(target.serverUrl!, target.token, options.package);
+          const val = res.values?.[key];
+          if (options.json) {
+            console.log(JSON.stringify({ key, value: val }, null, 2));
+          } else {
+            console.log(val !== undefined ? JSON.stringify(val) : "undefined");
+          }
+          return;
+        }
+
         const reveal = options.reveal || options.showSecrets;
         const globalStorage = createGlobalStorage();
         const globalVal = globalStorage.getConfig(key);
@@ -326,7 +378,10 @@ export function registerConfigCommands(program: Command): void {
     .description("Set a configuration value (Global by default outside project, or use -g for global)")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-g, --global", "Set globally across all packages")
-    .action((key, rawValue, options) => {
+    .option("-p, --profile <name>", "Set config on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
+    .action(async (key, rawValue, options) => {
       try {
         let parsed: unknown = rawValue;
         try {
@@ -335,6 +390,18 @@ export function registerConfigCommands(program: Command): void {
           parsed = rawValue;
         }
 
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          await setRemoteConfig(target.serverUrl!, key, parsed, target.token, options.package);
+          console.log(`[OK] Remote config '${key}' updated on ${target.serverUrl}`);
+          return;
+        }
+
         const projectRoot = !options.global ? resolvePackageRoot(options.package) : null;
         const isSecret = isSecretConfigKey(key);
         const displayVal = isSecret ? maskSecretValue(parsed) : JSON.stringify(parsed);
@@ -366,8 +433,27 @@ export function registerConfigCommands(program: Command): void {
     .description("Delete a configuration value")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-g, --global", "Delete from global configuration")
-    .action((key, options) => {
+    .option("-p, --profile <name>", "Delete config on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
+    .action(async (key, options) => {
       try {
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const res = await deleteRemoteConfig(target.serverUrl!, key, target.token, options.package);
+          if (res.deleted) {
+            console.log(`[OK] Remote config '${key}' deleted from ${target.serverUrl}`);
+          } else {
+            console.log(`Remote config '${key}' not found on ${target.serverUrl}`);
+          }
+          return;
+        }
+
         const projectRoot = !options.global ? resolvePackageRoot(options.package) : null;
 
         if (options.global || !projectRoot) {

package/src/commands/doctor.ts

@@ -1,4 +1,4 @@
-import { runDoctorChecks } from "@actiondock/core";
+import { fetchRemoteDoctor, resolveTarget, runDoctorChecks } from "@actiondock/core";
 import { Command } from "commander";
 
 export function registerDoctorCommand(program: Command): void {
@@ -6,13 +6,28 @@ export function registerDoctorCommand(program: Command): void {
     .command("doctor")
     .description("Check ActionDock environment, registry health, and project diagnostics")
     .option("-P, --package <id|path>", "Target package ID or directory path for project diagnostics")
+    .option("-p, --profile <name>", "Query doctor diagnostics on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("--json", "Output diagnostics report in JSON format")
     .action(async (options) => {
       try {
-        const report = await runDoctorChecks({
-          packageIdOrPath: options.package,
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
         });
 
+        let report;
+        if (target.type === "remote") {
+          const remoteRes = await fetchRemoteDoctor(target.serverUrl!, target.token, options.package);
+          report = remoteRes.report || remoteRes;
+        } else {
+          report = await runDoctorChecks({
+            packageIdOrPath: options.package,
+          });
+        }
+
         if (options.json) {
           console.log(JSON.stringify(report, null, 2));
           if (!report.ok) {
@@ -21,11 +36,14 @@ export function registerDoctorCommand(program: Command): void {
           return;
         }
 
-        console.log("[DOCTOR] ActionDock System & Project Diagnostics\n");
+        const title = target.type === "remote"
+          ? `[DOCTOR] Remote ActionDock Server Diagnostics (${target.serverUrl}${target.profileName ? ` - Profile: ${target.profileName}` : ""})\n`
+          : "[DOCTOR] ActionDock System & Project Diagnostics\n";
+        console.log(title);
 
         // 1. Runtime & Environment Group
         console.log("[Runtime & Environment]");
-        const envChecks = report.checks.filter((c) => c.category === "runtime" || c.category === "storage" || c.category === "registry");
+        const envChecks = (report.checks || []).filter((c: any) => c.category === "runtime" || c.category === "storage" || c.category === "registry");
         for (const c of envChecks) {
           const tag = c.status === "ok" ? "[OK]" : c.status === "warn" ? "[WARN]" : "[ERROR]";
           console.log(`  ${tag} ${c.name}: ${c.message}`);
@@ -37,7 +55,7 @@ export function registerDoctorCommand(program: Command): void {
         // 2. Project Group
         if (report.hasProject) {
           console.log(`\n[Project: ${report.packageId || "unknown"}] (${report.projectRoot})`);
-          const projChecks = report.checks.filter((c) => c.category === "project");
+          const projChecks = (report.checks || []).filter((c: any) => c.category === "project");
           for (const c of projChecks) {
             const tag = c.status === "ok" ? "[OK]" : c.status === "warn" ? "[WARN]" : "[ERROR]";
             console.log(`  ${tag} ${c.name}: ${c.message}`);

package/src/commands/index.ts

@@ -21,7 +21,7 @@ export function createCliProgram(): Command {
   program
     .name("ad")
     .description("ActionDock (ad) 2.0 - Toolchain for building and shipping standalone AI Agent Actions & Skills")
-    .version("2.0.1");
+    .version("2.0.2");
 
   registerInitCommand(program);
   registerInfoCommand(program);

package/src/commands/info.ts

@@ -191,16 +191,6 @@ export function registerInfoCommand(program: Command): void {
     .option("--json", "Output information as JSON")
     .action(async (patterns: string[] = [], options: any) => {
       try {
-        if (options.tree) {
-          const status = getRegistryStatus();
-          if (options.json) {
-            console.log(JSON.stringify(status, null, 2));
-          } else {
-            printRegistryTree(status);
-          }
-          return;
-        }
-
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const shouldFallback = options.fallback !== false;
 
@@ -214,121 +204,110 @@ export function registerInfoCommand(program: Command): void {
         if (target.type === "remote") {
           const remoteInfo = await fetchRemoteInfo(
             target.serverUrl!,
-            target.token
+            target.token,
+            {
+              intent: effectiveIntent,
+              package: options.package,
+              tree: Boolean(options.tree),
+            }
           );
 
           if (options.json) {
-            if (Array.isArray(remoteInfo.linkedPackages) && effectiveIntent) {
-              const filterRes = filterWithFallbackInfo(
-                remoteInfo.linkedPackages,
-                effectiveIntent,
-                [
-                  (p: any) => p.id,
-                  (p: any) => p.name,
-                  (p: any) => p.description,
-                  (p: any) => p.path,
-                  (p: any) => p.actions,
-                  (p: any) => p.playbooks,
-                ],
-                shouldFallback
-              );
-              console.log(
-                JSON.stringify(
-                  {
-                    ...remoteInfo,
-                    linkedPackages: filterRes.items,
-                    isFallback: filterRes.isFallback,
-                  },
-                  null,
-                  2
-                )
-              );
-            } else {
-              console.log(JSON.stringify(remoteInfo, null, 2));
+            console.log(JSON.stringify(remoteInfo, null, 2));
+            return;
+          }
+
+          console.log(
+            `Remote ActionDock Server: ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""}\n`
+          );
+
+          // Remote Tree
+          if (remoteInfo.type === "tree" || (options.tree && remoteInfo.workspaces)) {
+            printRegistryTree(remoteInfo);
+            return;
+          }
+
+          // Remote Package Detail
+          if (remoteInfo.type === "package_detail" || (remoteInfo.id && !remoteInfo.packages)) {
+            console.log(`ActionDock Project: ${remoteInfo.name || remoteInfo.id} (${remoteInfo.id})`);
+            console.log(`Version:     ${remoteInfo.version || "unknown"}`);
+            if (remoteInfo.description) console.log(`Description: ${remoteInfo.description}`);
+            if (remoteInfo.path || remoteInfo.projectRoot) {
+              console.log(`Root:        ${remoteInfo.path || remoteInfo.projectRoot}`);
             }
-          } else {
-            console.log(
-              `Remote ActionDock Server: ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""}`
-            );
-            if (remoteInfo.id) {
-              if (effectiveIntent) {
-                const match = filterWithFallbackInfo(
-                  [remoteInfo],
-                  effectiveIntent,
-                  [
-                    (r: any) => r.id,
-                    (r: any) => r.name,
-                    (r: any) => r.description,
-                    (r: any) => r.actions,
-                    (r: any) => r.playbooks,
-                  ],
-                  shouldFallback
-                );
-                if (match.matchedCount === 0 && !shouldFallback) {
-                  console.error(
-                    `Error: Remote project '${remoteInfo.id}' did not match intent '${effectiveIntent}'`
-                  );
-                  process.exit(1);
-                }
-              }
-              console.log(
-                `Project:     ${remoteInfo.name || remoteInfo.id} (${remoteInfo.id})`
-              );
-              console.log(`Version:     ${remoteInfo.version || "unknown"}`);
-              if (remoteInfo.description) {
-                console.log(`Description: ${remoteInfo.description}`);
-              }
-              if (Array.isArray(remoteInfo.actions)) {
-                console.log(`\nActions (${remoteInfo.actions.length}):`);
-                for (const actId of remoteInfo.actions) {
-                  console.log(`  - ${actId}`);
-                }
-              }
-              if (Array.isArray(remoteInfo.playbooks)) {
-                console.log(`\nPlaybooks (${remoteInfo.playbooks.length}):`);
-                for (const pbId of remoteInfo.playbooks) {
-                  console.log(`  - ${pbId}`);
-                }
+
+            const actions = remoteInfo.actionsDetail || remoteInfo.actions || [];
+            console.log(`\nActions (${remoteInfo.actionsCount || actions.length}):`);
+            for (const act of actions) {
+              if (typeof act === "string") {
+                console.log(`  - ${act}`);
+              } else {
+                console.log(`  - ${(act.id || "").padEnd(28)} ${act.description || ""}`);
               }
-            } else if (Array.isArray(remoteInfo.linkedPackages)) {
-              let list = remoteInfo.linkedPackages;
-              let isFallback = false;
-              if (effectiveIntent) {
-                const filterRes = filterWithFallbackInfo(
-                  list,
-                  effectiveIntent,
-                  [
-                    (p: any) => p.id,
-                    (p: any) => p.name,
-                    (p: any) => p.description,
-                    (p: any) => p.path,
-                    (p: any) => p.actions,
-                    (p: any) => p.playbooks,
-                  ],
-                  shouldFallback
-                );
-                if (filterRes.matchedCount === 0 && !shouldFallback) {
-                  console.error(
-                    `Error: No remote packages matched intent '${effectiveIntent}'`
-                  );
-                  process.exit(1);
-                }
-                list = filterRes.items;
-                isFallback = filterRes.isFallback;
+            }
+
+            const playbooks = remoteInfo.playbooksDetail || remoteInfo.playbooks || [];
+            console.log(`\nPlaybooks (${remoteInfo.playbooksCount || playbooks.length}):`);
+            for (const pb of playbooks) {
+              if (typeof pb === "string") {
+                console.log(`  - ${pb}`);
+              } else {
+                console.log(`  - ${(pb.id || "").padEnd(28)} ${pb.description || ""}`);
               }
-              console.log(`Version:     ${remoteInfo.version || "2.0.0"}`);
-              if (isFallback && effectiveIntent) {
+            }
+
+            const declared = remoteInfo.configDeclared || {};
+            const declaredKeys = Object.keys(declared);
+            if (declaredKeys.length > 0) {
+              console.log(`\nDeclared Config Keys:`);
+              for (const k of declaredKeys) {
+                const item = declared[k];
+                const isSec = item?.secret ? " [secret]" : "";
+                const def =
+                  item?.default !== undefined
+                    ? ` (default: ${JSON.stringify(item.default)})`
+                    : "";
                 console.log(
-                  `\n(No remote packages matched intent '${effectiveIntent}', showing all linked packages)`
+                  `  - ${k.padEnd(24)} ${item?.description || ""}${def}${isSec}`
                 );
               }
-              console.log(`\nLinked Packages (${list.length}):`);
-              for (const pkg of list) {
-                console.log(`  - ${pkg.id} (${pkg.path})`);
-              }
-            } else {
-              console.log(JSON.stringify(remoteInfo, null, 2));
             }
+            return;
+          }
+
+          // Remote Package List
+          const packages = remoteInfo.packages || remoteInfo.linkedPackages || [];
+          if (Array.isArray(packages)) {
+            console.log(`Remote ActionDock Packages (${packages.length}):\n`);
+            for (const p of packages) {
+              console.log(`* ${p.name || p.id} (${p.id}) v${p.version || "unknown"}`);
+              if (p.path) console.log(`  Path:      ${p.path}`);
+              if (p.description) console.log(`  Desc:      ${p.description}`);
+              const actNames = Array.isArray(p.actions)
+                ? p.actions.map((a: any) => (typeof a === "string" ? a : a.id)).join(", ")
+                : "";
+              const pbNames = Array.isArray(p.playbooks)
+                ? p.playbooks.map((pb: any) => (typeof pb === "string" ? pb : pb.id)).join(", ")
+                : "";
+              console.log(`  Actions (${p.actionsCount || (p.actions ? p.actions.length : 0)}):   ${actNames || "(none)"}`);
+              console.log(`  Playbooks (${p.playbooksCount || (p.playbooks ? p.playbooks.length : 0)}): ${pbNames || "(none)"}`);
+              console.log("");
+            }
+            console.log("Tip: Run 'ad info <package-id> --server <url>' to view detailed package configuration and schema.");
+            return;
+          }
+
+          console.log(JSON.stringify(remoteInfo, null, 2));
+          return;
+        }
+
+        // Local Tree
+        if (options.tree) {
+          const status = getRegistryStatus();
+          if (options.json) {
+            console.log(JSON.stringify(status, null, 2));
+          } else {
+            printRegistryTree(status);
           }
           return;
         }

package/src/commands/playbook.ts

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import {
+  fetchRemotePlaybooks,
+  fetchRemotePlaybookShow,
   filterWithFallbackInfo,
   findProjectRoot,
   listLinkedPackages,
@@ -8,6 +10,7 @@ import {
   loadPlaybooks,
   loadProjectConfig,
   resolvePlaybookProject,
+  resolveTarget,
 } from "@actiondock/core";
 import type { PlaybookDefinition } from "@actiondock/core";
 import { Command } from "commander";
@@ -23,13 +26,45 @@ export function registerPlaybookCommands(program: Command): void {
     .command("list [patterns...]")
     .description("List playbooks in current project or linked packages")
     .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
+    .option("-P, --package <id>", "Target package ID or path")
+    .option("-p, --profile <name>", "Query against a specific profile")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("--no-fallback", "Disable fallback to full list when no items match intent")
     .option("--json", "Output as JSON")
-    .action((patterns, options) => {
+    .action(async (patterns, options) => {
       try {
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const shouldFallback = options.fallback !== false;
 
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const remotePbs = await fetchRemotePlaybooks(target.serverUrl!, target.token, {
+            intent: effectiveIntent,
+            package: options.package,
+          });
+          if (options.json) {
+            console.log(JSON.stringify(remotePbs, null, 2));
+            return;
+          }
+          console.log(
+            `Playbooks on remote server ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""}:\n`
+          );
+          if (remotePbs.length === 0) {
+            console.log("  (No playbooks found)");
+          } else {
+            for (const p of remotePbs) {
+              console.log(`  ${p.id.padEnd(24)} ${p.description} (Package: ${p.packageId})`);
+            }
+          }
+          return;
+        }
+
         const root = findProjectRoot();
         if (root) {
           const config = loadProjectConfig(root);
@@ -228,9 +263,35 @@ This playbook provides task execution guidance for AI Agents.
   pbCmd
     .command("show <id>")
     .description("Show playbook content and metadata (from current project or linked packages)")
+    .option("-p, --profile <name>", "Query against a specific profile")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("--json", "Output as JSON")
-    .action((id, options) => {
+    .action(async (id, options) => {
       try {
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const pb = await fetchRemotePlaybookShow(target.serverUrl!, id, target.token);
+          if (options.json) {
+            console.log(JSON.stringify(pb, null, 2));
+            return;
+          }
+          console.log(`Playbook:    ${pb.id} (Package: ${pb.packageId})`);
+          if (pb.description) console.log(`Description: ${pb.description}`);
+          if (pb.actions && pb.actions.length > 0) {
+            console.log(`Actions:     ${pb.actions.join(", ")}`);
+          }
+          if (pb.filePath) console.log(`File:        ${pb.filePath}\n`);
+          console.log("--- Content ---");
+          console.log(pb.content);
+          return;
+        }
+
         const resolved = resolvePlaybookProject(id);
         const pb = resolved.playbook;
 

package/src/commands/runs.ts

@@ -1,8 +1,10 @@
 import { existsSync } from "node:fs";
 import {
   cancelRemoteRun,
+  clearRemoteRuns,
   createStorage,
   fetchRemoteRun,
+  fetchRemoteRuns,
   filterWithFallbackInfo,
   findProjectRoot,
   listLinkedPackages,
@@ -49,14 +51,50 @@ export function registerRunsCommands(program: Command): void {
     .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
     .option("-a, --action <actionId>", "Filter by action ID")
     .option("-n, --limit <count>", "Maximum number of records to return", "20")
+    .option("-p, --profile <name>", "Query against a specific profile")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("--no-fallback", "Disable fallback to full list when no items match intent")
     .option("--json", "Output as JSON")
-    .action((patterns, options) => {
+    .action(async (patterns, options) => {
       try {
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const shouldFallback = options.fallback !== false;
         const limit = Number.parseInt(options.limit, 10) || 20;
 
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const res = await fetchRemoteRuns(target.serverUrl!, target.token, {
+            packageId: options.package,
+            actionId: options.action,
+            intent: effectiveIntent,
+            limit,
+          });
+          if (options.json) {
+            console.log(JSON.stringify(res.items, null, 2));
+            return;
+          }
+          console.log(
+            `Execution Runs on remote server ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""} (${res.items.length}):\n`
+          );
+          console.log(
+            `  ${"RUN ID".padEnd(38)} ${"ACTION".padEnd(24)} ${"STATUS".padEnd(10)} ${"STARTED"}`
+          );
+          console.log("  " + "-".repeat(90));
+          for (const r of res.items) {
+            const time = (r.startedAt || "").replace("T", " ").slice(0, 19);
+            console.log(
+              `  ${r.id.padEnd(38)} ${r.actionId.padEnd(24)} ${r.status.padEnd(10)} ${time}`
+            );
+          }
+          return;
+        }
+
         const targetRoot = options.package
           ? resolvePackageRoot(options.package)
           : findProjectRoot();
@@ -315,5 +353,57 @@ export function registerRunsCommands(program: Command): void {
         process.exit(1);
       }
     });
+
+  // runs clear
+  runsCmd
+    .command("clear")
+    .description("Clear execution run records (locally or on remote server)")
+    .option("-P, --package <id>", "Target package ID or path")
+    .option("-a, --action <actionId>", "Filter by action ID")
+    .option("-p, --profile <name>", "Target profile")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      try {
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const res = await clearRemoteRuns(target.serverUrl!, target.token, {
+            packageId: options.package,
+            actionId: options.action,
+          });
+          if (options.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`Cleared ${res.clearedCount} execution run(s) on remote server.`);
+          }
+          return;
+        }
+
+        const targetRoot = options.package
+          ? resolvePackageRoot(options.package)
+          : findProjectRoot();
+
+        if (targetRoot) {
+          const projConfig = loadProjectConfig(targetRoot);
+          const storage = createStorage(projConfig.id, { projectRoot: targetRoot });
+          const count = storage.clearRuns({ actionId: options.action });
+          storage.close();
+          if (options.json) {
+            console.log(JSON.stringify({ ok: true, clearedCount: count }, null, 2));
+          } else {
+            console.log(`Cleared ${count} execution run(s) in package '${projConfig.id}'.`);
+          }
+        }
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
 }
 

package/src/commands/serve.ts

@@ -1,5 +1,7 @@
 import { resolve } from "node:path";
 import { findProjectRoot, loadProjectConfig, startActionDockServer } from "@actiondock/core";
+import { createActionDockMcpServer } from "@actiondock/mcp";
+import { createMcpHandler } from "@modelcontextprotocol/server";
 import { Command } from "commander";
 import { parseByteSize } from "../utils/bytes";
 
@@ -19,6 +21,7 @@ export function registerServeCommand(program: Command): void {
     )
     .option("--max-body <size>", "Maximum allowed JSON request body size (e.g. 1mb, 500kb)", "1mb")
     .option("--expose-debug-info", "Expose project root path in health and info responses")
+    .option("--no-mcp", "Disable unified MCP protocol endpoint at /mcp")
     .option("-d, --dir <path>", "Project root directory (default: current working directory)")
     .action(async (options) => {
       const port = parseInt(options.port, 10) || 5177;
@@ -55,6 +58,30 @@ export function registerServeCommand(program: Command): void {
         }
       }
 
+      let mcpHandler: ((req: Request) => Promise<Response | null | undefined>) | undefined;
+      const enableMcp = options.mcp !== false;
+      if (enableMcp) {
+        try {
+          const handler = createMcpHandler(
+            () => {
+              return createActionDockMcpServer({
+                projectRoot: projectRoot || undefined,
+              });
+            },
+            {
+              onerror: (err) => {
+                process.stderr.write(`[MCP HTTP Error] ${err?.message || String(err)}\n`);
+              },
+            }
+          );
+          mcpHandler = async (req: Request) => {
+            return handler.fetch(req);
+          };
+        } catch {
+          // 忽略 MCP 初始化异常
+        }
+      }
+
       try {
         const server = startActionDockServer({
           port,
@@ -64,6 +91,8 @@ export function registerServeCommand(program: Command): void {
           corsOrigins,
           maxBodyBytes,
           exposeDebugInfo,
+          enableMcp,
+          mcpHandler,
           projectRoot: projectRoot || undefined,
         });
 
@@ -79,6 +108,9 @@ export function registerServeCommand(program: Command): void {
         console.log(`  * CORS Origins:    ${corsOrigins ? corsOrigins.join(", ") : "Disabled (Default)"}`);
         console.log(`  * Max Body Size:   ${options.maxBody || "1mb"}`);
         console.log(`  * Health Endpoint: http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${server.port}/api/v1/health`);
+        if (enableMcp) {
+          console.log(`  * MCP Endpoint:    http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${server.port}/mcp`);
+        }
         console.log(`======================================================\n`);
         console.log(`Server is ready to accept remote 'ad run' requests.`);
         console.log(`Press Ctrl+C to terminate.\n`);

package/src/commands/state.ts

@@ -1,11 +1,17 @@
 import { existsSync } from "node:fs";
 import {
+  clearRemoteState,
   createStorage,
+  deleteRemoteStateKey,
+  fetchRemoteStateList,
   filterWithFallbackInfo,
   findProjectRoot,
+  getRemoteStateKey,
   listLinkedPackages,
   loadProjectConfig,
   resolvePackageRoot,
+  resolveTarget,
+  setRemoteStateKey,
 } from "@actiondock/core";
 import { Command } from "commander";
 import { resolveIntent } from "../utils/filter";
@@ -47,6 +53,9 @@ export function registerStateCommands(program: Command): void {
     .description("List state keys matching prefix, namespace, or intent pattern (in current project or linked packages)")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-n, --namespace <ns>", "Filter by specific namespace")
+    .option("-p, --profile <name>", "Query state on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
     .option("--no-fallback", "Disable fallback to full list when no items match intent")
     .option("-d, --detail", "Show detailed state entry objects (including namespace, expiration, update time)")
@@ -56,6 +65,31 @@ export function registerStateCommands(program: Command): void {
         const effectiveIntent = resolveIntent(options.intent, prefix ? [prefix] : []);
         const shouldFallback = options.fallback !== false;
 
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const res = await fetchRemoteStateList(target.serverUrl!, target.token, {
+            package: options.package,
+            namespace: options.namespace,
+            prefix,
+          });
+          if (options.json) {
+            console.log(JSON.stringify(res.keys, null, 2));
+            return;
+          }
+          console.log(
+            `State keys on remote server ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""} (${res.keys.length}):\n`
+          );
+          for (const k of res.keys) {
+            console.log(`  - ${k}`);
+          }
+          return;
+        }
+
         const targetRoot = options.package
           ? resolvePackageRoot(options.package)
           : findProjectRoot();
@@ -236,10 +270,32 @@ export function registerStateCommands(program: Command): void {
     .description("Get a state value by key, namespace:key, or package/namespace:key")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-n, --namespace <ns>", "Target namespace")
+    .option("-p, --profile <name>", "Query state on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("--json", "Output as JSON")
     .action(async (rawKey, options) => {
-      const { root, key } = getTargetRoot(options.package, rawKey);
       try {
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const res = await getRemoteStateKey(target.serverUrl!, rawKey, target.token, {
+            package: options.package,
+            namespace: options.namespace,
+          });
+          if (options.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(res.value !== undefined ? JSON.stringify(res.value, null, 2) : "undefined");
+          }
+          return;
+        }
+
+        const { root, key } = getTargetRoot(options.package, rawKey);
         const projConfig = loadProjectConfig(root);
         const storage = createStorage(projConfig.id, { projectRoot: root });
 
@@ -290,10 +346,36 @@ export function registerStateCommands(program: Command): void {
     .description("Set a state value by key, namespace:key, or package/namespace:key")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-n, --namespace <ns>", "Target namespace")
+    .option("-p, --profile <name>", "Set state on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("--ttl <seconds>", "Time to live in seconds", (v) => parseInt(v, 10))
     .action(async (rawKey, rawValue, options) => {
-      const { root, key } = getTargetRoot(options.package, rawKey);
       try {
+        let parsed: unknown = rawValue;
+        try {
+          parsed = JSON.parse(rawValue);
+        } catch {
+          parsed = rawValue;
+        }
+
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          await setRemoteStateKey(target.serverUrl!, rawKey, parsed, target.token, {
+            package: options.package,
+            namespace: options.namespace,
+            ttl: options.ttl,
+          });
+          console.log(`[OK] State '${rawKey}' updated on remote server ${target.serverUrl}`);
+          return;
+        }
+
+        const { root, key } = getTargetRoot(options.package, rawKey);
         const projConfig = loadProjectConfig(root);
         const storage = createStorage(projConfig.id, { projectRoot: root });
 
@@ -309,13 +391,6 @@ export function registerStateCommands(program: Command): void {
           actualKey = key.slice(colonIdx + 1);
         }
 
-        let parsed: unknown = rawValue;
-        try {
-          parsed = JSON.parse(rawValue);
-        } catch {
-          parsed = rawValue;
-        }
-
         await storage.setState(ns, actualKey, parsed, options.ttl);
         storage.close();
 
@@ -336,10 +411,28 @@ export function registerStateCommands(program: Command): void {
     .description("Delete a state value by key, namespace:key, or package/namespace:key")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-n, --namespace <ns>", "Target namespace")
+    .option("-p, --profile <name>", "Delete state on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("--silent", "Do not exit with error if key is not found")
     .action(async (rawKey, options) => {
-      const { root, key } = getTargetRoot(options.package, rawKey);
       try {
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          await deleteRemoteStateKey(target.serverUrl!, rawKey, target.token, {
+            package: options.package,
+            namespace: options.namespace,
+          });
+          console.log(`[OK] State '${rawKey}' deleted from remote server ${target.serverUrl}`);
+          return;
+        }
+
+        const { root, key } = getTargetRoot(options.package, rawKey);
         const projConfig = loadProjectConfig(root);
         const storage = createStorage(projConfig.id, { projectRoot: root });
         const deleted = await storage.deleteStateSmart(key, options.namespace);
@@ -366,10 +459,30 @@ export function registerStateCommands(program: Command): void {
     .description("Clear state entries by namespace, prefix, or all")
     .option("-P, --package <id>", "Target package ID or path")
     .option("-n, --namespace <ns>", "Target namespace to clear")
+    .option("-p, --profile <name>", "Clear state on a remote target")
+    .option("-s, --server <url>", "Remote server URL")
+    .option("-t, --token <token>", "Auth token for remote server")
     .option("-a, --all", "Clear all state entries across all namespaces in this package")
     .action(async (prefix = "", options) => {
-      const { root } = getTargetRoot(options.package);
       try {
+        const target = resolveTarget({
+          profile: options.profile,
+          server: options.server,
+          token: options.token,
+        });
+
+        if (target.type === "remote") {
+          const res = await clearRemoteState(target.serverUrl!, target.token, {
+            package: options.package,
+            namespace: options.namespace,
+            prefix,
+            all: Boolean(options.all),
+          });
+          console.log(`[OK] Cleared ${res.clearedCount} state entry(s) on remote server ${target.serverUrl}`);
+          return;
+        }
+
+        const { root } = getTargetRoot(options.package);
         const projConfig = loadProjectConfig(root);
         const storage = createStorage(projConfig.id, { projectRoot: root });
         const count = await storage.clearState({