gitaiflow MCP Server

v1.1.3 — MCP adapter for the existing gitaiflow AOT executable.

#What is gitaiflow MCP?

It owns:

• MCP transport (streamable-http and stdio)
• MCP tool registration and schemas
• bearer-token authentication for Streamable HTTP
• request rate limiting
• workspace validation
• subprocess execution
• MCP response shaping
• changed-artifact detection

It does not reimplement gitaiflow's Git, diff, AI, caching, usage, changelog, release-note, or artifact-generation logic.

flowchart LR
    Client["MCP client"] --> Transport["Streamable HTTP / stdio"]
    Transport --> MCP["gitaiflow MCP adapter"]
    MCP --> Tools["6 MCP tools"]
    Tools --> Runner["_run()"]
    Runner --> Binary["gitaiflow AOT"]
    Binary --> Repo["Git repository"]

#Version

For this release:

gitaiflow       1.1.3
MCP adapter     1.1.3
AOT binary      1.1.3

There is one gitaiflow binary distribution stream. Native MCP, Docker MCP, and the Claude Desktop integration use that same gitaiflow release.

#Installation: choose your path

There are two different audiences and two different installation paths.

#End user — Claude Desktop MCPB

If you only want to use gitaiflow MCP from Claude Desktop, use the packaged MCPB extension. You do not need a source checkout, Docker, Python, .mcp.env, or manual MCP server configuration.

macOS / Linux:

curl -fsSL https://install.djangoplay.org/gitaiflow-mcp | bash

Windows 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 downloaded .mcpb file with Claude Desktop to install the extension.

After installation, the extension manages the MCP server and gitaiflow executable according to its normal binary-resolution rules. End users do not need the Docker instructions in this repository.

#Developer — local source/Docker verification

If you are developing or validating the MCP server itself, continue with:

MCP Documentation Index

The developer path is:

Getting Started
    ↓
Native MCP
    ↓
Docker MCP
    ↓
MCP Inspector
    ↓
Claude Desktop
    ↓
Release gate

#Documentation

The documentation index is the primary navigation point for both new and existing developers. It explains installation, configuration, verification, Docker, MCP Inspector, Claude Desktop, troubleshooting, and release preparation.

MCP Documentation Index

#MCP tools

The MCP layer passes the corresponding CLI arguments to gitaiflow. It does not invent repository-specific remote names.

#Configuration boundary

There are two configuration systems. Keep them separate.

#MCP configuration

MCP runtime settings belong in .mcp.env, the process environment, or the deployment environment.

Typical local settings:

MCP_TRANSPORT=streamable-http
MCP_API_TOKEN=<local-secret>
MCP_WORKSPACE=/absolute/path/to/workspace
MCP_ALLOWED_WORKSPACES=/absolute/path/to/workspace
MCP_EXECUTION_TIMEOUT=120
MCP_RATE_LIMIT=100
MCP_RATE_WINDOW_SECONDS=60

MCP_RATE_LIMIT=100 is a local development value used for repeated Inspector/manual requests. The application default is 5 requests per 60 seconds.

For a workspace containing multiple repositories, MCP_WORKSPACE and MCP_ALLOWED_WORKSPACES identify the workspace container, while the tool path selects the individual Git repository inside it. For example:

Host:
/Users/<user>/projects/
├── gitaiflow/          ← Git repository
├── djangoplay-cli/     ← Git repository
└── issuetracker/       ← Git repository

Docker:
/workspace/
├── gitaiflow/
├── djangoplay-cli/
└── issuetracker/

The Docker environment is therefore:

MCP_WORKSPACE=/workspace
MCP_ALLOWED_WORKSPACES=/workspace

A request for path="gitaiflow" resolves to /workspace/gitaiflow and that directory must itself be a Git repository root.

#gitaiflow configuration

The existing gitaiflow configuration remains the source of truth:

~/.gitaiflow/config.env

for:

AI_PROVIDER
AI_API_KEY
AI_BASE_URL
AI_MODEL

Do not put workspace paths or developer binary paths in ~/.gitaiflow/config.env.

For Docker, mount:

$HOME/.gitaiflow  →  /root/.gitaiflow

The mount must be writable because gitaiflow persists local state such as usage.jsonl.

#.mcp.env and Docker overrides

When Docker uses:

--env-file .mcp.env

and also supplies:

-e MCP_WORKSPACE=/workspace
-e MCP_ALLOWED_WORKSPACES=/workspace

the explicit -e values are the effective container values. This is intentional: .mcp.env can keep native host paths while Docker uses container paths.

Do not change the host paths in .mcp.env merely to make Docker work.

#Transports

#Streamable HTTP

Default transport:

MCP_TRANSPORT=streamable-http

Endpoints:

http://localhost:8080/mcp
http://localhost:8080/health

Use this transport for native local verification, Docker verification, MCP Inspector, and service-style deployments.

#stdio

MCP_TRANSPORT=stdio

The server communicates through stdin/stdout and does not start Uvicorn.

This is the transport used by local desktop clients such as Claude Desktop.

#Docker model

For a multi-repository developer workspace, the important filesystem invariant is:

Host parent workspace containing Git repositories
        ↓
        /workspace

For example:

/Users/<user>/projects/
├── gitaiflow/.git
├── djangoplay-cli/.git
├── astwire/.git
└── issuetracker/.git

is mounted as:

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

/workspace itself does not need to be a Git repository in this multi-repository layout. The selected repository, such as /workspace/gitaiflow, must be its own Git repository root.

Do not use $PWD blindly in Docker commands. If $PWD is .../gitaiflow, it mounts only that repository as /workspace and prevents repository-name selection across sibling repositories. Resolve the intended parent workspace explicitly.

For v1.1.3 local Docker verification, the tested AOT binary is explicitly mounted into the container:

installers/AOT/v1.1.3/gitaiflow-linux-arm64
    →
/app/bin/gitaiflow

Use the matching Linux binary for the container architecture.

Do not assume that /app/bin/gitaiflow exists merely because the Docker image starts successfully.

#Where to go next

Cloud Run is the next deployment evolution and is intentionally outside the v1.1.3 local verification gate.