Skip to main content
Glama
README.md
# 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](https://github.com/modelcontextprotocol/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](https://docs.astral.sh/uv/).
This project is currently local-only and not yet published.
The qkrun runtime is installed from PyPI.

```bash
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.

## Client migration

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

```json
{
  "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](docs/usage.rst) 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](https://gofastmcp.com/docs/getting-started/welcome),
[official SDK](https://github.com/modelcontextprotocol/python-sdk),
[FastMCP releases](https://pypi.org/project/fastmcp/#history),
[SDK releases](https://pypi.org/project/mcp/#history).
[SDK 2.3.0 release](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0),
[official v2 migration guide](https://py.sdk.modelcontextprotocol.io/migration/).

## Development

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

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