diff --git a/.github/aw/mcp-clis.md b/.github/aw/mcp-clis.md new file mode 100644 index 00000000000..a2b9cad0e2f --- /dev/null +++ b/.github/aw/mcp-clis.md @@ -0,0 +1,70 @@ +--- +description: MCP CLI command usage guidance and JSON payload patterns +--- + +# MCP CLI Usage + +The MCP CLI feature exposes mounted MCP servers as shell commands on `PATH` and provides a consistent command interface for tool calls. + +> **IMPORTANT**: For `safeoutputs` and `mcpscripts`, **always use the CLI commands** instead of the equivalent MCP tools. The CLI wrappers are the preferred interface — do **not** call their MCP tools directly even though they may appear in your tool list. +> +> For `safeoutputs`, treat every successful command as a real write-intent declaration. Do **not** use `safeoutputs` for exploratory probing, auth checks, placeholder payloads, repeated "try again" variants, or manual runtime experiments. When you need a safe-output, emit the final intended call once. If you are not ready to perform the real action, use `noop` or `report_incomplete` instead. +> +> For all other servers listed here, they are **only** available as CLI commands and are **not** available as MCP tools. + +## How to use + +Each server is a standalone executable on your `PATH`. Invoke it from bash like any other shell command: + +```bash +# Call a tool — pass arguments as --name value pairs + --param1 value1 --param2 value2 +``` + +**Example** — using the `playwright` CLI: +```bash +playwright --help # list all browser tools +playwright browser_navigate --url https://example.com +playwright browser_snapshot # capture page accessibility tree +``` + +**Example** — using the `safeoutputs` CLI (safe outputs) when you are ready to emit the final real action: +```bash +safeoutputs add_comment --item_number 42 --body "Analysis complete" +``` + +**Example** — using the `mcpscripts` CLI (mcp-scripts): +```bash +mcpscripts --help # list all script tools +mcpscripts mcpscripts-gh --args "pr list --repo owner/repo --limit 5" +``` + +Passing multiple or complex arguments (preferred): + +**Preferred approach for any tool call with multiple or complex arguments**: supply a JSON object on stdin using `.` as the sentinel. The bridge parses stdin as the argument object, preserving all native types (numbers, booleans, arrays) without shell-quoting issues. + +```bash +# Full argument payload as JSON via printf pipe +printf '{"item_number":42,"body":"### Title\n\nBody paragraph one.\n\nBody paragraph two."}' \ + | safeoutputs add_comment . + +# Works with any tool — just match the parameter names from --help +printf '{"title":"Fix: something","body":"Details here","labels":["bug","priority-high"]}' \ + | safeoutputs create_issue . +``` + +If pipes are blocked by bash policy, write JSON to a file and use redirection with `.` (for example: `safeoutputs create_pull_request . < /tmp/payload.json`). + +> **Why prefer JSON payload mode?** +> - Preserves native types and avoids shell quoting/escaping pitfalls +> - Supports both pipe and file-redirection input with the same `.` sentinel + +## Notes + +- **Prefer JSON payload mode** (`. < file` or `printf '{...}' | server tool .`) for any call with multiple arguments or complex values +- All parameters can also be passed as `--name value` pairs; boolean flags can be set with `--flag` (no value) to mean `true` +- Use `.` as the only argument to parse stdin as a JSON object (all parameters supplied at once) +- Parameter names with hyphens or underscores are interchangeable (e.g. `issue-number` and `issue_number` both work) +- Output is printed to stdout; errors are printed to stderr with a non-zero exit code +- Run the CLI commands inside a `bash` tool call — they are shell executables, not MCP tools +- These CLI commands are read-only and cannot be modified by the agent diff --git a/actions/setup/md/mcp_cli_tools_prompt.md b/actions/setup/md/mcp_cli_tools_prompt.md index 2ed307d75ef..d9343b2fef7 100644 --- a/actions/setup/md/mcp_cli_tools_prompt.md +++ b/actions/setup/md/mcp_cli_tools_prompt.md @@ -1,68 +1,5 @@ -The following servers are available as CLI commands on `PATH`: - +CLI servers are available on `PATH`: __GH_AW_MCP_CLI_SERVERS_LIST__ - -> **IMPORTANT**: For `safeoutputs` and `mcpscripts`, **always use the CLI commands** listed above instead of the equivalent MCP tools. The CLI wrappers are the preferred interface — do **not** call their MCP tools directly even though they may appear in your tool list. -> -> For `safeoutputs`, treat every successful command as a real write-intent declaration. Do **not** use `safeoutputs` for exploratory probing, auth checks, placeholder payloads, repeated "try again" variants, or manual runtime experiments. When you need a safe-output, emit the final intended call once. If you are not ready to perform the real action, use `noop` or `report_incomplete` instead. -> -> For all other servers listed here, they are **only** available as CLI commands and are **not** available as MCP tools. - -How to use: - -Each server is a standalone executable on your `PATH`. Invoke it from bash like any other shell command: - -```bash -# Call a tool — pass arguments as --name value pairs - --param1 value1 --param2 value2 -``` - -**Example** — using the `playwright` CLI: -```bash -playwright --help # list all browser tools -playwright browser_navigate --url https://example.com -playwright browser_snapshot # capture page accessibility tree -``` - -**Example** — using the `safeoutputs` CLI (safe outputs) when you are ready to emit the final real action: -```bash -safeoutputs add_comment --item_number 42 --body "Analysis complete" -``` - -**Example** — using the `mcpscripts` CLI (mcp-scripts): -```bash -mcpscripts --help # list all script tools -mcpscripts mcpscripts-gh --args "pr list --repo owner/repo --limit 5" -``` - -Passing multiple or complex arguments (preferred): - -**Preferred approach for any tool call with multiple or complex arguments**: supply a JSON object on stdin using `.` as the sentinel. The bridge parses stdin as the argument object, preserving all native types (numbers, booleans, arrays) without shell-quoting issues. - -```bash -# Full argument payload as JSON via printf pipe -printf '{"item_number":42,"body":"### Title\n\nBody paragraph one.\n\nBody paragraph two."}' \ - | safeoutputs add_comment . - -# Works with any tool — just match the parameter names from --help -printf '{"title":"Fix: something","body":"Details here","labels":["bug","priority-high"]}' \ - | safeoutputs create_issue . -``` - -If pipes are blocked by bash policy, write JSON to a file and use redirection with `.` (for example: `safeoutputs create_pull_request . < /tmp/payload.json`). - -> **Why prefer JSON payload mode?** -> - Preserves native types and avoids shell quoting/escaping pitfalls -> - Supports both pipe and file-redirection input with the same `.` sentinel - -Notes: - -- **Prefer JSON payload mode** (`. < file` or `printf '{...}' | server tool .`) for any call with multiple arguments or complex values -- All parameters can also be passed as `--name value` pairs; boolean flags can be set with `--flag` (no value) to mean `true` -- Use `.` as the only argument to parse stdin as a JSON object (all parameters supplied at once) -- Parameter names with hyphens or underscores are interchangeable (e.g. `issue-number` and `issue_number` both work) -- Output is printed to stdout; errors are printed to stderr with a non-zero exit code -- Run the CLI commands inside a `bash` tool call — they are shell executables, not MCP tools -- These CLI commands are read-only and cannot be modified by the agent +Use ` --help` for tool names, parameters, and examples before calling any command. diff --git a/pkg/workflow/mcp_cli_mount_test.go b/pkg/workflow/mcp_cli_mount_test.go index 5fe1fe9ecec..205cfa178b5 100644 --- a/pkg/workflow/mcp_cli_mount_test.go +++ b/pkg/workflow/mcp_cli_mount_test.go @@ -225,5 +225,5 @@ func TestBuildMCPCLIPromptSection_PromptFileUsesNonHeadingLabels(t *testing.T) { prompt := string(content) assert.NotRegexp(t, `(?m)^\s*(>\s*)?##\s+`, prompt, "prompt must not contain H2 Markdown headings") assert.NotRegexp(t, `(?m)^\s*(>\s*)?###\s+`, prompt, "prompt must not contain H3 Markdown headings") - assert.Contains(t, prompt, "How to use:") + assert.Contains(t, prompt, "Use ` --help` for tool names, parameters, and examples before calling any command.") }