stpr 1.0.9 → 2.0.0

package/README.md

@@ -0,0 +1,159 @@
+# stpr — Stepper Skills CLI
+
+Skill Sets are a Stepper feature that let you bundle integration actions into curated, authenticated toolkits — and expose them to AI agents, CLIs, and any MCP-compatible client.
+
+`stpr` is a command-line interface for interacting with [Stepper](https://stepper.io) Skill Sets. Discover, inspect, and execute integration actions directly from your terminal. This is perfect for OpenClaw or agents that can interact with a CLI, or for developers who want to use skills in their own scripts.
+
+If you prefer, you can directly use the Stepper MCP server at `https://mcp.stepper.io/skill-sets/mcp`instead of the CLI.
+
+## Installation
+
+```bash
+npm install -g stpr
+```
+
+## Authentication
+
+The CLI supports three authentication methods:
+
+### OAuth Login (recommended)
+
+```bash
+stpr login
+```
+
+Opens your browser to authenticate and select a Skill Set. Credentials are saved to `~/.config/stepper-skillsets/config.json` and automatically refreshed when they expire.
+
+### Static Token
+
+Generate a token from [Stepper](https://app.stepper.io/flow/skill-sets) and pass it directly:
+
+```bash
+stpr --token sst_your_token_here list
+```
+
+### Environment Variable
+
+```bash
+export STEPPER_SKILL_TOKEN=sst_your_token_here
+stpr list
+```
+
+## Commands
+
+### Profile Management
+
+```bash
+stpr login                # Authenticate via OAuth (opens browser)
+stpr logout [name]        # Remove a saved profile, or all profiles if no name given
+stpr profiles             # List all saved profiles
+stpr use <name>           # Switch the active profile
+stpr whoami               # Show active profile and server info
+```
+
+### Discovering Skills
+
+```bash
+stpr list                 # List all available skills, grouped by service
+stpr list --verbose       # Include full input schemas
+stpr list <service>       # List skills for a specific service
+stpr <service>            # Shorthand for listing a service's skills
+```
+
+### Inspecting Parameters
+
+Many skills have dynamic parameters — fields that change based on the values of other fields. Calling a skill without `--call` returns its current parameter schema.
+
+```bash
+# See what fields are needed for add_row, given a spreadsheet
+stpr google-sheets add_row -i '{"spreadsheet_id": "abc123"}'
+```
+
+Some parameters have dynamic dropdown options. Fetch them with `--options`:
+
+```bash
+stpr google-sheets add_row --options worksheet_id \
+  -i '{"spreadsheet_id": "abc123"}' \
+  --search "Sheet" \
+  --cursor "next_page"
+```
+
+### Calling Skills
+
+Use the `--call` flag to execute an action:
+
+```bash
+stpr google-sheets create_sheet --call \
+  -i '{"name": "Q1 Report", "columns": "Name, Email, Phone"}'
+```
+
+### Polling Async Results
+
+Component library tools run asynchronously. Poll for results with:
+
+```bash
+stpr status <statusId>
+```
+
+## Input
+
+Pass JSON input via the `-i` / `--input` flag or pipe it through stdin:
+
+```bash
+# Flag
+stpr slack send_message --call -i '{"channel": "#general", "text": "Hello!"}'
+
+# Stdin
+echo '{"channel": "#general", "text": "Hello!"}' | stpr slack send_message --call
+```
+
+## Options Reference
+
+| Flag                 | Description                                                     |
+| -------------------- | --------------------------------------------------------------- |
+| `--token <token>`    | Auth token (overrides saved profiles and `STEPPER_SKILL_TOKEN`) |
+| `--base-url <url>`   | Override MCP server URL (default: `https://mcp.stepper.io`)     |
+| `--skillset <name>`  | Use a specific saved profile instead of the active one          |
+| `--call`             | Execute the skill (default behavior is parameter inspection)    |
+| `--verbose`          | Include full `inputSchema` when listing skills                  |
+| `-i, --input <json>` | JSON input for calls, parameter fetches, or option queries      |
+| `--options <param>`  | Fetch dynamic dropdown options for a parameter                  |
+| `--search <query>`   | Filter dropdown options by search term                          |
+| `--cursor <cursor>`  | Pagination cursor for dropdown options                          |
+| `-h, --help`         | Show help                                                       |
+| `-v, --version`      | Show version                                                    |
+
+## Environment Variables
+
+| Variable              | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| `STEPPER_SKILL_TOKEN` | Auth token (used when no `--token` flag and no saved profile) |
+| `STEPPER_URL`         | Override the MCP server base URL                              |
+
+## Examples
+
+```bash
+# Authenticate
+stpr login
+
+# List everything available
+stpr list
+
+# Explore a service
+stpr google-sheets
+
+# Inspect dynamic parameters step by step
+stpr google-sheets add_row -i '{}'
+stpr google-sheets add_row -i '{"spreadsheet_id": "abc123"}'
+
+# Fetch dropdown options
+stpr google-sheets add_row --options worksheet_id -i '{"spreadsheet_id": "abc123"}'
+
+# Execute
+stpr google-sheets add_row --call -i '{"spreadsheet_id": "abc123", "worksheet_id": "Sheet1", "values": {"Name": "Alice"}}'
+
+# Switch between skill sets
+stpr profiles
+stpr use "Production Tools"
+stpr list
+```

package/dist/cli.js

@@ -50,6 +50,19 @@ function writeCache(key, data) {
   } catch {
   }
 }
+function filterCatalog(catalog, service, connection) {
+  if (!service && !connection) return catalog;
+  let services = catalog.services;
+  let libs = catalog.component_libraries;
+  if (service) {
+    services = services.filter((s) => s.service === service);
+    libs = libs.filter((l) => l.library === service);
+  }
+  if (connection) {
+    services = services.filter((s) => s.connection_slug === connection);
+  }
+  return { services, component_libraries: libs };
+}
 var StepperClient = class {
   token;
   baseUrl;
@@ -80,6 +93,19 @@ var StepperClient = class {
     }
     return await response.json();
   }
+  /**
+   * Calls a static tool via tools/call RPC.
+   */
+  async callStaticTool(toolName, args) {
+    const res = await this.rpc("tools/call", {
+      name: toolName,
+      arguments: args
+    });
+    if (res.error) {
+      throw new Error(`tools/call (${toolName}) failed: ${res.error.message}`);
+    }
+    return res.result;
+  }
   async initialize() {
     const res = await this.rpc("initialize");
     if (res.error) {
@@ -100,73 +126,66 @@ var StepperClient = class {
   }
   async listTools({
     service,
+    connection,
     noCache
   }) {
-    const cacheKey = `tools-list:${this.baseUrl}:${this.token}`;
-    let allTools;
+    const cacheKey = `skills-list:${this.baseUrl}:${this.token}`;
+    let catalog;
     if (!noCache) {
       const cached = readCache(cacheKey);
       if (cached) {
-        allTools = cached;
-        return allTools.filter(
-          (tool) => service ? tool.service === service : !tool.service.startsWith("__")
-        );
+        catalog = cached;
       }
     }
-    const res = await this.rpc("tools/list");
-    if (res.error) {
-      throw new Error(`tools/list failed: ${res.error.message}`);
-    }
-    const tools = res.result.tools;
-    allTools = tools.filter((tool) => !tool.name.startsWith("__")).map(
-      (tool) => ({
-        service: tool.name.split("__")[0],
-        action: tool.name.split("__")[1],
-        description: tool.description,
-        inputSchema: tool.inputSchema
-      })
-    );
-    writeCache(cacheKey, allTools);
-    return allTools.filter(
-      (tool) => service ? tool.service === service : true
-    );
+    if (!catalog) {
+      const result = await this.callStaticTool("list_skills", {});
+      const text = result.content[0]?.text ?? "{}";
+      catalog = JSON.parse(text);
+      writeCache(cacheKey, catalog);
+    }
+    return filterCatalog(catalog, service, connection);
   }
-  async callTool(name, args) {
-    const res = await this.rpc("tools/call", { name, arguments: args });
-    if (res.error) {
-      throw new Error(`tools/call failed: ${res.error.message}`);
+  async callTool(service, action, args, connection) {
+    const toolArgs = { service, action, args };
+    if (connection) {
+      toolArgs.connection = connection;
     }
-    return res.result;
+    return this.callStaticTool("call_skill", toolArgs);
   }
   async pollStatus(statusId) {
-    const res = await this.rpc("tools/poll-status", { statusId });
-    if (res.error) {
-      throw new Error(`tools/poll-status failed: ${res.error.message}`);
-    }
-    return res.result;
+    return this.callStaticTool("poll_status", { statusId });
   }
-  async getToolParams(toolName, args) {
-    const res = await this.rpc("tools/params", {
-      name: toolName,
-      arguments: args
-    });
-    if (res.error) {
-      throw new Error(`tools/params failed: ${res.error.message}`);
+  async getToolParams(service, action, currentValues, connection) {
+    const args = { service, action };
+    if (connection) {
+      args.connection = connection;
     }
-    return res.result;
+    if (currentValues && Object.keys(currentValues).length > 0) {
+      args.current_parameter_values = currentValues;
+    }
+    return this.callStaticTool("get_skill_params", args);
   }
-  async getParameterOptions(toolName, parameterId, opts) {
-    const res = await this.rpc("tools/options", {
-      name: toolName,
-      parameter_id: parameterId,
-      current_parameter_values: opts?.currentParameterValues ?? {},
-      search: opts?.search ?? null,
-      cursor: opts?.cursor ?? null
-    });
-    if (res.error) {
-      throw new Error(`tools/options failed: ${res.error.message}`);
+  async getParameterOptions(service, action, parameterId, opts) {
+    const args = {
+      service,
+      action,
+      parameter_id: parameterId
+    };
+    if (opts?.connection) {
+      args.connection = opts.connection;
     }
-    return res.result;
+    if (opts?.currentParameterValues) {
+      args.current_parameter_values = opts.currentParameterValues;
+    }
+    if (opts?.search) {
+      args.search = opts.search;
+    }
+    if (opts?.cursor) {
+      args.cursor = opts.cursor;
+    }
+    const result = await this.callStaticTool("get_parameter_options", args);
+    const text = result.content[0]?.text ?? "{}";
+    return JSON.parse(text);
   }
 };
 
@@ -540,6 +559,8 @@ function parseArgs(argv) {
       flags.search = argv[++i];
     } else if (arg === "--cursor" && i + 1 < argv.length) {
       flags.cursor = argv[++i];
+    } else if (arg === "--connection" && i + 1 < argv.length) {
+      flags.connection = argv[++i];
     } else if (arg === "--call") {
       boolFlags.call = true;
     } else if (arg === "--no-cache") {
@@ -565,22 +586,24 @@ function parseArgs(argv) {
     input: flags.input,
     search: flags.search,
     cursor: flags.cursor,
+    connection: flags.connection,
     call: boolFlags.call ?? false,
     verbose: boolFlags.verbose ?? false,
     noCache: boolFlags.noCache ?? false,
     options: flags.options
   };
 }
-function toToolName(service, action) {
-  return `${service}__${action}`;
-}
-function formatToolsForList(tools, verbose) {
+function formatCatalogForList(catalog, verbose) {
   if (verbose) {
-    return tools;
+    return catalog;
   }
   const out = {};
-  for (const tool of tools) {
-    out[tool.service] = [...out[tool.service] || [], tool.action];
+  for (const svc of catalog.services) {
+    const key = catalog.services.filter((s) => s.service === svc.service).length > 1 ? `${svc.service}--${svc.connection_slug}` : svc.service;
+    out[key] = svc.actions.map((a) => a.action);
+  }
+  for (const lib of catalog.component_libraries) {
+    out[`${lib.library}`] = lib.components.map((c) => c.component);
   }
   return out;
 }
@@ -596,9 +619,9 @@ Commands:
   profiles             List all stored skillsets
   use <name>           Switch active skillset
   whoami               Show active skillset and server info
-  list [<service>]      List available skills (optionally for a service). Use --verbose for inputSchema.
+  list [<service>]      List available skills (optionally for a service). Use --verbose for full catalog.
   status <statusId>     Poll the status of a component tool run
-  <service>             List available skills for that service. Use --verbose for inputSchema.
+  <service>             List available skills for that service. Use --verbose for full catalog.
   <service> <action> (-i <json> | stdin)
                        Get the current parameters for a skill (default, for dynamic parameters)
   <service> <action> --call (-i <json> | stdin)
@@ -610,8 +633,9 @@ Options:
   --token <token>     Auth token (or set STEPPER_SKILL_TOKEN env var)
   --base-url <url>    Override base URL (or set STEPPER_URL env var)
   --skillset <name>   Use a specific skill set
+  --connection <slug> Connection slug (for multi-connection disambiguation)
   --call              Execute the skill (default is to fetch parameters only)
-  --verbose           Include inputSchema when listing skills
+  --verbose           Include full catalog when listing skills
   --no-cache          Bypass the 5-minute tools list cache
   -i, --input <json>  JSON input for call, parameters or options (alternative to stdin)
   --search <query>    Search query for dynamic dropdown options
@@ -632,17 +656,37 @@ Examples:
   Dynamic dropdown options:
     Some actions have dynamic dropdown options, which change depending on the
     value of other parameters. You can request the current dropdown options for
-    a skill by using the --options flag. This will return the current dropdown
-    options only, it will not call the skill. Dynamic dropdowns are also often
-    searchable and paginated via a cursor.
+    a skill by using the --options flag.
 
     stpr google-sheets add_row --options worksheet_id -i '{"spreadsheet_id": "abc123"}' --search "Sheet" --cursor "next_page"
-  
+
+  Multi-connection disambiguation:
+    When multiple connections exist for the same service, use the compound
+    format from "stpr list" or the --connection flag:
+
+    stpr google-sheets--my-sheets add_row --call -i '{"spreadsheet_id": "abc123"}'
+    stpr google-sheets add_row --connection my-sheets --call -i '{"spreadsheet_id": "abc123"}'
+
     Call a skill:
     stpr google-sheets create_sheet --call -i '{"name": "My Sheet", "columns": "Name, Email, Phone"}'
-  
+
   `);
 }
+function resolveServiceFromCatalog(rawService, catalog) {
+  if (catalog.services.some((s) => s.service === rawService)) {
+    return null;
+  }
+  if (catalog.component_libraries.some((l) => l.library === rawService)) {
+    return null;
+  }
+  for (const svc of catalog.services) {
+    const compound = `${svc.service}--${svc.connection_slug}`;
+    if (compound === rawService) {
+      return { service: svc.service, connection: svc.connection_slug };
+    }
+  }
+  return null;
+}
 function die(message) {
   process.stderr.write(`\x1B[31m[Error] ${message} \x1B[0m 
 `);
@@ -658,6 +702,7 @@ async function main() {
     input: inputFlag,
     search: searchFlag,
     cursor: cursorFlag,
+    connection: connectionFlag,
     call: callFlag,
     verbose: verboseFlag,
     noCache: noCacheFlag,
@@ -812,40 +857,53 @@ async function main() {
     console.log(result2.content.map((c) => c.text ?? "").join("\n"));
     return;
   }
-  if (subcommand === "list") {
-    const service2 = args[0];
-    const tools = await client.listTools({
-      service: service2 ?? void 0,
-      noCache: noCacheFlag
-    });
-    const formatted = formatToolsForList(tools, verboseFlag);
-    if (!tools.length) {
-      die(
-        service2 ? `No skills found for service "${service2}".` : "No skills found."
-      );
-    }
-    console.log(JSON.stringify(formatted, null, 2));
-    return;
-  }
-  const service = subcommand;
-  const action = args[0];
-  if (service.startsWith("--")) {
+  const rawServiceArg = subcommand === "list" ? args[0] : subcommand;
+  if (rawServiceArg?.startsWith("--")) {
     printUsage();
     process.exit(1);
     return;
   }
-  if (!action) {
-    const tools = await client.listTools({ service, noCache: noCacheFlag });
-    if (!tools.length) {
+  let service = rawServiceArg;
+  let connection = connectionFlag;
+  const action = subcommand === "list" ? void 0 : args[0];
+  if (service && !connection) {
+    const fullCatalog = await client.listTools({
+      service: void 0,
+      noCache: noCacheFlag
+    });
+    const resolved = resolveServiceFromCatalog(service, fullCatalog);
+    if (resolved) {
+      service = resolved.service;
+      connection = resolved.connection;
+    }
+  }
+  if (subcommand === "list" || !action) {
+    const catalog = await client.listTools({
+      service: service ?? void 0,
+      connection,
+      noCache: noCacheFlag
+    });
+    const hasContent = catalog.services.length > 0 || catalog.component_libraries.length > 0;
+    if (!hasContent) {
       die(
-        service ? `No skills found for service "${service}".` : "No skills found."
+        rawServiceArg ? `No skills found for service "${rawServiceArg}".` : "No skills found."
       );
     }
-    const formatted = verboseFlag ? formatToolsForList(tools, verboseFlag) : tools.map(({ action: action2 }) => action2);
-    console.log(JSON.stringify(formatted, null, 2));
+    if (subcommand === "list" || verboseFlag) {
+      const formatted = formatCatalogForList(catalog, verboseFlag);
+      console.log(JSON.stringify(formatted, null, 2));
+    } else {
+      const actions = [];
+      for (const svc of catalog.services) {
+        actions.push(...svc.actions.map((a) => a.action));
+      }
+      for (const lib of catalog.component_libraries) {
+        actions.push(...lib.components.map((c) => c.component));
+      }
+      console.log(JSON.stringify(actions, null, 2));
+    }
     return;
   }
-  const toolName = toToolName(service, action);
   const rawInput = inputFlag ?? await readStdin();
   let input = {};
   if (rawInput.trim()) {
@@ -856,27 +914,35 @@ async function main() {
     }
   }
   if (optionsFlag) {
-    const result2 = await client.getParameterOptions(toolName, optionsFlag, {
-      currentParameterValues: input,
-      search: searchFlag,
-      cursor: cursorFlag
-    });
+    const result2 = await client.getParameterOptions(
+      service,
+      action,
+      optionsFlag,
+      {
+        currentParameterValues: input,
+        search: searchFlag,
+        cursor: cursorFlag,
+        connection
+      }
+    );
     console.log(JSON.stringify(result2, null, 2));
     return;
   }
   if (callFlag) {
-    const result2 = await client.callTool(toolName, input);
+    const result2 = await client.callTool(service, action, input, connection);
     if (result2.isError) {
       die(result2.content.map((c) => c.text).join("\n"));
     }
     console.log(result2.content.map((c) => c.text ?? "").join("\n"));
     return;
   }
-  const result = await client.getToolParams(toolName, input);
+  const result = await client.getToolParams(service, action, input, connection);
   if (result.isError) {
     die(result.content?.map((c) => c.text).join("\n") ?? "Unknown error");
   }
-  console.log(JSON.stringify(result, null, 2));
+  console.log(
+    result.content?.map((c) => c.text ?? "").join("\n") ?? JSON.stringify(result, null, 2)
+  );
 }
 main().then(() => process.exit(0)).catch((err) => {
   console.error(`Error: ${err.message}`);

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "stpr",
-  "version": "1.0.9",
+  "version": "2.0.0",
   "description": "CLI for Stepper skill sets",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "bin": {
     "stpr": "./dist/cli.js"