mcp-cli
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| QCLI_URL | Yes | Server base URL, e.g. https://cli.example.com (a pasted …/api/qcli/mcp URL is accepted). | |
| QCLI_USER | No | Sign in with this user name instead of a token (needs QCLI_PASSWORD). | |
| QCLI_TOKEN | No | API token (`token create` in the web CLI) or the server's static mcp.token. | |
| QCLI_TOOLS | No | Comma-separated allow-list of tool names; a trailing * matches a prefix (fs_*). | all |
| QCLI_EXCLUDE | No | Comma-separated deny-list, same syntax, applied after QCLI_TOOLS. | |
| QCLI_ENV_FILE | No | Path to a .env file (same as --env-file). Variables already set in the environment win. | |
| QCLI_PASSWORD | No | Password for QCLI_USER. Never logged. | |
| QCLI_READ_ONLY | No | Expose and allow only tools annotated readOnlyHint: true. See read-only mode. | false |
| QCLI_TRUST_CERT | No | Accept a self-signed TLS certificate. | false |
| QCLI_REQUEST_TIMEOUT | No | Milliseconds a single request (tools/list, tools/call) may take. | 60000 |
| QCLI_CONNECTION_TIMEOUT | No | Milliseconds to wait for the TCP/TLS connection before reporting the server unreachable. | 8000 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| qcli_docs_searchA | Search the Qodalis CLI plugin-development guide (web plugins, server plugins, recipes). Returns the best matching topics as "Section › Topic" with their summary and an excerpt; read one in full with qcli_docs_read. |
| qcli_docs_readA | Read a topic of the Qodalis CLI plugin-development guide in full (markdown with code samples). Pass a topic heading (case-insensitive), "Section › Topic" when a heading exists in several sections, or a section name ("Web plugins") for the whole section. Lists the topics when nothing matches. |
| qcli_apiA | TypeScript declaration (with JSDoc) of an interface, type, class, function, enum or constant from the published @qodalis packages: the project's node_modules when installed, else the latest version on npm. Use it for exact member names and signatures, e.g. ICliCommandProcessor, ICliExecutionContext, ICliModule, ICliInputReader, CliProcessCommand. |
| qcli_scaffold_pluginA | Create a new web CLI plugin with @qodalis/create-cli-plugin (npx): processor, module, build config and tests. Inside a web-cli checkout it goes to packages/plugins/; elsewhere to a standalone qodalis-cli- project with its dependencies installed. Returns the created files and next steps. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| create-web-plugin | Create a Qodalis web CLI plugin (a command for the browser terminal): scaffold, implement, test and register it. |
| create-server-command | Add a command to a Qodalis CLI server (Node, .NET or Python) that the web terminal runs remotely. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| Overview › Web plugins vs server plugins | A Qodalis CLI command is either a web plugin running in the browser or a server plugin running in a CLI server; the user types both in the same terminal. |
| Overview › Packages | The npm, NuGet and PyPI packages a plugin author uses, by role. |
| Web plugins › Scaffolding a web plugin with create-cli-plugin | `@qodalis/create-cli-plugin` generates a ready-to-build web plugin, either standalone (its own npm project) or inside the web-cli monorepo. |
| Web plugins › ICliModule | `ICliModule` (from `@qodalis/cli-core`) is the unit a web plugin exports: it bundles command processors, services, guards, permissions and translations, plus lifecycle hooks. |
| Web plugins › ICliCommandProcessor | `ICliCommandProcessor` is the interface every web command implements; only `command` and `processCommand` are required. |
| Web plugins › CliProcessCommand and argument parsing | `CliProcessCommand` is the parsed command passed to `processCommand`: words, flags, positional values and piped data. |
| Web plugins › Parameters | `ICliCommandParameterDescriptor` declares a flag: name, aliases, type, required, default (help only) and an optional validator. |
| Web plugins › Sub-commands | Sub-commands are nested processors in `processors`; the engine walks the command words down the tree and runs the deepest match. |
| Web plugins › Processor metadata, access control and permissions | `metadata` (`CliProcessorMetadata`) flags how the engine treats a processor: sealing, visibility, server requirement, version requirements and access control. |
| Web plugins › Command guards | An `ICliCommandGuard` runs before every command (across all modules) and can block it; contribute guards through `ICliModule.guards`. |
| Web plugins › ICliExecutionContext | `ICliExecutionContext` is the second argument of `processCommand`: the command's access to the terminal, input, state, services, HTTP and process control. |
| Web plugins › Writer API | `context.writer` (`ICliTerminalWriter`) writes text, colors, tables, lists, JSON, boxes and links to the terminal. |
| Web plugins › Input reader | `context.reader` (`ICliInputReader`) shows interactive prompts; every method resolves `null` when the user aborts (Ctrl+C or Escape). |
| Web plugins › State store and persistence | Each root processor gets its own state store (`context.state`) configured by `stateConfiguration`; sub-commands share their root's store. |
| Web plugins › Configuration options | `configurationOptions` exposes processor settings in the built-in `configure` command (interactive menu and `configure get/set`). |
| Web plugins › Services and dependency injection | Modules register services with `services: CliProvider[]`; commands resolve them from `context.services` by token. |
| Web plugins › Translations (i18n) | Plugins ship translations in `ICliModule.translations` and translate at runtime with `context.translator.t(key, englishDefault, params?)`. |
| Web plugins › HTTP client | `context.http` (`ICliHttpClient`) is a fetch wrapper that parses JSON, throws `CliHttpError` on non-2xx and aborts on Ctrl+C. |
| Web plugins › Background services and jobs | `context.backgroundServices` runs daemons (long-lived) and jobs (one-shot) outside the command, on the main thread or in a Web Worker. |
| Web plugins › Full-screen mode and raw input | A processor can take over the terminal (games, editors, pagers) with `enterFullScreenMode`, receiving every keystroke in `onData`. |
| Web plugins › Touch keys for full-screen commands (controls) | A full-screen command lists the keys it reads in `controls`, so phones (which have no Ctrl, Esc or arrow keys) can show them as buttons. |
| Web plugins › Extending an existing command | Set `extendsProcessor = true` to wrap a processor registered with the same `command` and delegate to `originalProcessor`. |
| Web plugins › Registering a module in a host app | Hosts pass plugin modules to the terminal: Angular DI or `[modules]`, React/Vue `modules` prop, or `CliEngine.registerModule` in plain TypeScript. |
| Web plugins › Runtime installation with pkg add (UMD) | Published plugins can be installed in a running terminal with `pkg add @qodalis/cli-<name>`, which loads the plugin's IIFE bundle and boots its module. |
| Web plugins › Testing with CliTestHarness | `CliTestHarness` (from `@qodalis/cli`) runs commands through the real parser and executor without xterm or DOM, capturing output. |
| Web plugins › Building and publishing a web plugin | Web plugins build with tsup into CJS, ESM, type declarations and an IIFE bundle for runtime loading, then publish to npm. |
| Web plugins › Conventions for web plugins | Naming, structure and API-version rules that official and third-party web plugins follow. |
| Server plugins › How server commands reach the browser terminal | A server plugin registers command processors in a Qodalis CLI server (Node, .NET or Python); the browser terminal discovers them and proxies execution over HTTP. |
| Server plugins › Node: minimal server processor | A Node server command extends `CliCommandProcessor` from `@qodalis/cli-server-abstractions` and returns its output text from `handleAsync`. |
| Server plugins › Node: parameters, sub-commands and modules | Node server commands declare flags with `CliCommandParameterDescriptor`, nest sub-commands in `processors`, and are grouped into a `CliModule` registered with `builder.addModule`. |
| Server plugins › Node: structured and streaming output | Node processors return tables, lists, JSON and key-value output from `handleStructuredAsync`, or stream outputs over SSE with `handleStreamAsync`. |
| Server plugins › Node: permissions and MCP tools | Node processors declare `requiredPermissions`; every command automatically becomes an MCP tool when MCP is on, and plugins can add custom tools with an `McpToolProvider`. |
| Server plugins › Node: testing server processors | Node server processors are tested with Vitest, by calling `handleAsync` directly or through the HTTP API with Supertest. |
| Server plugins › .NET: minimal server processor | A .NET server command derives from `Qodalis.Cli.CliCommandProcessor` (interface `ICliCommandProcessor` in `Qodalis.Cli.Abstractions`) and returns text from `HandleAsync`. |
| Server plugins › .NET: parameters, sub-commands and modules | .NET server commands declare flags with `CliCommandParameterDescriptor` object initializers, nest sub-commands in `Processors`, and group them in a `CliModule` registered with `cli.AddModule`. |
| Server plugins › .NET: structured and streaming output | .NET processors return structured output by explicitly implementing `ICliCommandProcessor.HandleStructuredAsync` with `CliResponseBuilder`, and stream with `ICliStreamCommandProcessor`. |
| Server plugins › .NET: permissions and MCP tools | .NET processors declare `RequiredPermissions`; with `cli.AddMcp()` every command is an MCP tool, and plugins add tools by registering an `IMcpToolProvider`. |
| Server plugins › .NET: testing server processors | .NET server processors are tested with xUnit by building a `CliCommandRegistry` and `CliCommandExecutorService` directly. |
| Server plugins › Python: minimal server processor | A Python server command subclasses `CliCommandProcessor` from `qodalis_cli_server_abstractions` and returns text from `async handle_async(command, cancellation_event=None)`. |
| Server plugins › Python: parameters, sub-commands and modules | Python server commands declare flags with `CliCommandParameterDescriptor`, nest sub-commands in `processors`, and are grouped into a `CliModule` registered with `builder.add_module`. |
| Server plugins › Python: structured and streaming output | Python processors return structured output by overriding `handle_structured_async` with `CliResponseBuilder`, and stream by also implementing `ICliStreamCommandProcessor`. |
| Server plugins › Python: permissions and MCP tools | Python processors declare `required_permissions`; with `mcp=True` every command is an MCP tool, and plugins add tools by registering an `IMcpToolProvider` on `result.mcp`. |
| Server plugins › Python: testing server processors | Python server processors are tested with pytest (`asyncio_mode = "auto"`), calling `handle_async` directly or through `CliCommandExecutorService`. |
| Recipes › Recipe: a complete web plugin end to end | Build, test and register a `dice` web plugin (`dice roll --sides 20 --count 2`) from scaffold to host app. |
| Recipes › Recipe: a server command used from the browser terminal | Add a `sysinfo` command to a Node CLI server and run it from a web terminal configured with that server. |
| Recipes › Recipe: a web plugin with an interactive prompt | A `signup` web command that asks for a name, a plan, extra options and confirmation, handling Ctrl+C at every step. |
TDQS
Scored across 4 tools
Each tool targets a distinct need: docs discovery (search), docs consumption (read), type/signature lookup (api), and project creation (scaffold). The search/read pair is explicitly linked in the descriptions ('read one in full with qcli_docs_read', 'Lists the topics when nothing matches'), so the boundary is unambiguous.
All tools share a consistent qcli_ prefix and lowercase snake_case, which makes the family instantly recognizable. The component ordering varies (qcli_docs_search is noun_verb, qcli_scaffold_plugin is verb_noun) and qcli_api is a bare noun, a minor inconsistency but still readable.
Four tools is a lean but justified surface for a docs-plus-scaffolding helper: one search, one read, one API reference, one generator, with no redundancy. It is on the thin side since there is no tool for exercising or validating what you build, but every tool earns its place.
Documentation retrieval (search + read) and API introspection are fully covered, but the lifecycle stops at creation: there is no tool to build, run, test, or inspect an existing plugin/project, and no way to list available recipes or installed plugins except indirectly through search. Agents will hit a dead end after scaffolding, having to fall back on shell commands.