@qodalis/mcp-cli 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-10-27
+
+### Added
+
+- Plugin-development tools, served locally: `qcli_docs_search` and
+  `qcli_docs_read` over the plugin guide (`llms-full.txt` from
+  `QCLI_DOCS_URL`, default https://cli.qodalis.com/llms-full.txt, cached for an
+  hour, with a snapshot bundled in the package for offline use), `qcli_api`
+  (TypeScript declarations of the `@qodalis/*` packages from the project's
+  node_modules or the latest npm version) and `qcli_scaffold_plugin`
+  (`@qodalis/create-cli-plugin`).
+- MCP prompts `create-web-plugin` and `create-server-command`, and the docs
+  topics as resources (`qcli-docs://<section>/<topic>`).
+- `QCLI_DEV_TOOLS` (default `true`) and `QCLI_DOCS_URL`; `npm run sync-docs`
+  refreshes the bundled docs snapshot.
+
+### Changed
+
+- `QCLI_URL` is optional: without it the server runs in developer mode with only
+  the plugin-development tools. With it, the dev tools are listed before the
+  server's tools, and still listed when the server is unreachable.
+- `QCLI_READ_ONLY`, `QCLI_TOOLS` and `QCLI_EXCLUDE` apply to the dev tools too
+  (read-only mode hides `qcli_scaffold_plugin`).
+- `createProxyServer(remote, config, { dev })` accepts the dev tools and an
+  `undefined` remote.
+
+## [0.1.0] - 2026-10-15
+
+### Added
+
+- First release: a stdio MCP server that proxies Claude Code (or any MCP client)
+  to a Qodalis CLI server's MCP endpoint (`<QCLI_URL>/api/qcli/mcp`). Tools are
+  taken from the server's `tools/list` and passed through unchanged; calls are
+  forwarded.
+- Authentication with an API token or the server's static MCP token
+  (`QCLI_TOKEN`), or with `QCLI_USER` / `QCLI_PASSWORD` (signs in again after a
+  401).
+- `QCLI_READ_ONLY`, `QCLI_TOOLS` and `QCLI_EXCLUDE` client-side tool filters.
+- Resilience: connect on first use, failed connects are not cached, one retry on
+  connection loss, fast failure (`QCLI_CONNECTION_TIMEOUT`) with actionable
+  messages for unreachable servers, rejected credentials, missing permissions and
+  MCP not enabled; 60 s tool-list cache refreshed for unknown tools.
+- `QCLI_REQUEST_TIMEOUT`, `QCLI_TRUST_CERT`, `--env-file` / `QCLI_ENV_FILE`,
+  `QODALIS_CLI_*` aliases, `--help`, `--version`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qodalis Solutions SRL
+
+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.

package/README.md

@@ -1,3 +1,385 @@
-# Temporary Holding Version
+# @qodalis/mcp-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Model Context Protocol](https://modelcontextprotocol.io) server that helps
+[Claude Code](https://code.claude.com) **build [Qodalis CLI](https://cli.qodalis.com) plugins** (docs search, exact API
+declarations, scaffolding) and gives it the commands, files, data explorer, jobs and plugin tools of a running
+Qodalis CLI server through a resilient proxy.
+
+[![npm](https://img.shields.io/npm/v/@qodalis/mcp-cli)](https://www.npmjs.com/package/@qodalis/mcp-cli)
+[![Build & Test](https://github.com/qodalis-solutions/mcp-cli/actions/workflows/build.yml/badge.svg)](https://github.com/qodalis-solutions/mcp-cli/actions/workflows/build.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`mcp-cli` runs on your machine as a stdio MCP server in one of two modes:
+
+- **Developer mode** (no `QCLI_URL`): the [plugin-development tools](#plugin-development) only. No server needed.
+- **Server mode** (`QCLI_URL` set): the same tools plus a proxy to the server's MCP endpoint
+  (`<server>/api/qcli/mcp`): Claude Code sees exactly the server's tools, with the permissions of the account you
+  configure. It handles sign-in, reconnects after network drops and lets you narrow what the assistant may use.
+
+## Where it fits
+
+| Repository                                                                                                                                                                                                                        | Role                                                                                                |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| [web-cli](https://github.com/qodalis-solutions/web-cli)                                                                                                                                                                           | The browser terminal (Angular, React, Vue) and its plugins, including `token create` for API tokens |
+| [cli-server-node](https://github.com/qodalis-solutions/cli-server-node), [cli-server-dotnet](https://github.com/qodalis-solutions/cli-server-dotnet), [cli-server-python](https://github.com/qodalis-solutions/cli-server-python) | The servers that host the MCP endpoint                                                              |
+| [cli-server-dashboard](https://github.com/qodalis-solutions/cli-server-dashboard)                                                                                                                                                 | Admin dashboard served by the servers                                                               |
+| [pwa-cli](https://github.com/qodalis-solutions/pwa-cli)                                                                                                                                                                           | The CLI as a PWA and Android app                                                                    |
+| **mcp-cli**                                                                                                                                                                                                                       | This repository: the bridge from Claude Code to a server                                            |
+
+## Highlights
+
+- **Plugin development built in.** Search the plugin guide, read the exact
+  TypeScript declarations of `@qodalis/cli-core` and scaffold a plugin, with
+  prompts that walk the assistant through a web plugin or a server command.
+- **No tool-specific code.** Tools come from the server's `tools/list` and are
+  passed through unchanged (names, schemas, annotations); calls are forwarded.
+  New commands on the server show up without updating the proxy.
+- **Token or password.** Use an API token (`QCLI_TOKEN`), or sign in with
+  `QCLI_USER` / `QCLI_PASSWORD`; an expired session is renewed automatically on
+  the next call.
+- **Read-only mode** (`QCLI_READ_ONLY=true`) exposes only the tools the server
+  marks read-only, and refuses calls to anything else.
+- **Client-side allow and deny lists** (`QCLI_TOOLS`, `QCLI_EXCLUDE`, trailing
+  `*` allowed) on top of the server's own permissions.
+- **Self-healing connection.** It connects on first use, never caches a failed
+  connect, retries once when the connection drops, and fails fast (8 s) when the
+  server is unreachable, with a message that says what to check.
+- **Clear errors**: a rejected token, MCP not enabled on the server, a missing
+  permission or an unreachable host each come back as one actionable sentence.
+
+## Quick start
+
+For plugin development, nothing else is needed:
+
+```bash
+claude mcp add qcli -- npx -y @qodalis/mcp-cli
+```
+
+Then ask, for example, _"Create a Qodalis CLI plugin that converts temperatures"_ or run the
+`/mcp__qcli__create-web-plugin` prompt. See [Plugin development](#plugin-development).
+
+To also reach a running server, add `QCLI_URL` and credentials as described below.
+
+```bash
+npx -y @qodalis/mcp-cli --help
+```
+
+The server must have MCP enabled (default ports: .NET `8046`, Node `8047`, Python `8048`):
+
+| Server | Enable MCP                                     |
+| ------ | ---------------------------------------------- |
+| Node   | `createCliServer({ mcp: true })`               |
+| Python | `CliServerOptions(mcp=True)`                   |
+| .NET   | `builder.Services.AddCli(cli => cli.AddMcp())` |
+
+Each also takes options (tool allow/deny lists, a static token, instructions); see
+[MCP endpoint](https://cli.qodalis.com/docs/server-integration#mcp-endpoint).
+
+### Claude Code
+
+```bash
+claude mcp add qcli -- npx -y @qodalis/mcp-cli
+```
+
+then set the environment in `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "qcli": {
+      "command": "npx",
+      "args": ["-y", "@qodalis/mcp-cli"],
+      "env": {
+        "QCLI_URL": "http://localhost:8047",
+        "QCLI_TOKEN": "qcli_pat_..."
+      }
+    }
+  }
+}
+```
+
+or sign in with a user name and password instead of a token:
+
+```json
+"env": {
+  "QCLI_URL": "http://localhost:8047",
+  "QCLI_USER": "ops",
+  "QCLI_PASSWORD": "********"
+}
+```
+
+The same in one command, with `-e` flags:
+
+```bash
+claude mcp add qcli -e QCLI_URL=http://localhost:8047 -e QCLI_TOKEN=qcli_pat_... -- npx -y @qodalis/mcp-cli
+```
+
+Add `--scope user` to make it available in every project. With
+`--scope project` the entry goes into the project's `.mcp.json`, which is
+usually committed: keep the secret out of it with
+`"QCLI_TOKEN": "${QCLI_TOKEN}"` and set the variable in your shell. A `.env`
+file works too:
+
+```json
+{ "command": "npx", "args": ["-y", "@qodalis/mcp-cli", "--env-file", "/path/to/.env"] }
+```
+
+Pin a version in shared configs (`@qodalis/mcp-cli@0.2.0`) so an upgrade is a
+deliberate change.
+
+### Getting a token
+
+In the web CLI connected to the server (users plugin), signed in as the account
+the assistant should act as:
+
+```bash
+token create claude --expires=90
+# token create claude --permissions=commands:execute,files:read   (narrower scope)
+```
+
+The token (`qcli_pat_…`) is shown once. Without the web CLI, sign in and create
+one with curl:
+
+```bash
+SESSION=$(curl -s http://localhost:8047/api/v1/qcli/sessions \
+  -H 'Content-Type: application/json' -d '{"username":"ops","password":"..."}' | jq -r .token)
+curl -s http://localhost:8047/api/v1/qcli/tokens -H "Authorization: Bearer $SESSION" \
+  -H 'Content-Type: application/json' -d '{"name":"claude","expiresInDays":90}' | jq -r .token
+curl -s -X DELETE http://localhost:8047/api/v1/qcli/sessions/current -H "Authorization: Bearer $SESSION"
+```
+
+A server **without** the users plugin protects its endpoint with a static token
+(its `mcp.token` option): put that value in `QCLI_TOKEN`. If it sets none, the
+endpoint is open and no auth variable is needed.
+
+## Plugin development
+
+These tools are served locally and work without a server (developer mode) or next to
+a server's tools. Turn them off with `QCLI_DEV_TOOLS=false`.
+
+```bash
+claude mcp add qcli -- npx -y @qodalis/mcp-cli                 # developer mode
+claude mcp add qcli --scope user -- npx -y @qodalis/mcp-cli    # in every project
+```
+
+### Tools
+
+| Tool                   | Arguments                                              | What it does                                                                                                                                                                                                                    |
+| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `qcli_docs_search`     | `query`, `limit?` (default 5, max 20)                  | Ranked topics of the plugin guide as `Section › Topic`, with their summary and an excerpt.                                                                                                                                      |
+| `qcli_docs_read`       | `topic`                                                | A topic in full (heading match, case-insensitive; `Section › Topic` when a heading is in several sections), or a whole section (`Web plugins`). Lists the topics when nothing matches.                                          |
+| `qcli_api`             | `symbol`, `package?` (default `@qodalis/cli-core`)     | The TypeScript declaration of an interface, type, class, function, enum or constant, with its JSDoc and the related declarations to look up next. `package` takes any `@qodalis/*` package (`cli` is short for `@qodalis/cli`). |
+| `qcli_scaffold_plugin` | `name`, `description?`, `processorName?`, `directory?` | Runs `npx -y @qodalis/create-cli-plugin@latest` and returns the created files and next steps. Inside a web-cli checkout it creates `packages/plugins/<name>`; elsewhere a standalone `qodalis-cli-<name>` project.              |
+
+Where the data comes from:
+
+- **Docs**: [`https://cli.qodalis.com/llms-full.txt`](https://cli.qodalis.com/llms-full.txt)
+  (`QCLI_DOCS_URL`), cached for an hour. When it cannot be fetched, the last
+  download is reused, else the snapshot bundled in the package
+  (`docs/llms-full.txt`), so the tools work offline.
+- **API declarations**: the project's `node_modules` (the MCP server's working
+  directory and its parents) when the package is installed there, so the answer
+  matches the version you build against. Otherwise the `latest` version on npm,
+  downloaded from jsDelivr (unpkg as fallback) and cached in memory and in
+  `<tmp>/qodalis-mcp-cli`; offline, the newest cached version is used.
+- **Scaffolding**: validates the name (lowercase letters, digits and hyphens, no
+  `cli-` prefix), refuses an existing target directory, runs without a TTY and
+  stops after 5 minutes. The standalone project installs its dependencies.
+
+### Prompts
+
+| Prompt                  | Arguments                                          | Walks the assistant through                                                                                                             |
+| ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `create-web-plugin`     | `name`, `description`                              | Reading the guide, looking up the contracts with `qcli_api`, scaffolding, implementing the processor and module, tests, registering it. |
+| `create-server-command` | `language` (`node`, `dotnet`, `python`), `command` | Adding a command processor to a Node, .NET or Python server, registering it and testing it.                                             |
+
+In Claude Code they appear as `/mcp__qcli__create-web-plugin` and
+`/mcp__qcli__create-server-command`. The docs topics are also MCP resources
+(`qcli-docs://<section>/<topic>`), which Claude Code can attach with `@`.
+
+### Example requests
+
+- _"Search the Qodalis plugin docs for reading user input."_ → `qcli_docs_search`
+- _"Show me ICliExecutionContext."_ → `qcli_api { "symbol": "ICliExecutionContext" }`
+- _"Which options does CliEngine take?"_ → `qcli_api { "symbol": "CliEngine", "package": "cli" }`
+- _"Scaffold a plugin called json-tools."_ → `qcli_scaffold_plugin { "name": "json-tools" }`
+
+### Filters and read-only mode
+
+The dev tools are tools like any other: `QCLI_TOOLS` and `QCLI_EXCLUDE` apply to
+them (`QCLI_EXCLUDE=qcli_scaffold_plugin`, or `QCLI_TOOLS=qcli_*` for the dev
+tools alone), and `QCLI_READ_ONLY=true` hides and refuses `qcli_scaffold_plugin`
+(the docs and API tools are read-only). A server tool with the same name as a dev
+tool is hidden. When the server is unreachable, `tools/list` still returns the
+dev tools.
+
+## Configuration
+
+Every setting is an environment variable. `QODALIS_CLI_*` names are accepted as
+aliases for every key.
+
+| Variable                  | Default                                 | Description                                                                                                              |
+| ------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `QCLI_URL`                | none                                    | Server base URL, e.g. `https://cli.example.com` (a pasted `…/api/qcli/mcp` URL is accepted). Without it: developer mode. |
+| `QCLI_TOKEN`              | none                                    | API token (`token create` in the web CLI) or the server's static `mcp.token`.                                            |
+| `QCLI_USER`               | none                                    | Sign in with this user name instead of a token (needs `QCLI_PASSWORD`).                                                  |
+| `QCLI_PASSWORD`           | none                                    | Password for `QCLI_USER`. Never logged.                                                                                  |
+| `QCLI_READ_ONLY`          | `false`                                 | Expose and allow only tools annotated `readOnlyHint: true`. See [read-only mode](#read-only-mode).                       |
+| `QCLI_TOOLS`              | all                                     | Comma-separated allow-list of tool names; a trailing `*` matches a prefix (`fs_*`).                                      |
+| `QCLI_EXCLUDE`            | none                                    | Comma-separated deny-list, same syntax, applied after `QCLI_TOOLS`.                                                      |
+| `QCLI_CONNECTION_TIMEOUT` | `8000`                                  | Milliseconds to wait for the TCP/TLS connection before reporting the server unreachable.                                 |
+| `QCLI_REQUEST_TIMEOUT`    | `60000`                                 | Milliseconds a single request (`tools/list`, `tools/call`) may take.                                                     |
+| `QCLI_TRUST_CERT`         | `false`                                 | Accept a self-signed TLS certificate.                                                                                    |
+| `QCLI_ENV_FILE`           | none                                    | Path to a `.env` file (same as `--env-file`). Variables already set in the environment win.                              |
+| `QCLI_DEV_TOOLS`          | `true`                                  | The `qcli_*` plugin-development tools, prompts and docs resources. `false` requires `QCLI_URL`.                          |
+| `QCLI_DOCS_URL`           | `https://cli.qodalis.com/llms-full.txt` | Where the plugin guide is fetched from (falls back to the bundled snapshot).                                             |
+
+Set either `QCLI_TOKEN` or `QCLI_USER` + `QCLI_PASSWORD`, not both.
+
+## Tools
+
+The tools are whatever the server exposes to your account. A typical server
+offers:
+
+| Tools                                                                | Available when                         |
+| -------------------------------------------------------------------- | -------------------------------------- |
+| `server_info`                                                        | always: version, enabled features      |
+| one tool per CLI command (`weather`, `weather_current`, ...)         | always                                 |
+| `fs_list`, `fs_stat`, `fs_read`, `fs_write`, `fs_mkdir`, `fs_delete` | the server's filesystem API is enabled |
+| `data_sources`, `data_schema`, `data_query`                          | the data explorer is enabled           |
+| `jobs_list`, `jobs_get`, `jobs_history`, `jobs_trigger`, ...         | the jobs plugin is installed           |
+| plugin tools                                                         | a server plugin contributes them       |
+
+Each one is limited by the account's permissions on the server (for example
+`commands:execute`, `files:read` / `files:write`, `data:query`, `jobs:manage`),
+and by the token's scope when it was created with `--permissions`.
+
+## Read-only mode
+
+With `QCLI_READ_ONLY=true` the proxy lists only the tools the server annotates
+`readOnlyHint: true` (such as `server_info`, `fs_list`, `fs_read`,
+`data_schema`, `jobs_list`) and refuses calls to any other tool before they
+reach the server. Command tools carry no read-only annotation, so they are
+hidden in this mode; add the ones you want with a separate, non-read-only entry
+and `QCLI_TOOLS`.
+
+The filter is defence in depth. The real boundary is the account: give the
+assistant a user (or a token scope) with only the permissions it should have.
+
+## Several servers
+
+Add one entry per server (and per access level) with a distinct name:
+
+```json
+{
+  "mcpServers": {
+    "qcli-dev": {
+      "command": "npx",
+      "args": ["-y", "@qodalis/mcp-cli"],
+      "env": { "QCLI_URL": "http://localhost:8047", "QCLI_TOKEN": "qcli_pat_dev..." }
+    },
+    "qcli-prod": {
+      "command": "npx",
+      "args": ["-y", "@qodalis/mcp-cli"],
+      "env": {
+        "QCLI_URL": "https://cli.example.com",
+        "QCLI_TOKEN": "qcli_pat_prod...",
+        "QCLI_READ_ONLY": "true"
+      }
+    },
+    "qcli-prod-jobs": {
+      "command": "npx",
+      "args": ["-y", "@qodalis/mcp-cli"],
+      "env": {
+        "QCLI_URL": "https://cli.example.com",
+        "QCLI_TOKEN": "qcli_pat_prod...",
+        "QCLI_TOOLS": "jobs_*,server_info",
+        "QCLI_EXCLUDE": "jobs_cancel"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+`claude mcp list` shows whether each server connects; inside a session `/mcp`
+shows its status and tools and lets you reconnect. The proxy logs to stderr
+(`claude --debug` shows it).
+
+| Message                                                                       | What to do                                                                                                                                                |
+| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `… answered 401 (not authenticated): QCLI_TOKEN is wrong, expired or revoked` | Create a new token (`token create claude`) and update `QCLI_TOKEN`. `token list` in the web CLI shows expiry dates.                                       |
+| `… rejected QCLI_USER / QCLI_PASSWORD`                                        | Check the credentials; the account may be disabled or locked out after failed sign-ins.                                                                   |
+| `… answered 403 …`                                                            | The account lacks `commands:execute`, or the server rejected the request origin.                                                                          |
+| `MCP is not enabled on this server (enable the mcp option)`                   | Turn on the server's `mcp` option and restart it; check `QCLI_URL` (base URL, not a page of the web app).                                                 |
+| `Cannot reach … Check QCLI_URL / VPN.`                                        | The server is down, the URL or port is wrong, or the VPN is disconnected. Retry the call once it is back: the proxy reconnects by itself.                 |
+| `… did not answer within 60000 ms`                                            | A slow command; raise `QCLI_REQUEST_TIMEOUT`.                                                                                                             |
+| A tool is missing                                                             | The account (or token scope) lacks its permission, the feature is not enabled on the server, or `QCLI_READ_ONLY` / `QCLI_TOOLS` / `QCLI_EXCLUDE` hide it. |
+| `Nothing to serve: set QCLI_URL …` at startup                                 | `QCLI_DEV_TOOLS=false` without `QCLI_URL`: set the URL (check the variable name; `npx -y @qodalis/mcp-cli --help` lists every variable).                  |
+| Only the `qcli_*` tools are listed                                            | No `QCLI_URL` (developer mode), or the server is unreachable: the log says which.                                                                         |
+
+## How reconnection works
+
+1. The proxy connects to the endpoint on the first `tools/list` or
+   `tools/call`, not at startup, so Claude Code starts even when the server is
+   down.
+2. A failed connect is not cached: the next call tries again.
+3. A connection-level error (refused, reset, socket closed, DNS failure) drops
+   the connection and retries the request once on a fresh one. A connect timeout
+   is not retried, so an unreachable host fails within `QCLI_CONNECTION_TIMEOUT`.
+4. With `QCLI_USER` / `QCLI_PASSWORD`, a 401 signs in again and retries once.
+5. The tool list is cached for 60 s; a call to a tool the proxy does not know
+   yet refreshes it first, so new server commands work without a restart.
+
+## Security notes
+
+- Tokens and passwords are read from the environment, sent only to `QCLI_URL`,
+  and never written to logs or tool results.
+- Prefer an API token with a narrow `--permissions` scope and an expiry over a
+  password; revoke it with `token revoke <id>` when it is no longer needed.
+- Use `https://` for anything but `localhost`. `QCLI_TRUST_CERT=true` disables
+  certificate verification for this process; use it only for self-signed
+  certificates you control.
+- Nothing is written to stdout except the MCP protocol stream.
+
+See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
+
+## Library use
+
+The pieces are exported for embedding:
+
+```ts
+import { createProxyServer, loadConfig, RemoteServer } from '@qodalis/mcp-cli';
+
+const config = loadConfig(process.env);
+const remote = new RemoteServer(config, { clientInfo: { name: 'my-app', version: '1.0.0' } });
+const server = createProxyServer(remote, config); // a low-level MCP Server: connect any transport
+```
+
+With the plugin-development tools (`remote` may be `undefined` for developer mode):
+
+```ts
+import { createProxyServer, DevTools, loadConfig } from '@qodalis/mcp-cli';
+
+const config = loadConfig(process.env);
+const server = createProxyServer(undefined, config, { dev: new DevTools(config) });
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test             # unit tests and stdio end-to-end tests against a fake server (build first)
+npm run typecheck
+npm run check-format
+npm run dev -- --env-file .env   # run from source
+npm run sync-docs                # refresh docs/llms-full.txt: a path/URL argument, else generated by ../web-cli/tools/build-llms.js, else the site
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © Qodalis Solutions SRL

package/dist/src/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":""}

package/dist/src/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { ConfigError, describeConfig, ENV_FILE_VARIABLES, loadConfig } from './config.js';
+import { DevTools } from './dev/tools.js';
+import { applyEnvFile } from './env-file.js';
+import { RemoteServer } from './remote.js';
+import { createProxyServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+const SHUTDOWN_GRACE_MS = 5000;
+const usage = `Plugin-development tools for Qodalis CLI (docs search, API declarations, plugin
+scaffolding) and a proxy to a Qodalis CLI server's MCP endpoint (<QCLI_URL>/api/qcli/mcp).
+Without QCLI_URL it runs in developer mode: only the plugin-development tools.
+Configuration is read from the environment (QCLI_* or QODALIS_CLI_* names):
+  QCLI_URL                         server base URL, e.g. http://localhost:8047 (optional)
+  QCLI_TOKEN                       API token (token create in the web CLI) or the server's mcp token
+  QCLI_USER, QCLI_PASSWORD         sign in with a password instead (signs in again on 401)
+  QCLI_READ_ONLY (false)           only tools the server marks read-only
+  QCLI_TOOLS                       comma-separated allow-list of tool names (trailing * allowed)
+  QCLI_EXCLUDE                     comma-separated deny-list, applied after QCLI_TOOLS
+  QCLI_CONNECTION_TIMEOUT (8000 ms)  QCLI_REQUEST_TIMEOUT (60000 ms)
+  QCLI_TRUST_CERT (false)          accept a self-signed TLS certificate
+  QCLI_ENV_FILE                    path to a .env file (same as --env-file)
+  QCLI_DEV_TOOLS (true)            the qcli_* plugin-development tools, prompts and docs resources
+  QCLI_DOCS_URL                    plugin docs (default https://cli.qodalis.com/llms-full.txt)
+`;
+const log = (message) => {
+    // Anything written to stdout corrupts the JSON-RPC stream: all logging goes to stderr.
+    process.stderr.write(`[${SERVER_NAME}] ${message}\n`);
+};
+const parseArgs = (argv) => {
+    const result = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--help' || arg === '-h') {
+            process.stdout.write(`Usage: mcp-cli [--env-file <path>] [--help] [--version]\n\n${usage}`);
+            process.exit(0);
+        }
+        if (arg === '--version' || arg === '-v') {
+            process.stdout.write(`${SERVER_VERSION}\n`);
+            process.exit(0);
+        }
+        if (arg === '--env-file') {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new ConfigError('--env-file requires a path.');
+            }
+            result.envFile = value;
+            i++;
+            continue;
+        }
+        throw new ConfigError(`Unknown argument "${arg}".`);
+    }
+    return result;
+};
+const main = () => {
+    try {
+        const args = parseArgs(process.argv.slice(2));
+        const envFile = args.envFile ?? ENV_FILE_VARIABLES.map((name) => process.env[name]).find(Boolean);
+        if (envFile) {
+            applyEnvFile(envFile, process.env);
+        }
+        const config = loadConfig(process.env);
+        if (config.trustCert) {
+            log('QCLI_TRUST_CERT=true: TLS certificates are not verified');
+        }
+        if (!config.url && config.auth.kind !== 'none') {
+            log('QCLI_TOKEN / QCLI_USER are set but QCLI_URL is not: no server is used');
+        }
+        const remote = config.url
+            ? new RemoteServer(config, {
+                clientInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+                log,
+            })
+            : undefined;
+        const dev = config.devTools ? new DevTools(config, { log }) : undefined;
+        const handle = serveStdio(() => createProxyServer(remote, config, { dev, log }), {
+            onerror: (error) => log(`transport error: ${error.message}`),
+        });
+        log(`v${SERVER_VERSION} ready for ${describeConfig(config)}${remote ? '; connects on first use' : ''}`);
+        let shuttingDown = false;
+        const shutdown = async (reason) => {
+            if (shuttingDown) {
+                return;
+            }
+            shuttingDown = true;
+            log(`shutting down (${reason})`);
+            setTimeout(() => process.exit(0), SHUTDOWN_GRACE_MS).unref();
+            await handle.close().catch(() => undefined);
+            await remote?.close();
+            process.exit(0);
+        };
+        process.once('SIGINT', () => void shutdown('SIGINT'));
+        process.once('SIGTERM', () => void shutdown('SIGTERM'));
+        process.stdin.once('end', () => void shutdown('stdin closed'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`fatal: ${message}`);
+        process.exit(1);
+    }
+};
+main();
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/config.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Environment-driven configuration. Primary names use `QCLI_`; `QODALIS_CLI_`
+ * is accepted as an alias for every key.
+ */
+export type Env = Record<string, string | undefined>;
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/** How the proxy authenticates to the Qodalis CLI server. */
+export type AuthConfig = {
+    kind: 'none';
+} | {
+    kind: 'token';
+    token: string;
+} | {
+    kind: 'password';
+    password: string;
+    user: string;
+};
+export type Config = {
+    auth: AuthConfig;
+    connectionTimeoutMs: number;
+    /** Expose the local plugin-development tools and prompts (`qcli_*`) */
+    devTools: boolean;
+    /** Where the plugin-development docs (`llms-full.txt`) are fetched from */
+    docsUrl: string;
+    /** Client-side deny-list (trailing `*` allowed), applied after `tools` */
+    exclude: string[];
+    /** Expose and allow only tools annotated `readOnlyHint: true` */
+    readOnly: boolean;
+    requestTimeoutMs: number;
+    /** Client-side allow-list (trailing `*` allowed); empty = every tool */
+    tools: string[];
+    /** Accept self-signed TLS certificates */
+    trustCert: boolean;
+    /**
+     * Server base URL, e.g. `https://cli.example.com` (no trailing slash). Without it
+     * the process runs in developer mode: only the local plugin-development tools.
+     */
+    url: string | undefined;
+};
+export declare const DEFAULT_DOCS_URL = "https://cli.qodalis.com/llms-full.txt";
+export declare const PREFIXES: string[];
+/** `QCLI_<suffix>` plus the `QODALIS_CLI_<suffix>` alias. */
+export declare const names: (suffix: string) => string[];
+export declare const ENV_FILE_VARIABLES: string[];
+export type EnvReader = {
+    boolean: (names: string[], fallback: boolean) => boolean;
+    list: (names: string[]) => string[];
+    optional: (names: string[]) => string | undefined;
+    positiveInteger: (names: string[], fallback: number) => number;
+    required: (names: string[]) => string;
+};
+/** Typed readers over an environment map; the first non-empty name wins. */
+export declare const createEnvReader: (env: Env) => EnvReader;
+export declare const normalizeUrl: (input: string) => string;
+export declare const loadConfig: (env?: Env) => Config;
+/** One-line summary for the startup log (never contains secrets). */
+export declare const describeConfig: (config: Config) => string;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAErD,qBAAa,WAAY,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI9B;AAED,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,MAAM,MAAM,MAAM,GAAG;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iEAAiE;IACjE,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,gBAAgB,0CAA0C,CAAC;AAExE,eAAO,MAAM,QAAQ,UAA0B,CAAC;AAEhD,6DAA6D;AAC7D,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,MAAM,EAAqD,CAAC;AAEnG,eAAO,MAAM,kBAAkB,UAAoB,CAAC;AAKpD,MAAM,MAAM,SAAS,GAAG;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;IACzD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IACpC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,GAAG,SAAS,CAAC;IAClD,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/D,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;CACzC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,eAAe,GAAI,KAAK,GAAG,KAAG,SAoD1C,CAAC;AAmBF,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAI5C,CAAC;AAqBF,eAAO,MAAM,UAAU,GAAI,MAAK,GAAiB,KAAG,MAwBnD,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,MAmB/C,CAAC"}