--- since: 1.1.3 --- # gitaiflow MCP — Troubleshooting Runbook This document is for diagnosis after the normal verification procedures fail. Do not change multiple layers at once. --- ## 1. Start by identifying the failing boundary Use this decision tree: ```mermaid flowchart TB A["gitaiflow direct command"] -->|fail| B["Fix gitaiflow"] A -->|pass| C["Native MCP"] C -->|fail| D["Fix MCP config/server"] C -->|pass| E["Docker"] E -->|fail| F["Fix image/mount/runtime"] E -->|pass| G["Inspector"] G -->|fail| H["Fix MCP protocol/config"] G -->|pass| I["Claude"] I -->|fail| J["Fix stdio/Claude configuration"] I -->|pass| K["Local MCP gate complete"] ``` --- ## 2. Docker: `/app/bin/gitaiflow: not found` Symptom: ```text sh: 1: /app/bin/gitaiflow: not found ``` Check: ```bash docker exec -it gitaiflow-mcp sh -c ' ls -lh /app/bin/gitaiflow 2>&1 || true ls -la /app/bin echo "GITAIFLOW_BINARY=$GITAIFLOW_BINARY" ' ``` If `/app/bin` is empty, the AOT bind mount is missing. For ARM64: ```bash -v "$REPO_ROOT/installers/AOT/v1.1.3/gitaiflow-linux-arm64:/app/bin/gitaiflow:ro" ``` For AMD64: ```bash -v "$REPO_ROOT/installers/AOT/v1.1.3/gitaiflow-linux-amd64:/app/bin/gitaiflow:ro" ``` Do not diagnose MCP until: ```bash docker exec -it gitaiflow-mcp /app/bin/gitaiflow --version ``` works. --- ## 3. Docker: wrong CPU architecture Check: ```bash docker run --rm gitaiflow-mcp:local uname -m ``` Then select: ```text aarch64 → gitaiflow-linux-arm64 x86_64 → gitaiflow-linux-amd64 ``` A wrong-architecture binary can fail before gitaiflow itself starts. --- ## 4. Docker: repository mount is wrong The recommended Docker layout is a parent workspace containing multiple independent Git repositories: ```text /workspace/ ├── gitaiflow/.git ├── djangoplay-cli/.git └── issuetracker/.git ``` Verify the container: ```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 ' ``` Expected: ```text /workspace/gitaiflow/.git /workspace/gitaiflow ``` If `/workspace/gitaiflow/.git` is missing, inspect the Docker mount. A common mistake is: ```bash -v "$PWD:/workspace" ``` when `$PWD` is already `.../gitaiflow`. That mounts one repository as `/workspace` instead of mounting the parent multi-repository workspace. Use the explicit parent workspace: ```bash -v "/Users//pyc/missionmq/gl:/workspace" ``` --- ## 5. Docker: MCP says repository path must be Git root If you see: ```text MCP repository path must be the Git repository root. ``` first inspect the selected repository rather than `/workspace`: ```bash docker exec gitaiflow-mcp sh -c \ 'git -C /workspace/gitaiflow rev-parse --show-toplevel' ``` Expected: ```text /workspace/gitaiflow ``` If that command returns `/workspace`, or if `/workspace/gitaiflow/.git` does not exist, the Docker mount is wrong. Do not weaken the MCP Git-root validation. For a multi-repository workspace, the MCP request should use: ```text path="gitaiflow" ``` which resolves to: ```text /workspace/gitaiflow ``` Do not restrict the Docker mount to only `gitaiflow` as a workaround; that removes sibling repository selection. --- ## 6. `/health` works but MCP tool fails This means the Python MCP process is alive. It does **not** prove that: - the AOT binary exists - the AOT binary is executable - the repository is mounted correctly - gitaiflow can execute - the AI configuration works Run, in order: ```bash docker exec -it gitaiflow-mcp /app/bin/gitaiflow --version ``` then: ```bash docker exec -it gitaiflow-mcp sh -c \ 'cd /workspace && /app/bin/gitaiflow --last-summary' ``` Only then test MCP. --- ## 7. MCP initialize works but tool call fails Check the MCP session. The sequence is: ```text initialize ↓ Mcp-Session-Id ↓ tools/call using that session ``` A new server/container restart invalidates the old session. Reconnect the client or Inspector. --- ## 8. Inspector reports rate limit Default: ```text MCP_RATE_LIMIT=5 MCP_RATE_WINDOW_SECONDS=60 ``` For local development: ```text MCP_RATE_LIMIT=100 MCP_RATE_WINDOW_SECONDS=60 ``` Restart the server after changing `.mcp.env`. --- ## 9. Native workspace authorization error Native configuration needs both: ```text MCP_WORKSPACE=/absolute/path/to/workspace MCP_ALLOWED_WORKSPACES=/absolute/path/to/workspace ``` The first identifies the working directory. The second authorizes repository roots. --- ## 10. Claude reports only "server disconnected" First test the Docker stdio command outside Claude. Then verify: ```text MCP_TRANSPORT=stdio MCP_WORKSPACE=/workspace MCP_ALLOWED_WORKSPACES=/workspace GITAIFLOW_BINARY=/app/bin/gitaiflow ``` Also verify the AOT mount. A missing configured binary should produce a structured binary-resolution error from the extension rather than being diagnosed as a generic server disconnect. --- ## 11. Developer Binary Path does not fall back This is intentional. If the user explicitly configures: ```text /absolute/path/to/gitaiflow ``` and it does not exist, the extension reports the error. It must not silently select another executable. Remove the Developer Binary Path to return to normal production binary resolution. --- ## 12. `last_summary` appears to contain commits It does not. Output such as: ```text 1. gitaiflow: 2. _root: 3. tests: ``` represents directory/folder scopes inside one latest change-summary run. Those numbers are not commit numbers. --- ## 13. Configuration boundary problems If an MCP setting is missing, check `.mcp.env`. If an AI setting is missing, check: ```text ~/.gitaiflow/config.env ``` Do not move AI credentials into `.mcp.env` just to make MCP work. The MCP adapter intentionally delegates AI configuration to gitaiflow. --- ## 14. Minimal diagnostic bundle When reporting a Docker failure, collect: ```bash docker run --rm gitaiflow-mcp:local uname -m docker exec -it gitaiflow-mcp sh -c ' echo "MCP_WORKSPACE=$MCP_WORKSPACE" echo "MCP_ALLOWED_WORKSPACES=$MCP_ALLOWED_WORKSPACES" echo "GITAIFLOW_BINARY=$GITAIFLOW_BINARY" ls -lh /app/bin/gitaiflow 2>&1 || true ls -lad /workspace/gitaiflow/.git 2>&1 || true git -C /workspace/gitaiflow rev-parse --show-toplevel 2>&1 || true git -C /workspace/gitaiflow rev-parse --git-dir 2>&1 || true ' ``` Then: ```bash docker exec -it gitaiflow-mcp /app/bin/gitaiflow --version ``` and: ```bash docker exec -it gitaiflow-mcp sh -c \ 'cd /workspace && /app/bin/gitaiflow --last-summary' ``` Do not include secret values from `.mcp.env` or `~/.gitaiflow/config.env`. --- ## 15. Checksum or signature verification failed during install Symptom, from `install.sh`, `install.ps1`, or `mcp_server/binary.py`: ```text Error: checksum mismatch for ``` or, from `binary.py` only (this check is mandatory there, unlike the best-effort OpenSSL check in `install.sh`): ```text Release signature for gitaiflow did not verify. ``` Do not weaken or skip either check to get the install to complete. Check, in order: ```text [ ] is R2 itself degraded/returning partial content right now? [ ] does SHA256SUMS for this version exist and list this asset? [ ] does SHA256SUMS.sig exist for this version? [ ] was this version signed with scripts/release/sign_release.sh (or gitai_r2.sh with GITAIFLOW_SIGNING_KEY_FILE set) before upload? [ ] does the embedded public key in install.sh / binary.py still match the key that signed this release (no unreleased key rotation)? ``` If everything above checks out and the failure is reproducible, treat it as a possible compromise of the R2 bucket, not a transient bug. Full procedure and key management: [Release signing](../deployment/release-signing.md).