# 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

```bash
# 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

```toml
[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`](skills/gittree-workflow/SKILL.md)

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

## Tests / coverage

```bash
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:

```bash
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