gitaiflow MCP — Troubleshooting Runbook

Do not change multiple layers at once.

#1. Start by identifying the failing boundary

Use this decision tree:

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:

sh: 1: /app/bin/gitaiflow: not found

Check:

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:

-v "$REPO_ROOT/installers/AOT/v1.1.3/gitaiflow-linux-arm64:/app/bin/gitaiflow:ro"

For AMD64:

-v "$REPO_ROOT/installers/AOT/v1.1.3/gitaiflow-linux-amd64:/app/bin/gitaiflow:ro"

Do not diagnose MCP until:

docker exec -it gitaiflow-mcp /app/bin/gitaiflow --version

works.

#3. Docker: wrong CPU architecture

Check:

docker run --rm gitaiflow-mcp:local uname -m

Then select:

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:

/workspace/
├── gitaiflow/.git
├── djangoplay-cli/.git
└── issuetracker/.git

Verify the container:

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:

/workspace/gitaiflow/.git
/workspace/gitaiflow

If /workspace/gitaiflow/.git is missing, inspect the Docker mount. A common mistake is:

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

-v "/Users/<user>/pyc/missionmq/gl:/workspace"

#5. Docker: MCP says repository path must be Git root

If you see:

MCP repository path must be the Git repository root.

first inspect the selected repository rather than /workspace:

docker exec gitaiflow-mcp sh -c \
  'git -C /workspace/gitaiflow rev-parse --show-toplevel'

Expected:

/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:

path="gitaiflow"

which resolves to:

/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:

docker exec -it gitaiflow-mcp /app/bin/gitaiflow --version

then:

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:

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:

MCP_RATE_LIMIT=5
MCP_RATE_WINDOW_SECONDS=60

For local development:

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:

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:

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:

/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:

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:

~/.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:

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:

docker exec -it gitaiflow-mcp /app/bin/gitaiflow --version

and:

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:

Error: checksum mismatch for <asset> <version>

or, from binary.py only (this check is mandatory there, unlike the best-effort OpenSSL check in install.sh):

Release signature for gitaiflow <version> did not verify.

Do not weaken or skip either check to get the install to complete. Check, in order:

[ ] 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.