@mcp-s/cli 0.0.9

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Webrix Ltd. All rights reserved.
+https://webrix.ai
+
+This software and associated documentation files (the "Software") are proprietary and confidential. The Software is licensed, not sold.
+
+Use of this Software is permitted solely by users of Webrix Ltd. Unauthorized
+copying, distribution, modification, sublicensing, or use of this Software,
+in whole or in part, is strictly prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+WEBRIX LTD. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM THE USE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,475 @@
+# mcp-s-cli
+
+A lightweight CLI for connecting AI agents to the [Webrix](https://webrix.ai) MCP Gateway — Webrix's enterprise-grade identity and access layer for AI agents.
+
+## Overview
+
+Webrix's MCP Gateway is the secure connection layer between AI agents and your enterprise systems (GitHub, Slack, Jira, internal APIs, etc.). This CLI lets you interact with a single Webrix MCP server from your terminal or from inside AI coding agents (Claude, Cursor, Gemini CLI, etc.).
+
+## Features
+
+- **Lightweight** — Minimal dependencies, fast startup
+- **Shell-friendly** — JSON output for `call`, pipes with `jq`, chaining support
+- **Agent-optimized** — Designed for AI coding agents (Claude Code, Cursor, Gemini CLI, etc.)
+- **Secure** — Supports OAuth login and Bearer token auth to the Webrix Gateway
+- **Connection pooling** — Lazy-spawn daemon keeps connections warm (configurable idle timeout)
+- **Tool filtering** — Allow/disable specific tools via config
+- **Actionable errors** — Structured error messages with recovery suggestions
+
+---
+
+## Quick Start
+
+### 1. Install
+
+Requires [Node.js](https://nodejs.org/) >= 18.
+
+```bash
+npm install -g @mcp-s/cli
+```
+
+Or run without installing:
+
+```bash
+npx @mcp-s/cli
+```
+
+### 2. Initialize config with your Webrix Gateway URL
+
+```bash
+# Interactive setup (recommended)
+mcp-s-cli init
+
+# Or non-interactive: HTTP server with a Bearer token
+mcp-s-cli init --base-url https://<your-org>.webrix.ai/mcp --token <your-token>
+
+# Or: OAuth-based (run login after init)
+mcp-s-cli init --base-url https://<your-org>.webrix.ai/mcp
+mcp-s-cli login
+```
+
+### 3. Discover available tools
+
+```bash
+# List all tools
+mcp-s-cli
+
+# With descriptions
+mcp-s-cli -d
+```
+
+### 4. Call a tool
+
+```bash
+# View tool schema first
+mcp-s-cli info <tool_name>
+
+# Call the tool
+mcp-s-cli call <tool_name> '{"param": "value"}'
+```
+
+---
+
+## Usage
+
+```
+mcp-s-cli [options]                        List all tools
+mcp-s-cli [options] info                   Show server details
+mcp-s-cli [options] info <tool>            Show schema for a specific tool
+mcp-s-cli [options] grep <pattern>         Search tools by glob pattern
+mcp-s-cli [options] call <tool>            Call a tool (reads JSON args from stdin)
+mcp-s-cli [options] call <tool> <json>     Call a tool with inline JSON arguments
+mcp-s-cli init [--org <org>] [--base-url <url>] [...]  Initialize global config
+mcp-s-cli whoami                           Show config location and auth state
+mcp-s-cli login                            Log in to the configured server via OAuth
+mcp-s-cli logout                           Remove stored OAuth tokens
+mcp-s-cli clear                            Reset server config
+mcp-s-cli clear-auth                       Remove all stored auth data
+```
+
+> **Tip:** Add `-d` to any command to include tool descriptions.
+
+### Options
+
+| Option                    | Description                           |
+| ------------------------- | ------------------------------------- |
+| `-h, --help`              | Show help message                     |
+| `-v, --version`           | Show version number                   |
+| `-d, --with-descriptions` | Include tool descriptions in output   |
+| `-c, --config <path>`     | Path to a custom `config.json` config |
+
+### Output streams
+
+| Stream     | Content                                |
+| ---------- | -------------------------------------- |
+| **stdout** | Tool results and human-readable output |
+| **stderr** | Errors and diagnostics                 |
+
+---
+
+## Commands
+
+### List Tools
+
+```bash
+# Basic listing
+$ mcp-s-cli
+server
+  • search_issues
+  • create_ticket
+  • list_channels
+
+# With descriptions
+$ mcp-s-cli -d
+server
+  • search_issues - Search Jira issues by query
+  • create_ticket - Create a new Jira ticket
+  • list_channels - List Slack channels
+```
+
+### Search Tools
+
+```bash
+# Find tools matching a glob pattern
+$ mcp-s-cli grep "*ticket*"
+create_ticket
+update_ticket
+
+# With descriptions
+$ mcp-s-cli grep "*search*" -d
+search_issues - Search Jira issues by query
+```
+
+### View Server Details
+
+```bash
+$ mcp-s-cli info
+Server: server
+Transport: http
+URL: https://<your-org>.webrix.ai/mcp
+
+Tools (12):
+  search_issues
+    Search Jira issues by query
+    Parameters:
+      • query (string, required) - JQL or natural language query
+      • limit (number, optional) - Max results
+  ...
+```
+
+### View Tool Schema
+
+```bash
+$ mcp-s-cli info search_issues
+
+Tool: search_issues
+Server: server
+
+Description:
+  Search Jira issues by query
+
+Input Schema:
+  {
+    "type": "object",
+    "properties": {
+      "query": { "type": "string", "description": "JQL or natural language query" },
+      "limit": { "type": "number" }
+    },
+    "required": ["query"]
+  }
+```
+
+### Call a Tool
+
+```bash
+# With inline JSON
+$ mcp-s-cli call search_issues '{"query": "bug in authentication", "limit": 5}'
+
+# Pipe the JSON output
+$ mcp-s-cli call search_issues '{"query": "open bugs"}' | jq '.content[0].text'
+
+# Read JSON args from stdin (no '-' needed)
+$ echo '{"query": "urgent"}' | mcp-s-cli call search_issues
+
+# Heredoc for complex JSON
+$ mcp-s-cli call create_ticket <<EOF
+{"title": "Fix login bug", "description": "Users can't log in with SSO"}
+EOF
+```
+
+### Initialize Global Config
+
+Set up `~/.config/mcp-s-cli/config.json` with your Webrix MCP Gateway:
+
+```bash
+# Interactive (prompts for connection type, credentials)
+mcp-s-cli init
+
+# HTTP mode — derive URL from org name
+mcp-s-cli init --org <your-org>
+
+# HTTP mode — provide a custom base URL
+mcp-s-cli init --base-url https://<your-org>.mcp-s.com/mcp
+
+# HTTP mode with optional mcp/toolkit headers
+mcp-s-cli init --org <your-org> --mcp slack --toolkit my-tk
+
+# stdio mode — add a user access key (runs via npx @mcp-s/mcp)
+mcp-s-cli init --org <your-org> --mcp slack --toolkit my-tk --user-access-key <key>
+mcp-s-cli init --base-url example.com --mcp slack --user-access-key <key>
+```
+
+| Option                    | Description                                                    |
+| ------------------------- | -------------------------------------------------------------- |
+| `--org <org>`             | Org name — derives URL as `https://<org>.mcp-s.com/mcp`        |
+| `--base-url <url>`        | Custom server URL                                              |
+| `--mcp <id>`              | MCP identifier (sent as `x-mcp` header or `MCP` env var)       |
+| `--toolkit <name>`        | Toolkit name (sent as `x-toolkit` header or `TOOLKIT` env var) |
+| `--user-access-key <key>` | User access key — triggers stdio mode                          |
+
+**Mode selection:**
+
+- `--user-access-key` absent → **HTTP mode**: produces a `baseUrl` + optional headers config
+- `--user-access-key` present → **stdio mode**: produces a stdio config running `npx -y @mcp-s/mcp` with env vars
+
+Either `--org` or `--base-url` is required; they are mutually exclusive.
+
+> **Note:** `init` overwrites the global config file. It is intended as a quick-start helper.
+
+### Authentication
+
+```bash
+# Log in via OAuth (opens browser)
+mcp-s-cli login
+
+# Log out (removes stored tokens from auth.json)
+mcp-s-cli logout
+
+# Show current auth state and config location
+mcp-s-cli whoami
+```
+
+### Maintenance
+
+```bash
+# Reset server config (sets config.json to {})
+mcp-s-cli clear
+
+# Remove all stored OAuth tokens (sets auth.json to {})
+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`).
+
+```json
+{
+  "baseUrl": "https://<your-org>.mcp-s.com/mcp",
+  "mcp": "slack",
+  "toolkit": "my-tk",
+  "token": "<bearer-token>"
+}
+```
+
+For stdio mode (using a user access key):
+
+```json
+{
+  "baseUrl": "https://<your-org>.mcp-s.com/mcp",
+  "mcp": "slack",
+  "toolkit": "my-tk",
+  "userAccessKey": "<key>"
+}
+```
+
+**Fields:**
+
+| Field           | Description                                                |
+| --------------- | ---------------------------------------------------------- |
+| `baseUrl`       | MCP server URL (required for HTTP mode)                    |
+| `mcp`           | MCP identifier header / env var                            |
+| `toolkit`       | Toolkit name header / env var                              |
+| `token`         | Static Bearer token for HTTP auth                          |
+| `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)               |
+
+Environment variable substitution is supported: `"token": "${MY_TOKEN}"`.
+
+---
+
+## Working with Complex JSON Arguments
+
+For arguments containing single quotes, special characters, or multi-line content, use stdin to avoid shell escaping issues:
+
+```bash
+# Heredoc (clean, no escaping needed)
+mcp-s-cli call create_ticket <<EOF
+{"title": "It's broken", "description": "User said \"it doesn't work\""}
+EOF
+
+# From a file
+cat args.json | mcp-s-cli call some_tool
+
+# Using jq to build the payload
+jq -n '{query: "open bugs", assignee: "me"}' | mcp-s-cli call search_issues
+```
+
+---
+
+## Chaining and Scripting
+
+Chain MCP calls using shell pipes and `jq`:
+
+```bash
+# Find issues and extract URLs
+mcp-s-cli call search_issues '{"query": "priority: high"}' \
+  | jq -r '.content[0].text | fromjson | .issues[].url'
+
+# Conditional: check something exists before acting on it
+mcp-s-cli call list_channels '{}' \
+  | jq -e '.content[0].text | contains("engineering")' \
+  && mcp-s-cli call post_message '{"channel": "engineering", "text": "Deploy complete"}'
+
+# Error handling in scripts
+if result=$(mcp-s-cli call get_config '{}' 2>/dev/null); then
+  echo "$result" | jq '.content[0].text | fromjson'
+else
+  echo "Failed to fetch config"
+fi
+```
+
+**Tips:**
+
+- Use `jq -r` for raw string output (no surrounding quotes)
+- Use `jq -e` for conditional checks (exits 1 if false/null)
+- Use `2>/dev/null` to suppress errors when testing existence
+- Use `jq -s '.'` to merge multiple JSON outputs into an array
+
+---
+
+## Configuration
+
+### 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`   |
+
+---
+
+## Using with AI Agents
+
+`mcp-s-cli` is designed to give AI coding agents direct access to the Webrix MCP Gateway via the shell. Rather than loading full tool schemas into the agent's context window (which consumes thousands of tokens), the CLI lets agents discover and call tools on demand.
+
+### System Prompt Integration
+
+Add this to your AI agent's system prompt:
+
+```xml
+## MCP Tools (via Webrix Gateway)
+
+You have access to enterprise tools through the Webrix MCP Gateway via the `mcp-s-cli` CLI.
+
+Commands:
+  mcp-s-cli                    # List all tools
+  mcp-s-cli info               # Show server details
+  mcp-s-cli info <tool>        # Get tool schema
+  mcp-s-cli grep "<pattern>"   # Search tools by name
+  mcp-s-cli call <tool>        # Call tool (stdin for JSON args)
+  mcp-s-cli call <tool> '{}'   # Call tool with inline JSON
+
+Workflow:
+1. Discover: `mcp-s-cli` to see available tools
+2. Inspect:  `mcp-s-cli info <tool>` to get the schema
+3. Execute:  `mcp-s-cli call <tool> '<json>'` with the required args
+
+Examples:
+  mcp-s-cli call search_issues '{"query": "open bugs"}'
+  echo '{"query": "urgent"}' | mcp-s-cli call search_issues
+  mcp-s-cli call create_ticket <<EOF
+  {"title": "Bug", "description": "Details here"}
+  EOF
+```
+
+### Agents Skill
+
+For AI agents that support Skill files (Cursor, Gemini CLI, Claude Code, etc.), use the included `SKILL.md` in your skills directory for a ready-made integration.
+
+### Common Errors
+
+| Wrong command                  | Error code           | Fix                                |
+| ------------------------------ | -------------------- | ---------------------------------- |
+| `mcp-s-cli run tool`           | `UNKNOWN_SUBCOMMAND` | Use `call`                         |
+| `mcp-s-cli list`               | `UNKNOWN_SUBCOMMAND` | Use `mcp-s-cli` (no subcommand)    |
+| `mcp-s-cli call tool bad_json` | `INVALID_JSON_ARGS`  | Use valid JSON: `'{"key": "val"}'` |
+
+---
+
+## Architecture
+
+### Connection Model
+
+Each CLI invocation connects to the single configured server.
+
+| Command                      | Behaviour                         |
+| ---------------------------- | --------------------------------- |
+| `mcp-s-cli` (list all)       | Connects to the configured server |
+| `mcp-s-cli grep "<pattern>"` | Connects to the configured server |
+| `mcp-s-cli info`             | Connects to the configured server |
+| `mcp-s-cli info <tool>`      | Connects to the configured server |
+| `mcp-s-cli call <tool> '{}'` | Connects to the 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.
+
+```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
+```
+
+With daemon disabled, each CLI call opens a fresh connection and closes it when done.
+
+### Error Handling and Retry
+
+The CLI automatically retries transient failures with exponential backoff.
+
+**Retried automatically:** network errors (`ECONNREFUSED`, `ETIMEDOUT`, `ECONNRESET`), HTTP `429`, `502`, `503`, `504`
+
+**Fail immediately:** config errors, auth errors (`401`, `403`), tool not found, invalid JSON
+
+---
+
+## Error Messages
+
+All errors include actionable recovery suggestions, optimized for humans and AI agents alike:
+
+```
+Error [CONFIG_MISSING_FIELD]: Config file is missing required server fields
+  Suggestion: Config must have at least "baseUrl" (HTTP) or "userAccessKey" (stdio). Run mcp-s-cli init to set up.
+
+Error [TOOL_NOT_FOUND]: Tool "search" not found in server "server"
+  Details: Available tools: search_issues, create_ticket, list_channels (+5 more)
+  Suggestion: Run 'mcp-s-cli' to see all available tools
+
+Error [INVALID_JSON_ARGUMENTS]: Invalid JSON in tool arguments
+  Details: Parse error: Unexpected identifier "test"
+  Suggestion: Arguments must be valid JSON. Use single quotes: '{"key": "value"}'
+```
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: mcp-s-cli
+description: Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers.
+---
+
+# mcp-s-cli
+
+Access a single MCP server through the command line. MCP enables interaction with external systems like GitHub, filesystems, databases, and APIs.
+
+## 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                     |
+
+## Workflow
+
+1. **Discover**: `mcp-s-cli` → see all available tools
+2. **Inspect**: `mcp-s-cli info <tool>` → get full JSON schema
+3. **Execute**: `mcp-s-cli call <tool> '<json>'` → run with arguments
+
+## Examples
+
+```bash
+# List all tools
+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
+
+# Call tool
+mcp-s-cli call read_file '{"path": "./README.md"}'
+
+# Pipe from stdin (no '-' needed!)
+cat args.json | mcp-s-cli call read_file
+
+# Search for tools
+mcp-s-cli grep "*file*"
+
+# Output is raw text (pipe-friendly)
+mcp-s-cli call read_file '{"path": "./file"}' | head -10
+```
+
+## Advanced Chaining
+
+```bash
+# Chain: search files → read first match
+mcp-s-cli call search_files '{"path": ".", "pattern": "*.md"}' \
+  | head -1 \
+  | xargs -I {} mcp-s-cli call read_file '{"path": "{}"}'
+
+# Loop: process multiple files
+mcp-s-cli call list_directory '{"path": "./src"}' \
+  | while read f; do mcp-s-cli call read_file "{\"path\": \"$f\"}"; done
+
+# Save to file
+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.
+
+## Common Errors
+
+| Wrong Command               | Error              | Fix                                    |
+| --------------------------- | ------------------ | -------------------------------------- |
+| `mcp-s-cli run tool`        | UNKNOWN_SUBCOMMAND | Use `call` instead of `run`            |
+| `mcp-s-cli call`            | MISSING_ARGUMENT   | Add tool name                          |
+| `mcp-s-cli call tool {bad}` | INVALID_JSON       | Use valid JSON with quoted string keys |
+
+## Exit Codes
+
+- `0`: Success
+- `1`: Client error (bad args, missing config)
+- `2`: Server error (tool failed)
+- `3`: Network error

package/dist/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: mcp-s-cli
+description: Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers.
+---
+
+# mcp-s-cli
+
+Access a single MCP server through the command line. MCP enables interaction with external systems like GitHub, filesystems, databases, and APIs.
+
+## 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                     |
+
+## Workflow
+
+1. **Discover**: `mcp-s-cli` → see all available tools
+2. **Inspect**: `mcp-s-cli info <tool>` → get full JSON schema
+3. **Execute**: `mcp-s-cli call <tool> '<json>'` → run with arguments
+
+## Examples
+
+```bash
+# List all tools
+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
+
+# Call tool
+mcp-s-cli call read_file '{"path": "./README.md"}'
+
+# Pipe from stdin (no '-' needed!)
+cat args.json | mcp-s-cli call read_file
+
+# Search for tools
+mcp-s-cli grep "*file*"
+
+# Output is raw text (pipe-friendly)
+mcp-s-cli call read_file '{"path": "./file"}' | head -10
+```
+
+## Advanced Chaining
+
+```bash
+# Chain: search files → read first match
+mcp-s-cli call search_files '{"path": ".", "pattern": "*.md"}' \
+  | head -1 \
+  | xargs -I {} mcp-s-cli call read_file '{"path": "{}"}'
+
+# Loop: process multiple files
+mcp-s-cli call list_directory '{"path": "./src"}' \
+  | while read f; do mcp-s-cli call read_file "{\"path\": \"$f\"}"; done
+
+# Save to file
+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.
+
+## Common Errors
+
+| Wrong Command               | Error              | Fix                                    |
+| --------------------------- | ------------------ | -------------------------------------- |
+| `mcp-s-cli run tool`        | UNKNOWN_SUBCOMMAND | Use `call` instead of `run`            |
+| `mcp-s-cli call`            | MISSING_ARGUMENT   | Add tool name                          |
+| `mcp-s-cli call tool {bad}` | INVALID_JSON       | Use valid JSON with quoted string keys |
+
+## Exit Codes
+
+- `0`: Success
+- `1`: Client error (bad args, missing config)
+- `2`: Server error (tool failed)
+- `3`: Network error