@mcp-s/cli 0.0.9 → 0.0.11

package/README.md

@@ -263,7 +263,7 @@ mcp-s-cli clear-auth
 
 ## Config File Format
 
-The config file lives at `~/.config/mcp-s-cli/config.json` (or a custom path via `-c`/`MCP_CONFIG_PATH`).
+The config file lives at `~/.config/mcp-s-cli/config.json` (or a custom path via `-c`/`MCP_S_CLI_CONFIG_PATH`).
 
 ```json
 {
@@ -296,10 +296,36 @@ For stdio mode (using a user access key):
 | `userAccessKey` | User access key — triggers stdio mode via `npx @mcp-s/mcp` |
 | `allowedTools`  | Glob patterns of tools to allow (optional)                 |
 | `disabledTools` | Glob patterns of tools to exclude (optional)               |
+| `settings`      | Per-agent behavioral settings (see below)                  |
 
 Environment variable substitution is supported: `"token": "${MY_TOKEN}"`.
 
----
+### `settings` block
+
+The optional `settings` block lets you tune behavioral settings per config file — useful when different AI agents use different configs and need different tuning:
+
+```json
+{
+  "org": "my-org",
+  "settings": {
+    "timeout": 60,
+    "maxRetries": 1,
+    "retryDelay": 500,
+    "daemon": false,
+    "daemonTimeout": 120,
+    "history": true
+  }
+}
+```
+
+| Field           | Description                                         | Default |
+| --------------- | --------------------------------------------------- | ------- |
+| `timeout`       | Request timeout (seconds)                           | `1800`  |
+| `maxRetries`    | Retry attempts for transient errors (`0` = disable) | `3`     |
+| `retryDelay`    | Base retry delay (milliseconds)                     | `1000`  |
+| `daemon`        | Enable connection caching (daemon mode)             | `true`  |
+| `daemonTimeout` | Idle timeout for cached connections (seconds)       | `300`   |
+| `history`       | Append each invocation to `history.jsonl`           | `false` |
 
 ## Working with Complex JSON Arguments
 
@@ -355,15 +381,11 @@ fi
 
 ### Environment Variables
 
-| Variable             | Description                                       | Default |
-| -------------------- | ------------------------------------------------- | ------- |
-| `MCP_DEBUG`          | Enable debug output                               | `false` |
-| `MCP_TIMEOUT`        | Request timeout (seconds)                         | `1800`  |
-| `MCP_MAX_RETRIES`    | Retry attempts for transient errors (0 = disable) | `3`     |
-| `MCP_RETRY_DELAY`    | Base retry delay (milliseconds)                   | `1000`  |
-| `MCP_STRICT_ENV`     | Error on missing `${VAR}` in config               | `true`  |
-| `MCP_DAEMON`         | Enable connection caching (daemon mode)           | `true`  |
-| `MCP_DAEMON_TIMEOUT` | Idle timeout for cached connections (seconds)     | `300`   |
+| Variable                | Description                                           | Default |
+| ----------------------- | ----------------------------------------------------- | ------- |
+| `MCP_S_CLI_DEBUG`       | Enable debug output                                   | —       |
+| `MCP_S_CLI_STRICT_ENV`  | Error on missing `${VAR}` in config (`false` to warn) | `true`  |
+| `MCP_S_CLI_CONFIG_PATH` | Override config file path                             | —       |
 
 ---
 
@@ -431,14 +453,15 @@ Each CLI invocation connects to the single configured server.
 
 ### Connection Pooling (Daemon)
 
-Daemon mode is enabled by default. The daemon keeps the MCP server connection open for `MCP_DAEMON_TIMEOUT` seconds (default: 300s) after the last request, avoiding repeated startup latency on subsequent calls.
+Daemon mode is enabled by default. The daemon keeps the server connection open for `settings.daemonTimeout` seconds (default: 300s) after the last request, avoiding repeated startup latency on subsequent calls.
 
 ```bash
 mcp-s-cli call some_tool '{}'        # Uses cached connection (default)
-MCP_DAEMON=0 mcp-s-cli info          # Disable daemon, use a fresh connection
-MCP_DEBUG=1 mcp-s-cli info           # See connection debug output
+MCP_S_CLI_DEBUG=1 mcp-s-cli info     # See connection debug output
 ```
 
+To disable daemon for a specific config, add `"settings": { "daemon": false }` to `config.json`.
+
 With daemon disabled, each CLI call opens a fresh connection and closes it when done.
 
 ### Error Handling and Retry

package/SKILL.md

@@ -9,21 +9,44 @@ Access a single MCP server through the command line. MCP enables interaction wit
 
 ## Commands
 
-| Command                          | Output                                       |
-| -------------------------------- | -------------------------------------------- |
-| `mcp-s-cli`                      | List all available tools                     |
-| `mcp-s-cli info`                 | Show server details                          |
-| `mcp-s-cli info <tool>`          | Get tool JSON schema                         |
-| `mcp-s-cli grep "<pattern>"`     | Search tools by name                         |
-| `mcp-s-cli call <tool>`          | Call tool (reads JSON from stdin if no args) |
-| `mcp-s-cli call <tool> '<json>'` | Call tool with arguments                     |
+| Command                          | Output                                              |
+| -------------------------------- | --------------------------------------------------- |
+| `mcp-s-cli`                      | List all available tools                            |
+| `mcp-s-cli info <tool>`          | Get tool JSON schema                                |
+| `mcp-s-cli grep "<pattern>"`     | Search tools by name (names only, not descriptions) |
+| `mcp-s-cli call <tool>`          | Call tool (reads JSON from stdin if no args)        |
+| `mcp-s-cli call <tool> '<json>'` | Call tool with arguments                            |
 
 ## Workflow
 
-1. **Discover**: `mcp-s-cli` → see all available tools
+1. **Discover**: `mcp-s-cli grep "<pattern>"` → find tools by keyword; fall back to `mcp-s-cli` only when you need a full inventory
 2. **Inspect**: `mcp-s-cli info <tool>` → get full JSON schema
 3. **Execute**: `mcp-s-cli call <tool> '<json>'` → run with arguments
 
+## Cost-Aware Usage
+
+Every command consumes tokens. Pick the cheapest operation that gets the job done.
+
+### Discovery: start narrow
+
+- **`grep "<pattern>"`** — cheapest. Use when you can guess a keyword from the user's request (e.g., "read a github file" → `grep "file"` or `grep "content"`).
+- **`mcp-s-cli`** (names only) — moderate. Use when you need a full inventory (e.g., "what tools do I have?" or "analyze logs from all tools").
+- **`mcp-s-cli -d`** (names + descriptions) — most expensive. Use only when names alone aren't enough to pick the right tool.
+
+**Rule: if you can guess a keyword, grep first.**
+
+### Execution: keep responses small
+
+- Use **filter/query parameters** to request only what's needed (e.g., Jira JQL, GitHub search queries, field selectors) instead of fetching everything.
+- **Pipe output** through shell tools (`head`, `grep`, `jq`) to trim large responses before they enter context.
+- Never fetch a full list when the user only needs a few fields (names, links, IDs).
+
+### Decision heuristic
+
+- User mentions a specific tool or domain keyword → `grep` for it.
+- User asks a broad question across all tools → list tools first, then act.
+- Tool may return large payloads → use filter params + pipe to trim output.
+
 ## Examples
 
 ```bash
@@ -33,17 +56,14 @@ mcp-s-cli
 # With descriptions
 mcp-s-cli -d
 
-# Show server details
-mcp-s-cli info
-
 # Get tool schema
-mcp-s-cli info read_file
+mcp-s-cli info my-tool
 
 # Call tool
-mcp-s-cli call read_file '{"path": "./README.md"}'
+mcp-s-cli call my-tool '{"arg-name": "arg-value"}'
 
 # Pipe from stdin (no '-' needed!)
-cat args.json | mcp-s-cli call read_file
+cat args.json | mcp-s-cli call my-tool
 
 # Search for tools
 mcp-s-cli grep "*file*"
@@ -68,24 +88,7 @@ mcp-s-cli call list_directory '{"path": "./src"}' \
 mcp-s-cli call get_file_contents '{"owner": "x", "repo": "y", "path": "z"}' > output.txt
 ```
 
-**Note:** `call` outputs raw text content directly (no jq needed for text extraction)
-
-## Options
-
-| Flag        | Purpose              |
-| ----------- | -------------------- |
-| `-d`        | Include descriptions |
-| `-c <path>` | Specify config file  |
-
-## Config
-
-The config file (`~/.config/mcp-s-cli/config.json`) uses a flat structure:
-
-```json
-{ "org": "myorg" }
-```
-
-This derives the server URL as `https://myorg.mcp-s.com/mcp`. Alternatively, use `baseUrl` for a custom URL, or `userAccessKey` for stdio mode.
+**Note:** `call` extracts text content from MCP responses and outputs it directly (no jq needed). Falls back to pretty-printed JSON when the response has no text parts.
 
 ## Common Errors
 
@@ -95,9 +98,14 @@ This derives the server URL as `https://myorg.mcp-s.com/mcp`. Alternatively, use
 | `mcp-s-cli call`            | MISSING_ARGUMENT   | Add tool name                          |
 | `mcp-s-cli call tool {bad}` | INVALID_JSON       | Use valid JSON with quoted string keys |
 
+## Debugging
+
+Set `MCP_S_CLI_DEBUG=1` to enable verbose debug output to stderr.
+
 ## Exit Codes
 
 - `0`: Success
 - `1`: Client error (bad args, missing config)
 - `2`: Server error (tool failed)
-- `3`: Network error
+- `3`: Network error (connection failed)
+- `4`: Auth error (authentication required)

package/dist/SKILL.md

@@ -9,21 +9,44 @@ Access a single MCP server through the command line. MCP enables interaction wit
 
 ## Commands
 
-| Command                          | Output                                       |
-| -------------------------------- | -------------------------------------------- |
-| `mcp-s-cli`                      | List all available tools                     |
-| `mcp-s-cli info`                 | Show server details                          |
-| `mcp-s-cli info <tool>`          | Get tool JSON schema                         |
-| `mcp-s-cli grep "<pattern>"`     | Search tools by name                         |
-| `mcp-s-cli call <tool>`          | Call tool (reads JSON from stdin if no args) |
-| `mcp-s-cli call <tool> '<json>'` | Call tool with arguments                     |
+| Command                          | Output                                              |
+| -------------------------------- | --------------------------------------------------- |
+| `mcp-s-cli`                      | List all available tools                            |
+| `mcp-s-cli info <tool>`          | Get tool JSON schema                                |
+| `mcp-s-cli grep "<pattern>"`     | Search tools by name (names only, not descriptions) |
+| `mcp-s-cli call <tool>`          | Call tool (reads JSON from stdin if no args)        |
+| `mcp-s-cli call <tool> '<json>'` | Call tool with arguments                            |
 
 ## Workflow
 
-1. **Discover**: `mcp-s-cli` → see all available tools
+1. **Discover**: `mcp-s-cli grep "<pattern>"` → find tools by keyword; fall back to `mcp-s-cli` only when you need a full inventory
 2. **Inspect**: `mcp-s-cli info <tool>` → get full JSON schema
 3. **Execute**: `mcp-s-cli call <tool> '<json>'` → run with arguments
 
+## Cost-Aware Usage
+
+Every command consumes tokens. Pick the cheapest operation that gets the job done.
+
+### Discovery: start narrow
+
+- **`grep "<pattern>"`** — cheapest. Use when you can guess a keyword from the user's request (e.g., "read a github file" → `grep "file"` or `grep "content"`).
+- **`mcp-s-cli`** (names only) — moderate. Use when you need a full inventory (e.g., "what tools do I have?" or "analyze logs from all tools").
+- **`mcp-s-cli -d`** (names + descriptions) — most expensive. Use only when names alone aren't enough to pick the right tool.
+
+**Rule: if you can guess a keyword, grep first.**
+
+### Execution: keep responses small
+
+- Use **filter/query parameters** to request only what's needed (e.g., Jira JQL, GitHub search queries, field selectors) instead of fetching everything.
+- **Pipe output** through shell tools (`head`, `grep`, `jq`) to trim large responses before they enter context.
+- Never fetch a full list when the user only needs a few fields (names, links, IDs).
+
+### Decision heuristic
+
+- User mentions a specific tool or domain keyword → `grep` for it.
+- User asks a broad question across all tools → list tools first, then act.
+- Tool may return large payloads → use filter params + pipe to trim output.
+
 ## Examples
 
 ```bash
@@ -33,17 +56,14 @@ mcp-s-cli
 # With descriptions
 mcp-s-cli -d
 
-# Show server details
-mcp-s-cli info
-
 # Get tool schema
-mcp-s-cli info read_file
+mcp-s-cli info my-tool
 
 # Call tool
-mcp-s-cli call read_file '{"path": "./README.md"}'
+mcp-s-cli call my-tool '{"arg-name": "arg-value"}'
 
 # Pipe from stdin (no '-' needed!)
-cat args.json | mcp-s-cli call read_file
+cat args.json | mcp-s-cli call my-tool
 
 # Search for tools
 mcp-s-cli grep "*file*"
@@ -68,24 +88,7 @@ mcp-s-cli call list_directory '{"path": "./src"}' \
 mcp-s-cli call get_file_contents '{"owner": "x", "repo": "y", "path": "z"}' > output.txt
 ```
 
-**Note:** `call` outputs raw text content directly (no jq needed for text extraction)
-
-## Options
-
-| Flag        | Purpose              |
-| ----------- | -------------------- |
-| `-d`        | Include descriptions |
-| `-c <path>` | Specify config file  |
-
-## Config
-
-The config file (`~/.config/mcp-s-cli/config.json`) uses a flat structure:
-
-```json
-{ "org": "myorg" }
-```
-
-This derives the server URL as `https://myorg.mcp-s.com/mcp`. Alternatively, use `baseUrl` for a custom URL, or `userAccessKey` for stdio mode.
+**Note:** `call` extracts text content from MCP responses and outputs it directly (no jq needed). Falls back to pretty-printed JSON when the response has no text parts.
 
 ## Common Errors
 
@@ -95,9 +98,14 @@ This derives the server URL as `https://myorg.mcp-s.com/mcp`. Alternatively, use
 | `mcp-s-cli call`            | MISSING_ARGUMENT   | Add tool name                          |
 | `mcp-s-cli call tool {bad}` | INVALID_JSON       | Use valid JSON with quoted string keys |
 
+## Debugging
+
+Set `MCP_S_CLI_DEBUG=1` to enable verbose debug output to stderr.
+
 ## Exit Codes
 
 - `0`: Success
 - `1`: Client error (bad args, missing config)
 - `2`: Server error (tool failed)
-- `3`: Network error
+- `3`: Network error (connection failed)
+- `4`: Auth error (authentication required)

package/dist/daemon.js

@@ -64,7 +64,7 @@ async function saveAuthData() {
       mode: 384
     });
   } catch (err) {
-    if (process.env.MCP_DEBUG) {
+    if (process.env.MCP_S_CLI_DEBUG) {
       console.error(
         `[mcp-s-cli] Failed to save auth data: ${err.message}`
       );
@@ -358,48 +358,32 @@ var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_RETRY_DELAY_MS = 1e3;
 var DEFAULT_DAEMON_TIMEOUT_SECONDS = 300;
 function debug(message) {
-  if (process.env.MCP_DEBUG) {
+  if (process.env.MCP_S_CLI_DEBUG) {
     console.error(`[mcp-s-cli] ${message}`);
   }
 }
-function getTimeoutMs() {
-  const envTimeout = process.env.MCP_TIMEOUT;
-  if (envTimeout) {
-    const seconds = Number.parseInt(envTimeout, 10);
-    if (!Number.isNaN(seconds) && seconds > 0) {
-      return seconds * 1e3;
-    }
+function getTimeoutMs(settings) {
+  if (settings?.timeout != null && settings.timeout > 0) {
+    return settings.timeout * 1e3;
   }
   return DEFAULT_TIMEOUT_MS;
 }
-function getMaxRetries() {
-  const envRetries = process.env.MCP_MAX_RETRIES;
-  if (envRetries) {
-    const retries = Number.parseInt(envRetries, 10);
-    if (!Number.isNaN(retries) && retries >= 0) {
-      return retries;
-    }
+function getMaxRetries(settings) {
+  if (settings?.maxRetries != null && settings.maxRetries >= 0) {
+    return settings.maxRetries;
   }
   return DEFAULT_MAX_RETRIES;
 }
-function getRetryDelayMs() {
-  const envDelay = process.env.MCP_RETRY_DELAY;
-  if (envDelay) {
-    const delay = Number.parseInt(envDelay, 10);
-    if (!Number.isNaN(delay) && delay > 0) {
-      return delay;
-    }
+function getRetryDelayMs(settings) {
+  if (settings?.retryDelay != null && settings.retryDelay > 0) {
+    return settings.retryDelay;
   }
   return DEFAULT_RETRY_DELAY_MS;
 }
 var DAEMON_SERVER_NAME = "mcp-s-cli";
-function getDaemonTimeoutMs() {
-  const envTimeout = process.env.MCP_DAEMON_TIMEOUT;
-  if (envTimeout) {
-    const seconds = Number.parseInt(envTimeout, 10);
-    if (!Number.isNaN(seconds) && seconds > 0) {
-      return seconds * 1e3;
-    }
+function getDaemonTimeoutMs(settings) {
+  if (settings?.daemonTimeout != null && settings.daemonTimeout > 0) {
+    return settings.daemonTimeout * 1e3;
   }
   return DEFAULT_DAEMON_TIMEOUT_SECONDS * 1e3;
 }
@@ -430,13 +414,13 @@ import { join as join2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/version.ts
-var VERSION = "0.0.9";
+var VERSION = "0.0.11";
 
 // src/client.ts
-function getRetryConfig() {
-  const totalBudgetMs = getTimeoutMs();
-  const maxRetries = getMaxRetries();
-  const baseDelayMs = getRetryDelayMs();
+function getRetryConfig(settings) {
+  const totalBudgetMs = getTimeoutMs(settings);
+  const maxRetries = getMaxRetries(settings);
+  const baseDelayMs = getRetryDelayMs(settings);
   const retryBudgetMs = Math.max(0, totalBudgetMs - 5e3);
   return {
     maxRetries,
@@ -567,7 +551,7 @@ ${stderrOutput}`;
   }, `connect to ${serverName}`);
 }
 async function connectToHttpServer(serverName, config) {
-  const oauthEnabled = process.env.MCP_NO_OAUTH !== "1";
+  const oauthEnabled = process.env.MCP_S_CLI_NO_OAUTH !== "1";
   return withRetry(async () => {
     const configuredAuth = config.headers?.Authorization || config.headers?.authorization;
     let headers = { ...config.headers };
@@ -717,18 +701,22 @@ async function listTools(client) {
     }));
   }, "list tools");
 }
-async function callTool(client, toolName, args) {
-  return withRetry(async () => {
-    const result = await client.callTool(
-      {
-        name: toolName,
-        arguments: args
-      },
-      void 0,
-      { timeout: getTimeoutMs() }
-    );
-    return result;
-  }, `call tool ${toolName}`);
+async function callTool(client, toolName, args, settings) {
+  return withRetry(
+    async () => {
+      const result = await client.callTool(
+        {
+          name: toolName,
+          arguments: args
+        },
+        void 0,
+        { timeout: getTimeoutMs(settings) }
+      );
+      return result;
+    },
+    `call tool ${toolName}`,
+    getRetryConfig(settings)
+  );
 }
 
 // src/daemon.ts
@@ -800,10 +788,10 @@ function killProcess(pid) {
     return false;
   }
 }
-async function runDaemon(serverName, config) {
+async function runDaemon(serverName, config, settings) {
   const socketPath = getSocketPath();
   const configHash = getConfigHash(config);
-  const timeoutMs = getDaemonTimeoutMs();
+  const timeoutMs = getDaemonTimeoutMs(settings);
   let idleTimer = null;
   let mcpClient = null;
   let server = null;
@@ -995,8 +983,11 @@ async function runDaemon(serverName, config) {
 if (process.argv[2] === "--daemon") {
   const serverName = process.argv[3];
   const configJson = process.argv[4];
+  const settingsJson = process.argv[5];
   if (!serverName || !configJson) {
-    console.error("Usage: daemon.ts --daemon <serverName> <configJson>");
+    console.error(
+      "Usage: daemon.ts --daemon <serverName> <configJson> [settingsJson]"
+    );
     process.exit(1);
   }
   let config;
@@ -1006,7 +997,16 @@ if (process.argv[2] === "--daemon") {
     console.error("Invalid config JSON");
     process.exit(1);
   }
-  runDaemon(serverName, config).catch((error) => {
+  let settings;
+  if (settingsJson) {
+    try {
+      settings = JSON.parse(settingsJson);
+    } catch {
+      console.error("Invalid settings JSON");
+      process.exit(1);
+    }
+  }
+  runDaemon(serverName, config, settings).catch((error) => {
     console.error("Daemon failed:", error);
     process.exit(1);
   });