fullstory-mcp-server 1.0.1

package/src/cli.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as readline from 'readline';
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+function question(prompt: string): Promise<string> {
+  return new Promise((resolve) => {
+    rl.question(prompt, resolve);
+  });
+}
+
+async function setup() {
+  console.log('\n🔧 Fullstory MCP Server Setup\n');
+  
+  const apiKey = await question('Enter your Fullstory API key: ');
+  const dataCenter = apiKey.startsWith('eu1.') ? 'eu1' : 'na1';
+  
+  const configDir = path.join(os.homedir(), 'Library', 'Application Support', 'Claude');
+  const configPath = path.join(configDir, 'claude_desktop_config.json');
+  
+  // Ensure directory exists
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+  
+  // Read existing config or create new
+  let config: any = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch (e) {
+      config = {};
+    }
+  }
+  
+  // Find the installed package path
+  const packagePath = path.dirname(__dirname);
+  const serverPath = path.join(packagePath, 'dist', 'index.js');
+  
+  // Add fullstory server config
+  config.mcpServers = config.mcpServers || {};
+  config.mcpServers.fullstory = {
+    command: 'node',
+    args: [serverPath],
+    env: {
+      FULLSTORY_API_KEY: apiKey,
+      FULLSTORY_DATA_CENTER: dataCenter,
+      TRANSPORT: 'stdio'
+    }
+  };
+  
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  
+  console.log('\n✅ Setup complete!');
+  console.log(`   Data center: ${dataCenter}`);
+  console.log('\n👉 Please restart Claude Desktop (Cmd+Q, then reopen)\n');
+  
+  rl.close();
+}
+
+const command = process.argv[2];
+
+if (command === 'setup') {
+  setup().catch(console.error);
+} else {
+  // Run as MCP server
+  import('./index.js');
+}

package/src/fullstory-client.ts

@@ -0,0 +1,231 @@
+import axios, { AxiosInstance, AxiosError } from 'axios';
+
+export interface FullstoryConfig {
+  apiKey: string;
+  dataCenter?: 'na1' | 'eu1';  // na1 = North America, eu1 = Europe
+}
+
+export interface Session {
+  sessionId: string;
+  userId: string;
+  createdTime: string;
+  fsUrl: string;
+  deviceType?: string;
+  browser?: string;
+  location?: string;
+}
+
+export interface UserEvent {
+  eventId: string;
+  eventType: string;
+  eventTime: string;
+  eventData?: Record<string, unknown>;
+  sessionId?: string;
+}
+
+export interface User {
+  id: string;
+  uid?: string;
+  displayName?: string;
+  email?: string;
+  properties?: Record<string, unknown>;
+}
+
+export interface SegmentExport {
+  operationId: string;
+  status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
+  progress?: number;
+  downloadUrl?: string;
+}
+
+export interface ExportRequest {
+  segmentId: string;
+  type: 'individuals' | 'events';
+  format?: 'FORMAT_CSV' | 'FORMAT_JSON' | 'FORMAT_NDJSON';
+  startTime?: string;
+  endTime?: string;
+}
+
+export class FullstoryClient {
+  private client: AxiosInstance;
+  private dataCenter: string;
+
+  constructor(config: FullstoryConfig) {
+    this.dataCenter = config.dataCenter || 'na1';
+
+    const baseURL = this.dataCenter === 'eu1' 
+      ? 'https://api.eu1.fullstory.com' 
+      : 'https://api.fullstory.com';
+    
+    this.client = axios.create({
+      baseURL,
+      headers: {
+        'Authorization': `Basic ${config.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+    });
+  }
+
+  private handleError(error: unknown): never {
+    if (error instanceof AxiosError) {
+      const status = error.response?.status;
+      const message = error.response?.data?.message || error.message;
+
+      if (status === 401) {
+        throw new Error('Authentication failed. Check your API key.');
+      } else if (status === 403) {
+        throw new Error('Access forbidden. Your API key may not have sufficient permissions.');
+      } else if (status === 429) {
+        throw new Error('Rate limit exceeded. Please wait before making more requests.');
+      } else if (status === 404) {
+        throw new Error('Resource not found.');
+      }
+      throw new Error(`Fullstory API error: ${message}`);
+    }
+    throw error;
+  }
+
+  // ============ SESSIONS ============
+
+  async getUserSessions(userId: string, limit: number = 20): Promise<Session[]> {
+    try {
+      const response = await this.client.get('/v1/sessions', {
+        params: { uid: userId, limit },
+      });
+      return response.data.sessions || [];
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  async getSessionReplayUrl(sessionId: string): Promise<string> {
+    try {
+      const response = await this.client.get(`/v1/sessions/${sessionId}`);
+      return response.data.fsUrl;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // ============ USERS ============
+
+  async getUser(userId: string): Promise<User> {
+    try {
+      const response = await this.client.get(`/v2/users/${userId}`);
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  async searchUsers(query: Record<string, unknown>): Promise<User[]> {
+    try {
+      const response = await this.client.post('/v2/users/search', query);
+      return response.data.users || [];
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // ============ EVENTS ============
+
+  async getUserEvents(userId: string, startTime?: string, endTime?: string): Promise<UserEvent[]> {
+    try {
+      const params: Record<string, string> = { uid: userId };
+      if (startTime) params.start = startTime;
+      if (endTime) params.end = endTime;
+
+      const response = await this.client.get('/v1/users/events', { params });
+      return response.data.events || [];
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  async sendEvent(event: {
+    userId: string;
+    sessionId?: string;
+    eventName: string;
+    eventData?: Record<string, unknown>;
+    timestamp?: string;
+  }): Promise<void> {
+    try {
+      await this.client.post('/v2/events', {
+        user: { uid: event.userId },
+        session: event.sessionId ? { id: event.sessionId } : undefined,
+        name: event.eventName,
+        properties: event.eventData,
+        timestamp: event.timestamp || new Date().toISOString(),
+      });
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // ============ SEGMENT EXPORTS ============
+
+  async createSegmentExport(request: ExportRequest): Promise<SegmentExport> {
+    try {
+      const response = await this.client.post('/segments/v1/exports', {
+        segmentId: request.segmentId,
+        type: request.type.toUpperCase(),
+        format: request.format || 'FORMAT_JSON',
+        timeRange: {
+          start: request.startTime,
+          end: request.endTime,
+        },
+      });
+      return {
+        operationId: response.data.operationId,
+        status: 'PENDING',
+      };
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  async getExportStatus(operationId: string): Promise<SegmentExport> {
+    try {
+      const response = await this.client.get(`/operations/v1/${operationId}`);
+      return {
+        operationId,
+        status: response.data.state,
+        progress: response.data.progress,
+        downloadUrl: response.data.results?.downloadUrl,
+      };
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  async downloadExport(downloadUrl: string): Promise<unknown> {
+    try {
+      const response = await axios.get(downloadUrl);
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // ============ SEGMENTS ============
+
+  async listSegments(): Promise<Array<{ id: string; name: string; description?: string }>> {
+    try {
+      const response = await this.client.get('/segments/v1');
+      return response.data.segments || [];
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // ============ AUDIT / SETTINGS ============
+
+  async getAuditTrail(settingType: string): Promise<unknown> {
+    try {
+      const response = await this.client.get(`/settings/v1/audit/${settingType}`);
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+}