---
description: Add a new API/service integration with OAuth flow and MCP tools to ScopeGate
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, WebSearch, WebFetch
---

## Context

ScopeGate is an MCP gateway that connects AI agents to third-party APIs via OAuth. Each integration requires:
1. An OAuth module (`src/lib/{provider}-oauth.ts`)
2. OAuth route handlers (`src/app/api/oauth/{provider}/route.ts` + `callback/route.ts`)
3. An MCP API wrapper (`src/lib/mcp/{provider}.ts`)
4. MCP tool definitions (`src/lib/mcp/tools.ts`)
5. Permission groups (`src/lib/mcp/permissions.ts`)
6. UI updates for service connection (`src/components/`)

The user will specify which API/service to add. Use `$ARGUMENTS` for the service name.

## Your Task

Add a complete API integration for the specified service.

### Steps

1. **Research the API auth flow**
   - Search the web for the service's OAuth documentation
   - Identify: auth URL, token URL, required scopes, token refresh mechanism
   - Check if it uses OAuth 2.0, OAuth 1.0a, or API key auth
   - Determine token expiration and refresh strategy

2. **Study existing patterns**
   - Read a similar existing OAuth module (e.g., `src/lib/threads-oauth.ts` for simple OAuth 2.0, `src/lib/google-oauth.ts` for refresh token flows)
   - Read the corresponding callback route in `src/app/api/oauth/`
   - Read the MCP wrapper in `src/lib/mcp/`
   - Note the structure and follow it exactly

3. **Implement OAuth module** (`src/lib/{provider}-oauth.ts`)
   - `buildAuthUrl()` — construct OAuth authorization URL with correct scopes
   - `exchangeCodeForTokens()` — exchange auth code for access (and refresh) tokens
   - `getUserInfo()` — fetch authenticated user info for the account label
   - `getValidAccessToken()` — retrieve + auto-refresh token from DB
   - Add env vars: `{PROVIDER}_CLIENT_ID`, `{PROVIDER}_CLIENT_SECRET`

4. **Implement OAuth routes**
   - `src/app/api/oauth/{provider}/route.ts` — initiate OAuth flow (redirect to auth URL)
   - `src/app/api/oauth/{provider}/callback/route.ts` — handle callback, store tokens in DB

5. **Implement MCP wrapper** (`src/lib/mcp/{provider}.ts`)
   - Create `{provider}Fetch()` function that handles auth and API calls
   - Follow the pattern from existing wrappers (e.g., `src/lib/mcp/twitter.ts`)

6. **Add MCP tool definitions** (`src/lib/mcp/tools.ts`)
   - Research ALL available API methods — add comprehensive coverage
   - Each tool needs: name, description, action, inputSchema (zod), handler
   - Follow naming convention: `{provider}_{action}` (e.g., `threads_get_profile`)

7. **Add permission groups** (`src/lib/mcp/permissions.ts`)
   - Add permission group with all tool actions
   - Follow existing structure

8. **Add to service connection UI**
   - Update provider list in `src/components/` where other providers are listed
   - Add provider logo/icon if available

9. **Update token refresh cron** (`src/app/api/cron/refresh-tokens/route.ts`)
   - Add refresh logic for the new provider if it uses refresh tokens

10. **Add .env vars to `.env.example`** if it exists

### Guardrails

- **Verify OAuth scopes against official docs** — do NOT guess scopes. Wrong scopes cause silent auth failures and confusing errors. Always web search for the exact scope names.
- **Do not create Prisma migrations** — the existing `ServiceConnection` model handles all providers.
- **Token storage**: Always encrypt tokens with `encrypt()` from `@/lib/crypto` before storing in DB.
- **Follow existing patterns exactly** — do not invent new abstractions or change the architecture.
- **Include ALL API methods available** — the user wants comprehensive coverage, not minimal.
- **Test the OAuth flow mentally** — verify redirect URIs, CSRF token handling, and error cases match existing implementations.

---
*Generated by /reflect-skills from 15+ session patterns*
