mcptask-rails-runner
Rails distribution of the mcptask.online autonomous
runner, and the way a Rails app installs it. A thin Ruby wrapper around the
mcptask_runner Go binary: the gem ships the platform-specific binary inside
itself (libexec/) and exposes the same rake tasks as the legacy
mcptask_runner gem, delegating 1:1 to the CLI.
The legacy gem is retired. It gets critical fixes only, and it stays in
existence as the reference implementation the Go runner's conformance suite
measures against; everything new is written in Go. What you gain by moving:
Linux and Windows hosts, a scheduled job with no bundler in its path, and a
handful of places where the old implementation was simply wrong (its token
resolution read a different half of .mcp.json in each of three places, and
its stream reader died mid-run on an API error envelope).
One gem version carries exactly one binary version — mcptask-rails-runner X.Y.Z contains the binary from the vX.Y.Z release of
jchsoft/mcptask-releases.
mcptask_runner:install and :update copy that binary out of the gem to
~/.mcptask/bin/mcptask_runner and run it from there. The scheduled job runs
that copy, because a job pointing inside a gem directory dies at the next
bundle update — at 08:00, in a log nobody reads. So the pin is per project:
the Gemfile decides what a foreground rake mcptask_runner:* runs, while the
machine has one installed binary however many projects it carries, and the
newest version any of them offers is the one that stays. Install and update
print which version they wrote, and never replace a newer installed binary
with an older one.
Requirements
- Ruby >= 3.0, Rails >= 6.0
- One of Claude Code, Codex CLI or OpenCode, signed in by the machine owner — picked per project at install time (
--cli below; Codex and OpenCode need their own login on top of the runner account)
- An mcptask.online account
Installation
# Gemfile
gem "mcptask-rails-runner"
bundle install
bundle exec rake mcptask_runner:install
Migrating from the legacy mcptask_runner gem
The rake surface is identical — the migration is one Gemfile line:
- gem "mcptask_runner", git: "[email protected]:jchsoft/mcptask_runner.git"
+ gem "mcptask-rails-runner"
Then:
bundle install
FORCE=1 bundle exec rake mcptask_runner:install
Re-running install is what regenerates the scheduled job. The legacy launcher
runs bundle exec rake and logs the active version by grepping Gemfile.lock
for the old gem name — neither survives the rename, so a job left as it is
keeps working but stops recording what it ran. The regenerated one execs
~/.mcptask/bin/mcptask_runner directly, with no bundler in the 08:00 path.
Every rake mcptask_runner:* invocation and shell alias keeps working
unchanged. Your existing
config/mcptask_runner.yml, .mcp.json and .claude/ setup are read by the
Go binary as-is — with one exception: a project without a harness: line is
now refused by name (no silent default), and mcptask_runner:update will write
harness: claude once for a legacy .mcp.json-style install so the host gets
through the gate on the next run. The only legacy task without a counterpart is
mcptask_runner:prepare:permissions — permission sync is part of
mcptask_runner:install now.
Picking the coding CLI and the git host
mcptask_runner:install delegates to mcptask_runner init, which takes the
harness choice and the git host as flags. Both reach the binary through the
rake task in two equivalent ways — choose whichever fits how the command is
invoked:
# Square-bracket form — works inside a Procfile or a CI step:
bundle exec rake "mcptask_runner:install[--cli codex]"
bundle exec rake "mcptask_runner:install[--cli codex,--git-host bitbucket]"
# Environment form — what an operator types at the shell, where a one-line
# override (CLI=opencode rake …) is easier than retyping the rake args:
CLI=codex GIT_HOST=bitbucket bundle exec rake mcptask_runner:install
Env wins on a tie. update does not take flags — re-run install with the
ones you want.
Tasks
| Task | Delegates to |
|---|
mcptask_runner:install | mcptask_runner init [--cli <name>] [--git-host <name>] (from ~/.mcptask/bin) |
mcptask_runner:update | mcptask_runner update (from ~/.mcptask/bin) |
mcptask_runner:bug_report | mcptask_runner bug-report |
mcptask_runner:version | mcptask_runner version |
mcptask_runner:manual:once (once_dry, today, daily, review, reviews, workflow, queue) | mcptask_runner run <mode> |
mcptask_runner:manual:story[123] / manual:task[123] | run story_manual --story-id 123 / run task_manual --task-id 123 |
mcptask_runner:auto:once | run once_auto_squash |
mcptask_runner:auto:squash:today (queue, story[123], task[123]) | run <mode>_auto_squash |
verbose=true and ignore_quota=true environment variables are honored by
the binary itself, exactly as before.
install and update print one line before handing the process over, and it
is coloured the way the binary colours everything after it: green when the
install left the machine where it already was, yellow when a binary the host
was running has just been replaced or when the version on disk was kept
instead. Only at a terminal — a pipe, a redirect and CI get the plain text
they always got. NO_COLOR turns it off, and MCPTASK_RUNNER_COLOR (1 /
0) answers it either way, ahead of NO_COLOR. The binary reads the same two
variables.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
