@relayrail/server 0.1.5 → 0.1.7

package/README.md

@@ -6,7 +6,7 @@ RelayRail MCP Server - SMS and email connectivity for AI agents via Model Contex
 
 ```bash
 # Use with npx (recommended)
-npx @relayrail/server start
+npx @relayrail/server
 
 # Or install globally
 npm install -g @relayrail/server
@@ -23,21 +23,21 @@ Sign up at [relayrail.dev](https://relayrail.dev) and create an agent to get you
 **Claude Code (CLI):**
 
 ```bash
-claude mcp add --transport stdio relayrail \
-  --env RELAYRAIL_API_KEY=rr_your_api_key \
-  -- npx @relayrail/server start
+claude mcp add relayrail \
+  -e RELAYRAIL_API_KEY=rr_your_api_key \
+  -- npx @relayrail/server
 ```
 
 **Claude Desktop:**
 
-Add to `~/.config/claude/claude_desktop_config.json`:
+Add to your config file (`~/.config/claude/claude_desktop_config.json` on macOS/Linux or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
 
 ```json
 {
   "mcpServers": {
     "relayrail": {
       "command": "npx",
-      "args": ["@relayrail/server", "start"],
+      "args": ["@relayrail/server"],
       "env": {
         "RELAYRAIL_API_KEY": "rr_your_api_key"
       }
@@ -46,24 +46,57 @@ Add to `~/.config/claude/claude_desktop_config.json`:
 }
 ```
 
+**Cursor / Cline:**
+
+Same JSON format as above in your MCP settings.
+
 ## Available Tools
 
 | Tool | Description |
 |------|-------------|
-| `request_approval` | Request explicit user approval before proceeding |
-| `send_notification` | Send a one-way notification to the user |
-| `await_response` | Wait for a user response to an approval request |
+| `request_approval` | Request user approval with custom options (Yes/No or custom choices) |
+| `send_notification` | Send a one-way notification to the user (no response expected) |
+| `await_response` | Wait for a user response to a previous approval request |
 | `get_pending_commands` | Retrieve commands sent by the user via SMS/email |
 | `register_agent` | Self-register a new agent (if no API key configured) |
 | `get_account_status` | Check quota usage and account status |
 
+### Tool Parameters
+
+**`request_approval`**
+- `message` (required): The approval request message
+- `options`: Custom response options (default: `["Yes", "No"]`)
+- `severity`: `"info"` | `"warning"` | `"critical"` - affects notification priority
+- `timeout_minutes`: How long to wait for response (default: 60, max: 1440)
+- `context`: Additional context data (object)
+
+**`send_notification`**
+- `message` (required): The notification message
+- `severity`: `"info"` | `"warning"` | `"critical"`
+- `context`: Additional context data (object)
+
+**`await_response`**
+- `request_id` (required): The request_id from a previous `request_approval` call
+- `timeout_seconds`: How long to wait (default: 30, max: 300)
+
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `RELAYRAIL_API_KEY` | Yes | Your agent's API key from relayrail.dev |
-| `RELAYRAIL_API_URL` | No | Override API endpoint (default: https://www.relayrail.dev/api/mcp) |
-| `RELAYRAIL_DEBUG` | No | Enable debug logging |
+| `RELAYRAIL_BASE_URL` | No | Override API endpoint (default: https://www.relayrail.dev) |
+| `RELAYRAIL_DEBUG` | No | Enable debug logging (set to `true`) |
+
+> **Note:** You only need `RELAYRAIL_API_KEY`. The server automatically routes messages through the RelayRail API - no local Telnyx or Resend credentials required.
+
+## How It Works
+
+1. Your agent calls a tool like `request_approval`
+2. RelayRail sends an SMS or email to the user (based on their preferences)
+3. The user responds via the link or by replying directly
+4. Your agent retrieves the response with `await_response`
+
+All message delivery is handled by the RelayRail service - you don't need to configure any SMS or email providers.
 
 ## Documentation
 

package/dist/cli.js

@@ -147,7 +147,7 @@ function getApiKeyPrefix(apiKey) {
   if (!apiKey.startsWith(API_KEY_PREFIX)) {
     return "";
   }
-  return apiKey.substring(0, API_KEY_PREFIX.length + 8);
+  return apiKey.substring(0, API_KEY_PREFIX.length + 7);
 }
 async function authenticateApiKey(supabase, apiKey) {
   if (!apiKey || !apiKey.startsWith(API_KEY_PREFIX)) {
@@ -1576,16 +1576,22 @@ function createProxyRouter(config) {
 var VERSION = "0.1.0";
 var RelayRailServer = class {
   server;
-  supabase;
+  supabase = null;
   config;
   context = null;
   router = null;
   constructor(config) {
     this.config = config;
-    this.supabase = createServiceClient(config.supabaseUrl, config.supabaseServiceRoleKey);
+    const hasSupabaseCredentials = config.supabaseServiceRoleKey && config.supabaseServiceRoleKey.length > 0;
+    if (hasSupabaseCredentials) {
+      this.supabase = createServiceClient(config.supabaseUrl, config.supabaseServiceRoleKey);
+    }
     const hasEmail = !!config.resendApiKey;
     const hasSms = !!(config.telnyxApiKey && config.telnyxPhoneNumber);
     if (hasEmail || hasSms) {
+      if (!this.supabase) {
+        throw new Error("Supabase credentials required when using local email/SMS configuration");
+      }
       this.router = createRouter(
         {
           baseUrl: config.baseUrl,
@@ -1605,7 +1611,6 @@ var RelayRailServer = class {
         this.supabase
       );
     } else if (config.apiKey) {
-      console.log("[RelayRail] Using proxy router for message delivery");
       this.router = createProxyRouter({
         apiUrl: config.baseUrl,
         apiKey: config.apiKey
@@ -1617,6 +1622,26 @@ var RelayRailServer = class {
     });
     this.registerTools();
   }
+  /**
+   * Check if we're in proxy mode (no direct Supabase access)
+   */
+  isProxyMode() {
+    return !this.supabase && !!this.config.apiKey;
+  }
+  /**
+   * Make a proxy API call
+   */
+  async proxyApiCall(endpoint, body) {
+    const response = await fetch(`${this.config.baseUrl}/api/mcp/${endpoint}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.config.apiKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    return response.json();
+  }
   /**
    * Register all MCP tools
    */
@@ -1638,6 +1663,12 @@ var RelayRailServer = class {
           };
         }
         try {
+          if (this.isProxyMode()) {
+            const result2 = await this.proxyApiCall("request-approval", params);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result2) }]
+            };
+          }
           const result = await requestApproval(
             params,
             {
@@ -1681,6 +1712,12 @@ var RelayRailServer = class {
           };
         }
         try {
+          if (this.isProxyMode()) {
+            const result2 = await this.proxyApiCall("send-notification", params);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result2) }]
+            };
+          }
           const result = await sendNotification(
             params,
             {
@@ -1722,6 +1759,12 @@ var RelayRailServer = class {
           };
         }
         try {
+          if (this.isProxyMode()) {
+            const result2 = await this.proxyApiCall("await-response", params);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result2) }]
+            };
+          }
           const result = await awaitResponse(
             params,
             {
@@ -1875,6 +1918,12 @@ var RelayRailServer = class {
   getContext() {
     return this.context;
   }
+  /**
+   * Set authentication context directly (from pre-validated API key)
+   */
+  setAuthContext(context) {
+    this.context = context;
+  }
   /**
    * Get the underlying MCP server instance
    */
@@ -1882,7 +1931,7 @@ var RelayRailServer = class {
     return this.server;
   }
   /**
-   * Get the Supabase client
+   * Get the Supabase client (may be null in proxy mode)
    */
   getSupabase() {
     return this.supabase;
@@ -1906,6 +1955,23 @@ function createServer(config) {
 }
 
 // src/cli.ts
+async function validateApiKey(apiKey, baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/api/auth/validate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ api_key: apiKey })
+    });
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    return {
+      valid: false,
+      error: `Failed to connect to RelayRail API: ${error instanceof Error ? error.message : "Unknown error"}`,
+      hint: "Check your internet connection and try again."
+    };
+  }
+}
 async function main() {
   const apiKey = process.env.RELAYRAIL_API_KEY;
   if (!apiKey) {
@@ -1927,25 +1993,69 @@ async function main() {
     }, null, 2));
     process.exit(1);
   }
+  const baseUrl = process.env.RELAYRAIL_BASE_URL || "https://www.relayrail.dev";
+  const validation = await validateApiKey(apiKey, baseUrl);
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error || "Invalid API key"}`);
+    if (validation.hint) {
+      console.error(`Hint: ${validation.hint}`);
+    }
+    console.error("");
+    console.error("Get a new API key from https://relayrail.dev/dashboard/agents");
+    process.exit(1);
+  }
   const config = {
     supabaseUrl: process.env.SUPABASE_URL || process.env.NEXT_PUBLIC_SUPABASE_URL || "https://lcmdokppykqmigqcwnol.supabase.co",
-    supabaseServiceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY || "sb_secret_cj-1Y1KxjlapuwyXvfSKLA_xBJ0oS8i",
-    baseUrl: process.env.RELAYRAIL_BASE_URL || "https://www.relayrail.dev",
+    supabaseServiceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY || "",
+    baseUrl,
     resendApiKey: process.env.RESEND_API_KEY,
     telnyxApiKey: process.env.TELNYX_API_KEY,
     telnyxPhoneNumber: process.env.TELNYX_PHONE_NUMBER,
-    apiKey
+    apiKey,
     // Used for proxy routing when local email/SMS credentials unavailable
+    // Pre-validated context from hosted endpoint
+    validatedAgent: validation.agent,
+    validatedUser: validation.user
   };
   try {
     const server = createServer(config);
-    const authenticated = await server.authenticate(apiKey);
-    if (!authenticated) {
-      console.error("Error: Invalid API key");
-      console.error("");
-      console.error("Please check your RELAYRAIL_API_KEY and try again.");
-      console.error("Get a new API key from https://relayrail.dev/dashboard/agents");
-      process.exit(1);
+    if (validation.agent && validation.user) {
+      const agent = {
+        id: validation.agent.id,
+        name: validation.agent.name,
+        user_id: validation.agent.user_id,
+        is_active: validation.agent.is_active,
+        created_at: validation.agent.created_at,
+        // These fields are not needed for tool operations but required by type
+        api_key_hash: "",
+        api_key_prefix: "",
+        last_seen_at: null,
+        metadata: {}
+      };
+      const user = {
+        id: validation.user.id,
+        email: validation.user.email,
+        phone: validation.user.phone,
+        tier: validation.user.tier,
+        notification_preferences: validation.user.notification_preferences,
+        allow_email_overage: validation.user.allow_email_overage,
+        allow_sms_overage: validation.user.allow_sms_overage,
+        // These fields are not needed for tool operations but required by type
+        stripe_customer_id: null,
+        email_verified: true,
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        updated_at: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      server.setAuthContext({ agent, user });
+    } else {
+      const authenticated = await server.authenticate(apiKey);
+      if (!authenticated) {
+        console.error("Error: Invalid API key");
+        console.error("");
+        console.error("Please check your RELAYRAIL_API_KEY and try again.");
+        console.error("Get a new API key from https://relayrail.dev/dashboard/agents");
+        process.exit(1);
+      }
     }
     await server.start();
   } catch (error) {

package/dist/index.d.ts

@@ -239,6 +239,14 @@ declare class RelayRailServer {
     private context;
     private router;
     constructor(config: ServerConfig);
+    /**
+     * Check if we're in proxy mode (no direct Supabase access)
+     */
+    private isProxyMode;
+    /**
+     * Make a proxy API call
+     */
+    private proxyApiCall;
     /**
      * Register all MCP tools
      */
@@ -251,14 +259,18 @@ declare class RelayRailServer {
      * Get the current authentication context
      */
     getContext(): ToolContext | null;
+    /**
+     * Set authentication context directly (from pre-validated API key)
+     */
+    setAuthContext(context: ToolContext): void;
     /**
      * Get the underlying MCP server instance
      */
     getMcpServer(): McpServer;
     /**
-     * Get the Supabase client
+     * Get the Supabase client (may be null in proxy mode)
      */
-    getSupabase(): TypedSupabaseClient;
+    getSupabase(): TypedSupabaseClient | null;
     /**
      * Get the server configuration
      */

package/dist/index.js

@@ -145,7 +145,7 @@ function getApiKeyPrefix(apiKey) {
   if (!apiKey.startsWith(API_KEY_PREFIX)) {
     return "";
   }
-  return apiKey.substring(0, API_KEY_PREFIX.length + 8);
+  return apiKey.substring(0, API_KEY_PREFIX.length + 7);
 }
 async function authenticateApiKey(supabase, apiKey) {
   if (!apiKey || !apiKey.startsWith(API_KEY_PREFIX)) {
@@ -1574,16 +1574,22 @@ function createProxyRouter(config) {
 var VERSION = "0.1.0";
 var RelayRailServer = class {
   server;
-  supabase;
+  supabase = null;
   config;
   context = null;
   router = null;
   constructor(config) {
     this.config = config;
-    this.supabase = createServiceClient(config.supabaseUrl, config.supabaseServiceRoleKey);
+    const hasSupabaseCredentials = config.supabaseServiceRoleKey && config.supabaseServiceRoleKey.length > 0;
+    if (hasSupabaseCredentials) {
+      this.supabase = createServiceClient(config.supabaseUrl, config.supabaseServiceRoleKey);
+    }
     const hasEmail = !!config.resendApiKey;
     const hasSms = !!(config.telnyxApiKey && config.telnyxPhoneNumber);
     if (hasEmail || hasSms) {
+      if (!this.supabase) {
+        throw new Error("Supabase credentials required when using local email/SMS configuration");
+      }
       this.router = createRouter(
         {
           baseUrl: config.baseUrl,
@@ -1603,7 +1609,6 @@ var RelayRailServer = class {
         this.supabase
       );
     } else if (config.apiKey) {
-      console.log("[RelayRail] Using proxy router for message delivery");
       this.router = createProxyRouter({
         apiUrl: config.baseUrl,
         apiKey: config.apiKey
@@ -1615,6 +1620,26 @@ var RelayRailServer = class {
     });
     this.registerTools();
   }
+  /**
+   * Check if we're in proxy mode (no direct Supabase access)
+   */
+  isProxyMode() {
+    return !this.supabase && !!this.config.apiKey;
+  }
+  /**
+   * Make a proxy API call
+   */
+  async proxyApiCall(endpoint, body) {
+    const response = await fetch(`${this.config.baseUrl}/api/mcp/${endpoint}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.config.apiKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    return response.json();
+  }
   /**
    * Register all MCP tools
    */
@@ -1636,6 +1661,12 @@ var RelayRailServer = class {
           };
         }
         try {
+          if (this.isProxyMode()) {
+            const result2 = await this.proxyApiCall("request-approval", params);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result2) }]
+            };
+          }
           const result = await requestApproval(
             params,
             {
@@ -1679,6 +1710,12 @@ var RelayRailServer = class {
           };
         }
         try {
+          if (this.isProxyMode()) {
+            const result2 = await this.proxyApiCall("send-notification", params);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result2) }]
+            };
+          }
           const result = await sendNotification(
             params,
             {
@@ -1720,6 +1757,12 @@ var RelayRailServer = class {
           };
         }
         try {
+          if (this.isProxyMode()) {
+            const result2 = await this.proxyApiCall("await-response", params);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result2) }]
+            };
+          }
           const result = await awaitResponse(
             params,
             {
@@ -1873,6 +1916,12 @@ var RelayRailServer = class {
   getContext() {
     return this.context;
   }
+  /**
+   * Set authentication context directly (from pre-validated API key)
+   */
+  setAuthContext(context) {
+    this.context = context;
+  }
   /**
    * Get the underlying MCP server instance
    */
@@ -1880,7 +1929,7 @@ var RelayRailServer = class {
     return this.server;
   }
   /**
-   * Get the Supabase client
+   * Get the Supabase client (may be null in proxy mode)
    */
   getSupabase() {
     return this.supabase;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayrail/server",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "RelayRail MCP Server - SMS/Email connectivity for AI agents",
   "type": "module",
   "main": "./dist/index.js",