---
since: 1.1.3
---

# gitaiflow MCP — Local Verification

## Purpose

This document is the verification map for v1.1.3.

It does not contain every command. Instead, it tells you **what to verify, in what order, and which document owns the detailed procedure**.

The key principle is:

> Verify one boundary at a time.

---

## Verification order

```mermaid
flowchart TB
    Tests["1. Automated tests"]
    Native["2. Native Python MCP"]
    Docker["3. Docker MCP"]
    AOT["4. Direct AOT inside Docker"]
    Inspector["5. MCP Inspector"]
    Claude["6. Claude Desktop"]
    Release["7. Release gate"]

    Tests --> Native --> Docker --> AOT --> Inspector --> Claude --> Release
```

These layers are complementary.

| Layer | What it proves |
|---|---|
| Automated tests | MCP internals and isolated behavior |
| Native Python | MCP + installed gitaiflow executable |
| Docker | packaged/container runtime boundary and multi-repository workspace mount |
| Direct Docker AOT | AOT runtime independent of MCP |
| MCP Inspector | actual MCP protocol contract |
| Claude Desktop | stdio + desktop client end-to-end path |
| Release gate | all required v1.1.3 evidence exists |

---

## Current v1.1.3 boundary

For the release candidate, the local architecture is:

```text
Native Python MCP
        ↓
Docker MCP
        ↓
MCP Inspector
        ↓
Claude Desktop
        ↓
release
```

Cloud Run is not part of this local v1.1.3 gate. It is the next deployment evolution.

---

## 1. Automated tests

Run:

```bash
pytest tests/ -v
```

MCP-specific tests:

```text
tests/mcp-server/test_mcp_config.py
tests/mcp-server/test_mcp_executor.py
tests/mcp-server/test_mcp_middleware.py
tests/mcp-server/test_mcp_workspace.py
```

Recorded v1.1.3 baseline:

```text
138 passed
0 failed
```

If the test suite fails, stop before end-to-end verification.

---

## 2. Native Python MCP

Detailed procedure:

```text
MCP-LOCAL-VERIFICATION.md (this document)
```

Required evidence:

```text
[ ] gitaiflow executable found
[ ] gitaiflow --version works
[ ] gitaiflow --last-summary works
[ ] .mcp.env loaded
[ ] MCP server starts
[ ] /health returns 200
[ ] unauthenticated /mcp request is rejected
[ ] authenticated MCP session initializes
[ ] tools/list succeeds
[ ] gitaiflow_usage succeeds
[ ] gitaiflow_last_summary succeeds
```

---

## 3. Docker MCP

Detailed procedure:

```text
MCP-DOCKER-VERIFICATION.md
```

For the recommended developer setup, `/workspace` is a parent workspace containing multiple independent Git repositories. The selected repository must be its own Git root.

The Docker gate must be performed in this order:

```text
resolve host parent workspace
        ↓
build image
        ↓
start container
        ↓
verify /app/bin/gitaiflow
        ↓
verify /workspace contains the selected repository
        ↓
verify selected repository has its own .git
        ↓
verify selected Git root
        ↓
verify /health
        ↓
run gitaiflow --last-summary directly
        ↓
initialize MCP
        ↓
call gitaiflow_last_summary with path="gitaiflow"
```

Do not skip the direct AOT test or the repository-mount check.

## 4. MCP Inspector

Detailed procedure:

```text
MCP-INSPECTOR-VERIFICATION.md
```

Inspector is the protocol-level gate.

It should be used only after the server and direct runtime checks have passed.

Verify:

```text
[ ] connection
[ ] authentication
[ ] initialize
[ ] session
[ ] tools/list
[ ] six tools
[ ] required arguments
[ ] optional arguments
[ ] tool calls
[ ] successful MCP responses
```

---

## 5. Claude Desktop

Detailed procedure:

```text
MCP-CLAUDE-DESKTOP.md
```

Claude comes last because it adds another process boundary.

Verify:

```text
Claude Desktop
    ↓
stdio
    ↓
Docker MCP
    ↓
gitaiflow AOT
    ↓
Git repository
```

The actual tool invocation is the final local end-to-end proof.

---

## 6. v1.1.3 completion checklist

| Verification target | Status |
|---|---|
| Automated test suite | ✅ |
| MCP configuration | ✅ |
| Streamable HTTP | ✅ |
| stdio transport | ✅ |
| Authentication | ✅ |
| Rate limiting | ✅ |
| Workspace validation | ✅ |
| Native gitaiflow execution | ✅ |
| Docker gitaiflow execution | ✅ |
| Docker → AOT execution | ✅ |
| Multi-repository workspace mounting | ✅ |
| MCP initialization | ✅ |
| Tool discovery | ✅ |
| Tool schemas | ✅ |
| Six tool invocations | ✅ |
| AI configuration delegation | ✅ |
| Usage persistence | ✅ |
| MCP Inspector | ✅ |
| Claude Desktop Docker launch | ✅ |
| Claude tool discovery | ✅ |
| Actual Claude tool invocation | ✅ |
| Binary compatibility | ✅ |
| MCPB packaging | ✅ |

See [MCP release checklist](../runbooks/mcp-release-checklist.md) for the release-facing checklist.

---

## 7. What each document is for

```text
MCP-README.md
    Product documentation.
    Start here only when you need to understand what MCP is.

MCP-GETTING-STARTED.md
    New developer path.
    Setup → tests → verification order.

MCP-DOCKER-VERIFICATION.md
    Docker procedure.

MCP-INSPECTOR-VERIFICATION.md
    MCP protocol procedure.

MCP-CLAUDE-DESKTOP.md
    Claude/stdio/MCPB procedure.

MCP-RUNBOOK.md
    Troubleshooting.

MCP-RELEASE-CHECKLIST.md
    Release gate.
```