mcp-to-cli-kit 0.1.0__tar.gz → 0.2.0__tar.gz

{mcp_to_cli_kit-0.1.0 → mcp_to_cli_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-to-cli-kit
-Version: 0.1.0
+Version: 0.2.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
@@ -149,6 +149,27 @@ servers:
     sse_read_timeout: 100  # seconds to wait for an answer, streamed or not
 ```
 
+### Environment variables in values
+
+The `url` and the `headers` values may refer to environment variables as `${NAME}`, so a token can stay out of the config file and the code default:
+
+```yaml
+servers:
+  example:
+    url: https://${EXAMPLE_HOST}/mcp
+    headers:
+      Authorization: "Bearer ${EXAMPLE_TOKEN}"
+```
+
+- References are expanded when the CLI contacts the server, never when the config is loaded. An unset variable therefore fails only a command that needs that server, with a config error (exit code 2) that names the variable and the server, and never shows a value. An empty variable counts as set.
+- `--help`, a tool's `--help` and `schema` still work offline from a fresh tool cache when the variable is unset. With an expired cache the CLI warns and uses it, as when the server is down.
+- A template can come from any layer: the code default, the config file, or an environment variable such as `EXAMPLE_TOOL_SERVERS__EXAMPLE__HEADERS__AUTHORIZATION='Bearer ${EXAMPLE_TOKEN}'`.
+- `$${` is a literal `${`. A `$` not followed by `{` stays as it is. A `${` without a closing `}`, or one that does not enclose a variable name (letters, digits and `_`), is a config error when the config is loaded.
+- Only `url` and the header values are expanded. Names (servers, mounts, tool groups, tools) and help texts are taken as written.
+- A URL with references is checked once it is expanded: it must be a valid http(s) URL, and no value may move text into another part of the URL (a `/`, `?`, `#` or `@` in a password, for example), so percent-encode such characters in the variable. An expanded header value must not hold control or non-ASCII characters. Each of these is a config error that names the variable, never its value.
+- Error messages show the URL as configured, with `${NAME}` unexpanded and without its userinfo and query. The parts that carry secrets (the values of the variables in the headers, and the userinfo, password, query and fragment of the expanded URL, also in their percent-encoded forms, if they are 4 characters or longer) are also replaced in transport errors and in the `-v` / `-vv` log. Host, port and path values are not secrets and are shown.
+- The tool cache remembers a hash of the URL as configured and one of the expanded URL. Pointing a variable at another server fetches that server's tools; with the variable unset, the cache of the configured URL is used.
+
 ### Several servers in one bin
 
 A bin can serve several MCP servers. Each server says where its tools appear with `mount`:
@@ -169,6 +190,22 @@ Each server keeps its own session, cache file (`<cache>/<bin>/<server>.json`), h
 
 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.
 
+### Stripping prefixes from tool names
+
+Some servers put their own name in front of every tool (`vendor-x_list`, `vendor-x_get`). `strip_prefixes` removes it from the command names:
+
+```yaml
+servers:
+  example:
+    url: https://mcp.example.com/mcp
+    strip_prefixes: [vendor-x_, vendor_x-]   # vendor-x_list -> example-tool list
+```
+
+- The first prefix in the list that a tool name starts with is stripped. A name that equals the prefix is kept.
+- It works in every mount mode and happens before tool groups and mounts: `tool_groups` prefixes match the stripped names, and a group or prefix mount applies to the stripped command (`prefix: "v-"` gives `example-tool v-list`).
+- The tool's own name stays an alias (`example-tool vendor-x_list`), and `hidden_tools` still lists tools by their own names.
+- When a stripped name would clash with another tool or a tool group of the same server (`vendor-x_list` next to a plain `list`), that tool keeps its full name and the CLI warns on stderr, so neither tool hides the other; hide one of them with `hidden_tools` to silence it. A clash with another server's tool is a config error, as for any other command name.
+
 ### Tool groups and hidden tools
 
 A server with many tools can split them into subcommands by tool-name prefix:
@@ -210,6 +247,31 @@ A property named like a built-in option (`help`, `input-json`, `arg-file`, `json
 
 `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`.
 
+### The config command
+
+`example-tool config` prints the effective configuration as JSON: the code default, the config file and the environment variables merged, with every default filled in. Next to it, it shows the config file that was looked for (`config_file`), whether it was loaded (`config_file_loaded`), the environment variable prefix (`env_prefix`) and the names of the environment variables that were applied (`env_applied`), never their values.
+
+```console
+$ example-tool config --pretty
+{
+  "config_file": "/home/me/.config/example-tool/config.yaml",
+  "config_file_loaded": true,
+  "env_prefix": "EXAMPLE_TOOL_",
+  "env_applied": ["EXAMPLE_TOOL_SERVERS__EXAMPLE__TIMEOUT"],
+  "config": {"help": null, "servers": {"example": {"url": "https://mcp.example.com/mcp", "headers": {"Authorization": "Bearer ${EXAMPLE_TOKEN}"}, ...}}}
+}
+```
+
+- It reads the configuration only. It loads no tool list, sends nothing to any server and needs no cache, so it works offline and with unset variables.
+- `${NAME}` references are shown as written, never expanded.
+- Literal text that may be a secret is masked as `***` plus its last 4 characters, or only `***` when it is shorter than 12 characters. These are masked:
+  - every header value, except `Accept`, `Content-Type`, `User-Agent` and `X-Mcp-Client` (matched in any case), which are shown as written. A leading `Bearer`, `Basic`, `Token`, `Digest`, `Bot` or `ApiKey` followed by more text stays readable, as in `Bearer ***abcd`;
+  - a URL's whole userinfo (user and password), its query values and its fragment.
+- Shown as written: the URL's scheme, host, port and path, every other setting (timeouts, mounts, tool groups, hidden tools, prefixes, help texts), and all `${NAME}` references.
+- The output follows the usual modes: compact under an AI agent or with `--json`, indented otherwise or with `--pretty`.
+
+`config` is a reserved command name, like `schema`: a tool whose command would be `config` is renamed to `config-tool`, and no group mount or tool group may be called `config`.
+
 ### 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.

{mcp_to_cli_kit-0.1.0 → mcp_to_cli_kit-0.2.0}/README.md

@@ -117,6 +117,27 @@ servers:
     sse_read_timeout: 100  # seconds to wait for an answer, streamed or not
 ```
 
+### Environment variables in values
+
+The `url` and the `headers` values may refer to environment variables as `${NAME}`, so a token can stay out of the config file and the code default:
+
+```yaml
+servers:
+  example:
+    url: https://${EXAMPLE_HOST}/mcp
+    headers:
+      Authorization: "Bearer ${EXAMPLE_TOKEN}"
+```
+
+- References are expanded when the CLI contacts the server, never when the config is loaded. An unset variable therefore fails only a command that needs that server, with a config error (exit code 2) that names the variable and the server, and never shows a value. An empty variable counts as set.
+- `--help`, a tool's `--help` and `schema` still work offline from a fresh tool cache when the variable is unset. With an expired cache the CLI warns and uses it, as when the server is down.
+- A template can come from any layer: the code default, the config file, or an environment variable such as `EXAMPLE_TOOL_SERVERS__EXAMPLE__HEADERS__AUTHORIZATION='Bearer ${EXAMPLE_TOKEN}'`.
+- `$${` is a literal `${`. A `$` not followed by `{` stays as it is. A `${` without a closing `}`, or one that does not enclose a variable name (letters, digits and `_`), is a config error when the config is loaded.
+- Only `url` and the header values are expanded. Names (servers, mounts, tool groups, tools) and help texts are taken as written.
+- A URL with references is checked once it is expanded: it must be a valid http(s) URL, and no value may move text into another part of the URL (a `/`, `?`, `#` or `@` in a password, for example), so percent-encode such characters in the variable. An expanded header value must not hold control or non-ASCII characters. Each of these is a config error that names the variable, never its value.
+- Error messages show the URL as configured, with `${NAME}` unexpanded and without its userinfo and query. The parts that carry secrets (the values of the variables in the headers, and the userinfo, password, query and fragment of the expanded URL, also in their percent-encoded forms, if they are 4 characters or longer) are also replaced in transport errors and in the `-v` / `-vv` log. Host, port and path values are not secrets and are shown.
+- The tool cache remembers a hash of the URL as configured and one of the expanded URL. Pointing a variable at another server fetches that server's tools; with the variable unset, the cache of the configured URL is used.
+
 ### Several servers in one bin
 
 A bin can serve several MCP servers. Each server says where its tools appear with `mount`:
@@ -137,6 +158,22 @@ Each server keeps its own session, cache file (`<cache>/<bin>/<server>.json`), h
 
 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.
 
+### Stripping prefixes from tool names
+
+Some servers put their own name in front of every tool (`vendor-x_list`, `vendor-x_get`). `strip_prefixes` removes it from the command names:
+
+```yaml
+servers:
+  example:
+    url: https://mcp.example.com/mcp
+    strip_prefixes: [vendor-x_, vendor_x-]   # vendor-x_list -> example-tool list
+```
+
+- The first prefix in the list that a tool name starts with is stripped. A name that equals the prefix is kept.
+- It works in every mount mode and happens before tool groups and mounts: `tool_groups` prefixes match the stripped names, and a group or prefix mount applies to the stripped command (`prefix: "v-"` gives `example-tool v-list`).
+- The tool's own name stays an alias (`example-tool vendor-x_list`), and `hidden_tools` still lists tools by their own names.
+- When a stripped name would clash with another tool or a tool group of the same server (`vendor-x_list` next to a plain `list`), that tool keeps its full name and the CLI warns on stderr, so neither tool hides the other; hide one of them with `hidden_tools` to silence it. A clash with another server's tool is a config error, as for any other command name.
+
 ### Tool groups and hidden tools
 
 A server with many tools can split them into subcommands by tool-name prefix:
@@ -178,6 +215,31 @@ A property named like a built-in option (`help`, `input-json`, `arg-file`, `json
 
 `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`.
 
+### The config command
+
+`example-tool config` prints the effective configuration as JSON: the code default, the config file and the environment variables merged, with every default filled in. Next to it, it shows the config file that was looked for (`config_file`), whether it was loaded (`config_file_loaded`), the environment variable prefix (`env_prefix`) and the names of the environment variables that were applied (`env_applied`), never their values.
+
+```console
+$ example-tool config --pretty
+{
+  "config_file": "/home/me/.config/example-tool/config.yaml",
+  "config_file_loaded": true,
+  "env_prefix": "EXAMPLE_TOOL_",
+  "env_applied": ["EXAMPLE_TOOL_SERVERS__EXAMPLE__TIMEOUT"],
+  "config": {"help": null, "servers": {"example": {"url": "https://mcp.example.com/mcp", "headers": {"Authorization": "Bearer ${EXAMPLE_TOKEN}"}, ...}}}
+}
+```
+
+- It reads the configuration only. It loads no tool list, sends nothing to any server and needs no cache, so it works offline and with unset variables.
+- `${NAME}` references are shown as written, never expanded.
+- Literal text that may be a secret is masked as `***` plus its last 4 characters, or only `***` when it is shorter than 12 characters. These are masked:
+  - every header value, except `Accept`, `Content-Type`, `User-Agent` and `X-Mcp-Client` (matched in any case), which are shown as written. A leading `Bearer`, `Basic`, `Token`, `Digest`, `Bot` or `ApiKey` followed by more text stays readable, as in `Bearer ***abcd`;
+  - a URL's whole userinfo (user and password), its query values and its fragment.
+- Shown as written: the URL's scheme, host, port and path, every other setting (timeouts, mounts, tool groups, hidden tools, prefixes, help texts), and all `${NAME}` references.
+- The output follows the usual modes: compact under an AI agent or with `--json`, indented otherwise or with `--pretty`.
+
+`config` is a reserved command name, like `schema`: a tool whose command would be `config` is renamed to `config-tool`, and no group mount or tool group may be called `config`.
+
 ### 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.

{mcp_to_cli_kit-0.1.0 → mcp_to_cli_kit-0.2.0}/src/mcp_to_cli_kit/cache.py

@@ -6,6 +6,11 @@ A cache entry is fresh for an hour. An expired entry is still kept: when the ser
 be reached, the CLI falls back to it rather than failing to know its own commands. The entry
 records a hash of the server URL, never the URL itself, which may carry a token; an entry
 written for another URL is ignored.
+
+A configured URL may be a template with ``${NAME}`` references. The entry then records a hash
+of the template and one of the expanded URL. When the variables are set, both must match, so
+pointing a variable at another server does not reuse the old server's tools; when one is not
+set, the template alone decides, so ``--help`` still lists the tools offline.
 """
 
 from __future__ import annotations
@@ -60,8 +65,14 @@ class SchemaCache:
         """The cache file of one server."""
         return self.directory / f"{server}.json"
 
-    def load(self, server: str, url: str) -> CachedTools | None:
-        """Return the cached tools of a server, fresh or expired, or None when there is no usable entry."""
+    def load(self, server: str, url: str, resolved_url: str | None = None) -> CachedTools | None:
+        """Return the cached tools of a server, fresh or expired, or None when there is no usable entry.
+
+        Args:
+            server: The server's name.
+            url: The URL as configured, a template or not.
+            resolved_url: The URL with its variables expanded, or None when they cannot be.
+        """
         path = self.path(server)
         try:
             content = json.loads(path.read_text(encoding="utf-8"))
@@ -75,6 +86,7 @@ class SchemaCache:
             not isinstance(content, dict)
             or content.get("version") != _FORMAT_VERSION
             or content.get("url_sha256") != _url_hash(url)
+            or (resolved_url not in (None, url) and content.get("resolved_url_sha256") != _url_hash(resolved_url))
             or not isinstance(content.get("tools"), list)
             or not isinstance(content.get("fetched_at"), int | float)
         ):
@@ -86,9 +98,12 @@ class SchemaCache:
         tools = [tool for tool in content["tools"] if isinstance(tool, dict)]
         return CachedTools(tools=tools, fetched_at=fetched_at, fresh=0 <= age < self.ttl_seconds)
 
-    def save(self, server: str, url: str, tools: list[dict[str, Any]]) -> None:
+    def save(self, server: str, url: str, tools: list[dict[str, Any]], resolved_url: str | None = None) -> None:
         """Write a server's tools atomically. A failure to write is logged, never raised."""
-        content = {"version": _FORMAT_VERSION, "url_sha256": _url_hash(url), "fetched_at": time.time(), "tools": tools}
+        content: dict[str, Any] = {"version": _FORMAT_VERSION, "url_sha256": _url_hash(url)}
+        if resolved_url is not None and resolved_url != url:
+            content["resolved_url_sha256"] = _url_hash(resolved_url)
+        content.update(fetched_at=time.time(), tools=tools)
         path = self.path(server)
         try:
             self.directory.mkdir(mode=0o700, parents=True, exist_ok=True)