stpr 1.0.5 → 1.0.7

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

@@ -2,19 +2,49 @@
 
 // src/cli.ts
 import { createRequire } from "module";
-import * as path2 from "path";
+import * as path3 from "path";
 import { fileURLToPath } from "url";
 
 // src/auth.ts
 import * as childProcess from "child_process";
+import * as crypto2 from "crypto";
+import * as fs2 from "fs";
+import * as os2 from "os";
+import * as path2 from "path";
+import { createServer } from "http";
+
+// src/client.ts
 import * as crypto from "crypto";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { createServer } from "http";
-
-// src/client.ts
 var DEFAULT_BASE_URL = "https://mcp.stepper.io";
+var CACHE_DIR = path.join(os.homedir(), ".config", "stepper-skillsets", "cache");
+var CACHE_TTL_MS = 5 * 60 * 1e3;
+function getCachePath(key) {
+  const hash = crypto.createHash("sha256").update(key).digest("hex").slice(0, 16);
+  return path.join(CACHE_DIR, `${hash}.json`);
+}
+function readCache(key) {
+  try {
+    const filePath = getCachePath(key);
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const entry = JSON.parse(raw);
+    if (Date.now() - entry.timestamp < CACHE_TTL_MS) {
+      return entry.data;
+    }
+  } catch {
+  }
+  return null;
+}
+function writeCache(key, data) {
+  try {
+    fs.mkdirSync(CACHE_DIR, { recursive: true, mode: 448 });
+    const entry = { timestamp: Date.now(), data };
+    fs.writeFileSync(getCachePath(key), JSON.stringify(entry), { mode: 384 });
+  } catch {
+  }
+}
 var StepperClient = class {
   token;
   baseUrl;
@@ -63,20 +93,31 @@ var StepperClient = class {
       version: serverInfo.version ?? "1.0.0"
     };
   }
-  async listTools({ service }) {
+  async listTools({ service, noCache }) {
+    const cacheKey = `tools-list:${this.baseUrl}:${this.token}`;
+    let allTools;
+    if (!noCache) {
+      const cached = readCache(cacheKey);
+      if (cached) {
+        allTools = cached;
+        return allTools.filter(
+          (tool) => service ? tool.service === service : !tool.service.startsWith("__")
+        );
+      }
+    }
     const res = await this.rpc("tools/list");
     if (res.error) {
       throw new Error(`tools/list failed: ${res.error.message}`);
     }
     const tools = res.result.tools;
-    return tools.map(
-      (tool) => ({
-        service: tool.name.split(".")[0],
-        action: tool.name.split(".")[1],
-        description: tool.description,
-        inputSchema: tool.inputSchema
-      })
-    ).filter(
+    allTools = tools.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 : !tool.service.startsWith("__")
     );
   }
@@ -121,7 +162,7 @@ var StepperClient = class {
 
 // src/auth.ts
 function openBrowser(url) {
-  const platform2 = os.platform();
+  const platform2 = os2.platform();
   if (platform2 === "darwin") {
     childProcess.spawn("open", [url], { stdio: "ignore", detached: true });
   } else if (platform2 === "win32") {
@@ -136,51 +177,35 @@ function openBrowser(url) {
 var DEFAULT_BASE_URL2 = "https://mcp.stepper.io";
 var OAUTH_CALLBACK_PORT = 3847;
 var CALLBACK_PATH = "/callback";
-var CONFIG_DIR = path.join(os.homedir(), ".config", "stepper-skillsets");
-var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-var LEGACY_CREDENTIALS_FILE = path.join(CONFIG_DIR, "credentials.json");
+var CONFIG_DIR = path2.join(os2.homedir(), ".config", "stepper-skillsets");
+var CONFIG_FILE = path2.join(CONFIG_DIR, "config.json");
 function generatePKCE() {
-  const codeVerifier = crypto.randomBytes(32).toString("base64url");
-  const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest().toString("base64url");
+  const codeVerifier = crypto2.randomBytes(32).toString("base64url");
+  const codeChallenge = crypto2.createHash("sha256").update(codeVerifier).digest().toString("base64url");
   return { codeVerifier, codeChallenge };
 }
 function loadConfig() {
   try {
-    const data = fs.readFileSync(CONFIG_FILE, "utf-8");
+    const data = fs2.readFileSync(CONFIG_FILE, "utf-8");
     return JSON.parse(data);
   } catch {
     return { active: null, skillsets: {} };
   }
 }
 function saveConfig(config) {
-  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {
+  fs2.mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  fs2.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {
     mode: 384
   });
 }
-function migrateLegacyCredentials() {
-  try {
-    const data = fs.readFileSync(LEGACY_CREDENTIALS_FILE, "utf-8");
-    const creds = JSON.parse(data);
-    const config = {
-      active: "default",
-      skillsets: { default: creds }
-    };
-    saveConfig(config);
-    fs.unlinkSync(LEGACY_CREDENTIALS_FILE);
-  } catch {
-  }
-}
 function getConfigPathForDisplay() {
   return CONFIG_FILE;
 }
 function getActiveSkillset() {
-  migrateLegacyCredentials();
   const config = loadConfig();
   return config.active;
 }
 function setActiveSkillset(name) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   if (!(name in config.skillsets)) {
     return false;
@@ -190,7 +215,6 @@ function setActiveSkillset(name) {
   return true;
 }
 function listSkillsets() {
-  migrateLegacyCredentials();
   const config = loadConfig();
   return Object.entries(config.skillsets).map(([name, creds]) => ({
     name,
@@ -199,12 +223,10 @@ function listSkillsets() {
   }));
 }
 function getCredentials(name) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   return config.skillsets[name] ?? null;
 }
 function saveCredentials(name, creds) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   config.skillsets[name] = creds;
   if (!config.active || !(config.active in config.skillsets)) {
@@ -213,7 +235,6 @@ function saveCredentials(name, creds) {
   saveConfig(config);
 }
 function deleteSkillset(name) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   if (!(name in config.skillsets)) {
     return false;
@@ -226,7 +247,6 @@ function deleteSkillset(name) {
   return true;
 }
 function deleteAllSkillsets() {
-  migrateLegacyCredentials();
   const config = loadConfig();
   const count = Object.keys(config.skillsets).length;
   config.skillsets = {};
@@ -303,7 +323,7 @@ async function runLoginFlow(baseUrl) {
   const metadata = await fetchMetadata(normalizedBaseUrl);
   const { codeVerifier, codeChallenge } = generatePKCE();
   const clientId = await registerClient(normalizedBaseUrl, redirectUri);
-  const state = crypto.randomBytes(16).toString("hex");
+  const state = crypto2.randomBytes(16).toString("hex");
   const authUrl = new URL(metadata.authorization_endpoint);
   authUrl.searchParams.set("response_type", "code");
   authUrl.searchParams.set("client_id", clientId);
@@ -320,6 +340,18 @@ async function runLoginFlow(baseUrl) {
           res.end("Not found");
           return;
         }
+        const requestHost = req.headers.host ?? `127.0.0.1:${OAUTH_CALLBACK_PORT}`;
+        const callbackUrl = new URL(req.url ?? "/", `http://${requestHost}`);
+        const receivedCallbackUrl = `${callbackUrl.origin}${callbackUrl.pathname}`;
+        if (receivedCallbackUrl !== redirectUri) {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end(
+            "<html><body><h1>Login failed</h1><p>Redirect URI mismatch</p><p>You can close this tab.</p></body></html>"
+          );
+          server.close();
+          reject(new Error("OAuth redirect URI mismatch"));
+          return;
+        }
         const code = url.searchParams.get("code");
         const returnedState = url.searchParams.get("state");
         const error = url.searchParams.get("error");
@@ -412,7 +444,6 @@ async function refreshAccessToken(baseUrl, clientId, refreshToken) {
   };
 }
 async function getValidToken(skillsetName, baseUrl) {
-  migrateLegacyCredentials();
   const config = loadConfig();
   const name = skillsetName ?? config.active;
   if (!name || !(name in config.skillsets)) {
@@ -462,9 +493,9 @@ async function getValidToken(skillsetName, baseUrl) {
 }
 
 // src/cli.ts
-var __dirname = path2.dirname(fileURLToPath(import.meta.url));
+var __dirname = path3.dirname(fileURLToPath(import.meta.url));
 var pkg = createRequire(import.meta.url)(
-  path2.join(__dirname, "..", "package.json")
+  path3.join(__dirname, "..", "package.json")
 );
 var VERSION = pkg.version ?? "0.0.0";
 function readStdin() {
@@ -501,6 +532,8 @@ function parseArgs(argv) {
       flags.cursor = argv[++i];
     } else if (arg === "--call") {
       boolFlags.call = true;
+    } else if (arg === "--no-cache") {
+      boolFlags.noCache = true;
     } else if (arg === "--verbose") {
       boolFlags.verbose = true;
     } else if (arg === "--options" && i + 1 < argv.length) {
@@ -524,6 +557,7 @@ function parseArgs(argv) {
     cursor: flags.cursor,
     call: boolFlags.call ?? false,
     verbose: boolFlags.verbose ?? false,
+    noCache: boolFlags.noCache ?? false,
     options: flags.options
   };
 }
@@ -568,6 +602,7 @@ Options:
   --skillset <name>   Use a specific skill set
   --call              Execute the skill (default is to fetch parameters only)
   --verbose           Include inputSchema 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
   --cursor <cursor>   Pagination cursor for dynamic dropdown options
@@ -575,7 +610,6 @@ Options:
   -v, --version       Show version
 
 Examples:
-
   Auth (optional, can use STEPPER_SKILL_TOKEN env var, or --token <token> from https://app.stepper.io/flow/skill-sets):
     stpr login
 
@@ -616,6 +650,7 @@ async function main() {
     cursor: cursorFlag,
     call: callFlag,
     verbose: verboseFlag,
+    noCache: noCacheFlag,
     options: optionsFlag
   } = parseArgs(process.argv.slice(2));
   if (subcommand === "help") {
@@ -769,7 +804,7 @@ async function main() {
   }
   if (subcommand === "list") {
     const service2 = args[0];
-    const tools = await client.listTools({ service: service2 ?? void 0 });
+    const tools = await client.listTools({ service: service2 ?? void 0, noCache: noCacheFlag });
     const formatted = formatToolsForList(tools, verboseFlag);
     if (!tools.length) {
       die(
@@ -787,7 +822,7 @@ async function main() {
     return;
   }
   if (!action) {
-    const tools = await client.listTools({ service });
+    const tools = await client.listTools({ service, noCache: noCacheFlag });
     if (!tools.length) {
       die(
         service ? `No skills found for service "${service}".` : "No skills found."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stpr",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "CLI for Stepper skill sets",
   "type": "module",
   "files": [