fullstory-mcp-server 1.0.1

package/src/index.ts

@@ -0,0 +1,443 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { createServer, IncomingMessage, ServerResponse } from 'http';
+import { FullstoryClient } from './fullstory-client.js';
+
+// Configuration from environment variables
+const FULLSTORY_API_KEY = process.env.FULLSTORY_API_KEY;
+const FULLSTORY_DATA_CENTER = (process.env.FULLSTORY_DATA_CENTER as 'na1' | 'eu1') || 'na1';
+const PORT = parseInt(process.env.PORT || '3000', 10);
+const TRANSPORT = process.env.TRANSPORT || 'stdio'; // 'stdio' or 'http'
+
+if (!FULLSTORY_API_KEY) {
+  console.error('Error: FULLSTORY_API_KEY environment variable is required');
+  process.exit(1);
+}
+
+// Initialize Fullstory client
+const fullstory = new FullstoryClient({
+  apiKey: FULLSTORY_API_KEY,
+  dataCenter: FULLSTORY_DATA_CENTER,
+});
+
+// Define available tools
+const tools: Tool[] = [
+  {
+    name: 'fullstory_get_user_sessions',
+    description: 'Retrieve session replay data for a specific user. Returns list of sessions with replay URLs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        userId: {
+          type: 'string',
+          description: 'The user ID (uid) to look up sessions for',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of sessions to return (default: 20)',
+        },
+      },
+      required: ['userId'],
+    },
+  },
+  {
+    name: 'fullstory_get_session_replay_url',
+    description: 'Get a direct URL to watch a specific session replay in Fullstory.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: 'The session ID to get replay URL for',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'fullstory_get_user',
+    description: 'Get detailed information about a specific user including custom properties.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        userId: {
+          type: 'string',
+          description: 'The user ID to look up',
+        },
+      },
+      required: ['userId'],
+    },
+  },
+  {
+    name: 'fullstory_search_users',
+    description: 'Search for users matching specific criteria.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        email: {
+          type: 'string',
+          description: 'Filter by email address',
+        },
+        displayName: {
+          type: 'string',
+          description: 'Filter by display name',
+        },
+        customProperty: {
+          type: 'object',
+          description: 'Filter by custom property (key-value pair)',
+          properties: {
+            key: { type: 'string' },
+            value: { type: 'string' },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: 'fullstory_get_user_events',
+    description: 'Retrieve events recorded for a specific user within a time range.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        userId: {
+          type: 'string',
+          description: 'The user ID to get events for',
+        },
+        startTime: {
+          type: 'string',
+          description: 'Start time in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)',
+        },
+        endTime: {
+          type: 'string',
+          description: 'End time in ISO 8601 format',
+        },
+      },
+      required: ['userId'],
+    },
+  },
+  {
+    name: 'fullstory_list_segments',
+    description: 'List all available segments in your Fullstory account.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'fullstory_export_segment',
+    description: 'Start an export job for a segment. Returns an operation ID to check status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        segmentId: {
+          type: 'string',
+          description: 'The segment ID to export',
+        },
+        type: {
+          type: 'string',
+          enum: ['individuals', 'events'],
+          description: 'Export type: "individuals" for user data or "events" for event data',
+        },
+        format: {
+          type: 'string',
+          enum: ['FORMAT_CSV', 'FORMAT_JSON', 'FORMAT_NDJSON'],
+          description: 'Export format (default: FORMAT_JSON)',
+        },
+        startTime: {
+          type: 'string',
+          description: 'Start time for the export range (ISO 8601)',
+        },
+        endTime: {
+          type: 'string',
+          description: 'End time for the export range (ISO 8601)',
+        },
+      },
+      required: ['segmentId', 'type'],
+    },
+  },
+  {
+    name: 'fullstory_get_export_status',
+    description: 'Check the status of a segment export job. Returns progress and download URL when complete.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        operationId: {
+          type: 'string',
+          description: 'The operation ID from the export request',
+        },
+      },
+      required: ['operationId'],
+    },
+  },
+  {
+    name: 'fullstory_download_export',
+    description: 'Download the results of a completed export job.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        downloadUrl: {
+          type: 'string',
+          description: 'The download URL from the completed export status',
+        },
+      },
+      required: ['downloadUrl'],
+    },
+  },
+  {
+    name: 'fullstory_send_event',
+    description: 'Send a custom event to Fullstory for a user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        userId: {
+          type: 'string',
+          description: 'The user ID to associate the event with',
+        },
+        sessionId: {
+          type: 'string',
+          description: 'Optional session ID to associate the event with',
+        },
+        eventName: {
+          type: 'string',
+          description: 'Name of the custom event',
+        },
+        eventData: {
+          type: 'object',
+          description: 'Additional event properties (key-value pairs)',
+        },
+      },
+      required: ['userId', 'eventName'],
+    },
+  },
+];
+
+// Tool execution handler
+async function executeTool(name: string, args: Record<string, unknown> | undefined) {
+  switch (name) {
+    case 'fullstory_get_user_sessions': {
+      const sessions = await fullstory.getUserSessions(
+        args?.userId as string,
+        args?.limit as number | undefined
+      );
+      return JSON.stringify(sessions, null, 2);
+    }
+
+    case 'fullstory_get_session_replay_url': {
+      const url = await fullstory.getSessionReplayUrl(args?.sessionId as string);
+      return `Session replay URL: ${url}`;
+    }
+
+    case 'fullstory_get_user': {
+      const user = await fullstory.getUser(args?.userId as string);
+      return JSON.stringify(user, null, 2);
+    }
+
+    case 'fullstory_search_users': {
+      const query: Record<string, unknown> = {};
+      if (args?.email) query.email = args.email;
+      if (args?.displayName) query.displayName = args.displayName;
+      if (args?.customProperty) {
+        const prop = args.customProperty as { key: string; value: string };
+        query[prop.key] = prop.value;
+      }
+      const users = await fullstory.searchUsers(query);
+      return JSON.stringify(users, null, 2);
+    }
+
+    case 'fullstory_get_user_events': {
+      const events = await fullstory.getUserEvents(
+        args?.userId as string,
+        args?.startTime as string | undefined,
+        args?.endTime as string | undefined
+      );
+      return JSON.stringify(events, null, 2);
+    }
+
+    case 'fullstory_list_segments': {
+      const segments = await fullstory.listSegments();
+      return JSON.stringify(segments, null, 2);
+    }
+
+    case 'fullstory_export_segment': {
+      const exportResult = await fullstory.createSegmentExport({
+        segmentId: args?.segmentId as string,
+        type: args?.type as 'individuals' | 'events',
+        format: args?.format as 'FORMAT_CSV' | 'FORMAT_JSON' | 'FORMAT_NDJSON' | undefined,
+        startTime: args?.startTime as string | undefined,
+        endTime: args?.endTime as string | undefined,
+      });
+      return `Export started. Operation ID: ${exportResult.operationId}\nUse fullstory_get_export_status to check progress.`;
+    }
+
+    case 'fullstory_get_export_status': {
+      const status = await fullstory.getExportStatus(args?.operationId as string);
+      return JSON.stringify(status, null, 2);
+    }
+
+    case 'fullstory_download_export': {
+      const data = await fullstory.downloadExport(args?.downloadUrl as string);
+      return JSON.stringify(data, null, 2);
+    }
+
+    case 'fullstory_send_event': {
+      await fullstory.sendEvent({
+        userId: args?.userId as string,
+        sessionId: args?.sessionId as string | undefined,
+        eventName: args?.eventName as string,
+        eventData: args?.eventData as Record<string, unknown> | undefined,
+      });
+      return 'Event sent successfully.';
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+// Create server instance
+function createMcpServer() {
+  const server = new Server(
+    {
+      name: 'fullstory-mcp-server',
+      version: '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Handle tool listing
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+  });
+
+  // Handle tool execution
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      const result = await executeTool(name, args);
+      return {
+        content: [{ type: 'text', text: result }],
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      return {
+        content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+        isError: true,
+      };
+    }
+  });
+
+  return server;
+}
+
+// Start with stdio transport (for local use)
+async function startStdio() {
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Fullstory MCP Server running on stdio');
+}
+
+// Start with HTTP/SSE transport (for cloud deployment)
+async function startHttp() {
+  const sessions = new Map<string, SSEServerTransport>();
+
+  const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // Health check endpoint
+    if (req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', server: 'fullstory-mcp-server' }));
+      return;
+    }
+
+    // SSE endpoint for MCP connection
+    if (req.url === '/sse' && req.method === 'GET') {
+      const server = createMcpServer();
+      const transport = new SSEServerTransport('/message', res);
+      const sessionId = Date.now().toString();
+      sessions.set(sessionId, transport);
+
+      res.on('close', () => {
+        sessions.delete(sessionId);
+      });
+
+      await server.connect(transport);
+      return;
+    }
+
+    // Message endpoint for SSE
+    if (req.url === '/message' && req.method === 'POST') {
+      let body = '';
+      req.on('data', chunk => { body += chunk; });
+      req.on('end', async () => {
+        try {
+          // Find active session and forward message
+          for (const transport of sessions.values()) {
+            await transport.handlePostMessage(req, res, body);
+            return;
+          }
+          res.writeHead(404);
+          res.end('No active session');
+        } catch (error) {
+          res.writeHead(500);
+          res.end('Error processing message');
+        }
+      });
+      return;
+    }
+
+    // Default response
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      name: 'fullstory-mcp-server',
+      version: '1.0.0',
+      endpoints: {
+        health: '/health',
+        sse: '/sse',
+        message: '/message'
+      }
+    }));
+  });
+
+  httpServer.listen(PORT, () => {
+    console.log(`Fullstory MCP Server running on http://0.0.0.0:${PORT}`);
+    console.log(`SSE endpoint: http://0.0.0.0:${PORT}/sse`);
+  });
+}
+
+// Main entry point
+async function main() {
+  if (TRANSPORT === 'http') {
+    await startHttp();
+  } else {
+    await startStdio();
+  }
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}