mcp-gittree

Simple FastMCP server for multi-project git bare + worktrees (Rust gix, no git CLI).

Layer	Meaning	Path
project	git repo	{type.root}/{project}/.bare
workspace	physical checkout (session current)	{type.root}/{project}/{workspace}/
worktree	linked git worktree	same path

Quick start

# install
uv sync --all-packages
cd packages/mcp-gittree-git && uv run maturin develop && cd ../..

# config: see examples/gittree.toml ([types.*] roots + [[project]])
uv run mcp-gittree --config examples/gittree.toml

Env alternative: MCP_GITTREE_CONFIG=/path/to/gittree.toml.

Tools

Session: create_session, list_sessions, get_session, set_current_workspace

Projects: list_project, add_project(name, git_url, type), check_fetch_project(name), fetch_all_projects

Workspaces: list_workspace, new_workspace, create_worktree (new branch), checkout_worktree, prune_workspace (metadata for deleted=true only)

Not provided: rm/delete, commit, push, git CLI.

Config

[types.work]
root = "~/work"

[types.pet]
root = "~/pet"

[[project]]
name = "my-app"
type = "work"
origin = "https://github.com/org/my-app.git"

type is required; roots come from [types.<name>]. Registry writes are serialized (lock + atomic rename).

Prompt / skill

• MCP prompt gittree_workflow — short checklist for agents
• Agent skill: skills/gittree-workflow/SKILL.md

Flow: session → add/list project → workspace → set current → work only there → fetch / prune.

Tests / coverage

make test-rust
make test
make cov-py      # median ≥ 93%
make cov-rust    # median ≥ 93%
make e2e-vmcp    # FastMCP Client tools/call (vmcp-style)

scripts/e2e_vmcp.py default mode uses Client(mcp) (real MCP tool calls). Against a remote vmcp / HTTP MCP gateway:

MCP_GITTREE_MCP_URL=https://…/mcp \
MCP_GITTREE_E2E_GIT_URL=https://github.com/org/repo.git \
uv run python scripts/e2e_vmcp.py

Report: /opt/cursor/artifacts/e2e-vmcp-report.json (or MCP_GITTREE_E2E_REPORT).

License

MIT