qkrun-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PROJECT | No | Project alias and path supplied via the `--project` CLI option, in the form `alias:/absolute/path/to/_qk` (e.g. `--project myapp:/absolute/path/to/myapp/_qk`). May be repeated for multiple projects; when omitted, projects are discovered by searching ancestors of the CWD for `_qk/` or `_qk.py`. | |
| LOG_FILE | No | Path supplied via the `--log-file` CLI option for server diagnostic logging. Defaults to stderr; MCP stdio output is never used for logging. | |
| QK_EXECUTABLE | No | Path to the qk executable, used as the last-resort fallback after `_qk` virtual environments and project-root virtual environments during executable resolution. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Exposes qkrun project tasks defined in _qk/. Always call list_tasks first to discover available tasks and their required arguments, then use run_task to execute them. Pass 'project' to target a specific project when the server manages multiple projects.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| logging | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_tasksA | Discover available non-private tasks and their arguments. Returns project, project_root and tasks for every project, or only the selected project. Filter by invocation name or alias. |
| run_taskB | Execute a discovered task in a subprocess. Streams stdout as info and stderr as warning notifications; returns exit_code, stdout and stderr. Supply stdin for interactive input. Select project when multiple projects are registered. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 2 tools
The two tools map cleanly to a discover-then-execute workflow with no overlap: list_tasks only reads metadata, run_task only executes. An agent can unambiguously pick the right tool from the description.
Both names follow the same verb_noun snake_case pattern (list_tasks, run_task), using the shared 'task' noun. Fully predictable and consistent.
Two tools is thin but coherent for a narrow task-runner domain; there is no padding. However, with only a discovery and an execution tool, the surface feels minimal rather than well-scoped.
Core flow (discover tasks and their arguments, then run with stdin/stdout/stderr handling) is covered. Gaps remain: no way to cancel or kill a running task, check status of in-flight runs, or inspect a task's schema beyond the listing.