mcp-to-cli-kit 0.1.0__tar.gz

mcp_to_cli_kit-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

mcp_to_cli_kit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint and type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Ruff check
+        run: uv run ruff check --output-format github .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Mypy
+        run: uv run mypy --strict src
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Run tests
+        run: uv run pytest

mcp_to_cli_kit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-to-cli-kit
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

mcp_to_cli_kit-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tool caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Claude
+.claude/settings.local.json

mcp_to_cli_kit-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

mcp_to_cli_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filip Procházka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_to_cli_kit-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: mcp-to-cli-kit
+Version: 0.1.0
+Summary: Build a typed command-line interface for one or more remote MCP servers
+Project-URL: Homepage, https://github.com/fprochazka/mcp-to-cli-kit
+Project-URL: Repository, https://github.com/fprochazka/mcp-to-cli-kit
+Project-URL: Issues, https://github.com/fprochazka/mcp-to-cli-kit/issues
+Author-email: Filip Procházka <dev@fprochazka.cz>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,cli,click,json-schema,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.20
+Requires-Dist: mcp<2,>=1.26
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# mcp-to-cli-kit
+
+A small library for turning one or more remote MCP servers into a typed command-line tool. Each MCP tool becomes a subcommand with real options compiled from its JSON input schema, so a shell user or an AI coding agent can call it without hand-writing JSON-RPC.
+
+The kit owns the parts every such CLI needs and tends to get wrong when it is copied from project to project: the mapping from JSON schema to options, the configuration loading, the schema cache, and output that stays valid JSON when piped. A consumer package only supplies its bin name and a default configuration.
+
+## Installation
+
+Add the kit to the consumer package:
+
+```bash
+uv add mcp-to-cli-kit
+```
+
+## Building a consumer package
+
+A consumer is a small Python package with one console script. It names the bin, gives the default configuration, and hands both to the kit.
+
+`pyproject.toml`:
+
+```toml
+[project]
+name = "example-tool"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["mcp-to-cli-kit"]
+
+[project.scripts]
+example-tool = "example_tool.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/example_tool"]
+```
+
+`src/example_tool/cli.py`:
+
+```python
+from typing import Any
+
+from mcp_to_cli_kit.cli import main as kit_main
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "help": "Call the tools of the example MCP server.",
+    "servers": {"example": {"url": "https://mcp.example.com/mcp"}},
+}
+
+
+def main() -> None:
+    kit_main("example-tool", DEFAULT_CONFIG, distribution="example-tool")
+```
+
+`DEFAULT_CONFIG` has the same shape as the config file (see [Configuration](#configuration)), so a user's `~/.config/example-tool/config.yaml` can override any key of it.
+
+`distribution` is the name of the consumer's own package. The kit reads its version from the package metadata and shows it in `--version`, in the `X-Mcp-Client: example-tool/<version> (mcp-to-cli-kit <version>)` header of every request, and in the `clientInfo` of the MCP `initialize` request. Without it, the kit looks for the package that installed the `example-tool` script, and falls back to `0.1.0`.
+
+### Results reported as text
+
+Some servers report a failure as an ordinary result instead of setting `isError`. A `result_classifier` turns such a result into an error: it is printed to stderr and the exit code is 1. The kit calls it only for results the server did not already mark as errors.
+
+```python
+from mcp import types
+from mcp_to_cli_kit.cli import main as kit_main
+
+
+def is_error(server: str, tool: str, result: types.CallToolResult) -> bool:
+    first = next((item.text for item in result.content if isinstance(item, types.TextContent)), "")
+    return first.startswith("Error: HTTP ")
+
+
+def main() -> None:
+    kit_main("example-tool", DEFAULT_CONFIG, distribution="example-tool", result_classifier=is_error)
+```
+
+### Developing the kit and a consumer together
+
+To change the kit and a consumer at the same time, point the consumer at a local checkout of the kit as an editable path dependency, then install the consumer as a uv tool:
+
+```toml
+[tool.uv.sources]
+mcp-to-cli-kit = { path = "../mcp-to-cli-kit", editable = true }
+```
+
+```console
+$ uv tool install -e .
+$ example-tool --version
+example-tool 0.1.0 (mcp-to-cli-kit 0.1.dev7+g1d1eb86b6)
+```
+
+Because both installs are editable, a change in the kit or in the consumer takes effect without reinstalling. The kit takes its version from git tags, so a checkout between releases reports a development version such as `0.1.dev7+g1d1eb86b6`; the editable install records it when it is installed, so run `uv tool install -e .` again to refresh it.
+
+## Usage
+
+Every tool of the server is then a subcommand, named in kebab case (`search_items` becomes `search-items`; the tool's own name works too):
+
+```console
+$ example-tool --help                      # the tools, from a one-hour cache
+$ example-tool search-items --help         # a tool's full description and options
+$ example-tool schema search-items         # the tool's raw input schema
+$ example-tool search-items --query "red" --limit 5 --tags a --tags b --no-verbose
+```
+
+### Configuration
+
+The default from code is overridden by `~/.config/<bin>/config.yaml` (or the file given by `--config`), and that by environment variables with the bin's prefix, such as `EXAMPLE_TOOL_SERVERS__EXAMPLE__URL` or `EXAMPLE_TOOL_SERVERS__EXAMPLE__HEADERS__AUTHORIZATION`. Without a default and without a file, the CLI says which file it expected. See `mcp_to_cli_kit/config.py` for the full rules.
+
+```yaml
+servers:
+  example:
+    url: https://mcp.example.com/mcp
+    headers:
+      Authorization: Bearer ...
+    timeout: 30            # seconds to connect and to send a request
+    sse_read_timeout: 100  # seconds to wait for an answer, streamed or not
+```
+
+### Several servers in one bin
+
+A bin can serve several MCP servers. Each server says where its tools appear with `mount`:
+
+```yaml
+servers:
+  alpha:
+    url: https://alpha.example.com/mcp      # mount: root, the default: tools at the top level
+  beta:
+    url: https://beta.example.com/mcp
+    mount: {group: beta, help: The beta tools.}   # example-tool beta search-items ...
+  gamma:
+    url: https://gamma.example.com/mcp
+    mount: {prefix: "g-"}                    # example-tool g-search-items ...
+```
+
+Each server keeps its own session, cache file (`<cache>/<bin>/<server>.json`), headers and retries, and only the servers a command needs are contacted: `example-tool beta search-items` never talks to alpha. The top-level `--help` lists the groups without asking their servers, and lists the root and prefixed tools from the caches; a server that cannot be listed is shown under "Unavailable servers" while the others are still listed.
+
+Two servers must not produce the same command name. When the tool lists show that they do (two root servers with a tool of the same name, or a group named like a top-level tool), the CLI stops with a config error that names both servers; give one of them a group or prefix mount, or hide the tool with `hidden_tools`. Calling a group checks the other servers only from what is already known (their caches), so a clash with a server whose tools were never fetched surfaces in the top-level `--help`. When a command resolves on one server while another server that could also define it cannot be reached, the CLI runs it and warns that the other server could not be checked.
+
+### Tool groups and hidden tools
+
+A server with many tools can split them into subcommands by tool-name prefix:
+
+```yaml
+servers:
+  example:
+    url: https://mcp.example.com/mcp
+    tool_groups:
+      - {prefix: svc_a_, group: svc-a, help: Service A.}   # svc_a_list -> example-tool svc-a list
+      - {prefix: svc_b_, group: svc-b}                     # svc_b_search -> example-tool svc-b search
+    hidden_tools: [svc_a_delete]
+```
+
+- The prefix is stripped from the command name inside the group. The tool's own name still works as an alias, inside the group (`svc-a svc_a_list`) and at the server's mount level (`example-tool svc_a_list`). The longest matching prefix wins.
+- Tools that match no prefix stay at the server's mount level.
+- Tool groups sit where the server is mounted: at the top level for a root mount, under the group for a group mount (`example-tool ex svc-a list`), and behind the prefix for a prefix mount, because the prefix applies to everything the server puts at the top level (`prefix: "b-"` gives `example-tool b-svc-a list`).
+- A tool group name must not clash with a tool command of the same server, with a group mount, or with another server's tool or tool group; each clash is a config error.
+- `hidden_tools` lists tools by their own names. A hidden tool is not listed and cannot be called, inside a tool group as well; a tool group stays listed even when all its tools are hidden.
+
+### Options
+
+Each property of a tool's input schema becomes an option:
+
+- The option is the kebab-case name (`--start-time`). The schema's own spelling (`--startTime`) and the snake case (`--start_time`) are accepted too, and the schema's spelling is what is sent.
+- An option left out is not sent; the server applies its own default, which the help shows.
+- Booleans are `--flag` / `--no-flag`, so `false` can be sent.
+- Enums are fixed choices, listed in the help.
+- Arrays are repeated options, one item each, or one JSON array. Values are never split on commas.
+- Objects take a JSON literal; invalid JSON is an error, not a string.
+- `--input-json JSON|@FILE|-` passes all arguments as one JSON object; `--arg-file NAME=PATH` reads one value from a file, or from stdin with `-`.
+- Arguments are validated against the schema before the call. A usage error lists the tool's parameters, so no `--help` round trip is needed.
+
+A property named like a built-in option (`help`, `input-json`, `arg-file`, `json`, `pretty`) gets an `--arg-` prefix.
+
+### The schema command
+
+`schema TOOL` prints a tool's raw JSON input schema, as the server declared it in `tools/list`. It exists at every level where tools live (`example-tool schema search-items`, `example-tool beta schema search-items`, `example-tool svc-a schema list`) and accepts every name the tool's own command accepts. It reads the cached tool list, so with a warm cache nothing is sent to the server. The schema is printed as compact JSON in machine mode and indented otherwise.
+
+`schema` is a built-in command name: a tool whose command would be `schema` is renamed to `schema-tool`, and no group mount or tool group may be called `schema`.
+
+### Output and exit codes
+
+Under an AI coding agent (detected from its environment variables), or with `--json`, the result is printed exactly as the server sent it. Otherwise, or with `--pretty`, JSON is indented with `indent=2` and non-ASCII text stays readable. Several content items become one JSON array. Nothing is ever wrapped to the terminal width.
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | The tool reported an error; its text is on stderr |
+| 2 | Usage or configuration error |
+| 3 | The server could not be reached or did not speak MCP |
+
+Other global options: `--refresh-tools` fetches the tool list again, `-v` / `-vv` log to stderr, `--version`. Every request carries an `X-Mcp-Client: <bin>/<version> (mcp-to-cli-kit <version>)` header.
+
+When the server cannot be reached, an expired tool cache is used with a warning. `initialize` and `tools/list` are retried twice on connect errors, timeouts and HTTP 502/503/504; a tool call is retried only when it never reached the server. Ctrl-C abandons the request in flight and exits with 130.
+
+Config and cache live under `$XDG_CONFIG_HOME` and `$XDG_CACHE_HOME` when those are set, and under `~/.config` and `~/.cache` otherwise.
+
+## Troubleshooting
+
+- **A call ends with "timed out after 100s".** The server took longer than `sse_read_timeout`, which defaults to 100 seconds so that a coding agent's shell tool (often limited to 120 seconds) sees this error instead of killing the command. Raise `sse_read_timeout` for that server when its tools are legitimately slow. Timeouts exit with 3, never with 1, because the tool's own outcome is unknown.
+- **A call hangs until that timeout although the server already failed.** When a server or proxy cuts a streamed (SSE) answer in the middle, the MCP SDK swallows the broken stream and offers no hook to notice it, so the request ends only with the read timeout. A plain JSON answer cut the same way fails at once.
+- **Something else.** Run with `-v` to see what the CLI does, or `-vv` to also see the HTTP traffic and the MCP SDK's own log.
+
+## License
+
+MIT

mcp_to_cli_kit-0.1.0/README.md

@@ -0,0 +1,206 @@
+# mcp-to-cli-kit
+
+A small library for turning one or more remote MCP servers into a typed command-line tool. Each MCP tool becomes a subcommand with real options compiled from its JSON input schema, so a shell user or an AI coding agent can call it without hand-writing JSON-RPC.
+
+The kit owns the parts every such CLI needs and tends to get wrong when it is copied from project to project: the mapping from JSON schema to options, the configuration loading, the schema cache, and output that stays valid JSON when piped. A consumer package only supplies its bin name and a default configuration.
+
+## Installation
+
+Add the kit to the consumer package:
+
+```bash
+uv add mcp-to-cli-kit
+```
+
+## Building a consumer package
+
+A consumer is a small Python package with one console script. It names the bin, gives the default configuration, and hands both to the kit.
+
+`pyproject.toml`:
+
+```toml
+[project]
+name = "example-tool"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["mcp-to-cli-kit"]
+
+[project.scripts]
+example-tool = "example_tool.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/example_tool"]
+```
+
+`src/example_tool/cli.py`:
+
+```python
+from typing import Any
+
+from mcp_to_cli_kit.cli import main as kit_main
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "help": "Call the tools of the example MCP server.",
+    "servers": {"example": {"url": "https://mcp.example.com/mcp"}},
+}
+
+
+def main() -> None:
+    kit_main("example-tool", DEFAULT_CONFIG, distribution="example-tool")
+```
+
+`DEFAULT_CONFIG` has the same shape as the config file (see [Configuration](#configuration)), so a user's `~/.config/example-tool/config.yaml` can override any key of it.
+
+`distribution` is the name of the consumer's own package. The kit reads its version from the package metadata and shows it in `--version`, in the `X-Mcp-Client: example-tool/<version> (mcp-to-cli-kit <version>)` header of every request, and in the `clientInfo` of the MCP `initialize` request. Without it, the kit looks for the package that installed the `example-tool` script, and falls back to `0.1.0`.
+
+### Results reported as text
+
+Some servers report a failure as an ordinary result instead of setting `isError`. A `result_classifier` turns such a result into an error: it is printed to stderr and the exit code is 1. The kit calls it only for results the server did not already mark as errors.
+
+```python
+from mcp import types
+from mcp_to_cli_kit.cli import main as kit_main
+
+
+def is_error(server: str, tool: str, result: types.CallToolResult) -> bool:
+    first = next((item.text for item in result.content if isinstance(item, types.TextContent)), "")
+    return first.startswith("Error: HTTP ")
+
+
+def main() -> None:
+    kit_main("example-tool", DEFAULT_CONFIG, distribution="example-tool", result_classifier=is_error)
+```
+
+### Developing the kit and a consumer together
+
+To change the kit and a consumer at the same time, point the consumer at a local checkout of the kit as an editable path dependency, then install the consumer as a uv tool:
+
+```toml
+[tool.uv.sources]
+mcp-to-cli-kit = { path = "../mcp-to-cli-kit", editable = true }
+```
+
+```console
+$ uv tool install -e .
+$ example-tool --version
+example-tool 0.1.0 (mcp-to-cli-kit 0.1.dev7+g1d1eb86b6)
+```
+
+Because both installs are editable, a change in the kit or in the consumer takes effect without reinstalling. The kit takes its version from git tags, so a checkout between releases reports a development version such as `0.1.dev7+g1d1eb86b6`; the editable install records it when it is installed, so run `uv tool install -e .` again to refresh it.
+
+## Usage
+
+Every tool of the server is then a subcommand, named in kebab case (`search_items` becomes `search-items`; the tool's own name works too):
+
+```console
+$ example-tool --help                      # the tools, from a one-hour cache
+$ example-tool search-items --help         # a tool's full description and options
+$ example-tool schema search-items         # the tool's raw input schema
+$ example-tool search-items --query "red" --limit 5 --tags a --tags b --no-verbose
+```
+
+### Configuration
+
+The default from code is overridden by `~/.config/<bin>/config.yaml` (or the file given by `--config`), and that by environment variables with the bin's prefix, such as `EXAMPLE_TOOL_SERVERS__EXAMPLE__URL` or `EXAMPLE_TOOL_SERVERS__EXAMPLE__HEADERS__AUTHORIZATION`. Without a default and without a file, the CLI says which file it expected. See `mcp_to_cli_kit/config.py` for the full rules.
+
+```yaml
+servers:
+  example:
+    url: https://mcp.example.com/mcp
+    headers:
+      Authorization: Bearer ...
+    timeout: 30            # seconds to connect and to send a request
+    sse_read_timeout: 100  # seconds to wait for an answer, streamed or not
+```
+
+### Several servers in one bin
+
+A bin can serve several MCP servers. Each server says where its tools appear with `mount`:
+
+```yaml
+servers:
+  alpha:
+    url: https://alpha.example.com/mcp      # mount: root, the default: tools at the top level
+  beta:
+    url: https://beta.example.com/mcp
+    mount: {group: beta, help: The beta tools.}   # example-tool beta search-items ...
+  gamma:
+    url: https://gamma.example.com/mcp
+    mount: {prefix: "g-"}                    # example-tool g-search-items ...
+```
+
+Each server keeps its own session, cache file (`<cache>/<bin>/<server>.json`), headers and retries, and only the servers a command needs are contacted: `example-tool beta search-items` never talks to alpha. The top-level `--help` lists the groups without asking their servers, and lists the root and prefixed tools from the caches; a server that cannot be listed is shown under "Unavailable servers" while the others are still listed.
+
+Two servers must not produce the same command name. When the tool lists show that they do (two root servers with a tool of the same name, or a group named like a top-level tool), the CLI stops with a config error that names both servers; give one of them a group or prefix mount, or hide the tool with `hidden_tools`. Calling a group checks the other servers only from what is already known (their caches), so a clash with a server whose tools were never fetched surfaces in the top-level `--help`. When a command resolves on one server while another server that could also define it cannot be reached, the CLI runs it and warns that the other server could not be checked.
+
+### Tool groups and hidden tools
+
+A server with many tools can split them into subcommands by tool-name prefix:
+
+```yaml
+servers:
+  example:
+    url: https://mcp.example.com/mcp
+    tool_groups:
+      - {prefix: svc_a_, group: svc-a, help: Service A.}   # svc_a_list -> example-tool svc-a list
+      - {prefix: svc_b_, group: svc-b}                     # svc_b_search -> example-tool svc-b search
+    hidden_tools: [svc_a_delete]
+```
+
+- The prefix is stripped from the command name inside the group. The tool's own name still works as an alias, inside the group (`svc-a svc_a_list`) and at the server's mount level (`example-tool svc_a_list`). The longest matching prefix wins.
+- Tools that match no prefix stay at the server's mount level.
+- Tool groups sit where the server is mounted: at the top level for a root mount, under the group for a group mount (`example-tool ex svc-a list`), and behind the prefix for a prefix mount, because the prefix applies to everything the server puts at the top level (`prefix: "b-"` gives `example-tool b-svc-a list`).
+- A tool group name must not clash with a tool command of the same server, with a group mount, or with another server's tool or tool group; each clash is a config error.
+- `hidden_tools` lists tools by their own names. A hidden tool is not listed and cannot be called, inside a tool group as well; a tool group stays listed even when all its tools are hidden.
+
+### Options
+
+Each property of a tool's input schema becomes an option:
+
+- The option is the kebab-case name (`--start-time`). The schema's own spelling (`--startTime`) and the snake case (`--start_time`) are accepted too, and the schema's spelling is what is sent.
+- An option left out is not sent; the server applies its own default, which the help shows.
+- Booleans are `--flag` / `--no-flag`, so `false` can be sent.
+- Enums are fixed choices, listed in the help.
+- Arrays are repeated options, one item each, or one JSON array. Values are never split on commas.
+- Objects take a JSON literal; invalid JSON is an error, not a string.
+- `--input-json JSON|@FILE|-` passes all arguments as one JSON object; `--arg-file NAME=PATH` reads one value from a file, or from stdin with `-`.
+- Arguments are validated against the schema before the call. A usage error lists the tool's parameters, so no `--help` round trip is needed.
+
+A property named like a built-in option (`help`, `input-json`, `arg-file`, `json`, `pretty`) gets an `--arg-` prefix.
+
+### The schema command
+
+`schema TOOL` prints a tool's raw JSON input schema, as the server declared it in `tools/list`. It exists at every level where tools live (`example-tool schema search-items`, `example-tool beta schema search-items`, `example-tool svc-a schema list`) and accepts every name the tool's own command accepts. It reads the cached tool list, so with a warm cache nothing is sent to the server. The schema is printed as compact JSON in machine mode and indented otherwise.
+
+`schema` is a built-in command name: a tool whose command would be `schema` is renamed to `schema-tool`, and no group mount or tool group may be called `schema`.
+
+### Output and exit codes
+
+Under an AI coding agent (detected from its environment variables), or with `--json`, the result is printed exactly as the server sent it. Otherwise, or with `--pretty`, JSON is indented with `indent=2` and non-ASCII text stays readable. Several content items become one JSON array. Nothing is ever wrapped to the terminal width.
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | The tool reported an error; its text is on stderr |
+| 2 | Usage or configuration error |
+| 3 | The server could not be reached or did not speak MCP |
+
+Other global options: `--refresh-tools` fetches the tool list again, `-v` / `-vv` log to stderr, `--version`. Every request carries an `X-Mcp-Client: <bin>/<version> (mcp-to-cli-kit <version>)` header.
+
+When the server cannot be reached, an expired tool cache is used with a warning. `initialize` and `tools/list` are retried twice on connect errors, timeouts and HTTP 502/503/504; a tool call is retried only when it never reached the server. Ctrl-C abandons the request in flight and exits with 130.
+
+Config and cache live under `$XDG_CONFIG_HOME` and `$XDG_CACHE_HOME` when those are set, and under `~/.config` and `~/.cache` otherwise.
+
+## Troubleshooting
+
+- **A call ends with "timed out after 100s".** The server took longer than `sse_read_timeout`, which defaults to 100 seconds so that a coding agent's shell tool (often limited to 120 seconds) sees this error instead of killing the command. Raise `sse_read_timeout` for that server when its tools are legitimately slow. Timeouts exit with 3, never with 1, because the tool's own outcome is unknown.
+- **A call hangs until that timeout although the server already failed.** When a server or proxy cuts a streamed (SSE) answer in the middle, the MCP SDK swallows the broken stream and offers no hook to notice it, so the request ends only with the read timeout. A plain JSON answer cut the same way fails at once.
+- **Something else.** Run with `-v` to see what the CLI does, or `-vv` to also see the HTTP traffic and the MCP SDK's own log.
+
+## License
+
+MIT