@cyberistic/jj-mcp-server
v0.1.2
Published
Model Context Protocol server for Jujutsu (jj) version control, built on Effect v4. Optional first-class support for jjCoW (jjw) workspaces.
Maintainers
Readme
jj-mcp-server
A Model Context Protocol server for
Jujutsu (jj) version control, built on
Effect v4. Optional first-class support for
jjCoW (clone-on-write workspace
manager, ~40× faster than jj workspace add).
- Typed end-to-end: parameter schemas are
effect/Schema(decoded at the boundary, not coerced at runtime); results are typed; errors areSchema.TaggedErrorso the caller can pattern-match on_tag. - Effect-native:
Effect.gen, scoped resources, tagged errors,Layer.launch. Noany, no thrown exceptions. - Curated: 22
jjtools + 7jjcowtools — the day-to-day operations an agent actually reaches for. Not 40 hand-rolledargs.pushblocks. - Stable tool surface:
jjcowtools are always registered and fail at call time with a typedJjCowNotInstallederror whenjjwis missing, so clients never see a different schema across hosts. - Tiny payload: bundled to a single self-contained
dist/cli.cjs(CJS, Node 22 target).npx -y @cyberistic/jj-mcp-serverworks with no build step, nonubrequired, no native dependencies.
Install
# npm
npm install -g @cyberistic/jj-mcp-server
# pnpm
pnpm add -g @cyberistic/jj-mcp-server
# bunx (no install)
bunx @cyberistic/jj-mcp-serverThen point your MCP client at the jj-mcp-server bin. The exact
configuration depends on the client; for opencode:
{
"mcp": {
"jj": {
"type": "local",
"command": ["jj-mcp-server"],
"enabled": true
}
}
}opencode exposes the tools as jj_status, jj_log, jj_workspace_create,
etc. The server name (jj) and tool name (status) are combined.
Uninstall
npm uninstall -g @cyberistic/jj-mcp-server
# or
pnpm remove -g @cyberistic/jj-mcp-serverThen remove the jj entry from your MCP client's config.
Tools
Tool names are unprefixed; the MCP client prepends its own server-name
prefix (e.g. opencode's jj_status). All 29 tools always register,
even when jjw is missing.
Meta — call first
| Name in code | Wraps |
| ------------------ | ------------------------------------------------------------------------------------------- |
| workflow | Returns the jj mental model + canonical workflow. Read this before any non-trivial jj op. |
Read-only jj tools (16)
| Name in code | Wraps |
| ---------------- | -------------------------------------------------------------------- |
| status | jj status |
| log | jj log [-r revisions] [-n limit] [-T template] [-G] [-p] |
| show | jj show [revision] [-T template] [-p] |
| diff | jj diff [-r revset] [-f from] [-t to] [--context N] [--summary\|--stat] |
| files | jj file list [-r revision] [paths] [-T template] |
| bookmark_list | jj bookmark list [--all-remotes] [--remote] [--tracked] [-T template] |
| git_fetch | jj git fetch [--all-remotes] [--remote R] [-b branch] |
| workspace_root | jj workspace root |
| op_log | jj op log [-n limit] [-T template] [-G] [-p] |
Mutating jj tools (13)
| Name in code | Wraps |
| ------------------ | ------------------------------------------------------ |
| describe | jj describe -m message [revision] |
| new | jj new [revisions...] [-m message] [--no-edit] |
| abandon | jj abandon [revisions...] [--retain-bookmarks] |
| rebase | jj rebase [-s source] [-d destination] |
| squash | jj squash [--from] [--into] [-k] |
| duplicate | jj duplicate [revs...] [-d destination] [-A after] [-B before] |
| bookmark_create | jj bookmark create <name> [-r revision] |
| bookmark_set | jj bookmark set <name> -r revision [--allow-backwards] |
| bookmark_delete | jj bookmark delete <names...> |
| git_push | jj git push [--remote R] [-b bookmark] [--all] [--tracked] |
| resolve | jj resolve [-r revision] [--list] |
| undo | jj undo |
Optional jjcow tools (7) — always registered; fail with JjCowNotInstalled if jjw is missing
| Name in code | Wraps |
| --------------------- | -------------------------------------------------------- |
| workspace_create | jjw create <name> [-r revision] [-b bookmark] [--no-cow] [--lazy] |
| workspace_delete | jjw delete [name] [-f] [-k] |
| workspace_list | jjw list [-v] |
| workspace_cleanup | jjw cleanup [-n] [-f] [-k] |
| repo_root | jjw root |
| cow_version | jjw version (jjCoW binary version) |
| workspace_init | jjw init <shell> for zsh/bash/fish shell integration |
Install jjCoW to enable the
workspace_* tools:
git clone https://github.com/Cyberistic/jjCoW
cd jjCoW
just build && just installThen workspace_* tools start working without any change to the MCP
server. If jjw is not on $PATH, the tools return a typed
JjCowNotInstalled error explaining how to install it.
What's deliberately not exposed
The keanemind-style reference exposes 40+ tools. We keep the surface
small. If an agent needs bookmark-track, git-remote-add,
file-annotate, evolog, interdiff, revert, restore, edit, or
any of the operation-* forensics commands, they can shell out to
jj directly. This keeps the tool catalog fast to scan and the LLM
prompt smaller.
Error taxonomy
Every failure is a Schema.TaggedError with a stable _tag:
| _tag | Meaning |
| -------------------- | ---------------------------------------------------------------------- |
| JjError | Catch-all for runtime failures (e.g. spawn error when jj is missing). |
| CommandFailed | jj or jjw exited non-zero. Carries exitCode + stderr. |
| NotARepository | The target cwd / repoPath isn't inside a jj repo. |
| JjCowNotInstalled | jjw isn't on $PATH. Install jjCoW. |
Library use
The bin is the canonical entry; this package also exports the underlying
Layer and Toolkits so an embedder can splice them into a richer
layer graph:
import { MainLayer, JjToolkit, JjCowToolkit } from "@cyberistic/jj-mcp-server";Development
This package uses nub for tooling.
nub install # install deps
nub run build # esbuild src/cli.ts → dist/cli.cjs
nub run build:check # node dist/cli.cjs < scripts/smoke.json
nub run typecheck # tsc --noEmit
nub run lint # oxlint .
nub run fmt # oxfmt .
nub scripts/smoke.ts # print the tool catalogueslefthook runs oxfmt + oxlint on pre-commit and tsc --noEmit
on pre-push (LEFTHOOK=0 skips). prepublishOnly runs the build so
the bundled dist/cli.cjs matches the source before every publish.
License
MIT
