agentgate-mcp 0.2.0

package/ARCHITECTURE.md

@@ -0,0 +1,56 @@
+# AgentGate Architecture
+
+## How it works
+
+1. User runs `agentgate login` → opens Chromium → signs into Google → browser profile saved
+2. `agentgate serve` starts MCP server over stdio
+3. AI agent calls `get_or_create_key({ service, signup_url, api_key_url })`
+4. Orchestrator checks SQLite cache for an active key
+5. If cached: returns immediately
+6. If not cached: launches browser with saved Google profile
+7. Smart navigation: finds Google sign-in → authenticates → navigates to API keys → extracts key
+8. Key is stored in SQLite and returned to agent
+
+## Core modules
+
+- `src/cli.js` — CLI entry point (`login`, `serve`, `doctor`, `scaffold`)
+- `src/mcp-server.js` — MCP JSON-RPC over stdio
+- `src/orchestrator.js` — Key lifecycle: cache check → create → store
+- `src/playwright-engine.js` — Browser automation with persistent Google session
+- `src/signup-engine.js` — Logging wrapper around PlaywrightEngine
+- `src/browser-runtime.js` — Workflow DSL executor (for service recipes)
+- `src/vault.js` — AES-256-GCM encrypted local vault
+- `src/db.js` — SQLite key + alias storage
+- `src/registry.js` — Optional service recipe loader
+- `src/scaffold.js` — Recipe template generator
+- `src/logger.js` — Structured JSON logging with rotation
+
+## Two modes of key creation
+
+### Smart mode (default)
+No recipe needed. Engine uses heuristics to:
+1. Find and click Google sign-in buttons
+2. Handle OAuth popup
+3. Navigate to API keys page
+4. Click "Create API Key" buttons
+5. Extract the key from the page
+
+### Recipe mode (optional)
+For services with non-standard flows, a JSON recipe in `services/` provides
+an explicit workflow with DSL actions (goto, click, fill, extract, etc.).
+
+## Security
+
+- Browser profile stored locally in `~/.agentgate/browser-profile/`
+- Vault encrypted with AES-256-GCM (keyring + vault file)
+- SQLite database stored locally
+- API keys masked in logs (last 4 chars visible)
+- File permissions 0o600 on sensitive files
+- No cloud sync, no telemetry
+
+## MCP protocol
+
+- Version: 2024-11-05
+- Methods: `initialize`, `ping`, `tools/list`, `tools/call`
+- Notifications: `notifications/initialized`, `notifications/cancelled`
+- Tools: `get_or_create_key`, `list_my_keys`, `revoke_key`, `check_key_status`

package/MCP_TOOLS.md

@@ -0,0 +1,45 @@
+# AgentGate MCP Tools
+
+## `get_or_create_key`
+
+Works for **any** service. No pre-configuration needed.
+
+Input:
+
+```json
+{
+  "service": "twelvelabs",
+  "signup_url": "https://api.twelvelabs.io/signup",
+  "api_key_url": "https://api.twelvelabs.io/dashboard/api-keys"
+}
+```
+
+Parameters:
+- `service` (required) — Service name, used as cache key
+- `signup_url` (required) — Where to start the sign-up/login flow
+- `api_key_url` (optional) — Direct link to the API keys dashboard
+
+Behavior:
+1. Returns cached key from SQLite if one exists
+2. Otherwise opens browser with saved Google session
+3. Navigates to signup_url, finds Google sign-in, authenticates
+4. Navigates to api_key_url (if provided), creates and extracts key
+5. Caches key in SQLite and returns it
+
+## `list_my_keys`
+
+Input: `{}`
+
+Returns all API keys in the local database (active and revoked).
+
+## `revoke_key`
+
+Input: `{ "service": "openai" }`
+
+Marks the local key as revoked. Does NOT revoke it on the provider side.
+
+## `check_key_status`
+
+Input: `{ "service": "openai" }`
+
+Returns whether an active key exists. Does not create one.

package/README.md

@@ -0,0 +1,142 @@
+# AgentGate
+
+MCP server that lets AI agents get API keys for **any** service. Sign in with Google once, then your agent can create keys anywhere.
+
+## How it works
+
+1. You sign into Google in a real browser (one time)
+2. AgentGate saves that browser session
+3. When your AI agent needs an API key, AgentGate opens a browser with your Google session, signs up for the service, and extracts the key
+4. Keys are cached locally — second request is instant
+
+No hardcoded services. No config files per provider. Works for anything with "Sign in with Google".
+
+## Install
+
+```bash
+npm install -g agentgate-mcp
+```
+
+Requires Node.js 23+ (for built-in SQLite support).
+
+## Setup (one time)
+
+```bash
+agentgate login
+```
+
+This opens Chromium — sign into your Google account, then close the browser. Done.
+
+## Add to Claude Code
+
+```bash
+claude mcp add agentgate -- agentgate serve
+```
+
+Or manually add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "agentgate": {
+      "command": "agentgate",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+## Usage
+
+Just ask your AI agent naturally:
+
+- *"Get me an API key for Twelve Labs"*
+- *"I need an OpenAI key"*
+- *"Set me up with a Replicate key"*
+- *"Show all my keys"*
+- *"Revoke my openai key"*
+
+## MCP Tools
+
+### `get_or_create_key`
+
+Works for **any** service. Just provide the name and URLs.
+
+```json
+{
+  "service": "twelvelabs",
+  "signup_url": "https://api.twelvelabs.io/signup",
+  "api_key_url": "https://api.twelvelabs.io/dashboard/api-keys"
+}
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `service` | Yes | Service name (used as cache key) |
+| `signup_url` | Yes | Signup or login page URL |
+| `api_key_url` | No | Direct link to API keys dashboard |
+
+### `list_my_keys`
+
+Returns all stored keys (active and revoked).
+
+### `revoke_key`
+
+Removes a key from local store. `{ "service": "openai" }`
+
+### `check_key_status`
+
+Checks if an active key exists. `{ "service": "openai" }`
+
+## Service Recipes (optional)
+
+For services with non-standard flows, add a JSON recipe:
+
+```bash
+agentgate scaffold myservice https://myservice.com/signup
+```
+
+Most services work without a recipe.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `agentgate login` | Sign in with Google (opens browser) |
+| `agentgate serve` | Start MCP server |
+| `agentgate doctor` | Health check |
+| `agentgate scaffold <name> <url>` | Generate a service recipe |
+
+## How it stays secure
+
+- Your Google session stays on **your machine** in `~/.agentgate/browser-profile/`
+- API keys stored in local SQLite, encrypted vault uses AES-256-GCM
+- Nothing is sent to any cloud — fully local
+- No telemetry
+
+## Troubleshooting
+
+```bash
+# Check everything is working
+agentgate doctor
+
+# Check logs
+cat ~/.agentgate/logs/agentgate.log
+
+# Re-login if session expired
+agentgate login
+```
+
+## Development
+
+```bash
+git clone https://github.com/junaid-mahmood/Agent-Gate.git
+cd Agent-Gate
+npm install
+npx playwright install chromium
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "agentgate-mcp",
+  "version": "0.2.0",
+  "description": "MCP server that lets AI agents get API keys for any service via Google sign-in",
+  "type": "module",
+  "bin": {
+    "agentgate": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "services/",
+    "README.md",
+    "ARCHITECTURE.md",
+    "MCP_TOOLS.md"
+  ],
+  "scripts": {
+    "start": "node --disable-warning=ExperimentalWarning src/cli.js serve",
+    "login": "node --disable-warning=ExperimentalWarning src/cli.js login",
+    "doctor": "node --disable-warning=ExperimentalWarning src/cli.js doctor",
+    "scaffold": "node --disable-warning=ExperimentalWarning src/cli.js scaffold",
+    "test": "node --disable-warning=ExperimentalWarning --test test/run.js",
+    "postinstall": "npx playwright install chromium 2>/dev/null || echo 'Run: npx playwright install chromium'"
+  },
+  "dependencies": {
+    "playwright": "^1.55.0"
+  },
+  "engines": {
+    "node": ">=23.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "api-keys",
+    "ai-agents",
+    "claude",
+    "playwright",
+    "automation",
+    "google-sign-in",
+    "developer-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/junaid-mahmood/Agent-Gate"
+  },
+  "homepage": "https://github.com/junaid-mahmood/Agent-Gate#readme",
+  "bugs": {
+    "url": "https://github.com/junaid-mahmood/Agent-Gate/issues"
+  },
+  "author": "Junaid Mahmood",
+  "license": "MIT"
+}

package/services/_template.service.json

@@ -0,0 +1,34 @@
+{
+  "name": "replace_me",
+  "signup_url": "https://example.com/signup",
+  "requires": {
+    "google": false,
+    "card": false
+  },
+  "runtime": {
+    "headless": true
+  },
+  "workflow": [
+    { "type": "goto", "url": "{{service.signup_url}}" },
+    { "type": "wait_for", "selector": "body" },
+
+    { "type": "fill", "selector": "input[name='email']", "value": "{{generated.emailAlias}}" },
+    { "type": "fill", "selector": "input[name='password']", "value": "{{generated.password}}" },
+    { "type": "click", "selector": "button[type='submit']" },
+    { "type": "store_alias", "emailPath": "generated.emailAlias", "passwordPath": "generated.password" },
+
+    { "type": "wait_for_email_code", "target": "scratch.emailCode", "timeoutMs": 120000 },
+    { "type": "fill", "selector": "input[name='verification_code']", "value": "{{scratch.emailCode}}" },
+    { "type": "click", "selector": "button[type='submit']" },
+
+    { "type": "solve_captcha", "target": "scratch.captchaToken", "provider": "capsolver" },
+    { "type": "fill_card" },
+
+    { "type": "goto", "url": "https://example.com/dashboard/api-keys" },
+    { "type": "click", "selector": "text=Create API Key" },
+
+    { "type": "extract_text", "selector": "body", "target": "scratch.pageText" },
+    { "type": "regex_extract", "source": "scratch.pageText", "pattern": "api[_-]?key[:\\s]+([A-Za-z0-9_\\-]{20,})", "target": "result.apiKey" },
+    { "type": "assert_present", "path": "result.apiKey", "message": "API key not found in page output" }
+  ]
+}