@getguru/fullstory-mcp 0.0.1

package/README.md

@@ -0,0 +1,15 @@
+# @getguru/fullstory-mcp
+
+FullStory MCP server for session replays, users, segments, and events.
+
+## Install
+
+Use the MCP with npx (no global install):
+
+```bash
+npx @getguru/fullstory-mcp
+```
+
+Configure your MCP client (e.g. Cursor) to run: **command** `npx`, **args** `@getguru/fullstory-mcp`.
+
+Set `FULLSTORY_API_KEY` in the client’s env (or in your shell). Use an Admin or Architect key from FullStory Settings > API Keys; format is `{datacenter}.{token}` (e.g. `na1.xxxx`).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const FULLSTORY_API_BASE = "https://api.fullstory.com";
+/** API key from process env; set via MCP client config (e.g. Cursor MCP env) or .env. */
+function getApiKey() {
+    const key = process.env.FULLSTORY_API_KEY;
+    return key?.trim();
+}
+async function fullstoryFetch(path, init) {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        throw new Error("FULLSTORY_API_KEY is not set. Set it in the environment or .env (Admin or Architect key from FullStory Settings > API Keys).");
+    }
+    const url = path.startsWith("http") ? path : `${FULLSTORY_API_BASE}${path}`;
+    return fetch(url, {
+        ...init,
+        headers: {
+            Authorization: `Basic ${Buffer.from(apiKey + ":").toString("base64")}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            ...init?.headers,
+        },
+    });
+}
+const server = new Server({
+    name: "fullstory-mcp",
+    version: "0.0.1",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "fullstory_sessions_for_user",
+                description: "List FullStory session replay URLs for a user by email or UID. Returns session IDs and FsUrl links for replay.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        email: {
+                            type: "string",
+                            description: "User's email address (use either email or uid, not both)",
+                        },
+                        uid: {
+                            type: "string",
+                            description: "User's application UID (use either email or uid, not both)",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Max sessions to return (default 20)",
+                            default: 20,
+                        },
+                    },
+                },
+            },
+            {
+                name: "fullstory_session_events",
+                description: "Get raw event data for a FullStory session by session ID. Useful for programmatic analysis of what happened.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: {
+                            type: "string",
+                            description: "FullStory session ID (numeric or from a session URL)",
+                        },
+                    },
+                    required: ["session_id"],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const raw = args ?? {};
+    if (name === "fullstory_sessions_for_user") {
+        const email = raw.email;
+        const uid = raw.uid;
+        const limit = raw.limit ?? 20;
+        if (!email && !uid) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: provide either 'email' or 'uid'.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const params = new URLSearchParams();
+        if (email)
+            params.set("email", email);
+        if (uid)
+            params.set("uid", uid);
+        params.set("limit", String(limit));
+        const res = await fullstoryFetch(`/sessions/v2?${params.toString()}`);
+        const text = await res.text();
+        if (!res.ok) {
+            return {
+                content: [{ type: "text", text: `FullStory API error (${res.status}): ${text}` }],
+                isError: true,
+            };
+        }
+        const data = JSON.parse(text);
+        const table = "| # | Session URL | Created | User ID |\n|---|-------------|---------|--------|\n" +
+            data
+                .slice(0, 20)
+                .map((s, i) => `| ${i + 1} | ${s.FsUrl ?? "-"} | ${s.CreatedTime ?? "-"} | ${s.UserId ?? "-"} |`)
+                .join("\n");
+        return {
+            content: [{ type: "text", text: table || "No sessions found." }],
+        };
+    }
+    if (name === "fullstory_session_events") {
+        const sessionId = raw.session_id;
+        if (!sessionId) {
+            return {
+                content: [{ type: "text", text: "Error: 'session_id' is required." }],
+                isError: true,
+            };
+        }
+        const res = await fullstoryFetch(`/v2/sessions/${encodeURIComponent(sessionId)}/events`);
+        const text = await res.text();
+        if (!res.ok) {
+            return {
+                content: [{ type: "text", text: `FullStory API error (${res.status}): ${text}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: text || "[]" }],
+        };
+    }
+    return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true,
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@getguru/fullstory-mcp",
+  "version": "0.0.1",
+  "description": "FullStory MCP server for session replays, users, segments, and events",
+  "type": "module",
+  "bin": { "fullstory-mcp": "./dist/index.js" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.25 || ^4.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}