Merge pull request #10 from Eilodon/claude/code-analysis-optimization-9m6kdr

fix(mcp): stop racing SessionStart hook against ci server connection

Author: Eilodon

.claude/hooks/ci-mcp-entrypoint.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# MCP stdio entrypoint for the "ci" server (see .mcp.json). Ensures the
+# ci-cli binary exists, then execs it directly — instead of going through
+# `cargo run` on every single connection attempt.
+#
+# Why this exists (full story: docs/cloud-environment-setup.md):
+# Claude Code dials configured MCP servers asynchronously, with NO ordering
+# guarantee relative to SessionStart hooks completing (confirmed against
+# code.claude.com/docs/en/mcp + .../claude-code-on-the-web: MCP startup is
+# "non-blocking by default", and SessionStart hooks "typically fire before
+# servers finish connecting"). A failed initial connection gets at most 3
+# quick retries (~7s of total backoff, v2.1.121+) and is then marked failed
+# for the rest of the session — nowhere near enough to cover a cold
+# `cargo build` of this workspace (~59s measured: tree-sitter grammars +
+# stack-graphs + bundled SQLite). A SessionStart hook that pre-builds the
+# binary (session-start-build-ci.sh) can win that race but is NOT
+# guaranteed to — it runs concurrently with the connection attempt, not
+# strictly before it.
+#
+# Routing every connection through `cargo run` made this worse than it had
+# to be: every connect paid cargo's own freshness-check overhead, and any
+# connect could be silently upgraded into a full rebuild if cargo decided
+# one was needed — reintroducing the exact race this file exists to avoid.
+#
+# This script removes that variability: if a binary is already on disk,
+# exec it immediately, no cargo involved at all. It only builds here if the
+# binary is missing outright — a real fallback for local/non-cloud use
+# (no environment Setup Script exists there), NOT a substitute for one in
+# cloud sessions. The actual fix for the cold-start race is a Cloud
+# environment Setup Script that builds this binary once, before Claude Code
+# (and its MCP dialing) ever launches — see docs/cloud-environment-setup.md
+# for the exact script to paste into the environment settings UI. That
+# config lives outside this repo (Anthropic-side, not git-tracked), which
+# is exactly why it needs to be written down somewhere a future reader of
+# this repo can find it.
+set -uo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.." || exit 1
+
+BIN="target/debug/ci"
+
+if [ ! -x "$BIN" ]; then
+  # Build output goes to stderr only — stdout is the MCP JSON-RPC channel,
+  # and any stray text there would corrupt the handshake.
+  cargo build --quiet -p ci-cli 1>&2
+fi
+
+exec "$BIN" serve --project-root . "$@"

.claude/hooks/session-start-build-ci.sh

@@ -1,19 +1,30 @@
 #!/usr/bin/env bash
-# SessionStart hook: pre-build the ci-cli binary synchronously so the "ci"
-# stdio MCP server (.mcp.json: `cargo run --quiet -p ci-cli -- serve ...`)
-# can finish its handshake inside the MCP client's fixed 30s connection
-# timeout.
+# SessionStart hook: best-effort pre-build of the ci-cli binary.
 #
-# On a fresh checkout (empty target/), `cargo build -p ci-cli` compiles the
-# full dependency tree (tree-sitter grammars, rusqlite bundled, stack-graphs,
-# embeddings) — measured ~60s even with a warm crates.io registry cache,
-# over 2x the client's timeout, so `cargo run` in .mcp.json reliably times
-# out on the very first connection of every fresh session/container.
-# Once target/ is warm, `cargo run` reconnects in well under 1s (cargo's own
-# freshness check + exec), so paying the compile cost here — before the
-# session (and the MCP client's timer) starts — fixes it for the rest of
-# the session. Must stay synchronous: async mode would let the MCP connect
-# attempt race the build, which is the failure this hook exists to avoid.
+# CORRECTION (2026-07-02): the previous version of this comment claimed a
+# synchronous build here "fixes it for the rest of the session" — that is
+# false, confirmed against code.claude.com/docs/en/mcp and
+# .../claude-code-on-the-web. SessionStart hooks and MCP server connection
+# attempts are NOT ordered: MCP startup is "non-blocking by default" and
+# dials configured servers concurrently with hooks, not after them. A cold
+# `cargo build -p ci-cli` (~59s measured: tree-sitter grammars + stack-graphs
+# + bundled SQLite) can easily still be running when the "ci" server's
+# initial connection attempt times out — which gets at most 3 quick retries
+# (~7s total backoff, v2.1.121+) before Claude Code marks the server failed
+# for the rest of the session, with no further retry. This hook can *win*
+# that race, but cannot *guarantee* winning it — see
+# docs/cloud-environment-setup.md for why the real fix is a Cloud
+# environment Setup Script (runs once, before Claude Code launches at all,
+# cached across sessions), not anything that runs from SessionStart.
+#
+# This hook is still worth keeping for two reasons: (1) it's the only
+# mechanism available for local/non-cloud Claude Code, where there is no
+# environment Setup Script concept at all; (2) unlike
+# `ci-mcp-entrypoint.sh` (.mcp.json's actual entrypoint, which only builds
+# when the binary is *missing*), this always runs `cargo build`, so it also
+# catches the binary being *stale* — e.g. mid-session edits to ci's own
+# source in a prior session. Kept synchronous so that when it does win the
+# race, the win is real (no async handoff for the MCP dial to slip past).
 set -uo pipefail
 
 if ! command -v cargo >/dev/null 2>&1; then
@@ -24,7 +35,7 @@ build_output=$(cargo build --quiet -p ci-cli 2>&1)
 build_status=$?
 
 if [ "$build_status" -ne 0 ]; then
-  jq -n --arg msg "ci-cli pre-build failed (exit $build_status) — the ci MCP server will likely fail to connect (30s client timeout). Build output:
+  jq -n --arg msg "ci-cli pre-build failed (exit $build_status) — the ci MCP server will likely fail to connect. Build output:
 $build_output" \
     '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $msg}}'
 fi

.mcp.json

@@ -17,8 +17,8 @@
     },
     "ci": {
       "type": "stdio",
-      "command": "cargo",
-      "args": ["run", "--quiet", "-p", "ci-cli", "--", "serve", "--project-root", "."],
+      "command": "bash",
+      "args": [".claude/hooks/ci-mcp-entrypoint.sh"],
       "env": {}
     }
   }

docs/cloud-environment-setup.md

@@ -0,0 +1,119 @@
+# Cloud environment setup — why the "ci" MCP server needs a Setup Script
+
+This repo dogfoods its own MCP server: `.mcp.json` wires up a `ci` stdio
+server pointed at this workspace's own `ci-cli` binary. On Claude Code on
+the web, that binary does not exist until something compiles it — and
+where that compile happens determines whether the server ever connects.
+
+## The failure this document exists to prevent
+
+`ci-cli` is a Rust binary with a nontrivial dependency tree (tree-sitter
+grammars, stack-graphs, bundled SQLite). A cold `cargo build -p ci-cli` on
+a fresh checkout measures **~59s** in this environment. Claude Code's MCP
+client dials configured servers **concurrently with, not after,**
+`SessionStart` hooks — confirmed against the official docs:
+
+- [code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp) —
+  MCP server startup is "non-blocking by default"; a failed initial
+  connection gets at most 3 retries on transient errors (~7s of total
+  backoff, as of v2.1.121), then the server is marked failed **for the
+  rest of the session**, with no further retry.
+- [code.claude.com/docs/en/claude-code-on-the-web](https://code.claude.com/docs/en/claude-code-on-the-web) —
+  `SessionStart` hooks "run after Claude Code launches, on every session,"
+  which is a different (and unordered, relative to MCP dialing) point in
+  startup than a Setup Script, which runs "before Claude Code launches."
+
+A `SessionStart` hook that runs `cargo build` (this repo has one —
+`.claude/hooks/session-start-build-ci.sh`) can therefore **win** the race
+against a cold connection attempt, but cannot **guarantee** winning it — a
+59s build has no trouble outlasting a ~7s retry budget. A previous version
+of this repo's setup relied on that hook alone and believed it had fixed
+the problem; it hadn't — it had just usually won the race, until a session
+where it didn't.
+
+## The actual fix: a Cloud environment Setup Script
+
+Setup Scripts and `SessionStart` hooks look similar but solve different
+problems:
+
+| | Setup Script | `SessionStart` hook |
+|---|---|---|
+| Runs | Once, **before** Claude Code (and MCP dialing) launches at all | Every session, **after** Claude Code launches, concurrently with MCP dialing |
+| Configured in | Cloud environment settings UI (not in this repo) | `.claude/settings.json` (this repo, `.claude/hooks/session-start-build-ci.sh`) |
+| Output persistence | Filesystem snapshotted and reused for ~7 days, or until the script/network config changes | None — runs fresh every session |
+
+Only the Setup Script runs early enough to structurally rule out the race.
+Because it's environment-level config, it is **not stored in this repo** —
+that's exactly why it needs to be written down here, or the next person to
+hit this failure has no way to discover it.
+
+### What to paste in
+
+Open the environment settings dialog (cloud icon → environment selector →
+settings icon) for the environment used to run sessions against this repo,
+and put this in the **Setup script** field:
+
+```bash
+#!/bin/bash
+cd "$(dirname "$0")" 2>/dev/null || true
+cargo build --quiet -p ci-cli
+```
+
+(Setup scripts run with the repo checked out as the working directory, so
+a plain `cargo build --quiet -p ci-cli` without the `cd` is equally fine —
+the `cd` guard above is only there in case that assumption ever changes.)
+
+This must build to the **same path** `.mcp.json` expects:
+`target/debug/ci` (debug, not `--release` — release compiles slower for no
+benefit here, since this binary is a local dev/dogfood tool, not a
+distributed artifact; keep this in sync with
+`.claude/hooks/session-start-build-ci.sh` and
+`.claude/hooks/ci-mcp-entrypoint.sh` if that ever changes).
+
+Keep it under Claude Code's ~5-minute Setup Script budget — 59s measured
+leaves a wide margin.
+
+### Optional extra margin: `MCP_TIMEOUT`
+
+`MCP_TIMEOUT` (milliseconds) controls the MCP client's own initial
+connection timeout. It is a process-level environment variable for the
+`claude` process itself (e.g. `MCP_TIMEOUT=10000 claude` locally) — **not**
+a per-server `.mcp.json` field, and **not** the same as `.mcp.json`'s
+per-server `timeout` field (that one bounds individual tool *calls* after
+connection, not the initial handshake). For cloud sessions, the
+equivalent lever is adding `MCP_TIMEOUT=120000` as an **environment
+variable** in the same environment settings dialog as the Setup Script.
+This is optional defense-in-depth (matters mainly for the very first
+session before any cache exists, or right after the ~7-day cache expiry)
+— the Setup Script is what actually fixes the steady state.
+
+## What's already handled in this repo (defense in depth, not a substitute)
+
+- `.claude/hooks/ci-mcp-entrypoint.sh` — `.mcp.json`'s actual entrypoint
+  now. Execs the pre-built binary directly if present (no `cargo`
+  involved, no risk of an unexpected rebuild reopening this exact race);
+  only builds inline if the binary is missing outright.
+- `.claude/hooks/session-start-build-ci.sh` — still runs every session.
+  Redundant with the Setup Script in the common case (no-op if `target/`
+  is already warm), but it's what keeps the binary from going *stale*
+  (e.g. after editing `ci`'s own source), and it's the only mechanism at
+  all for local/non-cloud Claude Code, which has no Setup Script concept.
+
+None of this replaces the Setup Script for cloud sessions — it narrows the
+window and covers the cases the Setup Script can't (local dev, staleness),
+but only the Setup Script removes the compile step from the connection
+race entirely.
+
+## How to verify it worked
+
+At the start of a session, once indexing has had a moment to run:
+
+```
+mcp__ci__repo_overview()
+```
+
+If this resolves (rather than the tool being entirely absent from your
+tool list), the connection succeeded. If it's missing, check for a `ci-cli
+pre-build failed` message in the session's `SessionStart` hook output —
+that means the fallback hook itself failed (e.g. a real compile error),
+which is a different problem than the timing race this document covers.