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 are Schema.TaggedError so the caller can pattern-match on _tag.

• Effect-native: Effect.gen, scoped resources, tagged errors, Layer.launch. No any, no thrown exceptions.

• Curated: 22 jj tools + 7 jjcow tools — the day-to-day operations an agent actually reaches for. Not 40 hand-rolled args.push blocks.

• Stable tool surface: jjcow tools are always registered and fail at call time with a typed JjCowNotInstalled error when jjw is missing, so clients never see a different schema across hosts.

Install

# npm
npm install -g @cyberistic/jj-mcp-server

# pnpm
pnpm add -g @cyberistic/jj-mcp-server

# bunx (no install)
bunx @cyberistic/jj-mcp-server

Then 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"]
    }
  }
}

Related MCP server: aira-mcp-server

Uninstall

npm uninstall -g @cyberistic/jj-mcp-server
# or
pnpm remove -g @cyberistic/jj-mcp-server

Then remove the jj entry from your MCP client's config.

Tools

Meta — call first

Read-only jj tools

Mutating jj tools

Optional jjcow tools (always registered; fail with JjCowNotInstalled if jjw is missing)

Install jjCoW to enable these:

git clone https://github.com/Cyberistic/jjCoW
cd jjCoW
just build && just install

Then jjcow_* 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:

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 and bun for tooling. Two CLIs cover the entire lifecycle — nothing else is required.

nub install                # install deps
nub run typecheck          # tsc --noEmit
nub run lint               # oxlint .
nub run fmt                # oxfmt .
nub scripts/smoke.ts       # verify the toolkits expose the expected tools
nub src/cli.ts < scripts/smoke.json
                           # end-to-end JSON-RPC smoke over stdio

lefthook runs oxfmt + oxlint on pre-commit and tsc --noEmit on pre-push (LEFTHOOK=0 skips).

License

MIT