n2-stitch-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nton2 (https://nton2.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# 🛡️ N2 Stitch MCP — Resilient Proxy for Google Stitch
+
+> **Never lose a screen generation again.** Built by [Nton2](https://nton2.com)
+
+[![npm version](https://img.shields.io/npm/v/n2-stitch-mcp)](https://www.npmjs.com/package/n2-stitch-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight, resilient MCP proxy server for [Google Stitch](https://stitch.withgoogle.com/). While other Stitch MCP servers silently fail when connections drop during long-running screen generations, **N2 Stitch MCP keeps going**.
+
+## 🔥 The Problem
+
+Google Stitch's `generate_screen_from_text` takes **2–10 minutes** to create a screen. But the API **drops the TCP connection after ~60 seconds**.
+
+```
+Other MCP servers:
+  Request → 60s → TCP dropped → ❌ "Error: connection reset" → Your work is LOST
+
+N2 Stitch MCP:
+  Request → 60s → TCP dropped → 🛡️ Auto-recovery → Polling... → ✅ Screen delivered!
+```
+
+## 🆚 Why N2 Stitch MCP?
+
+| Feature | Official CLI | Other MCPs | **N2 Stitch MCP** |
+|---------|:---:|:---:|:---:|
+| TCP Drop Recovery | ❌ | ❌ | ✅ **Auto-polling** |
+| Generation Tracking | ❌ | ❌ | ✅ `generation_status` |
+| Generation List | ❌ | ❌ | ✅ `list_generations` |
+| Exponential Backoff | ❌ | ❌ | ✅ **3x retry + jitter** |
+| Auto Token Refresh | ✅ | ⚠️ | ✅ **Background refresh** |
+| Test Suite | ? | ❌ | ✅ **33 tests** |
+| Lightweight | ❌ (heavy CLI) | ✅ | ✅ **Pure proxy** |
+| npx support | ✅ | ✅ | ✅ |
+
+## 🚀 Quick Start
+
+### 1. Prerequisites
+
+You need **one** of these for authentication:
+
+- **Option A**: Google Cloud SDK (recommended)
+  ```bash
+  # Install gcloud
+  # Windows: winget install Google.CloudSDK
+  # macOS:   brew install --cask google-cloud-sdk
+  # Linux:   curl https://sdk.cloud.google.com | bash
+
+  # Login
+  gcloud auth application-default login
+  ```
+
+- **Option B**: API Key
+  ```bash
+  export STITCH_API_KEY="your-api-key"
+  ```
+
+### 2. Add to MCP Client
+
+Add this to your MCP configuration (Cursor, Claude Desktop, Gemini CLI, Antigravity, etc.):
+
+**With gcloud (recommended):**
+```json
+{
+  "mcpServers": {
+    "n2-stitch": {
+      "command": "npx",
+      "args": ["-y", "n2-stitch-mcp"]
+    }
+  }
+}
+```
+
+**With API Key:**
+```json
+{
+  "mcpServers": {
+    "n2-stitch": {
+      "command": "npx",
+      "args": ["-y", "n2-stitch-mcp"],
+      "env": {
+        "STITCH_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+That's it! Your AI agent can now use Google Stitch. 🎉
+
+### 3. Setup Wizard (Optional)
+
+Run the interactive setup to verify everything:
+```bash
+npx -y n2-stitch-mcp init
+```
+
+## 🛡️ 3-Layer Safety Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Your AI Agent                         │
+│         "Create a mobile login screen"                   │
+└────────────────────┬────────────────────────────────────┘
+                     │ MCP (STDIO)
+┌────────────────────▼────────────────────────────────────┐
+│              N2 Stitch MCP Proxy                         │
+│                                                          │
+│  ┌──────────────────────────────────────────────────┐   │
+│  │ L1: Exponential Backoff Retry                    │   │
+│  │     Network errors → retry 3x (1s→2s→4s ±jitter)│   │
+│  ├──────────────────────────────────────────────────┤   │
+│  │ L2: Auto Token Refresh                           │   │
+│  │     401 response → refresh token → retry         │   │
+│  ├──────────────────────────────────────────────────┤   │
+│  │ L3: TCP Drop Recovery                            │   │
+│  │     Connection lost → poll list_screens every    │   │
+│  │     10s → detect new screen → return result      │   │
+│  └──────────────────────────────────────────────────┘   │
+└────────────────────┬────────────────────────────────────┘
+                     │ HTTPS
+┌────────────────────▼────────────────────────────────────┐
+│           Google Stitch API                              │
+│           stitch.googleapis.com/mcp                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Layer 1: Exponential Backoff Retry
+- Transient errors (ECONNRESET, timeout, 429, 503) → automatic retry
+- 3 attempts with exponential backoff: 1s → 2s → 4s (±30% jitter)
+- Non-transient errors (400, 404) fail immediately
+
+### Layer 2: Auto Token Refresh
+- Background token refresh every 50 minutes (before 60-min expiry)
+- On 401 response → force refresh → retry the request
+
+### Layer 3: TCP Drop Recovery (⭐ Unique!)
+- When `generate_screen_from_text` connection drops:
+  1. Wait 5 seconds (let Stitch finish processing)
+  2. Poll `list_screens` every 10 seconds
+  3. Detect new screen by comparing before/after screen lists
+  4. Return the generated screen — **as if nothing happened!**
+- Timeout: 12 minutes max polling
+
+## 🔧 Available Tools
+
+### Stitch API Tools (Auto-discovered)
+| Tool | Description |
+|------|-------------|
+| `create_project` | Create a new Stitch project |
+| `list_projects` | List all projects |
+| `get_project` | Get project details |
+| `list_screens` | List screens in a project |
+| `get_screen` | Get screen details (HTML/CSS) |
+| `generate_screen_from_text` | **✨ Generate UI from text (Resilient!)** |
+| `edit_screens` | Edit existing screens |
+| `generate_variants` | Generate design variants |
+
+### Virtual Tools (N2 Exclusive)
+| Tool | Description |
+|------|-------------|
+| `generation_status` | Check real-time status of a screen generation |
+| `list_generations` | List all in-flight and recent generations |
+
+## ⚙️ Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `STITCH_HOST` | Stitch API URL | `https://stitch.googleapis.com/mcp` |
+| `STITCH_API_KEY` | API Key (alternative to gcloud) | — |
+| `STITCH_PROJECT_ID` | GCP Project ID | — |
+| `STITCH_DEBUG` | Enable debug logging (`1`) | `0` |
+
+## 🧪 Tests
+
+```bash
+npm test
+# 33 passed, 0 failed ✅
+```
+
+Tests cover:
+- ✅ Configuration loading & defaults
+- ✅ API key & ADC authentication
+- ✅ Exponential backoff calculation
+- ✅ Transient error detection
+- ✅ Generation tracking state management
+- ✅ Server module integration
+
+## 📁 Project Structure
+
+```
+n2-stitch-mcp/
+├── index.js                    # Entry point + setup wizard
+├── src/
+│   ├── config.js               # Configuration from env vars
+│   ├── auth.js                 # Google auth (ADC / API key)
+│   ├── proxy-client.js         # HTTP client (L1 + L2)
+│   ├── generation-tracker.js   # TCP drop recovery (L3)
+│   └── server.js               # MCP server + tool routing
+├── test.js                     # Test suite (33 tests)
+├── package.json
+├── LICENSE
+└── README.md
+```
+
+## 📊 Performance
+
+| Metric | Value |
+|--------|-------|
+| Cold start | ~2 seconds |
+| Memory usage | ~30 MB |
+| Request overhead | < 10ms per proxy call |
+| Dependencies | Only 2 (`@modelcontextprotocol/sdk`, `google-auth-library`) |
+
+## 🤝 Contributing
+
+Issues and PRs welcome at [GitHub](https://github.com/choihyunsus/n2-stitch-mcp).
+
+## 📄 License
+
+MIT — Use it freely, modify it, sell it, whatever you want.
+
+---
+
+Made with ❤️ by [Nton2](https://nton2.com) — *Building the Body for AI*

package/index.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * N2 Stitch MCP — Entry Point
+ * 
+ *   ╔═══════════════════════════════════════════════════════════╗
+ *   ║  N2 Stitch MCP Proxy Server                             ║
+ *   ║                                                          ║
+ *   ║  A resilient STDIO MCP proxy for Google Stitch.          ║
+ *   ║  Built by the N2 AI Family (Rose 🌹 & Jennie 💎)        ║
+ *   ║                                                          ║
+ *   ║  3-Layer Safety Architecture:                            ║
+ *   ║    L1 — Exponential-backoff retry (network errors)       ║
+ *   ║    L2 — Auto token refresh on 401                        ║
+ *   ║    L3 — TCP drop recovery via polling for generation     ║
+ *   ╚═══════════════════════════════════════════════════════════╝
+ * 
+ * Usage:
+ *   node index.js              # Run with gcloud ADC
+ *   STITCH_API_KEY=xxx node index.js  # Run with API key
+ *   STITCH_DEBUG=1 node index.js      # Enable debug logging
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig, useApiKey } from './src/config.js';
+import { AuthManager } from './src/auth.js';
+import { ProxyClient } from './src/proxy-client.js';
+import { GenerationTracker } from './src/generation-tracker.js';
+import { StitchMCPServer } from './src/server.js';
+
+// ── Logger (all output to stderr; stdout reserved for STDIO MCP) ──
+
+const logger = {
+    info: (msg) => process.stderr.write(`[n2-stitch] INFO  ${msg}\n`),
+    warn: (msg) => process.stderr.write(`[n2-stitch] WARN  ${msg}\n`),
+    error: (msg) => process.stderr.write(`[n2-stitch] ERROR ${msg}\n`),
+    debug: (msg) => process.stderr.write(`[n2-stitch] DEBUG ${msg}\n`),
+};
+
+// ── Main ────────────────────────────────────────────────────
+
+async function main() {
+    // Handle init subcommand
+    if (process.argv[2] === 'init') {
+        await runInit();
+        return;
+    }
+
+    const config = loadConfig();
+
+    if (!config.debug) {
+        // In non-debug mode, suppress info/debug logs
+        logger.info = () => { };
+        logger.debug = () => { };
+    }
+
+    logger.info('Starting N2 Stitch MCP proxy server');
+    logger.info(`Stitch API: ${config.stitchHost}`);
+
+    // ── Step 1: Authentication ──
+    const auth = new AuthManager(config, logger);
+    try {
+        await auth.initialize();
+    } catch (err) {
+        process.stderr.write(`\n[n2-stitch] FATAL: Authentication failed!\n`);
+        process.stderr.write(`[n2-stitch] ${err.message}\n\n`);
+        process.stderr.write(`[n2-stitch] To fix, run one of:\n`);
+        process.stderr.write(`[n2-stitch]   1. Set API key:  $env:STITCH_API_KEY="your-key"\n`);
+        process.stderr.write(`[n2-stitch]   2. Install gcloud + run:  gcloud auth application-default login\n`);
+        process.stderr.write(`[n2-stitch]   3. Run:  node index.js init\n\n`);
+        process.exit(1);
+    }
+
+    // ── Step 2: Proxy client ──
+    const proxyClient = new ProxyClient(config, auth, logger);
+
+    // ── Step 3: Generation tracker ──
+    const genTracker = new GenerationTracker(proxyClient, config, logger);
+
+    // ── Step 4: MCP Server ──
+    const server = new StitchMCPServer(config, proxyClient, genTracker, logger);
+
+    try {
+        await server.discoverAndRegisterTools();
+    } catch (err) {
+        process.stderr.write(`\n[n2-stitch] FATAL: Failed to discover tools from Stitch API\n`);
+        process.stderr.write(`[n2-stitch] ${err.message}\n`);
+        process.stderr.write(`[n2-stitch] Check your network and authentication.\n\n`);
+        process.exit(1);
+    }
+
+    // ── Step 5: STDIO transport ──
+    const transport = new StdioServerTransport();
+    await server.getServer().connect(transport);
+
+    logger.info('STDIO MCP server ready — listening for JSON-RPC on stdin');
+
+    // Graceful shutdown
+    const shutdown = () => {
+        logger.info('Shutting down...');
+        auth.stop();
+        process.exit(0);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+
+// ── Init subcommand ─────────────────────────────────────────
+
+async function runInit() {
+    console.log(`
+╔═══════════════════════════════════════════════════════════╗
+║  N2 Stitch MCP — Setup Wizard                            ║
+╚═══════════════════════════════════════════════════════════╝
+`);
+
+    // Check gcloud
+    const { execSync } = await import('child_process');
+
+    try {
+        execSync('gcloud --version', { stdio: 'pipe' });
+        console.log('✅ gcloud CLI found');
+    } catch {
+        console.log('❌ gcloud CLI not found');
+        console.log('');
+        console.log('Install Google Cloud SDK:');
+        console.log('  Windows:  winget install Google.CloudSDK');
+        console.log('  macOS:    brew install --cask google-cloud-sdk');
+        console.log('  Linux:    curl https://sdk.cloud.google.com | bash');
+        console.log('');
+        console.log('After installing, run this command again.');
+        process.exit(1);
+    }
+
+    // Check ADC
+    try {
+        execSync('gcloud auth application-default print-access-token', { stdio: 'pipe' });
+        console.log('✅ Application Default Credentials found');
+    } catch {
+        console.log('⚠️  No Application Default Credentials found');
+        console.log('');
+        console.log('Running: gcloud auth application-default login');
+        console.log('A browser window will open for Google Login...');
+        console.log('');
+        try {
+            execSync('gcloud auth application-default login', { stdio: 'inherit' });
+            console.log('✅ Authentication successful!');
+        } catch (err) {
+            console.log(`❌ Authentication failed: ${err.message}`);
+            process.exit(1);
+        }
+    }
+
+    // Test Stitch API
+    console.log('');
+    console.log('Testing Stitch API connection...');
+
+    try {
+        const token = execSync('gcloud auth application-default print-access-token', { encoding: 'utf-8' }).trim();
+
+        const resp = await fetch('https://stitch.googleapis.com/mcp', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                method: 'tools/list',
+                params: {},
+                id: 1,
+            }),
+        });
+
+        if (resp.ok) {
+            const json = await resp.json();
+            const toolCount = json.result?.tools?.length || 0;
+            console.log(`✅ Stitch API connected! Found ${toolCount} tools.`);
+        } else {
+            console.log(`⚠️  Stitch API returned HTTP ${resp.status}`);
+            console.log('  You may need to enable the Stitch API in your GCP project.');
+        }
+    } catch (err) {
+        console.log(`⚠️  Could not reach Stitch API: ${err.message}`);
+    }
+
+    // Print MCP configuration
+    console.log('');
+    console.log('═══════════════════════════════════════════════════════════');
+    console.log('');
+    console.log('Add this to your MCP client configuration:');
+    console.log('');
+    console.log(JSON.stringify({
+        mcpServers: {
+            'n2-stitch': {
+                command: 'npx',
+                args: ['-y', 'n2-stitch-mcp'],
+                env: {
+                    STITCH_DEBUG: '1',
+                },
+            },
+        },
+    }, null, 2));
+    console.log('');
+    console.log('Or with API key (no gcloud needed):');
+    console.log('');
+    console.log(JSON.stringify({
+        mcpServers: {
+            'n2-stitch': {
+                command: 'npx',
+                args: ['-y', 'n2-stitch-mcp'],
+                env: {
+                    STITCH_API_KEY: 'your-api-key-here',
+                },
+            },
+        },
+    }, null, 2));
+    console.log('');
+    console.log('Setup complete! 🎉');
+}
+
+// ── Entry ───────────────────────────────────────────────────
+
+main().catch(err => {
+    process.stderr.write(`[n2-stitch] FATAL: ${err.message}\n`);
+    process.stderr.write(`[n2-stitch] ${err.stack}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "n2-stitch-mcp",
+    "version": "1.0.0",
+    "description": "Resilient MCP proxy for Google Stitch — 3-layer safety (auto-retry, token refresh, TCP drop recovery). Never lose a generation again!",
+    "type": "module",
+    "main": "index.js",
+    "bin": {
+        "n2-stitch-mcp": "index.js"
+    },
+    "files": [
+        "index.js",
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/choihyunsus/n2-stitch-mcp"
+    },
+    "homepage": "https://nton2.com",
+    "bugs": {
+        "url": "https://github.com/choihyunsus/n2-stitch-mcp/issues"
+    },
+    "scripts": {
+        "start": "node index.js",
+        "test": "node test.js"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "keywords": [
+        "mcp",
+        "mcp-server",
+        "google-stitch",
+        "stitch",
+        "ui-generation",
+        "ai-design",
+        "resilient-proxy",
+        "tcp-recovery",
+        "auto-retry",
+        "ai-tools",
+        "ai-agent",
+        "claude",
+        "cursor",
+        "antigravity",
+        "gemini"
+    ],
+    "author": "Nton2 <nton2@nton2.com> (https://nton2.com)",
+    "license": "MIT",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.12.1",
+        "google-auth-library": "^9.15.1"
+    }
+}

package/src/auth.js

@@ -0,0 +1,113 @@
+/**
+ * N2 Stitch MCP — Auth Module
+ * 
+ * Manages Google Cloud authentication via:
+ *   1. API Key (simplest — set STITCH_API_KEY)
+ *   2. ADC (gcloud auth application-default login)
+ *   3. Service Account JSON (GOOGLE_APPLICATION_CREDENTIALS)
+ * 
+ * Handles automatic token refresh before expiry.
+ */
+
+import { GoogleAuth } from 'google-auth-library';
+
+export class AuthManager {
+    /** @param {import('./config.js').loadConfig} config */
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+
+        this._accessToken = '';
+        this._expiresAt = 0;
+        this._refreshTimer = null;
+        this._googleAuth = null;
+        this._client = null;
+    }
+
+    // ── Public ──────────────────────────────────────────────
+    async initialize() {
+        if (this.config.apiKey) {
+            this.logger.info('Using API key authentication');
+            return;
+        }
+
+        this.logger.info('Using Google ADC authentication');
+
+        this._googleAuth = new GoogleAuth({
+            scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+        });
+
+        this._client = await this._googleAuth.getClient();
+
+        // Fetch initial token
+        await this._refreshToken();
+
+        // Start background refresh
+        this._startRefreshLoop();
+    }
+
+    /**
+     * Returns the current access token (or empty string if API key mode).
+     */
+    getAccessToken() {
+        return this._accessToken;
+    }
+
+    /**
+     * Returns headers suitable for Stitch API requests.
+     */
+    getAuthHeaders() {
+        if (this.config.apiKey) {
+            return { 'x-goog-api-key': this.config.apiKey };
+        }
+        return { Authorization: `Bearer ${this._accessToken}` };
+    }
+
+    /**
+     * Force-refresh the token (called on 401 responses).
+     */
+    async forceRefresh() {
+        if (this.config.apiKey) return; // API keys don't refresh
+        this.logger.info('Force-refreshing access token...');
+        await this._refreshToken();
+    }
+
+    /**
+     * Stop the background refresh loop.
+     */
+    stop() {
+        if (this._refreshTimer) {
+            clearInterval(this._refreshTimer);
+            this._refreshTimer = null;
+        }
+    }
+
+    // ── Private ─────────────────────────────────────────────
+    async _refreshToken() {
+        try {
+            const tokenResponse = await this._client.getAccessToken();
+            this._accessToken = tokenResponse.token || tokenResponse;
+            this._expiresAt = Date.now() + this.config.tokenRefreshIntervalMs;
+            this.logger.info('Access token refreshed successfully');
+        } catch (err) {
+            this.logger.error(`Failed to refresh token: ${err.message}`);
+            throw err;
+        }
+    }
+
+    _startRefreshLoop() {
+        // Refresh every tokenRefreshIntervalMs (50 min by default)
+        this._refreshTimer = setInterval(async () => {
+            try {
+                await this._refreshToken();
+            } catch (err) {
+                this.logger.error(`Background token refresh failed: ${err.message}`);
+            }
+        }, this.config.tokenRefreshIntervalMs);
+
+        // Don't let the timer block process exit
+        if (this._refreshTimer.unref) {
+            this._refreshTimer.unref();
+        }
+    }
+}