@relayrail/server 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @relayrail/server
+
+RelayRail MCP Server - SMS and email connectivity for AI agents via Model Context Protocol.
+
+## Installation
+
+```bash
+# Use with npx (recommended)
+npx @relayrail/server start
+
+# Or install globally
+npm install -g @relayrail/server
+```
+
+## Quick Start
+
+### 1. Get your API key
+
+Sign up at [relayrail.dev](https://relayrail.dev) and create an agent to get your API key.
+
+### 2. Configure your MCP client
+
+**Claude Code (CLI):**
+
+```bash
+claude mcp add --transport stdio relayrail \
+  --env RELAYRAIL_API_KEY=rr_your_api_key \
+  -- npx @relayrail/server start
+```
+
+**Claude Desktop:**
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "relayrail": {
+      "command": "npx",
+      "args": ["@relayrail/server", "start"],
+      "env": {
+        "RELAYRAIL_API_KEY": "rr_your_api_key"
+      }
+    }
+  }
+}
+```
+
+## 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 |
+| `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 |
+
+## 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 |
+
+## Documentation
+
+Full documentation available at [relayrail.dev/docs](https://relayrail.dev/docs)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,507 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Agent, User, TypedSupabaseClient } from '@relayrail/database';
+import { Tier } from '@relayrail/shared';
+
+/**
+ * RelayRail MCP Server Types
+ */
+
+/**
+ * Server configuration options
+ */
+interface ServerConfig {
+    /** Supabase URL */
+    supabaseUrl: string;
+    /** Supabase service role key (bypasses RLS) */
+    supabaseServiceRoleKey: string;
+    /** Resend API key for email */
+    resendApiKey?: string;
+    /** Telnyx API key for SMS */
+    telnyxApiKey?: string;
+    /** Telnyx phone number for sending SMS */
+    telnyxPhoneNumber?: string;
+    /** Base URL for response pages */
+    baseUrl: string;
+}
+/**
+ * Context passed to tool handlers
+ */
+interface ToolContext {
+    /** The authenticated agent making the request */
+    agent: Agent;
+    /** The user who owns this agent */
+    user: User;
+}
+/**
+ * Auth error codes for specific failure reasons
+ */
+type AuthErrorCode = 'INVALID_FORMAT' | 'KEY_TRUNCATED' | 'KEY_NOT_FOUND' | 'KEY_INACTIVE' | 'HASH_MISMATCH' | 'USER_NOT_FOUND';
+/**
+ * Detailed auth error with code, message, and hint
+ */
+interface AuthError {
+    /** Error code for programmatic handling */
+    code: AuthErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Actionable hint for the user */
+    hint: string;
+}
+/**
+ * Result of API key authentication
+ */
+interface AuthResult {
+    success: boolean;
+    agent?: Agent;
+    user?: User;
+    /** Simple error string for backwards compatibility */
+    error?: string;
+    /** Detailed error information */
+    authError?: AuthError;
+}
+/**
+ * User context included in tool responses
+ */
+interface UserContext {
+    /** User's email address */
+    email: string;
+    /** User's subscription tier */
+    tier: 'free' | 'pro' | 'team';
+    /** Preferred notification channel */
+    preferred_channel: 'email' | 'sms';
+}
+/**
+ * Quota information included in tool responses
+ */
+interface QuotaInfo$1 {
+    /** Number of messages used this period */
+    used: number;
+    /** Included limit for the tier */
+    limit: number;
+    /** Remaining in included quota */
+    remaining: number;
+    /** Whether this message was an overage */
+    overage?: boolean;
+    /** Total overage messages this period */
+    overage_count?: number;
+    /** Overage rate in dollars */
+    overage_rate?: number;
+    /** Human-readable message */
+    message?: string;
+}
+/**
+ * Quota error when limits are exceeded and overage is disabled
+ */
+interface QuotaError$1 {
+    /** Always true when this object is present */
+    exceeded: true;
+    /** Current usage count */
+    current: number;
+    /** Included limit */
+    limit: number;
+    /** User's tier */
+    tier: 'free' | 'pro' | 'team';
+    /** Whether overage is disabled by user */
+    overage_disabled?: boolean;
+    /** Human-readable error message */
+    message: string;
+    /** URL to enable overage charges */
+    enable_overage_url?: string;
+    /** URL to upgrade tier */
+    upgradeUrl: string;
+}
+/**
+ * Approval request parameters
+ */
+interface ApprovalRequestParams {
+    /** Message to send to the user */
+    message: string;
+    /** Optional list of response options */
+    options?: string[];
+    /** Additional context data */
+    context?: Record<string, unknown>;
+    /** Timeout in minutes (default: 60, max: 1440) */
+    timeout_minutes?: number;
+    /** Severity level */
+    severity?: 'info' | 'warning' | 'critical';
+}
+/**
+ * Notification parameters
+ */
+interface NotificationParams {
+    /** Message to send to the user */
+    message: string;
+    /** Additional context data */
+    context?: Record<string, unknown>;
+    /** Severity level */
+    severity?: 'info' | 'warning' | 'critical';
+}
+/**
+ * Await response parameters
+ */
+interface AwaitResponseParams {
+    /** Request ID to wait for */
+    request_id: string;
+    /** Timeout in seconds to wait for response */
+    timeout_seconds?: number;
+}
+/**
+ * Get pending commands parameters
+ */
+interface GetPendingCommandsParams {
+    /** Maximum number of commands to return */
+    limit?: number;
+}
+/**
+ * Tool response for request_approval
+ */
+interface ApprovalResponse {
+    /** Request ID for tracking */
+    request_id: string;
+    /** Current status */
+    status: 'pending' | 'approved' | 'rejected' | 'expired' | 'blocked';
+    /** User's response if available */
+    response?: {
+        choice?: string;
+        message?: string;
+    };
+    /** When the request expires */
+    expires_at: string;
+    /** User context for the request */
+    user?: UserContext;
+    /** Quota information */
+    quota?: QuotaInfo$1;
+    /** Quota error if blocked */
+    quota_error?: QuotaError$1;
+}
+/**
+ * Tool response for send_notification
+ */
+interface NotificationResponse {
+    /** Request ID for tracking */
+    request_id: string;
+    /** Delivery status */
+    status: 'pending' | 'delivered' | 'failed' | 'blocked';
+    /** Channel used */
+    channel: 'email' | 'sms';
+    /** User context for the request */
+    user?: UserContext;
+    /** Quota information */
+    quota?: QuotaInfo$1;
+    /** Quota error if blocked */
+    quota_error?: QuotaError$1;
+}
+/**
+ * Tool response for await_response
+ */
+interface AwaitResult {
+    /** Request ID */
+    request_id: string;
+    /** Current status */
+    status: 'pending' | 'approved' | 'rejected' | 'expired';
+    /** User's response if available */
+    response?: {
+        choice?: string;
+        message?: string;
+    };
+    /** Whether the wait timed out */
+    timed_out: boolean;
+}
+/**
+ * Command from user
+ */
+interface UserCommand {
+    /** Request ID */
+    request_id: string;
+    /** Command message from user */
+    message: string;
+    /** When the command was received */
+    received_at: string;
+    /** Channel the command came from */
+    channel: 'email' | 'sms';
+}
+
+/**
+ * RelayRail MCP Server
+ * Core server implementation using Model Context Protocol SDK
+ */
+
+declare const VERSION = "0.1.0";
+/**
+ * RelayRail MCP Server
+ */
+declare class RelayRailServer {
+    private server;
+    private supabase;
+    private config;
+    private context;
+    private router;
+    constructor(config: ServerConfig);
+    /**
+     * Register all MCP tools
+     */
+    private registerTools;
+    /**
+     * Authenticate with an API key and set the context
+     */
+    authenticate(apiKey: string): Promise<boolean>;
+    /**
+     * Get the current authentication context
+     */
+    getContext(): ToolContext | null;
+    /**
+     * Get the underlying MCP server instance
+     */
+    getMcpServer(): McpServer;
+    /**
+     * Get the Supabase client
+     */
+    getSupabase(): TypedSupabaseClient;
+    /**
+     * Get the server configuration
+     */
+    getConfig(): ServerConfig;
+    /**
+     * Start the server with stdio transport
+     */
+    start(): Promise<void>;
+}
+/**
+ * Create a new RelayRail server instance
+ */
+declare function createServer(config: ServerConfig): RelayRailServer;
+
+/**
+ * RelayRail MCP Server Authentication
+ * API key validation and agent lookup
+ */
+
+/**
+ * Hash an API key for storage/comparison
+ */
+declare function hashApiKey(apiKey: string): string;
+/**
+ * Extract the prefix from an API key for lookup
+ */
+declare function getApiKeyPrefix(apiKey: string): string;
+/**
+ * Validate an API key and return the associated agent and user
+ */
+declare function authenticateApiKey(supabase: TypedSupabaseClient, apiKey: string): Promise<AuthResult>;
+/**
+ * Generate a new API key for an agent
+ */
+declare function generateApiKey(): {
+    key: string;
+    prefix: string;
+    hash: string;
+};
+
+/**
+ * Email service using Resend
+ * Handles sending approval requests and notifications via email
+ */
+
+interface EmailConfig {
+    resendApiKey: string;
+    fromEmail: string;
+    fromName: string;
+    baseUrl: string;
+    /** Inbound domain for email replies (e.g., in.relayrail.dev) */
+    inboundDomain?: string;
+}
+
+/**
+ * SMS service using Telnyx
+ * Handles sending approval requests and notifications via SMS
+ */
+
+interface SmsConfig {
+    apiKey: string;
+    fromNumber: string;
+    baseUrl: string;
+}
+
+/**
+ * Request Router
+ * Routes requests to appropriate channels (email/SMS) based on user preferences
+ * Includes quota enforcement and overage billing
+ */
+
+interface RouterConfig {
+    email: EmailConfig;
+    sms?: SmsConfig;
+    baseUrl: string;
+}
+interface RouteApprovalParams {
+    requestId: string;
+    responseToken: string;
+    message: string;
+    options?: string[];
+    expiresAt: string;
+    severity?: 'info' | 'warning' | 'critical';
+}
+interface RouteNotificationParams {
+    requestId: string;
+    message: string;
+    severity?: 'info' | 'warning' | 'critical';
+}
+interface QuotaInfo {
+    used: number;
+    limit: number;
+    remaining: number;
+    overage?: boolean;
+    overage_count?: number;
+    overage_rate?: number;
+    message?: string;
+}
+interface QuotaError {
+    exceeded: true;
+    current: number;
+    limit: number;
+    tier: Tier;
+    overage_disabled?: boolean;
+    message: string;
+    enable_overage_url?: string;
+    upgradeUrl: string;
+}
+interface RouteResult {
+    success: boolean;
+    channel: 'email' | 'sms';
+    /** Channel the user requested (may differ from channel used) */
+    channel_requested?: 'email' | 'sms';
+    /** Reason for fallback if channel differs from requested */
+    fallback_reason?: string;
+    messageId?: string;
+    error?: string;
+    /** Quota information if send was successful */
+    quota?: QuotaInfo;
+    /** Quota error if send was blocked */
+    quotaError?: QuotaError;
+}
+/**
+ * Request router that sends requests via the appropriate channel
+ * with quota enforcement and overage billing
+ */
+declare class RequestRouter {
+    private emailService;
+    private smsService?;
+    private usageService;
+    private smsEnabled;
+    private baseUrl;
+    constructor(config: RouterConfig, supabase: TypedSupabaseClient);
+    /**
+     * Route an approval request to the user
+     */
+    routeApproval(params: RouteApprovalParams, user: User, agent: Agent): Promise<RouteResult>;
+    /**
+     * Route a notification to the user
+     */
+    routeNotification(params: RouteNotificationParams, user: User, agent: Agent): Promise<RouteResult>;
+    /**
+     * Select the best available channel with fallback logic
+     * Returns the channel to use and a reason if fallback occurred
+     */
+    private selectChannel;
+    /**
+     * Create quota info object for successful sends
+     */
+    private createQuotaInfo;
+    /**
+     * Create quota error result when send is blocked
+     */
+    private createQuotaErrorResult;
+}
+
+/**
+ * HTTP Transport for MCP Server
+ * Handles MCP protocol messages over HTTP POST
+ */
+
+interface MCPRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface MCPResponse {
+    jsonrpc: '2.0';
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface MCPNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+}
+declare const MCP_ERRORS: {
+    PARSE_ERROR: number;
+    INVALID_REQUEST: number;
+    METHOD_NOT_FOUND: number;
+    INVALID_PARAMS: number;
+    INTERNAL_ERROR: number;
+    NOT_AUTHENTICATED: number;
+    RATE_LIMITED: number;
+};
+interface HTTPTransportConfig {
+    supabase: TypedSupabaseClient;
+    serverConfig: ServerConfig;
+    router?: RequestRouter;
+}
+/**
+ * HTTP Transport handler for MCP protocol
+ */
+declare class HTTPTransport {
+    private supabase;
+    private config;
+    private router;
+    private sessions;
+    private sessionTTL;
+    constructor(transportConfig: HTTPTransportConfig);
+    /**
+     * Handle an incoming HTTP request
+     */
+    handleRequest(body: MCPRequest | MCPRequest[], apiKey?: string, sessionId?: string): Promise<{
+        response: MCPResponse | MCPResponse[];
+        newSessionId?: string;
+    }>;
+    /**
+     * Handle a single MCP request
+     */
+    private handleSingleRequest;
+    /**
+     * Handle initialize request
+     */
+    private handleInitialize;
+    /**
+     * Handle tools/list request
+     */
+    private handleListTools;
+    /**
+     * Handle tools/call request
+     */
+    private handleToolCall;
+    /**
+     * Create a success response
+     */
+    private successResponse;
+    /**
+     * Create an error response
+     */
+    private errorResponse;
+    /**
+     * Clean up expired sessions
+     */
+    private cleanupSessions;
+}
+/**
+ * Create an HTTP transport instance
+ */
+declare function createHTTPTransport(config: HTTPTransportConfig): HTTPTransport;
+
+export { type ApprovalRequestParams, type ApprovalResponse, type AuthResult, type AwaitResponseParams, type AwaitResult, type GetPendingCommandsParams, HTTPTransport, type HTTPTransportConfig, type MCPNotification, type MCPRequest, type MCPResponse, MCP_ERRORS, type NotificationParams, type NotificationResponse, RelayRailServer, type ServerConfig, type ToolContext, type UserCommand, VERSION, authenticateApiKey, createHTTPTransport, createServer, generateApiKey, getApiKeyPrefix, hashApiKey };