title: MCP Server Unavailable to Claude Code

insight: Genesis V2 has a fully built MCP server with 10 tools but Claude Code cannot access any of them because the `.claude/settings.json` has no `mcpServers` section - the configuration only existed for Gemini ADK, not for Claude Code sessions.

reasoning_chain: Genesis V2 has 10 MCP tools (KG, browser, identity, health) in genesis_v2/mcp/

reasoning_chain: These tools run via stdio transport in the MCP server

reasoning_chain: Claude Code's .claude/settings.json has no mcpServers section - it's configured only for Gemini ADK

reasoning_chain: Without mcpServers config, Claude Code cannot discover or use any MCP tools

reasoning_chain: Solution: Add mcpServers.genesis-v2 to Claude Code settings with WSL paths

source_context: Genesis V2 has a fully built MCP server (genesis_v2/mcp/) with 10 tools (KG, browser, identity, health) running via stdio. The mcp-config.json at root is for the Gemini ADK agent, NOT Claude Code. Claude Code's .claude/settings.json has no mcpServers section.


title: Phase 1-4 Implementation Sequence

insight: The implementation follows a dependency-ordered sequence: MCP registration first (enables tool access), then Antigravity tools (uses MCP infrastructure), then shared state (created by tools on first use), then WebSocket bridge (uses all previous components).

reasoning_chain: Phase 1: Register Genesis V2 MCP in Claude Code - no dependencies, starts here

reasoning_chain: Phase 2: Add Antigravity Sync Tools to MCP Server - needs MCP server working first

reasoning_chain: Phase 3: Shared State Protocol - runs parallel with Phase 2, created by tools on first use

reasoning_chain: Phase 4: Extension Backend + WebSocket Server - needs Phase 2+3 (uses all tools + shared state)

reasoning_chain: Execution order is strictly dependency-based to avoid integration failures

source_context: Execution Order: Phase 1 (MCP Registration) ← Start here, no dependencies; Phase 2 (Antigravity Tools) ← After Phase 1; Phase 3 (Shared State) ← Parallel with Phase 2; Phase 4 (WS Bridge) ← After Phase 2+3


title: File-Based Shared State with Advisory Locking

insight: Instead of a database, the shared state protocol uses file-based storage with advisory file locking - current_state.json for read-modify-write operations and events.jsonl for append-only concurrent writes.

reasoning_chain: Need shared state between Claude Code (via MCP tools) and Gemini (via AntigravityWorkflow)

reasoning_chain: Database adds complexity and deployment requirements

reasoning_chain: File-based approach is simpler: current_state.json + events.jsonl

reasoning_chain: current_state.json uses advisory file locking for read-modify-write

reasoning_chain: events.jsonl is append-only (safe for concurrent writes without locking)

reasoning_chain: Both Claude Code and Gemini read/write to same state files

source_context: State format: data/antigravity-sync/ with current_state.json (advisory file-locked read-modify-write) and events.jsonl (append-only, concurrent-write safe). Both Claude Code (via MCP tools) and Gemini (via AntigravityWorkflow) read/write to same state.


title: WebSocket Bridge on Port 8765

insight: A new aiohttp WebSocket server on port 8765 provides HTTP endpoints for Chrome extension communication, tool execution, and voice/browser bridges - enabling the extension to trigger Gemini decision extraction.

reasoning_chain: Chrome extension expects a WebSocket backend for real-time communication

reasoning_chain: Need HTTP endpoints for session init, vision data, tool calls

reasoning_chain: Need WebSocket endpoints for voice I/O and browser commands

reasoning_chain: When extension sends vision data from gemini.google.com, server uses gemini_query() to analyze DOM and extract decisions, then pushes to shared state via sync_push()

source_context: Server provides: POST /session/start, POST /vision, POST /tools/call, GET /health, WS /voice, WS /ws. Gemini decision extraction: When extension sends vision data from gemini.google.com, server uses gemini_query() to analyze DOM and extract decisions, then pushes to shared state.


title: Graceful Degradation for Gemini Tools

insight: All Gemini-dependent tools are wrapped in try/except with clear error messages - if GEMINI_API_KEY is missing, tools return errors without crashing, while existing KG/browser/identity tools remain unaffected.

reasoning_chain: 8 new tools depend on Gemini API (antigravity_plan, gemini_query, memory_query, etc.)

reasoning_chain: If API key is missing, tools should not crash the entire MCP server

reasoning_chain: Return clear error messages when API key missing

reasoning_chain: Existing non-Gemini tools (KG, browser, identity, health) remain fully functional

source_context: Graceful degradation: All Gemini-dependent tools wrapped in try/except. If GEMINI_API_KEY is missing, tools return clear error messages. Existing KG/browser/identity tools remain unaffected.


title: Claude Code as Connected Agent

insight: Claude Code transforms from isolated session to connected node in a multi-agent system - now part of Gemini-orchestrated workflows with bidirectional memory and state sharing.

reasoning_chain: Previously: Claude Code sessions were isolated, each starting fresh

reasoning_chain: Genesis V2 MCP tools existed but were inaccessible to Claude Code

reasoning_chain: Now: Claude Code has 18 MCP tools available

reasoning_chain: Plus: Gemini workflow planning (antigravity_plan/execute)

reasoning_chain: Plus: Shared state that persists across sessions

reasoning_chain: Plus: Memory bridge for context continuity

reasoning_chain: Claude Code becomes a connected agent in a larger orchestration system

source_context: Moving from isolated Claude Code sessions to connected multi-agent system. Claude Code now becomes part of a larger Gemini-orchestrated workflow.


title: Self-Analysis Loop for Gemini

insight: The WebSocket bridge creates a self-analysis loop: when the Chrome extension visits gemini.google.com, it sends DOM data to the server, which uses Gemini to analyze and extract decisions, then pushes back to shared state - Gemini analyzing Gemini's outputs.

reasoning_chain: Chrome extension captures DOM/screenshot from any page

reasoning_chain: When on gemini.google.com, the extension sends vision data to server

reasoning_chain: Server uses gemini_query() to analyze the DOM

reasoning_chain: Extracts decisions/action items from the Gemini interface itself

reasoning_chain: Pushes extracted decisions to shared state via sync_push()

reasoning_chain: This creates a feedback loop where Gemini can analyze its own outputs

source_context: Gemini decision extraction: When the extension sends vision data from gemini.google.com, the server uses gemini_query() to analyze the DOM and extract decisions/action items, then pushes them to shared state via sync_push().