@prompteryx/mcp-server 1.0.1

package/README.md

@@ -0,0 +1,271 @@
+# @prompteryx/mcp-server
+
+**The most feature-rich browser automation MCP server.** Control web browsers, run workflows, send emails, manage spreadsheets, and more — all from your favourite AI assistant.
+
+Works with **Claude Desktop, ChatGPT, Cursor, VS Code, Gemini CLI**, and 400+ other MCP clients.
+
+---
+
+## Quick Start (5 minutes)
+
+### 1. Get your API key
+
+1. Log in at [prompteryx.ai](https://www.prompteryx.ai)
+2. Go to **Settings → API Keys**
+3. Click **Create API Key** and copy it (starts with `px_key_`)
+
+### 2. Add to your AI tool
+
+**Claude Desktop** — edit `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "prompteryx": {
+      "command": "npx",
+      "args": ["@prompteryx/mcp-server@latest"],
+      "env": { "PROMPTERYX_API_KEY": "px_key_YOUR_KEY_HERE" }
+    }
+  }
+}
+```
+
+**Cursor** — create `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "prompteryx": {
+      "command": "npx",
+      "args": ["@prompteryx/mcp-server@latest"],
+      "env": { "PROMPTERYX_API_KEY": "px_key_YOUR_KEY_HERE" }
+    }
+  }
+}
+```
+
+**VS Code** — add to `.vscode/settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "prompteryx": {
+        "command": "npx",
+        "args": ["@prompteryx/mcp-server@latest"],
+        "env": { "PROMPTERYX_API_KEY": "px_key_YOUR_KEY_HERE" }
+      }
+    }
+  }
+}
+```
+
+**ChatGPT** — via MCP connectors:
+
+```
+Server URL: https://www.prompteryx.ai/api/mcp
+API Key:    px_key_YOUR_KEY_HERE
+```
+
+**Gemini CLI**:
+
+```bash
+gemini --mcp-server="npx @prompteryx/mcp-server" \
+       --mcp-env="PROMPTERYX_API_KEY=px_key_YOUR_KEY_HERE"
+```
+
+### 3. Start using it
+
+Just ask your AI assistant:
+
+- *"Go to amazon.com and find wireless headphones under £50"*
+- *"Take a screenshot of the current page"*
+- *"Send an email via Gmail to john@example.com with subject 'Meeting tomorrow'"*
+- *"Read the data from my Google Sheet"*
+- *"Create a Prompteryx workflow that monitors Gmail and posts to Slack"*
+- *"Run my 'Daily Report' workflow"*
+
+---
+
+## What You Can Do
+
+### Browser Automation (21 tools)
+
+Navigate websites, click buttons, fill forms, extract data, take screenshots, generate PDFs, manage cookies, upload files, execute JavaScript, and more.
+
+All browser actions run in a **cloud browser** by default — nothing to install locally.
+
+| Tool | Description |
+|------|-------------|
+| `browser_navigate` | Go to a URL |
+| `browser_click` | Click an element |
+| `browser_fill` | Fill an input field |
+| `browser_type` | Type text character by character |
+| `browser_press_key` | Press keyboard keys (Enter, Tab, etc.) |
+| `browser_select` | Select a dropdown option |
+| `browser_check` | Check/uncheck a checkbox |
+| `browser_hover` | Hover over an element |
+| `browser_scroll` | Scroll the page or to an element |
+| `browser_extract_text` | Get text content from an element |
+| `browser_extract_attribute` | Get an HTML attribute (href, src, etc.) |
+| `browser_screenshot` | Take a screenshot (returns image) |
+| `browser_evaluate` | Run JavaScript in the page |
+| `browser_wait` | Wait for elements, timeouts, or navigation |
+| `browser_get_page_info` | Get current URL and title |
+| `browser_drag_drop` | Drag and drop elements |
+| `browser_set_files` | Upload files |
+| `browser_get_cookies` | Read cookies |
+| `browser_set_cookies` | Set cookies |
+| `browser_pdf` | Generate a PDF of the page |
+| `browser_close` | Close the browser session |
+
+### AI Browser Agent
+
+Give natural language instructions and let the AI see the screen and act:
+
+| Tool | Description |
+|------|-------------|
+| `browser_ai_action` | "Log in and download the monthly report" — the AI figures out the clicks, scrolls, and typing |
+
+Uses Google Gemini Computer Use. Actions are recorded so you can replay them without AI costs.
+
+### Workflows (unique — no other MCP server has this)
+
+| Tool | Description |
+|------|-------------|
+| `workflow_list` | List your saved workflows |
+| `workflow_get` | Get workflow details |
+| `workflow_execute` | Run a saved workflow |
+| `workflow_create` | Create a workflow (from nodes or natural language) |
+| `workflow_delete` | Delete a workflow |
+| `workflow_add_node` | Add a node to an existing workflow |
+| `workflow_record_actions` | Record browser actions → save as reusable workflow |
+
+### Integrations
+
+Automatically available for services you've connected on [prompteryx.ai/connections](https://www.prompteryx.ai/connections):
+
+- **Gmail** — send, read, search emails
+- **Google Sheets** — read, append, update data
+- **Google Calendar** — create, list events
+- **Google Drive** — upload, download, list files
+- **Google Docs** — create, read documents
+- **Slack** — send messages, manage channels
+- **Notion** — create pages, manage databases
+- **Airtable** — CRUD operations on bases
+- **Microsoft Outlook, Excel, Word, SharePoint, Teams**
+- **Telegram, WhatsApp, Facebook, Instagram, YouTube**
+- **WordPress** — create posts, manage content
+- **Stripe** — customers, charges, invoices
+- **OpenAI, Anthropic, Gemini, ElevenLabs** — AI model calls
+- More added regularly — new integrations appear automatically
+
+### Data Tools (zero cost, run locally)
+
+| Tool | Description |
+|------|-------------|
+| `transform_json` | Parse, query, transform JSON data |
+| `generate_uuid` | Generate a UUID |
+| `base64_encode` | Encode text to Base64 |
+| `base64_decode` | Decode Base64 to text |
+| `format_date` | Format dates and timestamps |
+| `math_operation` | Evaluate math expressions |
+
+### Resources
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Workflows | `prompteryx://workflows` | Your saved workflows |
+| Connections | `prompteryx://connections` | Connected OAuth services |
+| Usage | `prompteryx://usage` | Current usage stats and limits |
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PROMPTERYX_API_KEY` | Yes | — | Your API key (from Settings → API Keys) |
+| `PROMPTERYX_API_URL` | No | `https://www.prompteryx.ai` | API base URL |
+| `PROMPTERYX_EXECUTION_MODE` | No | `cloud` | `cloud` or `local` |
+| `PROMPTERYX_CHROME_PROFILE` | No | — | Chrome profile ID (local mode only) |
+| `PROMPTERYX_SESSION_TIMEOUT` | No | `300000` | Session idle timeout in ms |
+| `PROMPTERYX_STEALTH_MODE` | No | `true` | Bypass bot detection (Patchright) |
+| `PROMPTERYX_VIDEO_RECORDING` | No | `false` | Record browser sessions |
+
+---
+
+## Local Browser Mode (optional)
+
+For using your own Chrome profiles with saved logins:
+
+1. Download the **Prompteryx Desktop App** from [prompteryx.ai/download](https://www.prompteryx.ai/download)
+2. Install and launch it (runs in the system tray)
+3. Add to your config:
+
+```json
+"env": {
+  "PROMPTERYX_API_KEY": "px_key_...",
+  "PROMPTERYX_EXECUTION_MODE": "local",
+  "PROMPTERYX_CHROME_PROFILE": "your-profile-id"
+}
+```
+
+---
+
+## Pricing
+
+MCP usage is included in your Prompteryx subscription:
+
+| | Free | Starter (£20/mo) | Pro (£45/mo) | Enterprise |
+|---|---|---|---|---|
+| Browser tools | 1,500/mo | 3,000/mo | 12,000/mo | Custom |
+| Cloud browser | — | 60 min | 300 min | 1,200 min |
+| AI credits | 50 | 500 | 1,500 | Custom |
+| Integrations | 3 services | All | All | All |
+| Workflow execution | Limited | Unlimited | Unlimited | Unlimited |
+| Workflow creation | — | Yes | Yes | Yes |
+| Record to workflow | — | Yes | Yes | Yes |
+| Stealth mode | — | Yes | Yes | Yes |
+| Video recording | — | — | Yes | Yes |
+
+---
+
+## How It Compares
+
+| Feature | Prompteryx | Playwright MCP | Zapier MCP | Puppeteer MCP |
+|---------|-----------|---------------|-----------|--------------|
+| Browser automation | 21 tools | 13 tools | None | 8 tools |
+| Cloud browser | Yes | No | No | No |
+| Chrome profiles | Yes | No | No | No |
+| AI browser agent | Yes | No | No | No |
+| Stealth mode | Yes | No | No | No |
+| Integrations | 20+ | None | 8,000+ | None |
+| Workflow builder | Yes | No | No | No |
+| Action recording | Yes | No | No | No |
+| Screenshots | Visual | Text-only | N/A | Yes |
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "API key invalid" | Verify key starts with `px_key_` and is active in Settings |
+| "Cloud browser minutes exceeded" | Upgrade your plan or use `PROMPTERYX_EXECUTION_MODE=local` |
+| "Integration not available" | Connect the service at [prompteryx.ai/connections](https://www.prompteryx.ai/connections) |
+| "Session disconnected" | The server auto-recovers — just retry your request |
+| "AI credits exhausted" | Purchase more at Settings → AI Credits |
+| Server not starting | Ensure Node.js 18+ is installed: `node --version` |
+
+---
+
+## Support
+
+- Website: [prompteryx.ai](https://www.prompteryx.ai)
+- Documentation: [docs.prompteryx.ai](https://docs.prompteryx.ai)
+- Email: support@prompteryx.ai
+
+## License
+
+MIT

package/dist/auth/api-key-auth.d.ts

@@ -0,0 +1,51 @@
+/**
+ * API Key Authentication
+ *
+ * Validates the Prompteryx API key against the platform API
+ * and returns a full auth context with user info, subscription tier,
+ * usage stats, credentials, and workflows.
+ */
+export interface CredentialSummary {
+    id: string;
+    connectorId: string;
+    name: string;
+    isValid: boolean;
+}
+export interface WorkflowSummary {
+    id: string;
+    name: string;
+    description?: string;
+    nodeCount: number;
+    lastRun?: string;
+}
+export interface MonthlyUsage {
+    executions: number;
+    cloudBrowserMinutes: number;
+    aiCreditsUsed: number;
+}
+export interface AuthContext {
+    userId: string;
+    email: string;
+    apiKeyId: string;
+    scopes: string[];
+    subscriptionTier: 'free' | 'starter' | 'pro' | 'enterprise';
+    aiCreditsIncluded: number;
+    aiCreditsUsedThisMonth: number;
+    cloudBrowserMinutesAllowed: number;
+    monthlyExecutionsAllowed: number;
+    monthlyUsage: MonthlyUsage;
+    credentials: CredentialSummary[];
+    workflows: WorkflowSummary[];
+    browserbaseContextId?: string;
+}
+export declare class AuthError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode?: number);
+}
+export declare function authenticate(apiKey: string, apiUrl: string): Promise<AuthContext>;
+/**
+ * Refreshes usage data from the platform.
+ * Called periodically to keep limits in sync.
+ */
+export declare function refreshAuthContext(apiKey: string, apiUrl: string): Promise<AuthContext>;
+//# sourceMappingURL=api-key-auth.d.ts.map

package/dist/auth/api-key-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-auth.d.ts","sourceRoot":"","sources":["../../src/auth/api-key-auth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,YAAY,CAAC;IAC5D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,0BAA0B,EAAE,MAAM,CAAC;IACnC,wBAAwB,EAAE,MAAM,CAAC;IACjC,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,SAAU,SAAQ,KAAK;IACE,UAAU,EAAE,MAAM;gBAA1C,OAAO,EAAE,MAAM,EAAS,UAAU,GAAE,MAAY;CAI7D;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA8BvF;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAE7F"}

package/dist/auth/api-key-auth.js

@@ -0,0 +1,50 @@
+/**
+ * API Key Authentication
+ *
+ * Validates the Prompteryx API key against the platform API
+ * and returns a full auth context with user info, subscription tier,
+ * usage stats, credentials, and workflows.
+ */
+export class AuthError extends Error {
+    statusCode;
+    constructor(message, statusCode = 401) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'AuthError';
+    }
+}
+export async function authenticate(apiKey, apiUrl) {
+    if (!apiKey) {
+        throw new AuthError('PROMPTERYX_API_KEY environment variable is required');
+    }
+    const response = await fetch(`${apiUrl}/api/v1/auth/validate`, {
+        method: 'GET',
+        headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/json',
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        if (response.status === 401) {
+            throw new AuthError('Invalid API key. Generate one at prompteryx.ai → Settings → API Keys.');
+        }
+        if (response.status === 403) {
+            throw new AuthError('API key does not have required scopes. Ensure workflows.execute and executions.create are enabled.');
+        }
+        throw new AuthError(`Authentication failed (${response.status}): ${body}`, response.status);
+    }
+    const data = await response.json();
+    if (!data.success || !data.data) {
+        throw new AuthError('Unexpected response from auth endpoint');
+    }
+    return data.data;
+}
+/**
+ * Refreshes usage data from the platform.
+ * Called periodically to keep limits in sync.
+ */
+export async function refreshAuthContext(apiKey, apiUrl) {
+    return authenticate(apiKey, apiUrl);
+}
+//# sourceMappingURL=api-key-auth.js.map

package/dist/auth/api-key-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-auth.js","sourceRoot":"","sources":["../../src/auth/api-key-auth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuCH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACE;IAApC,YAAY,OAAe,EAAS,aAAqB,GAAG;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,eAAU,GAAV,UAAU,CAAc;QAE1D,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAc,EAAE,MAAc;IAC/D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,uBAAuB,EAAE;QAC7D,MAAM,EAAE,KAAK;QACb,OAAO,EAAE;YACP,WAAW,EAAE,MAAM;YACnB,cAAc,EAAE,kBAAkB;SACnC;KACF,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,SAAS,CAAC,uEAAuE,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,SAAS,CAAC,oGAAoG,CAAC,CAAC;QAC5H,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,0BAA0B,QAAQ,CAAC,MAAM,MAAM,IAAI,EAAE,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,IAAI,CAAC,IAAmB,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAc,EAAE,MAAc;IACrE,OAAO,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC"}

package/dist/auth/usage-enforcer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Usage Enforcement
+ *
+ * Pre-checks subscription limits before every tool call and
+ * records usage after successful execution.
+ * Mirrors the checks in lib/subscription-config.ts and
+ * app/api/cloud-execute/route.ts from the main platform.
+ */
+import type { AuthContext } from './api-key-auth.js';
+export type ToolCategory = 'browser' | 'ai-agent' | 'integration' | 'workflow' | 'data';
+export interface UsageCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+export declare function getTierFeatures(tier: string): {
+    cloudBrowser: boolean;
+    aiAgent: boolean;
+    stealth: boolean;
+    videoRecording: boolean;
+    debugUrl: boolean;
+    workflowCreate: boolean;
+    recordToWorkflow: boolean;
+    maxIntegrationServices: number;
+};
+export declare function enforceUsageLimits(auth: AuthContext, category: ToolCategory, executionMode?: 'cloud' | 'local'): UsageCheckResult;
+/**
+ * Records usage by calling the platform API.
+ * This increments the user's Firestore counters server-side.
+ */
+export declare function recordUsage(apiKey: string, apiUrl: string, usage: {
+    cloudBrowserMinutes?: number;
+    aiCreditsUsed?: number;
+    executionCount?: number;
+}): Promise<void>;
+export declare function formatUsageRemaining(auth: AuthContext): {
+    cloudBrowserMinutes: number;
+    aiCredits: number;
+    executions: number;
+};
+//# sourceMappingURL=usage-enforcer.d.ts.map

package/dist/auth/usage-enforcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-enforcer.d.ts","sourceRoot":"","sources":["../../src/auth/usage-enforcer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAExF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsDD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM;kBAnD5B,OAAO;aACZ,OAAO;aACP,OAAO;oBACA,OAAO;cACb,OAAO;oBACD,OAAO;sBACL,OAAO;4BACD,MAAM;EA8C/B;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,YAAY,EACtB,aAAa,GAAE,OAAO,GAAG,OAAiB,GACzC,gBAAgB,CA2DlB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE;IACL,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW;;;;EAMrD"}

package/dist/auth/usage-enforcer.js

@@ -0,0 +1,134 @@
+/**
+ * Usage Enforcement
+ *
+ * Pre-checks subscription limits before every tool call and
+ * records usage after successful execution.
+ * Mirrors the checks in lib/subscription-config.ts and
+ * app/api/cloud-execute/route.ts from the main platform.
+ */
+const TIER_FEATURES = {
+    free: {
+        cloudBrowser: false,
+        aiAgent: true,
+        stealth: false,
+        videoRecording: false,
+        debugUrl: false,
+        workflowCreate: false,
+        recordToWorkflow: false,
+        maxIntegrationServices: 3,
+    },
+    starter: {
+        cloudBrowser: true,
+        aiAgent: true,
+        stealth: true,
+        videoRecording: false,
+        debugUrl: true,
+        workflowCreate: true,
+        recordToWorkflow: true,
+        maxIntegrationServices: Infinity,
+    },
+    pro: {
+        cloudBrowser: true,
+        aiAgent: true,
+        stealth: true,
+        videoRecording: true,
+        debugUrl: true,
+        workflowCreate: true,
+        recordToWorkflow: true,
+        maxIntegrationServices: Infinity,
+    },
+    enterprise: {
+        cloudBrowser: true,
+        aiAgent: true,
+        stealth: true,
+        videoRecording: true,
+        debugUrl: true,
+        workflowCreate: true,
+        recordToWorkflow: true,
+        maxIntegrationServices: Infinity,
+    },
+};
+export function getTierFeatures(tier) {
+    return TIER_FEATURES[tier] ?? TIER_FEATURES.free;
+}
+export function enforceUsageLimits(auth, category, executionMode = 'cloud') {
+    const features = getTierFeatures(auth.subscriptionTier);
+    // Browser tools using cloud need cloud minutes
+    if (category === 'browser' && executionMode === 'cloud') {
+        if (!features.cloudBrowser) {
+            return {
+                allowed: false,
+                reason: 'Cloud browser is not available on the Free plan. Upgrade to Starter (£20/mo) or use local mode with the Prompteryx Desktop App.',
+            };
+        }
+        if (auth.monthlyUsage.cloudBrowserMinutes >= auth.cloudBrowserMinutesAllowed) {
+            return {
+                allowed: false,
+                reason: `Cloud browser minutes exceeded (${auth.monthlyUsage.cloudBrowserMinutes}/${auth.cloudBrowserMinutesAllowed}). Upgrade your plan or switch to local execution mode.`,
+            };
+        }
+    }
+    // AI agent needs credits
+    if (category === 'ai-agent') {
+        const remaining = auth.aiCreditsIncluded - auth.aiCreditsUsedThisMonth;
+        if (remaining <= 0) {
+            return {
+                allowed: false,
+                reason: 'AI credits exhausted. Purchase more at prompteryx.ai → Settings → AI Credits, or upgrade your plan.',
+            };
+        }
+        if (executionMode === 'cloud' && !features.cloudBrowser) {
+            return {
+                allowed: false,
+                reason: 'AI Browser Agent requires cloud browser access. Upgrade to Starter or higher.',
+            };
+        }
+    }
+    // Workflow execution counts
+    if (category === 'workflow') {
+        if (auth.monthlyUsage.executions >= auth.monthlyExecutionsAllowed) {
+            return {
+                allowed: false,
+                reason: `Monthly execution limit reached (${auth.monthlyUsage.executions}/${auth.monthlyExecutionsAllowed}). Upgrade your plan for more executions.`,
+            };
+        }
+    }
+    // Integration calls count as executions
+    if (category === 'integration') {
+        if (auth.monthlyUsage.executions >= auth.monthlyExecutionsAllowed) {
+            return {
+                allowed: false,
+                reason: `Monthly execution limit reached (${auth.monthlyUsage.executions}/${auth.monthlyExecutionsAllowed}).`,
+            };
+        }
+    }
+    // Data tools are always allowed (run locally, zero cost)
+    return { allowed: true };
+}
+/**
+ * Records usage by calling the platform API.
+ * This increments the user's Firestore counters server-side.
+ */
+export async function recordUsage(apiKey, apiUrl, usage) {
+    try {
+        await fetch(`${apiUrl}/api/v1/usage/record`, {
+            method: 'POST',
+            headers: {
+                'X-API-Key': apiKey,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(usage),
+        });
+    }
+    catch {
+        // Best-effort — don't block the tool call on usage recording failure
+    }
+}
+export function formatUsageRemaining(auth) {
+    return {
+        cloudBrowserMinutes: auth.cloudBrowserMinutesAllowed - auth.monthlyUsage.cloudBrowserMinutes,
+        aiCredits: auth.aiCreditsIncluded - auth.aiCreditsUsedThisMonth,
+        executions: auth.monthlyExecutionsAllowed - auth.monthlyUsage.executions,
+    };
+}
+//# sourceMappingURL=usage-enforcer.js.map

package/dist/auth/usage-enforcer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-enforcer.js","sourceRoot":"","sources":["../../src/auth/usage-enforcer.ts"],"names":[],"mappings":"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"}

package/dist/execution/cloud-executor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Cloud Executor
+ *
+ * Executes browser node operations on a cloud Browserbase session
+ * by calling individual node actions against the active Playwright page.
+ * Mirrors the logic from lib/node-executor.ts executeNode().
+ */
+import type { Page } from 'playwright-core';
+import { type McpToolResult } from '../utils/output-formatter.js';
+/**
+ * Core browser action executor.
+ * Takes a Playwright Page and a command with params,
+ * then executes the corresponding browser action.
+ */
+export declare function executeBrowserAction(page: Page, action: string, params: Record<string, any>): Promise<McpToolResult>;
+//# sourceMappingURL=cloud-executor.d.ts.map

package/dist/execution/cloud-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-executor.d.ts","sourceRoot":"","sources":["../../src/execution/cloud-executor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAItC;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,OAAO,CAAC,aAAa,CAAC,CAsNxB"}