README
¶
just-mcp-work
Just work with your workspace — over MCP.
Your coding agent spends context reading build files and re-reading logs it
already ran. just-mcp-work is a small local MCP server that gives it one way
to find and run everything a workspace can run, and answers with a short receipt
instead of a wall of output.
- No build files in context. Just, CMake, Docker, and GNU Make projects, nested anywhere in the workspace, are discovered on demand. The agent asks for one task and gets that one task.
- Output only when it is wanted. A run answers with its status, exit code, and short output tails. The full stdout and stderr stay one call away — for the failures where they matter.
- Long runs stay out of the way. Anything slow moves to the background with a run ID the agent can follow, wait on, or stop.
- Anything else still runs. A plain shell command, when no task fits.
The agent gets the usage rules from the server itself, so there is nothing here you have to teach it.
Install
Download an archive from the latest GitHub Release:
| Platform | Download |
|---|---|
| Linux x86_64 | just-mcp-work_linux_amd64.tar.gz |
| Linux arm64 | just-mcp-work_linux_arm64.tar.gz |
| macOS Apple Silicon | just-mcp-work_darwin_arm64.tar.gz (opening notes) |
| Windows x86_64 | just-mcp-work_windows_amd64.zip |
Extract it and put just-mcp-work (or just-mcp-work.exe) on PATH. The
release checksums.txt verifies the archive. From source:
go install github.com/palchukovsky/just-mcp-work/cmd/just-mcp-work@latest
just, CMake,
Docker with the
Compose v2 plugin, and
GNU Make are needed only for the project
types you actually have. A tool missing on this host is reported as a warning,
and everything else in the workspace keeps working.
Set it up
Run this once in the workspace:
just-mcp-work init
It registers the server and adds a short instruction block for the coding agents
you use — Claude Code, Codex, Cursor, Copilot, Windsurf. Existing configuration
is edited in place: only the entries this server owns are rewritten, and your
own content, ordering, and formatting are left untouched, down to the line
endings. init stops when it cannot edit a configuration safely or finds a
hand-written Codex entry for this server; it tells you what to fix instead of
taking the entry over. For Claude Code it also offers matching tool permissions
and asks before changing them.
Run init again after an update. init --help and serve --help list the
agent targets and the server options.
Security
Tasks and shell commands run with your privileges and without a sandbox: trust a
selected task the way you trust the project's build scripts. run_task runs an
existing recipe or target with its arguments kept separate; run_shell_command
deliberately hands command text to the OS shell. Need isolation? Run
just-mcp-work in a container. See SECURITY.md.
Configuration
| Flag | Environment | Default |
|---|---|---|
--root |
JMW_ROOT |
Current directory |
--timeout |
JMW_TIMEOUT |
15m (0 disables the timeout) |
--sync-deadline |
JMW_SYNC_DEADLINE |
1m |
--retention |
JMW_RETENTION |
72h |
--exclude |
— | None |
Run data is kept under .just-mcp-work/log/ in the selected workspace.
Development and release
With Just:
just install-lint
just verify
just build-all
just package
just verify checks formatting, dependencies, strict lint, vet, race-enabled
tests, build, and the MCP smoke flow. just build-all produces the Linux,
macOS, and Windows binaries; just package creates the release archives and
checksums.
just release patch|minor|major verifies the project, creates and pushes the
next tag, then GitHub Actions builds and publishes the release.
just release-dry [patch|minor|major] runs the same checks and starts a
pipeline dry run without creating a tag; it needs authenticated GitHub CLI
access.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
just-mcp-work
command
|
|
|
internal
|
|
|
agentinit
Package agentinit installs a small managed task-server instruction block.
|
Package agentinit installs a small managed task-server instruction block. |
|
executor
Package executor runs runner-provided commands and streams their output to a run store.
|
Package executor runs runner-provided commands and streams their output to a run store. |
|
mcpserver
Package mcpserver exposes workspace tasks through the local STDIO MCP transport.
|
Package mcpserver exposes workspace tasks through the local STDIO MCP transport. |
|
runmanager
Package runmanager owns live asynchronous executor runs for one server process.
|
Package runmanager owns live asynchronous executor runs for one server process. |
|
runner
Package runner defines task backends used by the workspace registry.
|
Package runner defines task backends used by the workspace registry. |
|
runner/cmake
Package cmake implements the CMake preset task runner.
|
Package cmake implements the CMake preset task runner. |
|
runner/docker
Package docker implements Dockerfile and Docker Compose tasks.
|
Package docker implements Dockerfile and Docker Compose tasks. |
|
runner/just
Package just implements the just task runner.
|
Package just implements the just task runner. |
|
runner/make
Package makerunner implements the GNU Make task runner.
|
Package makerunner implements the GNU Make task runner. |
|
runstats
Package runstats derives short-lived duration summaries from the run ledger.
|
Package runstats derives short-lived duration summaries from the run ledger. |
|
runstore
Package runstore persists compact run metadata and append-only process logs.
|
Package runstore persists compact run metadata and append-only process logs. |
|
updatecheck
Package updatecheck checks the public release tags without delaying MCP tools.
|
Package updatecheck checks the public release tags without delaying MCP tools. |
|
version
Package version exposes release and Go build information.
|
Package version exposes release and Go build information. |
|
workspace
Package workspace discovers runner-backed projects below one root directory.
|
Package workspace discovers runner-backed projects below one root directory. |