Skip to main content
Glama

qkrun-mcp

Standalone MCP stdio server for qkrun tasks. It exposes list_tasks and run_task, with live stdout/stderr notifications, using the official MCP Python SDK. The SDK owns framing, initialization, transport, protocol validation, and error responses. Tool arguments are validated with jsonschema; this project does not implement the MCP protocol.

Local setup

Requires Python 3.12+ and uv. This project is currently local-only and not yet published. The qkrun runtime is installed from PyPI.

cd ~/projects/qkrun-mcp
uv sync --dev
uv run qkrun-mcp --help
uv run qkrun-mcp --project myapp:/absolute/path/to/myapp/_qk

Built wheels declare the portable qkrun>=2.1,<3 dependency and never embed local source paths.

Related MCP server: Codex Control Plane MCP

Client migration

qkrun 2.1 removes its bundled MCP server. Point your client's stdio command at the standalone qkrun-mcp executable instead:

{
  "mcpServers": {
    "qkrun": {
      "command": "/absolute/path/to/qkrun-mcp/.venv/bin/qkrun-mcp",
      "args": ["--project", "myapp:/absolute/path/to/myapp/_qk"]
    }
  }
}

On Windows the executable is .venv/Scripts/qkrun-mcp.exe. Replace python -m qkrun.mcp with qkrun-mcp or python -m qkrun_mcp.server using the new environment's Python. --version now reports the standalone server version, not the runner version. Server diagnostic logging goes to stderr by default (or --log-file), never the MCP stdio output.

Tool names, parameters, text JSON results, structured results, stdout/stderr streaming, stdin, timeouts, project aliases/paths, TOML/JSON config precedence, and CWD-based discovery are preserved. list_tasks returns a JSON array (structured content wraps it as {"result": [...]}); run_task returns {"exit_code": 0, "stdout": "...", "stderr": "..."}. Tool errors are surfaced as SDK tool errors, and invalid arguments are rejected by jsonschema validation before execution. See usage and tool reference for the complete configuration/API.

SDK 2.3 supports both legacy initialization and modern 2026-07-28 connections. MCP logging is deprecated by SEP-2577, but retained here to preserve streamed stdout/stderr; the SDK emits MCPDeprecationWarning on these supported paths. On modern connections clients must opt into logging per request; the SDK's Client(..., logging_callback=..., log_level="info") handles that opt-in. Transport and logging negotiation remain SDK-managed.

qkrun integration boundary

The server owns its CLI parser and standard-library logging configuration. It reuses qkrun._launcher.Launcher for project discovery and executable resolution rather than duplicating qkrun's launcher logic. This is an internal qkrun API. Discovery searches ancestors for _qk/ or _qk.py; executable precedence is _qk virtual environments, project-root virtual environments, then QK_EXECUTABLE. For standalone _qk.py modules, the server creates a temporary package wrapper so qkrun can cache task metadata; the wrapper is removed when the server exits.

The boundary for task execution/metadata is the CLI: prefer each project's local qk, invoke qk :list --json for metadata, and fall back to sys.executable -m qkrun in the project root. Subprocesses set QK_LAUNCHER_RUNNING=true to prevent launcher recursion. Explicit module paths are normalized to absolute paths before changing the subprocess directory. The installed runner must support :list --json (qkrun 2.1+). Tasks execute arbitrary project code: only register projects you trust.

Dependency choice

The user approved replacing FastMCP with the official SDK before dependency changes. Counts below include the named root package, its extras and transitive runtime dependencies, exclude development packages, and include conditional packages across platforms. Counts are not vulnerability findings.

Resolution

Packages

Original qkrun checked-in uv.lock, FastMCP 3.4.2 closure

71

Fresh compatible FastMCP 3.x resolution (3.4.11)

70

Fresh current FastMCP 4.x resolution (4.2.0)

64

Fresh current official SDK 2.x resolution (mcp 2.3.0)

30

Original qkrun runtime including bundled MCP

77

Updated qkrun runtime without MCP

11

Standalone qkrun-mcp runtime, including qkrun 2.1 and SDK 2.3.0

39

Baseline: qkrun commit 7e8f3fd9276233955d713166d2ec5a015dfc82d7. Fresh comparisons used uv pip compile --python-version 3.12 --universal with fastmcp>=3.4,<4, fastmcp>=4.2,<5, and mcp>=2.3,<3, respectively. The server uses the current SDK major (mcp>=2.3,<3); its lock resolves 2.3.0, released on 2026-10-02 according to both official GitHub and PyPI metadata. The dependency comparison and lock counts were rechecked on 2026-11-15.

Both projects are maintained: FastMCP is a full framework maintained by Prefect; the official SDK is maintained by the MCP project. FastMCP adds useful automatic schema generation, dependency injection, and client utilities but brings a larger tree (authentication, keyring, file storage, CLI/watch facilities). For this two-tool stdio server the official low-level SDK avoids that framework layer at the cost of explicit tool schemas, dispatch, argument validation, and request logging. The v2 API uses constructor on_* handlers, explicit request contexts, snake-case SDK fields, and full SDK result objects. Since v2 no longer automatically validates low-level tool arguments, jsonschema is an explicit direct dependency (already part of the SDK's runtime closure); expected application failures are returned as SDK error-flagged tool results. The SDK still includes HTTP/authentication dependencies even for stdio; no claim is made that this eliminates vulnerability maintenance.

The runner constrains Watchdog to 6.x: native macOS watcher regression tests failed or hung after upgrading to 7.1, while all 44 passed with 6.0.0. Other compatible dependencies and both lockfiles have been refreshed.

Sources: FastMCP, official SDK, FastMCP releases, SDK releases. SDK 2.3.0 release, official v2 migration guide.

Development

uv sync --dev --locked
uv run python -m pytest
uv run ruff check .
uv run ruff format --check .
uv build

Available Tools

2 tools
list_tasksA
Read-only

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.

Inputs: filter, project.

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.

Inputs: task_name (required), args, stdin, project, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    Both names follow the same verb_noun snake_case pattern (list_tasks, run_task), using the shared 'task' noun. Fully predictable and consistent.

    Tool Count3/5

    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.

    Completeness3/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers