fullstory-mcp-server 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +20 -0
- package/DEPLOYMENT_GUIDE.md +272 -0
- package/Dockerfile +28 -0
- package/README.md +181 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +63 -0
- package/dist/cli.js.map +1 -0
- package/dist/fullstory-client.d.ts +68 -0
- package/dist/fullstory-client.d.ts.map +1 -0
- package/dist/fullstory-client.js +172 -0
- package/dist/fullstory-client.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +401 -0
- package/dist/index.js.map +1 -0
- package/package.json +31 -0
- package/src/cli.ts +75 -0
- package/src/fullstory-client.ts +231 -0
- package/src/index.ts +443 -0
- package/tsconfig.json +18 -0
package/.env.example
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Fullstory MCP Server Configuration
|
|
2
|
+
# Copy this file to .env and fill in your values
|
|
3
|
+
|
|
4
|
+
# Required: Your Fullstory API Key
|
|
5
|
+
# Get this from Fullstory > Settings > API Keys
|
|
6
|
+
# Use an Admin or Architect key for full access (required for segment exports)
|
|
7
|
+
FULLSTORY_API_KEY=your_api_key_here
|
|
8
|
+
|
|
9
|
+
# Optional: Data center region
|
|
10
|
+
# na1 = North America (default)
|
|
11
|
+
# eu1 = Europe
|
|
12
|
+
FULLSTORY_DATA_CENTER=na1
|
|
13
|
+
|
|
14
|
+
# Transport mode
|
|
15
|
+
# stdio = Local use with Claude Desktop (default)
|
|
16
|
+
# http = Cloud deployment with SSE support
|
|
17
|
+
TRANSPORT=stdio
|
|
18
|
+
|
|
19
|
+
# Port for HTTP mode (ignored in stdio mode)
|
|
20
|
+
PORT=3000
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
# Fullstory MCP Server - Cloud Deployment Guide
|
|
2
|
+
|
|
3
|
+
This guide walks you through deploying the Fullstory MCP server to the cloud using **GitHub** and **Railway** (a free cloud platform).
|
|
4
|
+
|
|
5
|
+
**Time required:** ~20 minutes
|
|
6
|
+
**Cost:** Free (Railway offers a free tier)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Prerequisites
|
|
11
|
+
|
|
12
|
+
Before starting, you'll need:
|
|
13
|
+
- [ ] A GitHub account (you have this!)
|
|
14
|
+
- [ ] Your Fullstory API key (Admin or Architect role)
|
|
15
|
+
- [ ] A Railway account (we'll create this)
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Step 1: Get Your Fullstory API Key
|
|
20
|
+
|
|
21
|
+
1. Log into [Fullstory](https://app.fullstory.com)
|
|
22
|
+
2. Go to **Settings** → **API Keys** (or **Integrations** → **API Keys**)
|
|
23
|
+
3. Click **Create API Key**
|
|
24
|
+
4. Select role: **Admin** or **Architect** (required for segment exports)
|
|
25
|
+
5. Copy and save the key somewhere safe — you won't see it again!
|
|
26
|
+
|
|
27
|
+
**Note your data center:**
|
|
28
|
+
- If your Fullstory URL contains `app.fullstory.com` → use `na1`
|
|
29
|
+
- If it contains `app.eu1.fullstory.com` → use `eu1`
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Step 2: Create a GitHub Repository
|
|
34
|
+
|
|
35
|
+
### Option A: Using GitHub.com (easiest)
|
|
36
|
+
|
|
37
|
+
1. Go to [github.com/new](https://github.com/new)
|
|
38
|
+
2. Fill in:
|
|
39
|
+
- **Repository name:** `fullstory-mcp-server`
|
|
40
|
+
- **Description:** `MCP server for Fullstory analytics integration`
|
|
41
|
+
- **Visibility:** Private (recommended) or Public
|
|
42
|
+
3. Click **Create repository**
|
|
43
|
+
4. You'll see instructions for uploading code — keep this page open
|
|
44
|
+
|
|
45
|
+
### Option B: Using Git command line
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# Navigate to the project folder
|
|
49
|
+
cd fullstory-mcp-server
|
|
50
|
+
|
|
51
|
+
# Initialize git
|
|
52
|
+
git init
|
|
53
|
+
|
|
54
|
+
# Add all files
|
|
55
|
+
git add .
|
|
56
|
+
|
|
57
|
+
# Commit
|
|
58
|
+
git commit -m "Initial commit: Fullstory MCP server"
|
|
59
|
+
|
|
60
|
+
# Add your GitHub repo as remote (replace YOUR_USERNAME)
|
|
61
|
+
git remote add origin https://github.com/YOUR_USERNAME/fullstory-mcp-server.git
|
|
62
|
+
|
|
63
|
+
# Push to GitHub
|
|
64
|
+
git branch -M main
|
|
65
|
+
git push -u origin main
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Step 3: Create a Railway Account
|
|
71
|
+
|
|
72
|
+
1. Go to [railway.app](https://railway.app)
|
|
73
|
+
2. Click **Login** → **Login with GitHub**
|
|
74
|
+
3. Authorize Railway to access your GitHub
|
|
75
|
+
4. You now have a Railway account linked to GitHub!
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Step 4: Deploy to Railway
|
|
80
|
+
|
|
81
|
+
### 4.1 Create a New Project
|
|
82
|
+
|
|
83
|
+
1. In Railway dashboard, click **New Project**
|
|
84
|
+
2. Select **Deploy from GitHub repo**
|
|
85
|
+
3. Find and select your `fullstory-mcp-server` repository
|
|
86
|
+
4. Click **Deploy Now**
|
|
87
|
+
|
|
88
|
+
### 4.2 Add Environment Variables
|
|
89
|
+
|
|
90
|
+
Railway will start deploying but it will fail (no API key yet). Fix this:
|
|
91
|
+
|
|
92
|
+
1. Click on your deployed service
|
|
93
|
+
2. Go to the **Variables** tab
|
|
94
|
+
3. Click **New Variable** and add these:
|
|
95
|
+
|
|
96
|
+
| Variable Name | Value |
|
|
97
|
+
|---------------|-------|
|
|
98
|
+
| `FULLSTORY_API_KEY` | `your_actual_api_key_here` |
|
|
99
|
+
| `FULLSTORY_DATA_CENTER` | `na1` (or `eu1` if European) |
|
|
100
|
+
| `TRANSPORT` | `http` |
|
|
101
|
+
| `PORT` | `3000` |
|
|
102
|
+
|
|
103
|
+
4. Click **Deploy** to redeploy with the new variables
|
|
104
|
+
|
|
105
|
+
### 4.3 Wait for Deployment
|
|
106
|
+
|
|
107
|
+
- Railway will automatically build and deploy your server
|
|
108
|
+
- Watch the **Deployments** tab for progress
|
|
109
|
+
- When it shows ✅ **Success**, your server is live!
|
|
110
|
+
|
|
111
|
+
### 4.4 Get Your Server URL
|
|
112
|
+
|
|
113
|
+
1. Go to **Settings** tab
|
|
114
|
+
2. Under **Networking**, click **Generate Domain**
|
|
115
|
+
3. Railway will give you a URL like: `fullstory-mcp-server-production.up.railway.app`
|
|
116
|
+
4. **Save this URL** — your team will need it!
|
|
117
|
+
|
|
118
|
+
### 4.5 Verify It's Working
|
|
119
|
+
|
|
120
|
+
Visit your server URL in a browser. You should see:
|
|
121
|
+
|
|
122
|
+
```json
|
|
123
|
+
{
|
|
124
|
+
"name": "fullstory-mcp-server",
|
|
125
|
+
"version": "1.0.0",
|
|
126
|
+
"endpoints": {
|
|
127
|
+
"health": "/health",
|
|
128
|
+
"sse": "/sse",
|
|
129
|
+
"message": "/message"
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Also try: `https://your-server-url.up.railway.app/health`
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Step 5: Connect Claude to Your Server
|
|
139
|
+
|
|
140
|
+
### For Claude Desktop App
|
|
141
|
+
|
|
142
|
+
Edit your Claude configuration file:
|
|
143
|
+
|
|
144
|
+
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
145
|
+
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
146
|
+
|
|
147
|
+
Add your server as a remote MCP server:
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
{
|
|
151
|
+
"mcpServers": {
|
|
152
|
+
"fullstory": {
|
|
153
|
+
"url": "https://your-server-url.up.railway.app/sse",
|
|
154
|
+
"transport": "sse"
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Restart Claude Desktop to connect.
|
|
161
|
+
|
|
162
|
+
### For Cowork Mode (Claude.ai)
|
|
163
|
+
|
|
164
|
+
If your organization has custom MCP server support enabled:
|
|
165
|
+
1. Go to Settings → MCP Servers
|
|
166
|
+
2. Add new server with SSE URL: `https://your-server-url.up.railway.app/sse`
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## Step 6: Share with Your Team
|
|
171
|
+
|
|
172
|
+
Send your colleagues:
|
|
173
|
+
|
|
174
|
+
1. **The server URL:** `https://your-server-url.up.railway.app/sse`
|
|
175
|
+
2. **These setup instructions:**
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
To connect to our Fullstory integration:
|
|
179
|
+
|
|
180
|
+
1. Open Claude Desktop config file:
|
|
181
|
+
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
|
|
182
|
+
- Windows: %APPDATA%\Claude\claude_desktop_config.json
|
|
183
|
+
|
|
184
|
+
2. Add this configuration:
|
|
185
|
+
{
|
|
186
|
+
"mcpServers": {
|
|
187
|
+
"fullstory": {
|
|
188
|
+
"url": "https://your-server-url.up.railway.app/sse",
|
|
189
|
+
"transport": "sse"
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
3. Restart Claude Desktop
|
|
195
|
+
|
|
196
|
+
4. Try asking: "List my Fullstory segments"
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Troubleshooting
|
|
202
|
+
|
|
203
|
+
### "Deployment failed"
|
|
204
|
+
- Check the **Logs** tab in Railway for error messages
|
|
205
|
+
- Most common: missing environment variables
|
|
206
|
+
|
|
207
|
+
### "Connection refused" or timeout
|
|
208
|
+
- Make sure `TRANSPORT=http` is set
|
|
209
|
+
- Check that Railway generated a public domain
|
|
210
|
+
- Verify the health endpoint works: `/health`
|
|
211
|
+
|
|
212
|
+
### "Authentication failed" from Fullstory
|
|
213
|
+
- Double-check your API key is correct
|
|
214
|
+
- Make sure the key hasn't been revoked
|
|
215
|
+
- Verify the data center setting (`na1` vs `eu1`)
|
|
216
|
+
|
|
217
|
+
### "Rate limit exceeded"
|
|
218
|
+
- Segment exports are limited to 2 requests/minute
|
|
219
|
+
- Wait a minute and try again
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Managing Your Server
|
|
224
|
+
|
|
225
|
+
### Viewing Logs
|
|
226
|
+
- Railway Dashboard → Your Project → **Logs** tab
|
|
227
|
+
|
|
228
|
+
### Updating the Server
|
|
229
|
+
1. Make changes to your code locally
|
|
230
|
+
2. Push to GitHub: `git push`
|
|
231
|
+
3. Railway automatically redeploys!
|
|
232
|
+
|
|
233
|
+
### Changing Environment Variables
|
|
234
|
+
- Railway Dashboard → Your Project → **Variables** tab
|
|
235
|
+
- Changes trigger automatic redeployment
|
|
236
|
+
|
|
237
|
+
### Monitoring Usage
|
|
238
|
+
- Railway Dashboard → Your Project → **Metrics** tab
|
|
239
|
+
- Free tier includes 500 hours/month (plenty for an MCP server)
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## Security Best Practices
|
|
244
|
+
|
|
245
|
+
1. **Keep your repo private** — it doesn't contain secrets, but why not
|
|
246
|
+
2. **Use Railway's variable encryption** — secrets are stored securely
|
|
247
|
+
3. **Rotate API keys periodically** — update in Railway Variables
|
|
248
|
+
4. **Monitor usage** — check Railway logs for unexpected activity
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Cost Information
|
|
253
|
+
|
|
254
|
+
**Railway Free Tier includes:**
|
|
255
|
+
- 500 hours of runtime per month
|
|
256
|
+
- 512 MB RAM
|
|
257
|
+
- Automatic SSL
|
|
258
|
+
- GitHub integration
|
|
259
|
+
|
|
260
|
+
This is more than enough for an MCP server. You'll only pay if you exceed these limits.
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
## Next Steps
|
|
265
|
+
|
|
266
|
+
Once deployed, try asking Claude:
|
|
267
|
+
- "Show me sessions for user@example.com"
|
|
268
|
+
- "What events did user 12345 trigger last week?"
|
|
269
|
+
- "List all our Fullstory segments"
|
|
270
|
+
- "Export the Power Users segment as CSV"
|
|
271
|
+
|
|
272
|
+
Enjoy your Fullstory + Claude integration! 🎉
|
package/Dockerfile
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Build stage
|
|
2
|
+
FROM node:20-alpine AS builder
|
|
3
|
+
|
|
4
|
+
WORKDIR /app
|
|
5
|
+
|
|
6
|
+
COPY package*.json ./
|
|
7
|
+
RUN npm install
|
|
8
|
+
|
|
9
|
+
COPY tsconfig.json ./
|
|
10
|
+
COPY src ./src
|
|
11
|
+
RUN npm run build
|
|
12
|
+
|
|
13
|
+
# Production stage
|
|
14
|
+
FROM node:20-alpine
|
|
15
|
+
|
|
16
|
+
WORKDIR /app
|
|
17
|
+
|
|
18
|
+
COPY package*.json ./
|
|
19
|
+
RUN npm install --omit=dev
|
|
20
|
+
|
|
21
|
+
COPY --from=builder /app/dist ./dist
|
|
22
|
+
|
|
23
|
+
ENV NODE_ENV=production
|
|
24
|
+
ENV TRANSPORT=http
|
|
25
|
+
ENV PORT=3000
|
|
26
|
+
|
|
27
|
+
EXPOSE 3000
|
|
28
|
+
CMD ["node", "dist/index.js"]
|
package/README.md
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# Fullstory MCP Server
|
|
2
|
+
|
|
3
|
+
An MCP (Model Context Protocol) server that connects Claude to your Fullstory analytics data. Once configured, you and your team can ask Claude questions about user sessions, events, segments, and more.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
| Tool | Description |
|
|
8
|
+
|------|-------------|
|
|
9
|
+
| `fullstory_get_user_sessions` | Get session replays for a user |
|
|
10
|
+
| `fullstory_get_session_replay_url` | Get direct URL to watch a session |
|
|
11
|
+
| `fullstory_get_user` | Get user details and properties |
|
|
12
|
+
| `fullstory_search_users` | Search users by email, name, or custom properties |
|
|
13
|
+
| `fullstory_get_user_events` | Get events for a user within a time range |
|
|
14
|
+
| `fullstory_list_segments` | List all saved segments |
|
|
15
|
+
| `fullstory_export_segment` | Export segment data (users or events) |
|
|
16
|
+
| `fullstory_get_export_status` | Check export job progress |
|
|
17
|
+
| `fullstory_download_export` | Download completed export data |
|
|
18
|
+
| `fullstory_send_event` | Send custom events to Fullstory |
|
|
19
|
+
|
|
20
|
+
## Prerequisites
|
|
21
|
+
|
|
22
|
+
- Node.js 18+
|
|
23
|
+
- Fullstory account with API access
|
|
24
|
+
- Admin or Architect API key (for full functionality)
|
|
25
|
+
|
|
26
|
+
## Quick Start
|
|
27
|
+
|
|
28
|
+
### 1. Clone and Install
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
cd fullstory-mcp-server
|
|
32
|
+
npm install
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### 2. Configure Environment
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
cp .env.example .env
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Edit `.env` and add your Fullstory API key:
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
FULLSTORY_API_KEY=your_api_key_here
|
|
45
|
+
FULLSTORY_DATA_CENTER=na1
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Getting your API key:**
|
|
49
|
+
1. Log into Fullstory
|
|
50
|
+
2. Go to **Settings** → **API Keys**
|
|
51
|
+
3. Create a new key with **Admin** or **Architect** role
|
|
52
|
+
4. Copy the key (you won't be able to see it again)
|
|
53
|
+
|
|
54
|
+
### 3. Build
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm run build
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### 4. Test Locally
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
npm start
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Deployment Options
|
|
67
|
+
|
|
68
|
+
### Option A: Shared Server (Recommended for Teams)
|
|
69
|
+
|
|
70
|
+
Deploy to a cloud server so all team members can use the same connection.
|
|
71
|
+
|
|
72
|
+
#### Using Docker
|
|
73
|
+
|
|
74
|
+
```dockerfile
|
|
75
|
+
# Dockerfile
|
|
76
|
+
FROM node:20-alpine
|
|
77
|
+
WORKDIR /app
|
|
78
|
+
COPY package*.json ./
|
|
79
|
+
RUN npm ci --only=production
|
|
80
|
+
COPY dist ./dist
|
|
81
|
+
ENV NODE_ENV=production
|
|
82
|
+
CMD ["node", "dist/index.js"]
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
docker build -t fullstory-mcp-server .
|
|
87
|
+
docker run -d \
|
|
88
|
+
-e FULLSTORY_API_KEY=your_key \
|
|
89
|
+
-e FULLSTORY_DATA_CENTER=na1 \
|
|
90
|
+
--name fullstory-mcp \
|
|
91
|
+
fullstory-mcp-server
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
#### Using PM2 (on a Linux server)
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npm install -g pm2
|
|
98
|
+
pm2 start dist/index.js --name fullstory-mcp
|
|
99
|
+
pm2 save
|
|
100
|
+
pm2 startup
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Option B: Local Machine (Per User)
|
|
104
|
+
|
|
105
|
+
Each team member runs the server on their own machine.
|
|
106
|
+
|
|
107
|
+
## Connecting to Claude
|
|
108
|
+
|
|
109
|
+
### For Claude Desktop App
|
|
110
|
+
|
|
111
|
+
Add to your Claude configuration file:
|
|
112
|
+
|
|
113
|
+
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
114
|
+
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"mcpServers": {
|
|
119
|
+
"fullstory": {
|
|
120
|
+
"command": "node",
|
|
121
|
+
"args": ["/path/to/fullstory-mcp-server/dist/index.js"],
|
|
122
|
+
"env": {
|
|
123
|
+
"FULLSTORY_API_KEY": "your_api_key_here",
|
|
124
|
+
"FULLSTORY_DATA_CENTER": "na1"
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### For Remote/Shared Server
|
|
132
|
+
|
|
133
|
+
If running on a shared server, configure the connection URL in your MCP client settings.
|
|
134
|
+
|
|
135
|
+
## Usage Examples
|
|
136
|
+
|
|
137
|
+
Once connected, you can ask Claude things like:
|
|
138
|
+
|
|
139
|
+
- "Show me the recent sessions for user john@example.com"
|
|
140
|
+
- "What events did user 12345 trigger last week?"
|
|
141
|
+
- "List all our Fullstory segments"
|
|
142
|
+
- "Export the 'Power Users' segment as CSV"
|
|
143
|
+
- "Get me the replay URL for session abc123"
|
|
144
|
+
|
|
145
|
+
## API Key Permissions
|
|
146
|
+
|
|
147
|
+
| Feature | Required Role |
|
|
148
|
+
|---------|---------------|
|
|
149
|
+
| Sessions, Users, Events | Normal, Admin, Architect |
|
|
150
|
+
| Segment Exports | Admin, Architect |
|
|
151
|
+
| Audit Trails | Admin, Architect |
|
|
152
|
+
|
|
153
|
+
## Troubleshooting
|
|
154
|
+
|
|
155
|
+
### "Authentication failed"
|
|
156
|
+
- Check that your API key is correct
|
|
157
|
+
- Ensure the key hasn't been revoked
|
|
158
|
+
- Verify the data center setting matches your account
|
|
159
|
+
|
|
160
|
+
### "Rate limit exceeded"
|
|
161
|
+
- Segment exports are limited to 2 requests/minute
|
|
162
|
+
- Wait before making additional requests
|
|
163
|
+
|
|
164
|
+
### "Access forbidden"
|
|
165
|
+
- Your API key may not have sufficient permissions
|
|
166
|
+
- Upgrade to Admin or Architect role for full access
|
|
167
|
+
|
|
168
|
+
## Security Notes
|
|
169
|
+
|
|
170
|
+
- Store API keys securely (use environment variables, not hardcoded values)
|
|
171
|
+
- Rotate API keys periodically
|
|
172
|
+
- Use the minimum required permission level
|
|
173
|
+
- For team deployments, consider using a dedicated service account
|
|
174
|
+
|
|
175
|
+
## Contributing
|
|
176
|
+
|
|
177
|
+
Feel free to extend this server with additional Fullstory API endpoints as needed.
|
|
178
|
+
|
|
179
|
+
## License
|
|
180
|
+
|
|
181
|
+
MIT
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import * as fs from 'fs';
|
|
3
|
+
import * as path from 'path';
|
|
4
|
+
import * as os from 'os';
|
|
5
|
+
import * as readline from 'readline';
|
|
6
|
+
const rl = readline.createInterface({
|
|
7
|
+
input: process.stdin,
|
|
8
|
+
output: process.stdout
|
|
9
|
+
});
|
|
10
|
+
function question(prompt) {
|
|
11
|
+
return new Promise((resolve) => {
|
|
12
|
+
rl.question(prompt, resolve);
|
|
13
|
+
});
|
|
14
|
+
}
|
|
15
|
+
async function setup() {
|
|
16
|
+
console.log('\n🔧 Fullstory MCP Server Setup\n');
|
|
17
|
+
const apiKey = await question('Enter your Fullstory API key: ');
|
|
18
|
+
const dataCenter = apiKey.startsWith('eu1.') ? 'eu1' : 'na1';
|
|
19
|
+
const configDir = path.join(os.homedir(), 'Library', 'Application Support', 'Claude');
|
|
20
|
+
const configPath = path.join(configDir, 'claude_desktop_config.json');
|
|
21
|
+
// Ensure directory exists
|
|
22
|
+
if (!fs.existsSync(configDir)) {
|
|
23
|
+
fs.mkdirSync(configDir, { recursive: true });
|
|
24
|
+
}
|
|
25
|
+
// Read existing config or create new
|
|
26
|
+
let config = {};
|
|
27
|
+
if (fs.existsSync(configPath)) {
|
|
28
|
+
try {
|
|
29
|
+
config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
|
|
30
|
+
}
|
|
31
|
+
catch (e) {
|
|
32
|
+
config = {};
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
// Find the installed package path
|
|
36
|
+
const packagePath = path.dirname(__dirname);
|
|
37
|
+
const serverPath = path.join(packagePath, 'dist', 'index.js');
|
|
38
|
+
// Add fullstory server config
|
|
39
|
+
config.mcpServers = config.mcpServers || {};
|
|
40
|
+
config.mcpServers.fullstory = {
|
|
41
|
+
command: 'node',
|
|
42
|
+
args: [serverPath],
|
|
43
|
+
env: {
|
|
44
|
+
FULLSTORY_API_KEY: apiKey,
|
|
45
|
+
FULLSTORY_DATA_CENTER: dataCenter,
|
|
46
|
+
TRANSPORT: 'stdio'
|
|
47
|
+
}
|
|
48
|
+
};
|
|
49
|
+
fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
|
|
50
|
+
console.log('\n✅ Setup complete!');
|
|
51
|
+
console.log(` Data center: ${dataCenter}`);
|
|
52
|
+
console.log('\n👉 Please restart Claude Desktop (Cmd+Q, then reopen)\n');
|
|
53
|
+
rl.close();
|
|
54
|
+
}
|
|
55
|
+
const command = process.argv[2];
|
|
56
|
+
if (command === 'setup') {
|
|
57
|
+
setup().catch(console.error);
|
|
58
|
+
}
|
|
59
|
+
else {
|
|
60
|
+
// Run as MCP server
|
|
61
|
+
import('./index.js');
|
|
62
|
+
}
|
|
63
|
+
//# sourceMappingURL=cli.js.map
|
package/dist/cli.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAErC,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;IAClC,KAAK,EAAE,OAAO,CAAC,KAAK;IACpB,MAAM,EAAE,OAAO,CAAC,MAAM;CACvB,CAAC,CAAC;AAEH,SAAS,QAAQ,CAAC,MAAc;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,KAAK;IAClB,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IAEjD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,gCAAgC,CAAC,CAAC;IAChE,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;IAE7D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,qBAAqB,EAAE,QAAQ,CAAC,CAAC;IACtF,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,4BAA4B,CAAC,CAAC;IAEtE,0BAA0B;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,qCAAqC;IACrC,IAAI,MAAM,GAAQ,EAAE,CAAC;IACrB,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,GAAG,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAED,kCAAkC;IAClC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAE9D,8BAA8B;IAC9B,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC;IAC5C,MAAM,CAAC,UAAU,CAAC,SAAS,GAAG;QAC5B,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,CAAC,UAAU,CAAC;QAClB,GAAG,EAAE;YACH,iBAAiB,EAAE,MAAM;YACzB,qBAAqB,EAAE,UAAU;YACjC,SAAS,EAAE,OAAO;SACnB;KACF,CAAC;IAEF,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAE9D,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,mBAAmB,UAAU,EAAE,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC;IAEzE,EAAE,CAAC,KAAK,EAAE,CAAC;AACb,CAAC;AAED,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEhC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;IACxB,KAAK,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;KAAM,CAAC;IACN,oBAAoB;IACpB,MAAM,CAAC,YAAY,CAAC,CAAC;AACvB,CAAC"}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
export interface FullstoryConfig {
|
|
2
|
+
apiKey: string;
|
|
3
|
+
dataCenter?: 'na1' | 'eu1';
|
|
4
|
+
}
|
|
5
|
+
export interface Session {
|
|
6
|
+
sessionId: string;
|
|
7
|
+
userId: string;
|
|
8
|
+
createdTime: string;
|
|
9
|
+
fsUrl: string;
|
|
10
|
+
deviceType?: string;
|
|
11
|
+
browser?: string;
|
|
12
|
+
location?: string;
|
|
13
|
+
}
|
|
14
|
+
export interface UserEvent {
|
|
15
|
+
eventId: string;
|
|
16
|
+
eventType: string;
|
|
17
|
+
eventTime: string;
|
|
18
|
+
eventData?: Record<string, unknown>;
|
|
19
|
+
sessionId?: string;
|
|
20
|
+
}
|
|
21
|
+
export interface User {
|
|
22
|
+
id: string;
|
|
23
|
+
uid?: string;
|
|
24
|
+
displayName?: string;
|
|
25
|
+
email?: string;
|
|
26
|
+
properties?: Record<string, unknown>;
|
|
27
|
+
}
|
|
28
|
+
export interface SegmentExport {
|
|
29
|
+
operationId: string;
|
|
30
|
+
status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
|
|
31
|
+
progress?: number;
|
|
32
|
+
downloadUrl?: string;
|
|
33
|
+
}
|
|
34
|
+
export interface ExportRequest {
|
|
35
|
+
segmentId: string;
|
|
36
|
+
type: 'individuals' | 'events';
|
|
37
|
+
format?: 'FORMAT_CSV' | 'FORMAT_JSON' | 'FORMAT_NDJSON';
|
|
38
|
+
startTime?: string;
|
|
39
|
+
endTime?: string;
|
|
40
|
+
}
|
|
41
|
+
export declare class FullstoryClient {
|
|
42
|
+
private client;
|
|
43
|
+
private dataCenter;
|
|
44
|
+
constructor(config: FullstoryConfig);
|
|
45
|
+
private handleError;
|
|
46
|
+
getUserSessions(userId: string, limit?: number): Promise<Session[]>;
|
|
47
|
+
getSessionReplayUrl(sessionId: string): Promise<string>;
|
|
48
|
+
getUser(userId: string): Promise<User>;
|
|
49
|
+
searchUsers(query: Record<string, unknown>): Promise<User[]>;
|
|
50
|
+
getUserEvents(userId: string, startTime?: string, endTime?: string): Promise<UserEvent[]>;
|
|
51
|
+
sendEvent(event: {
|
|
52
|
+
userId: string;
|
|
53
|
+
sessionId?: string;
|
|
54
|
+
eventName: string;
|
|
55
|
+
eventData?: Record<string, unknown>;
|
|
56
|
+
timestamp?: string;
|
|
57
|
+
}): Promise<void>;
|
|
58
|
+
createSegmentExport(request: ExportRequest): Promise<SegmentExport>;
|
|
59
|
+
getExportStatus(operationId: string): Promise<SegmentExport>;
|
|
60
|
+
downloadExport(downloadUrl: string): Promise<unknown>;
|
|
61
|
+
listSegments(): Promise<Array<{
|
|
62
|
+
id: string;
|
|
63
|
+
name: string;
|
|
64
|
+
description?: string;
|
|
65
|
+
}>>;
|
|
66
|
+
getAuditTrail(settingType: string): Promise<unknown>;
|
|
67
|
+
}
|
|
68
|
+
//# sourceMappingURL=fullstory-client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fullstory-client.d.ts","sourceRoot":"","sources":["../src/fullstory-client.ts"],"names":[],"mappings":"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"}
|