--- since: 1.1.3 --- # gitaiflow MCP — Claude Desktop Integration Claude Desktop is the final local integration step for developers. If you are an end user, install the packaged MCPB extension instead of configuring Docker manually. See the installation section in [MCP overview](./README.md). For developer verification, follow: ```text native MCP ↓ Docker MCP ↓ MCP Inspector ↓ Claude Desktop ``` --- ## 1. What Claude Desktop adds Claude introduces another process boundary: ```mermaid flowchart TB Claude["Claude Desktop"] STDIO["stdio"] MCP["gitaiflow MCP"] AOT["gitaiflow AOT"] Repo["Selected Git repository"] Claude --> STDIO --> MCP --> AOT --> Repo ``` The goal is to prove that Claude can launch the server, initialize MCP, discover the tools, invoke a tool, and receive the result. --- ## 2. End-user installation For normal Claude Desktop use, install the packaged MCPB extension. macOS / Linux: ```bash curl -fsSL https://install.djangoplay.org/gitaiflow-mcp | bash ``` Windows PowerShell: ```powershell irm https://install.djangoplay.org/gitaiflow-mcp.ps1 | iex ``` The installer downloads the platform-specific `.mcpb` file to the default Downloads directory and prints its full path. Open the `.mcpb` file with Claude Desktop to install the extension. The end-user MCPB path does not require: - Docker - Python - `.mcp.env` - a source checkout - a manual `docker run` command --- ## 3. Docker stdio model for developers Claude launches: ```text docker run ``` The container uses: ```text MCP_TRANSPORT=stdio ``` There is no HTTP port mapping. For a multi-repository developer workspace, mount the **parent directory containing the repositories**: ```text /Users//pyc/missionmq/gl → /workspace ``` For example: ```text /workspace/ ├── gitaiflow/.git ├── djangoplay-cli/.git ├── astwire/.git └── issuetracker/.git ``` Then: ```text MCP_WORKSPACE=/workspace MCP_ALLOWED_WORKSPACES=/workspace ``` Claude can select repositories by name, for example `path="gitaiflow"`. The gitaiflow configuration is mounted as: ```text $HOME/.gitaiflow → /root/.gitaiflow ``` For the v1.1.3 local Docker test, the matching AOT binary is explicitly mounted: ```text installers/AOT/v1.1.3/gitaiflow-linux-arm64 → /app/bin/gitaiflow ``` --- ## 4. Verify Docker stdio outside Claude first Do this before editing Claude Desktop configuration. Define the parent workspace explicitly: ```bash export MCP_HOST_WORKSPACE="/Users//pyc/missionmq/gl" ``` Then run: ```bash docker run --rm -i \ --env-file .mcp.env \ -e MCP_TRANSPORT=stdio \ -e MCP_WORKSPACE=/workspace \ -e MCP_ALLOWED_WORKSPACES=/workspace \ -e GITAIFLOW_BINARY=/app/bin/gitaiflow \ -v "$HOME/.gitaiflow:/root/.gitaiflow" \ -v "$MCP_HOST_WORKSPACE:/workspace" \ -v "$MCP_HOST_WORKSPACE/gitaiflow/installers/AOT/v1.1.3/gitaiflow-linux-arm64:/app/bin/gitaiflow:ro" \ gitaiflow-mcp:local ``` Expected: ```text stdio starts no Uvicorn no HTTP listener ``` If this does not work, do not move to Claude. ### Verify the actual Docker filesystem before Claude Start the HTTP variant when you need an inspectable running container, then verify: ```bash docker ps --filter name=gitaiflow-mcp ``` ```bash docker exec gitaiflow-mcp sh -c ' echo "=== WORKSPACE ===" ls -lad /workspace echo echo "=== GITAIFLOW ===" ls -lad /workspace/gitaiflow ls -lad /workspace/gitaiflow/.git echo echo "=== GITAIFLOW ROOT ===" git -C /workspace/gitaiflow rev-parse --show-toplevel echo echo "=== OTHER REPO ===" git -C /workspace/djangoplay-cli rev-parse --show-toplevel ' ``` Expected: ```text /workspace/gitaiflow/.git /workspace/gitaiflow /workspace/djangoplay-cli ``` This check catches an incorrect Docker mount before Claude is involved. --- ## 5. Claude Desktop configuration A local Docker configuration follows this shape: ```json { "mcpServers": { "gitaiflow-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "--env-file", "/absolute/path/to/gitaiflow/.mcp.env", "-e", "MCP_TRANSPORT=stdio", "-e", "MCP_WORKSPACE=/workspace", "-e", "MCP_ALLOWED_WORKSPACES=/workspace", "-e", "GITAIFLOW_BINARY=/app/bin/gitaiflow", "-v", "/absolute/path/to/home/.gitaiflow:/root/.gitaiflow", "-v", "/absolute/path/to/parent-workspace:/workspace", "-v", "/absolute/path/to/parent-workspace/gitaiflow/installers/AOT/v1.1.3/gitaiflow-linux-arm64:/app/bin/gitaiflow:ro", "gitaiflow-mcp:local" ] } } } ``` Replace all absolute paths with paths on the developer machine. **The `/workspace` host path must be the parent workspace containing the repositories, not an individual repository, when you want Claude to select multiple repositories.** For your multi-repository layout, this is the intended mapping: ```text /Users//pyc/missionmq/gl:/workspace ``` not: ```text /Users//pyc/missionmq/gl/gitaiflow:/workspace ``` For AMD64, use: ```text gitaiflow-linux-amd64 ``` No: ```text -p 8080:8080 ``` is required for stdio. ### `.mcp.env` and explicit Docker values Your `.mcp.env` can contain native host paths, for example: ```text MCP_WORKSPACE=/Users//pyc/missionmq/gl/ MCP_ALLOWED_WORKSPACES=/Users//pyc/missionmq/gl/ ``` That is compatible with Docker because the Claude command explicitly overrides them: ```text -e MCP_WORKSPACE=/workspace -e MCP_ALLOWED_WORKSPACES=/workspace ``` The effective values inside the container are the explicit Docker values. --- ## 6. What Claude should show On successful startup, Claude should initialize the MCP connection and discover: ```text gitaiflow_change_summary gitaiflow_last_summary gitaiflow_changelog gitaiflow_release_notes gitaiflow_usage gitaiflow_list_models ``` The exact client UI may vary. The protocol evidence is tool discovery and successful invocation. --- ## 7. First Claude tool test Use a deliberately simple prompt: ```text Use the gitaiflow_last_summary tool for the gitaiflow repository and show me the result. Do not tell me how to run gitaiflow manually. ``` Expected repository selection: ```text path="gitaiflow" ↓ /workspace/gitaiflow ↓ Git root = /workspace/gitaiflow ``` You can test another repository without changing the Claude configuration: ```text Use the gitaiflow_last_summary tool for the djangoplay-cli repository and show me the result. ``` The important thing is that Claude actually invokes the MCP tool and receives the tool result. --- ## 8. Claude MCPB extension The packaged Claude Desktop extension is a separate local integration path. Its responsibilities include: - launching MCP locally through stdio - resolving the gitaiflow executable - honoring an explicit Developer Binary Path - using normal production binary locations when no developer override exists - inheriting existing gitaiflow configuration - returning structured binary-resolution errors It does not replace standalone gitaiflow installation. --- ## 9. Developer Binary Path When configured: ```text /absolute/path/to/gitaiflow ``` the extension uses that executable directly. If the configured binary does not exist, the extension must return the configuration error rather than silently falling back. Expected error semantics: ```text Configured developer gitaiflow binary does not exist: Remove the Developer Binary Path from the Claude extension settings to use the production binary automatically. ``` --- ## 10. Normal production binary resolution When Developer Binary Path is empty, normal production locations are: ```text macOS / Linux ~/.local/bin/gitaiflow /usr/local/bin/gitaiflow Windows %LOCALAPPDATA%\Programs\gitaiflow\gitaiflow.exe ``` The extension does not automatically select: ```text ./bin/gitaiflow ``` A binary installed through this path is verified against a signed checksum before the extension trusts it — see [Release signing](../deployment/release-signing.md). --- ## 11. Empty optional configuration Claude Desktop can pass: ```text ${user_config.binary_path} ``` when the optional setting is empty. The launcher treats that unresolved literal as unset. Therefore: ```text explicit developer path → use it empty/unresolved developer path → normal production binary resolution ``` --- ## 12. AI configuration The extension continues to use: ```text ~/.gitaiflow/config.env ``` for: ```text AI_PROVIDER AI_API_KEY AI_BASE_URL AI_MODEL ``` Workspace paths and developer binary paths do not belong there. --- ## 13. Claude verification checklist ```text [ ] End-user installation path is understood [ ] Developer Docker stdio works without Claude [ ] Parent multi-repository workspace is mounted [ ] selected repository has its own .git [ ] Claude launches the Docker process [ ] MCP initialization succeeds [ ] six tools are discovered [ ] gitaiflow_last_summary can be invoked for gitaiflow [ ] another repository can be selected without changing the Docker mount [ ] Claude receives the result [ ] explicit Developer Binary Path works [ ] missing Developer Binary Path produces structured error [ ] normal production binary resolution works ``` Only after this gate should the MCP release be considered locally complete.