# Gemini Argon Bridge (MCP Server & CLI)

[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol%202024--11--05-blue.svg)](https://modelcontextprotocol.io/)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Google AI Studio](https://img.shields.io/badge/Model-Gemini%204%20Argon-orange.svg)](https://aistudio.google.com/)

> **High-performance Model Context Protocol (MCP) server & CLI bridging AI assistants (Antigravity, Claude Desktop, Cursor, Windsurf) with Google AI Studio's Gemini 4 Argon reasoning model via an authenticated real-browser CDP session.**

---

## 🌟 Key Highlights

- **🧠 Deep Reasoning Oracle:** Direct access to Gemini 4 Argon's extended chain-of-thought, returning both `[ARGON_THOUGHTS]` (full reasoning trace) and `[ARGON_RESPONSE]` (verdict & code).
- **🚀 Sub-Millisecond Input Streaming:** Uses native DOM prototype property setters (`HTMLTextAreaElement.prototype.value`) to inject 85,000+ characters in **13 milliseconds**, bypassing sluggish CDP keystroke simulation.
- **📦 Massive Context Offloading (>120k chars):** Automatically converts massive inputs into temporary file attachments, uploads them into AI Studio's file dock, and awaits backend tokenization stabilization before executing.
- **🔒 Cross-Process IPC Locking & CDP Multiplexing:** Share a single headless/headful Chromium instance between multiple MCP calls and independent CLI executions with zero collision or port conflicts.
- **💾 Google Drive Persistence & Session Resumption:** Every conversation is automatically titled, saved to Google Drive, and can be resumed across sessions via semantic `session_id` or Google Drive `prompt_id`.
- **🛡️ 100% API Quota-Free:** Operates through your authenticated Google AI Studio web account—no pay-per-token API keys, tier restrictions, or rate limit caps.

---

## 🏗️ Architecture

```mermaid
flowchart TD
    subgraph Clients["AI Clients & CLI"]
        AGY["Antigravity / Gemini IDE"]
        CLD["Claude Desktop / Cursor"]
        CLI["ask-argon CLI Tool"]
    end

    subgraph MCP["Gemini Argon Bridge"]
        STDIO["mcp-server.js (Stdio JSON-RPC)"]
        ENGINE["ArgonEngine (engine.js)"]
        IPCLOCK["IPC File Lock & Mutex"]
        LRU["LRU Tab Manager & Session Registry"]
    end

    subgraph Browser["Google Chrome CDP"]
        CHROME["Isolated Chromium Profile"]
        CDP["Chrome DevTools Protocol (WebSocket)"]
        STUDIO["Google AI Studio Web UI\n(Gemini 4 Argon Session)"]
    end

    AGY <-->|Stdio MCP| STDIO
    CLD <-->|Stdio MCP| STDIO
    CLI <-->|Direct Engine| ENGINE
    STDIO <--> ENGINE
    ENGINE <--> IPCLOCK
    ENGINE <--> LRU
    ENGINE <-->|Puppeteer CDP| CDP
    CDP <--> CHROME
    CHROME <--> STUDIO
```

---

## 🚀 Quick Start

### 1. Prerequisites
- **Node.js:** v18.0.0 or higher (`node -v`)
- **Browser:** Google Chrome (or Microsoft Edge) installed on your system.

### 2. Installation
```bash
# Clone the repository
git clone https://github.com/Aldiyuar/gemini-argon-bridge.git
cd gemini-argon-bridge

# Install dependencies
npm install
```

### 3. One-Time Interactive Login
Launch Chrome with the dedicated isolated profile (`~/.gemini/argon-browser-profile`) to sign into your Google account:

```bash
# Windows (via batch script)
login.bat

# Or directly via Node.js (Windows / Linux / macOS)
node login.js
```

1. Chrome will open to **Google AI Studio**.
2. Sign in with your Google account.
3. Accept terms and open/test any prompt to verify access.
4. Close the browser. Your session cookies and tokens remain safely persisted in the isolated user profile.

---

## ⚙️ Configuration

### 1. Google Antigravity / Gemini CLI
Add to `~/.gemini/config/mcp_config.json`:
```json
{
  "mcpServers": {
    "gemini-argon": {
      "command": "node",
      "args": [
        "C:\\path\\to\\gemini-argon-bridge\\mcp-server.js"
      ]
    }
  }
}
```

### 2. Claude Desktop
Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
  "mcpServers": {
    "gemini-argon": {
      "command": "node",
      "args": [
        "/path/to/gemini-argon-bridge/mcp-server.js"
      ]
    }
  }
}
```

### 3. Cursor / Windsurf
Add to `.cursor/mcp.json` or Global MCP Settings:
```json
{
  "mcpServers": {
    "gemini-argon": {
      "command": "node",
      "args": [
        "/path/to/gemini-argon-bridge/mcp-server.js"
      ]
    }
  }
}
```

---

## 🛠️ MCP Tools Reference

The server registers 3 tools under the Model Context Protocol:

### 1. `ask_argon`
Executes deep reasoning prompts in Gemini 4 Argon.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `prompt` | `string` | **Yes** | The core inquiry, audit request, or problem specification. |
| `session_id` | `string` | No | Semantic conversation slug (e.g. `auth-audit`). Keeps multi-turn state. Defaults to anonymous. |
| `file_paths` | `array<string>` | No | List of absolute local file paths (`.ts`, `.py`, `.json`, `.md`, `.pdf`, etc.) to attach. |
| `timeout_sec` | `number` | No | Maximum wait time in seconds (default: 360, max: 1200). |
| `prompt_id` | `string` | No | Existing Google Drive prompt resource ID to resume an existing web session. |

**Example Return:**
```markdown
[ARGON_THOUGHTS]
1. Analyzing attached state_machine.ts...
2. Detected race condition between event queue flush and mutex release at line 142.
3. Solution requires double-checked locking with atomic CAS.

[ARGON_RESPONSE]
### Root Cause Analysis
The race condition stems from...

```typescript
// Verified minimal diff
```
```

### 2. `argon_status`
Returns real-time health and diagnostics of the bridge:
- Browser running status & CDP WebSocket URL
- IPC mutex state (`isLocked`)
- Active sessions and attached tab count
- Persistent Google Drive prompt registry

### 3. `reset_argon`
Closes browser tabs and frees memory:
- With `session_id`: Closes the specific tab and unregisters the session.
- Without arguments: Closes all tabs and cleans up temporary scratch files.

---

## 💻 CLI Usage

The package includes a standalone CLI (`ask-argon-cli.js`) that shares the browser instance with MCP without conflicts:

```bash
# Direct single prompt
node ask-argon-cli.js "Explain the difference between optimistic and pessimistic locking"

# Attach local files for deep review
node ask-argon-cli.js "Audit these files for security flaws" --file src/auth.ts --file src/jwt.ts

# Multi-turn session continuation
node ask-argon-cli.js "Fix the race condition you identified" --session bug-hunt-1

# Save output to markdown file
node ask-argon-cli.js "Design a high-throughput event bus" --output architecture.md
```

---

## 🧪 Verification & Automated Tests

Run the end-to-end integration test suite:

```bash
npm test
```

The test runner will:
1. Spawn `mcp-server.js` via stdio JSON-RPC.
2. Initialize the protocol and query `argon_status`.
3. Dispatch an `ask_argon` query.
4. Concurrently launch `ask-argon-cli.js` in a parallel process to verify IPC lock arbitration and WebSocket endpoint reuse.
5. Verify mathematical precision (17 + 25 = 42) and custom token presence (`АРГОН_ОК`).
6. Perform clean LIFO session teardown via `reset_argon`.

---

## 📂 Repository Structure

```
gemini-argon-bridge/
├── package.json               # Node.js manifest with bin shortcuts & dependencies
├── engine.js                  # Core ArgonEngine (CDP browser lifecycle, DOM injection, IPC)
├── mcp-server.js              # Model Context Protocol stdio transport server
├── ask-argon-cli.js           # Production CLI companion tool
├── login.js                   # Interactive profile setup & Google authentication
├── login.bat                  # One-click Windows setup launcher
├── mcp_config.example.json    # Example configuration templates for IDEs
├── skills/
│   └── argon-reasoning/
│       └── SKILL.md          # Antigravity skill for automated deep reasoning routing
├── tests/
│   └── integration.test.js    # Concurrency and end-to-end verification test suite
├── LICENSE                    # MIT License
└── README.md                  # Documentation and API reference
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).
Created and maintained by [Aldiyuar](https://github.com/Aldiyuar).