Add JSON output documentation and tool call examples to CLI help

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `--json` output documentation in `--help` for all commands, describing the MCP object shape returned
+- `tools-get` now shows an example `tools-call` command with placeholder arguments based on the tool's schema
+
+### Fixed
+
+- `build:readme` script failing on macOS due to `sed -i` platform difference
+
 ## [0.2.4] - 2026-04-07
 
 ### Security

README.md

@@ -106,6 +106,53 @@ mcpc @fs tools-list
 <!-- AUTO-GENERATED: mcpc --help -->
 
 ```
+Usage: mcpc [<@session>] [<command>] [options]
+
+Universal command-line client for the Model Context Protocol (MCP).
+
+Commands:
+  connect <server> <@session>  Connect to an MCP server and start a new named @session
+  close <@session>             Close a session
+  restart <@session>           Restart a session (losing all state)
+  shell <@session>             Open interactive shell for a session
+  login <server>               Interactively login to a server using OAuth and save profile
+  logout <server>              Delete an OAuth profile for a server
+  clean [resources...]         Clean up mcpc data (sessions, profiles, logs, all)
+  grep <pattern>               Search tools and instructions across all active sessions
+  x402 [subcommand] [args...]  Configure an x402 payment wallet (EXPERIMENTAL)
+  help [command] [subcommand]  Show help for a specific command
+
+Options:
+  -j, --json                   Output in JSON format for scripting
+  --verbose                    Enable debug logging
+  --profile <name>             OAuth profile for the server ("default" if not provided)
+  --schema <file>              Validate tool/prompt schema against expected schema
+  --schema-mode <mode>         Schema validation mode: strict, compatible (default), ignore
+  --timeout <seconds>          Request timeout in seconds (default: 300)
+  --insecure                   Skip TLS certificate verification (for self-signed certs)
+  -v, --version                Output the version number
+  -h, --help                   Display help
+
+MCP session commands (after connecting):
+  <@session>                   Show MCP server info, capabilities, and tools
+  <@session> grep <pattern>    Search tools and instructions
+  <@session> tools-list        List all server tools
+  <@session> tools-get <name>  Get tool details and schema
+  <@session> tools-call <name> [arg:=val ... | <json> | <stdin]
+  <@session> prompts-list
+  <@session> prompts-get <name> [arg:=val ... | <json> | <stdin]
+  <@session> resources-list
+  <@session> resources-read <uri>
+  <@session> resources-subscribe <uri>
+  <@session> resources-unsubscribe <uri>
+  <@session> resources-templates-list
+  <@session> tasks-list
+  <@session> tasks-get <taskId>
+  <@session> tasks-cancel <taskId>
+  <@session> logging-set-level <level>
+  <@session> ping
+
+Run "mcpc" without arguments to show active sessions and OAuth profiles.
 ```
 
 ### General actions

docs/TODOs.md

@@ -1,6 +1,9 @@
 
 # TODOs
 
+- "mcpc help tools-call" - show more info how to pass args, including stdio pipe and JSON. Maybe add short examples.
+Make "mcpc @apify grep --help" and "mcpc grep --help" more consistent with info what they print.
+The former should provide the --json example.
 
 ## NEW
 
@@ -30,6 +33,8 @@
 - Make "mcpc connect mcp.apify.com" work without @session, and generate session name on best effort basis (e.g. use the main hostname without TLD 
 + suffix)
 
+- and finally, "mcpc connect" should connect to all server configs found - see https://www.withone.ai/docs/cli#mcp-server-installation 
+
 - mcpc @apify tools-get fetch-actor-details => should print also "object" properties in human mode
 
 - mcpc @apify tools-call xxx --help / "mcpc @apify/xxx --help" should print tools-get + command info

scripts/update-readme.sh

@@ -66,7 +66,8 @@ echo "  Done"
 echo "Updating table of contents..."
 doctoc "$README" --github --notitle --maxlevel 2
 # Remove mcpc: entries from TOC (internal anchors that shouldn't be in TOC)
-sed -i '/^- \[mcpc:/d' "$README"
+# Use temp file for cross-platform compatibility (macOS sed -i requires different syntax)
+sed '/^- \[mcpc:/d' "$README" > "$README.tmp" && mv "$README.tmp" "$README"
 echo "  Done"
 
 # Step 3: Check for broken internal links

src/cli/commands/grep.ts

@@ -421,7 +421,7 @@ function formatGrepResultHuman(
       pattern && options
         ? highlightMatch(result.instructions, pattern, options)
         : result.instructions;
-    lines.push(`${indent}${chalk.bold('Instructions:')}  ${chalk.dim('````' + snippet + '````')}`);
+    lines.push(`${indent}${chalk.bold('Instructions:')} ${chalk.dim('````' + snippet + '````')}`);
   }
   lines.push(
     ...formatResultSection('Tools', result.tools, formatToolLine as (item: never) => string, indent)

src/cli/commands/tools.ts

@@ -4,7 +4,13 @@
 
 import ora from 'ora';
 import chalk from 'chalk';
-import { formatOutput, formatToolDetail, formatSuccess, formatWarning } from '../output.js';
+import {
+  formatOutput,
+  formatToolDetail,
+  formatToolCallExample,
+  formatSuccess,
+  formatWarning,
+} from '../output.js';
 import { ClientError } from '../../lib/errors.js';
 import type { CommandOptions, TaskUpdate } from '../../lib/types.js';
 import { withMcpClient } from '../helpers.js';
@@ -85,6 +91,10 @@ export async function getTool(
 
     if (options.outputMode === 'human') {
       console.log(formatToolDetail(tool));
+      const example = formatToolCallExample(tool, target);
+      if (example) {
+        console.log('\n' + example + '\n');
+      }
     } else {
       console.log(formatOutput(tool, 'json'));
     }