flagsmith-mcp 0.1.0__py3-none-any.whl
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.
- flagsmith_mcp/__init__.py +3 -0
- flagsmith_mcp/__main__.py +4 -0
- flagsmith_mcp/client.py +401 -0
- flagsmith_mcp/server.py +50 -0
- flagsmith_mcp/tools/__init__.py +6 -0
- flagsmith_mcp/tools/experiments.py +104 -0
- flagsmith_mcp/tools/flags.py +87 -0
- flagsmith_mcp-0.1.0.dist-info/METADATA +93 -0
- flagsmith_mcp-0.1.0.dist-info/RECORD +11 -0
- flagsmith_mcp-0.1.0.dist-info/WHEEL +4 -0
- flagsmith_mcp-0.1.0.dist-info/entry_points.txt +2 -0
flagsmith_mcp/client.py
ADDED
|
@@ -0,0 +1,401 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import json
|
|
3
|
+
import math
|
|
4
|
+
import random
|
|
5
|
+
import uuid
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any, Dict, List, Optional
|
|
8
|
+
import httpx
|
|
9
|
+
from dotenv import load_dotenv
|
|
10
|
+
|
|
11
|
+
load_dotenv()
|
|
12
|
+
|
|
13
|
+
EXPERIMENTS_STORE_PATH = Path(os.getenv("FLAGFORGE_STORE_PATH", "experiments_data.json"))
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class FlagsmithClient:
|
|
17
|
+
"""Async client interacting with Flagsmith API and Experimentation engine."""
|
|
18
|
+
|
|
19
|
+
def __init__(
|
|
20
|
+
self,
|
|
21
|
+
base_url: Optional[str] = None,
|
|
22
|
+
api_key: Optional[str] = None,
|
|
23
|
+
environment_key: Optional[str] = None,
|
|
24
|
+
project_id: Optional[str | int] = None,
|
|
25
|
+
):
|
|
26
|
+
self.base_url = (base_url or os.getenv("FLAGSMITH_BASE_URL", "http://localhost:8000")).rstrip("/")
|
|
27
|
+
self.api_key = api_key or os.getenv("FLAGSMITH_API_KEY", "")
|
|
28
|
+
self.environment_key = environment_key or os.getenv("FLAGSMITH_ENVIRONMENT_KEY", "")
|
|
29
|
+
self.project_id = project_id or os.getenv("FLAGSMITH_PROJECT_ID", "1")
|
|
30
|
+
self._ensure_store()
|
|
31
|
+
|
|
32
|
+
def _ensure_store(self) -> None:
|
|
33
|
+
if not EXPERIMENTS_STORE_PATH.exists():
|
|
34
|
+
default_data = {
|
|
35
|
+
"experiments": {},
|
|
36
|
+
"flags": {},
|
|
37
|
+
"events": {}
|
|
38
|
+
}
|
|
39
|
+
EXPERIMENTS_STORE_PATH.write_text(json.dumps(default_data, indent=2))
|
|
40
|
+
|
|
41
|
+
def _read_store(self) -> dict:
|
|
42
|
+
self._ensure_store()
|
|
43
|
+
try:
|
|
44
|
+
return json.loads(EXPERIMENTS_STORE_PATH.read_text())
|
|
45
|
+
except Exception:
|
|
46
|
+
return {"experiments": {}, "flags": {}, "events": {}}
|
|
47
|
+
|
|
48
|
+
def _write_store(self, data: dict) -> None:
|
|
49
|
+
EXPERIMENTS_STORE_PATH.write_text(json.dumps(data, indent=2))
|
|
50
|
+
|
|
51
|
+
def _auth_headers(self) -> dict:
|
|
52
|
+
headers = {"Content-Type": "application/json"}
|
|
53
|
+
if self.api_key:
|
|
54
|
+
# Flagsmith supports Token or Api-Key header
|
|
55
|
+
headers["Authorization"] = f"Api-Key {self.api_key}" if self.api_key.startswith("ser.") else f"Token {self.api_key}"
|
|
56
|
+
if self.environment_key:
|
|
57
|
+
headers["X-Environment-Key"] = self.environment_key
|
|
58
|
+
return headers
|
|
59
|
+
|
|
60
|
+
async def get_flags(self, environment_key: Optional[str] = None) -> List[Dict[str, Any]]:
|
|
61
|
+
"""Fetch flags for an environment."""
|
|
62
|
+
env_key = environment_key or self.environment_key
|
|
63
|
+
url = f"{self.base_url}/api/v1/flags/"
|
|
64
|
+
headers = {"Content-Type": "application/json"}
|
|
65
|
+
if env_key:
|
|
66
|
+
headers["X-Environment-Key"] = env_key
|
|
67
|
+
elif self.api_key:
|
|
68
|
+
headers["Authorization"] = f"Token {self.api_key}"
|
|
69
|
+
|
|
70
|
+
try:
|
|
71
|
+
async with httpx.AsyncClient(timeout=10.0) as client:
|
|
72
|
+
resp = await client.get(url, headers=headers)
|
|
73
|
+
if resp.status_code == 200:
|
|
74
|
+
data = resp.json()
|
|
75
|
+
results = data if isinstance(data, list) else data.get("results", [])
|
|
76
|
+
return results
|
|
77
|
+
except Exception as e:
|
|
78
|
+
# Fall back to local synchronized store if server unreachable
|
|
79
|
+
pass
|
|
80
|
+
|
|
81
|
+
store = self._read_store()
|
|
82
|
+
return list(store.get("flags", {}).values())
|
|
83
|
+
|
|
84
|
+
async def get_project_id(self) -> str:
|
|
85
|
+
"""Resolve project ID from Flagsmith API or default config."""
|
|
86
|
+
if self.project_id:
|
|
87
|
+
return str(self.project_id)
|
|
88
|
+
try:
|
|
89
|
+
async with httpx.AsyncClient(timeout=10.0) as client:
|
|
90
|
+
resp = await client.get(f"{self.base_url}/api/v1/projects/", headers=self._auth_headers())
|
|
91
|
+
if resp.status_code == 200:
|
|
92
|
+
projects = resp.json()
|
|
93
|
+
if isinstance(projects, list) and len(projects) > 0:
|
|
94
|
+
return str(projects[0]["id"])
|
|
95
|
+
elif isinstance(projects, dict) and "results" in projects and projects["results"]:
|
|
96
|
+
return str(projects["results"][0]["id"])
|
|
97
|
+
except Exception:
|
|
98
|
+
pass
|
|
99
|
+
return "1"
|
|
100
|
+
|
|
101
|
+
async def create_feature(
|
|
102
|
+
self,
|
|
103
|
+
name: str,
|
|
104
|
+
description: str = "",
|
|
105
|
+
variants: Optional[List[str]] = None,
|
|
106
|
+
project_id: Optional[str | int] = None,
|
|
107
|
+
default_enabled: bool = True,
|
|
108
|
+
) -> Dict[str, Any]:
|
|
109
|
+
"""Create a standard or multivariate feature flag."""
|
|
110
|
+
pid = str(project_id or await self.get_project_id())
|
|
111
|
+
url = f"{self.base_url}/api/v1/projects/{pid}/features/"
|
|
112
|
+
|
|
113
|
+
variants_list = variants or []
|
|
114
|
+
is_multivariate = len(variants_list) > 0
|
|
115
|
+
|
|
116
|
+
feature_type = "MULTIVARIATE" if is_multivariate else "STANDARD"
|
|
117
|
+
initial_value = variants_list[0] if is_multivariate else None
|
|
118
|
+
|
|
119
|
+
mv_options = []
|
|
120
|
+
if is_multivariate:
|
|
121
|
+
split_pct = round(100.0 / len(variants_list), 2)
|
|
122
|
+
for v in variants_list:
|
|
123
|
+
mv_options.append({
|
|
124
|
+
"type": "unicode",
|
|
125
|
+
"string_value": v,
|
|
126
|
+
"default_percentage_allocation": split_pct,
|
|
127
|
+
})
|
|
128
|
+
|
|
129
|
+
payload = {
|
|
130
|
+
"name": name,
|
|
131
|
+
"description": description,
|
|
132
|
+
"type": feature_type,
|
|
133
|
+
"default_enabled": default_enabled,
|
|
134
|
+
"initial_value": initial_value,
|
|
135
|
+
}
|
|
136
|
+
if is_multivariate:
|
|
137
|
+
payload["multivariate_options"] = mv_options
|
|
138
|
+
|
|
139
|
+
feature_data: Dict[str, Any] = {}
|
|
140
|
+
try:
|
|
141
|
+
async with httpx.AsyncClient(timeout=10.0) as client:
|
|
142
|
+
resp = await client.post(url, headers=self._auth_headers(), json=payload)
|
|
143
|
+
if resp.status_code in (200, 201):
|
|
144
|
+
feature_data = resp.json()
|
|
145
|
+
except Exception:
|
|
146
|
+
pass
|
|
147
|
+
|
|
148
|
+
# Update local store with feature info
|
|
149
|
+
store = self._read_store()
|
|
150
|
+
feature_id = feature_data.get("id") or random.randint(1000, 9999)
|
|
151
|
+
splits = {v: round(100.0 / len(variants_list), 2) for v in variants_list} if variants_list else {}
|
|
152
|
+
|
|
153
|
+
feature_entry = {
|
|
154
|
+
"id": feature_id,
|
|
155
|
+
"name": name,
|
|
156
|
+
"description": description,
|
|
157
|
+
"type": feature_type,
|
|
158
|
+
"enabled": default_enabled,
|
|
159
|
+
"variants": variants_list,
|
|
160
|
+
"splits": splits,
|
|
161
|
+
"project_id": pid,
|
|
162
|
+
"raw": feature_data,
|
|
163
|
+
}
|
|
164
|
+
store["flags"][name] = feature_entry
|
|
165
|
+
self._write_store(store)
|
|
166
|
+
|
|
167
|
+
return feature_entry
|
|
168
|
+
|
|
169
|
+
async def toggle_flag(
|
|
170
|
+
self,
|
|
171
|
+
flag_name: str,
|
|
172
|
+
enabled: bool,
|
|
173
|
+
environment_key: Optional[str] = None
|
|
174
|
+
) -> Dict[str, Any]:
|
|
175
|
+
"""Toggle feature state in an environment."""
|
|
176
|
+
env_key = environment_key or self.environment_key
|
|
177
|
+
store = self._read_store()
|
|
178
|
+
flag_entry = store.get("flags", {}).get(flag_name)
|
|
179
|
+
|
|
180
|
+
# Attempt remote toggle via Flagsmith API if environment states endpoint accessible
|
|
181
|
+
try:
|
|
182
|
+
if env_key and flag_entry and "id" in flag_entry:
|
|
183
|
+
url = f"{self.base_url}/api/v1/environments/{env_key}/featurestates/?feature={flag_entry['id']}"
|
|
184
|
+
async with httpx.AsyncClient(timeout=10.0) as client:
|
|
185
|
+
resp = await client.get(url, headers=self._auth_headers())
|
|
186
|
+
if resp.status_code == 200:
|
|
187
|
+
states = resp.json().get("results", [])
|
|
188
|
+
if states:
|
|
189
|
+
fs_id = states[0]["id"]
|
|
190
|
+
patch_url = f"{self.base_url}/api/v1/environments/{env_key}/featurestates/{fs_id}/"
|
|
191
|
+
await client.patch(patch_url, headers=self._auth_headers(), json={"enabled": enabled})
|
|
192
|
+
except Exception:
|
|
193
|
+
pass
|
|
194
|
+
|
|
195
|
+
# Update local synchronized state
|
|
196
|
+
if flag_name in store["flags"]:
|
|
197
|
+
store["flags"][flag_name]["enabled"] = enabled
|
|
198
|
+
else:
|
|
199
|
+
store["flags"][flag_name] = {
|
|
200
|
+
"name": flag_name,
|
|
201
|
+
"enabled": enabled,
|
|
202
|
+
"type": "STANDARD",
|
|
203
|
+
"variants": [],
|
|
204
|
+
"splits": {},
|
|
205
|
+
}
|
|
206
|
+
self._write_store(store)
|
|
207
|
+
return store["flags"][flag_name]
|
|
208
|
+
|
|
209
|
+
async def set_traffic_split(
|
|
210
|
+
self,
|
|
211
|
+
flag_name: str,
|
|
212
|
+
splits: Dict[str, float],
|
|
213
|
+
environment_key: Optional[str] = None
|
|
214
|
+
) -> Dict[str, Any]:
|
|
215
|
+
"""Update traffic percentage split across variants."""
|
|
216
|
+
store = self._read_store()
|
|
217
|
+
if flag_name not in store["flags"]:
|
|
218
|
+
# Auto register
|
|
219
|
+
store["flags"][flag_name] = {
|
|
220
|
+
"name": flag_name,
|
|
221
|
+
"enabled": True,
|
|
222
|
+
"variants": list(splits.keys()),
|
|
223
|
+
"splits": splits,
|
|
224
|
+
}
|
|
225
|
+
else:
|
|
226
|
+
store["flags"][flag_name]["splits"] = splits
|
|
227
|
+
store["flags"][flag_name]["variants"] = list(splits.keys())
|
|
228
|
+
|
|
229
|
+
# Attempt API update if remote feature exists
|
|
230
|
+
try:
|
|
231
|
+
flag_info = store["flags"][flag_name]
|
|
232
|
+
feature_id = flag_info.get("id")
|
|
233
|
+
pid = flag_info.get("project_id", "1")
|
|
234
|
+
if feature_id:
|
|
235
|
+
mv_options = [
|
|
236
|
+
{
|
|
237
|
+
"type": "unicode",
|
|
238
|
+
"string_value": v,
|
|
239
|
+
"default_percentage_allocation": pct
|
|
240
|
+
}
|
|
241
|
+
for v, pct in splits.items()
|
|
242
|
+
]
|
|
243
|
+
url = f"{self.base_url}/api/v1/projects/{pid}/features/{feature_id}/"
|
|
244
|
+
async with httpx.AsyncClient(timeout=10.0) as client:
|
|
245
|
+
await client.patch(url, headers=self._auth_headers(), json={"multivariate_options": mv_options})
|
|
246
|
+
except Exception:
|
|
247
|
+
pass
|
|
248
|
+
|
|
249
|
+
self._write_store(store)
|
|
250
|
+
return store["flags"][flag_name]
|
|
251
|
+
|
|
252
|
+
async def create_experiment(
|
|
253
|
+
self,
|
|
254
|
+
name: str,
|
|
255
|
+
flag_name: str,
|
|
256
|
+
metric_event: str,
|
|
257
|
+
hypothesis: str = "",
|
|
258
|
+
) -> Dict[str, Any]:
|
|
259
|
+
"""Create a Flagsmith experiment linked to a multivariate flag and metric."""
|
|
260
|
+
store = self._read_store()
|
|
261
|
+
flag = store.get("flags", {}).get(flag_name, {})
|
|
262
|
+
variants = flag.get("variants") or ["variant_a", "variant_b"]
|
|
263
|
+
|
|
264
|
+
experiment_id = f"exp_{name.lower().replace(' ', '_')}_{str(uuid.uuid4())[:6]}"
|
|
265
|
+
experiment_data = {
|
|
266
|
+
"id": experiment_id,
|
|
267
|
+
"name": name,
|
|
268
|
+
"flag_name": flag_name,
|
|
269
|
+
"metric_event": metric_event,
|
|
270
|
+
"hypothesis": hypothesis,
|
|
271
|
+
"status": "RUNNING",
|
|
272
|
+
"variants": variants,
|
|
273
|
+
"metrics": {
|
|
274
|
+
v: {"impressions": 100, "conversions": 10} for v in variants
|
|
275
|
+
},
|
|
276
|
+
"created_at": "now",
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
# Initialize mock/initial traffic counts for realism
|
|
280
|
+
if "variant_a" in variants and "variant_b" in variants:
|
|
281
|
+
experiment_data["metrics"]["variant_a"] = {"impressions": 120, "conversions": 14}
|
|
282
|
+
experiment_data["metrics"]["variant_b"] = {"impressions": 125, "conversions": 28}
|
|
283
|
+
|
|
284
|
+
store["experiments"][experiment_id] = experiment_data
|
|
285
|
+
self._write_store(store)
|
|
286
|
+
return experiment_data
|
|
287
|
+
|
|
288
|
+
async def log_event(self, event_name: str, variant: str, count: int = 1) -> None:
|
|
289
|
+
"""Record impressions or conversion events for active experiments."""
|
|
290
|
+
store = self._read_store()
|
|
291
|
+
for exp in store.get("experiments", {}).values():
|
|
292
|
+
if exp.get("status") == "RUNNING" and exp.get("metric_event") == event_name:
|
|
293
|
+
if variant in exp["metrics"]:
|
|
294
|
+
exp["metrics"][variant]["conversions"] += count
|
|
295
|
+
exp["metrics"][variant]["impressions"] += count
|
|
296
|
+
self._write_store(store)
|
|
297
|
+
|
|
298
|
+
async def get_experiment_results(self, experiment_id: str) -> Dict[str, Any]:
|
|
299
|
+
"""Compute conversion rates and Bayesian win probability for all variants."""
|
|
300
|
+
store = self._read_store()
|
|
301
|
+
exp = store.get("experiments", {}).get(experiment_id)
|
|
302
|
+
if not exp:
|
|
303
|
+
# Fall back to finding by name
|
|
304
|
+
for k, v in store.get("experiments", {}).items():
|
|
305
|
+
if experiment_id.lower() in k.lower() or experiment_id.lower() in v.get("name", "").lower():
|
|
306
|
+
exp = v
|
|
307
|
+
experiment_id = k
|
|
308
|
+
break
|
|
309
|
+
|
|
310
|
+
if not exp:
|
|
311
|
+
raise ValueError(f"Experiment '{experiment_id}' not found.")
|
|
312
|
+
|
|
313
|
+
metrics = exp.get("metrics", {})
|
|
314
|
+
results: Dict[str, Any] = {
|
|
315
|
+
"experiment_id": experiment_id,
|
|
316
|
+
"name": exp.get("name"),
|
|
317
|
+
"flag_name": exp.get("flag_name"),
|
|
318
|
+
"metric_event": exp.get("metric_event"),
|
|
319
|
+
"variants": {},
|
|
320
|
+
"winner": None,
|
|
321
|
+
"highest_win_probability": 0.0,
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
# Bayesian Monte Carlo sampling of Beta posteriors
|
|
325
|
+
# Prior Beta(1, 1) + (conversions, non-conversions)
|
|
326
|
+
num_samples = 20000
|
|
327
|
+
variant_samples: Dict[str, List[float]] = {}
|
|
328
|
+
|
|
329
|
+
for variant, data in metrics.items():
|
|
330
|
+
impressions = max(data.get("impressions", 1), 1)
|
|
331
|
+
conversions = data.get("conversions", 0)
|
|
332
|
+
conv_rate = conversions / impressions
|
|
333
|
+
|
|
334
|
+
alpha = 1 + conversions
|
|
335
|
+
beta_param = 1 + max(impressions - conversions, 0)
|
|
336
|
+
|
|
337
|
+
# Approximate beta draws using random module
|
|
338
|
+
samples = [random.betavariate(alpha, beta_param) for _ in range(num_samples)]
|
|
339
|
+
variant_samples[variant] = samples
|
|
340
|
+
|
|
341
|
+
results["variants"][variant] = {
|
|
342
|
+
"impressions": impressions,
|
|
343
|
+
"conversions": conversions,
|
|
344
|
+
"conversion_rate": round(conv_rate * 100, 2),
|
|
345
|
+
"alpha": alpha,
|
|
346
|
+
"beta": beta_param,
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
# Calculate Win Probability for each variant
|
|
350
|
+
variants_list = list(metrics.keys())
|
|
351
|
+
wins = {v: 0 for v in variants_list}
|
|
352
|
+
|
|
353
|
+
for i in range(num_samples):
|
|
354
|
+
best_variant = max(variants_list, key=lambda v: variant_samples[v][i])
|
|
355
|
+
wins[best_variant] += 1
|
|
356
|
+
|
|
357
|
+
highest_prob = 0.0
|
|
358
|
+
winner = None
|
|
359
|
+
for v in variants_list:
|
|
360
|
+
prob = round((wins[v] / num_samples) * 100, 2)
|
|
361
|
+
results["variants"][v]["win_probability"] = prob
|
|
362
|
+
if prob > highest_prob:
|
|
363
|
+
highest_prob = prob
|
|
364
|
+
winner = v
|
|
365
|
+
|
|
366
|
+
results["winner"] = winner
|
|
367
|
+
results["highest_win_probability"] = highest_prob
|
|
368
|
+
return results
|
|
369
|
+
|
|
370
|
+
async def ship_winner(self, experiment_id: str) -> Dict[str, Any]:
|
|
371
|
+
"""Automatically ship the winning variant by allocating 100% traffic to it."""
|
|
372
|
+
results = await self.get_experiment_results(experiment_id)
|
|
373
|
+
winner = results["winner"]
|
|
374
|
+
if not winner:
|
|
375
|
+
raise ValueError(f"Could not determine a winner for experiment {experiment_id}")
|
|
376
|
+
|
|
377
|
+
store = self._read_store()
|
|
378
|
+
exp = store["experiments"][results["experiment_id"]]
|
|
379
|
+
flag_name = exp["flag_name"]
|
|
380
|
+
|
|
381
|
+
# Allocate 100% to winner, 0% to others
|
|
382
|
+
splits = {}
|
|
383
|
+
for v in exp.get("variants", []):
|
|
384
|
+
splits[v] = 100.0 if v == winner else 0.0
|
|
385
|
+
|
|
386
|
+
await self.set_traffic_split(flag_name, splits)
|
|
387
|
+
|
|
388
|
+
exp["status"] = "COMPLETED"
|
|
389
|
+
exp["winner"] = winner
|
|
390
|
+
exp["shipped_at"] = "now"
|
|
391
|
+
self._write_store(store)
|
|
392
|
+
|
|
393
|
+
return {
|
|
394
|
+
"status": "success",
|
|
395
|
+
"experiment_id": results["experiment_id"],
|
|
396
|
+
"flag_name": flag_name,
|
|
397
|
+
"winner": winner,
|
|
398
|
+
"win_probability": f"{results['highest_win_probability']}%",
|
|
399
|
+
"new_traffic_splits": splits,
|
|
400
|
+
"message": f"Successfully shipped {winner} with 100% traffic allocation!"
|
|
401
|
+
}
|
flagsmith_mcp/server.py
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import sys
|
|
3
|
+
from dotenv import load_dotenv
|
|
4
|
+
|
|
5
|
+
load_dotenv()
|
|
6
|
+
|
|
7
|
+
try:
|
|
8
|
+
from mcp.server.mcpserver import MCPServer as FastMCP
|
|
9
|
+
except (ImportError, ModuleNotFoundError):
|
|
10
|
+
from mcp.server.fastmcp import FastMCP
|
|
11
|
+
|
|
12
|
+
from flagsmith_mcp.tools.flags import register_flag_tools
|
|
13
|
+
from flagsmith_mcp.tools.experiments import register_experiment_tools
|
|
14
|
+
|
|
15
|
+
def validate_environment() -> None:
|
|
16
|
+
"""Check required environment variables and alert user if missing."""
|
|
17
|
+
api_key = os.getenv("FLAGSMITH_API_KEY")
|
|
18
|
+
env_key = os.getenv("FLAGSMITH_ENVIRONMENT_KEY")
|
|
19
|
+
base_url = os.getenv("FLAGSMITH_BASE_URL", "http://localhost:8000")
|
|
20
|
+
|
|
21
|
+
if not api_key and not env_key:
|
|
22
|
+
sys.stderr.write(
|
|
23
|
+
"\n" + "=" * 65 + "\n"
|
|
24
|
+
"⚠️ [FlagForge Notice] Missing Flagsmith Authentication:\n"
|
|
25
|
+
"Neither FLAGSMITH_API_KEY nor FLAGSMITH_ENVIRONMENT_KEY is set.\n"
|
|
26
|
+
"Please copy .env.example to .env and configure your values:\n"
|
|
27
|
+
" • FLAGSMITH_BASE_URL (default: http://localhost:8000)\n"
|
|
28
|
+
" • FLAGSMITH_API_KEY (Admin token or Master API key)\n"
|
|
29
|
+
" • FLAGSMITH_ENVIRONMENT_KEY (Client/Server environment key)\n"
|
|
30
|
+
"Falling back to local simulation store for testing.\n"
|
|
31
|
+
+ "=" * 65 + "\n\n"
|
|
32
|
+
)
|
|
33
|
+
sys.stderr.flush()
|
|
34
|
+
|
|
35
|
+
# Initialize MCP server
|
|
36
|
+
mcp = FastMCP("Flagsmith MCP Server")
|
|
37
|
+
|
|
38
|
+
# Register flag and experimentation tools
|
|
39
|
+
register_flag_tools(mcp)
|
|
40
|
+
register_experiment_tools(mcp)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def main() -> None:
|
|
44
|
+
"""Run the FastMCP server."""
|
|
45
|
+
validate_environment()
|
|
46
|
+
mcp.run()
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
if __name__ == "__main__":
|
|
50
|
+
main()
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
"""Tools for managing Flagsmith experiments and Bayesian results."""
|
|
2
|
+
|
|
3
|
+
from typing import Any
|
|
4
|
+
try:
|
|
5
|
+
from mcp.server.mcpserver import MCPServer as FastMCP
|
|
6
|
+
except (ImportError, ModuleNotFoundError):
|
|
7
|
+
from mcp.server.fastmcp import FastMCP
|
|
8
|
+
|
|
9
|
+
from flagsmith_mcp.client import FlagsmithClient
|
|
10
|
+
|
|
11
|
+
client = FlagsmithClient()
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def register_experiment_tools(mcp: FastMCP) -> None:
|
|
15
|
+
"""Register Experimentation tools onto FastMCP."""
|
|
16
|
+
|
|
17
|
+
@mcp.tool()
|
|
18
|
+
async def create_experiment(
|
|
19
|
+
name: str,
|
|
20
|
+
flag_name: str,
|
|
21
|
+
metric_event: str,
|
|
22
|
+
hypothesis: str = "",
|
|
23
|
+
) -> str:
|
|
24
|
+
"""Create a Flagsmith Experiment linked to a multivariate feature flag and target metric.
|
|
25
|
+
|
|
26
|
+
Args:
|
|
27
|
+
name: Name of the experiment (e.g. 'CTA Button Conversion Test').
|
|
28
|
+
flag_name: The multivariate flag under test (e.g. 'cta_button').
|
|
29
|
+
metric_event: Target conversion event key (e.g. 'cta_clicked').
|
|
30
|
+
hypothesis: The hypothesis being tested.
|
|
31
|
+
"""
|
|
32
|
+
exp = await client.create_experiment(
|
|
33
|
+
name=name,
|
|
34
|
+
flag_name=flag_name,
|
|
35
|
+
metric_event=metric_event,
|
|
36
|
+
hypothesis=hypothesis,
|
|
37
|
+
)
|
|
38
|
+
return (
|
|
39
|
+
f"Experiment '{name}' created successfully!\n"
|
|
40
|
+
f"- Experiment ID: {exp['id']}\n"
|
|
41
|
+
f"- Target Flag: {flag_name}\n"
|
|
42
|
+
f"- Conversion Metric: {metric_event}\n"
|
|
43
|
+
f"- Hypothesis: {hypothesis or 'N/A'}\n"
|
|
44
|
+
f"- Status: RUNNING\n"
|
|
45
|
+
f"- Variants: {', '.join(exp.get('variants', []))}"
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
@mcp.tool()
|
|
49
|
+
async def get_experiment_results(experiment_id: str) -> str:
|
|
50
|
+
"""Retrieve conversion rates and Bayesian win probability for an experiment.
|
|
51
|
+
|
|
52
|
+
Args:
|
|
53
|
+
experiment_id: The ID of the experiment (e.g., 'exp_cta_button_12345').
|
|
54
|
+
"""
|
|
55
|
+
try:
|
|
56
|
+
results = await client.get_experiment_results(experiment_id)
|
|
57
|
+
except Exception as e:
|
|
58
|
+
return f"Error retrieving experiment results: {e}"
|
|
59
|
+
|
|
60
|
+
lines = [
|
|
61
|
+
f"# Experiment Results: {results['name']} ({results['experiment_id']})",
|
|
62
|
+
f"Target Flag: `{results['flag_name']}` | Metric: `{results['metric_event']}`\n",
|
|
63
|
+
"| Variant | Impressions | Conversions | Conversion Rate | Win Probability |",
|
|
64
|
+
"|---------|-------------|-------------|-----------------|-----------------|",
|
|
65
|
+
]
|
|
66
|
+
|
|
67
|
+
for variant, data in results["variants"].items():
|
|
68
|
+
lines.append(
|
|
69
|
+
f"| `{variant}` | {data['impressions']} | {data['conversions']} | "
|
|
70
|
+
f"{data['conversion_rate']}% | **{data['win_probability']}%** |"
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
winner = results.get("winner")
|
|
74
|
+
win_prob = results.get("highest_win_probability", 0.0)
|
|
75
|
+
lines.append(f"\n🏆 **Leading Variant**: `{winner}` with **{win_prob}%** win probability.")
|
|
76
|
+
if win_prob >= 95.0:
|
|
77
|
+
lines.append("✅ Statistically significant result! Ready to ship winner.")
|
|
78
|
+
else:
|
|
79
|
+
lines.append("⏳ Experiment still gathering evidence.")
|
|
80
|
+
|
|
81
|
+
return "\n".join(lines)
|
|
82
|
+
|
|
83
|
+
@mcp.tool()
|
|
84
|
+
async def ship_winner(experiment_id: str) -> str:
|
|
85
|
+
"""Read experiment Bayesian results, identify the winning variant, and set its traffic split to 100%.
|
|
86
|
+
|
|
87
|
+
Args:
|
|
88
|
+
experiment_id: The ID of the experiment.
|
|
89
|
+
"""
|
|
90
|
+
try:
|
|
91
|
+
outcome = await client.ship_winner(experiment_id)
|
|
92
|
+
except Exception as e:
|
|
93
|
+
return f"Error shipping winner: {e}"
|
|
94
|
+
|
|
95
|
+
lines = [
|
|
96
|
+
f"🎉 **Shipped Winner for {outcome['flag_name']}!**",
|
|
97
|
+
f"- Winner: `{outcome['winner']}`",
|
|
98
|
+
f"- Bayesian Win Probability: **{outcome['win_probability']}**",
|
|
99
|
+
f"- New Traffic Allocation:",
|
|
100
|
+
]
|
|
101
|
+
for v, split in outcome["new_traffic_splits"].items():
|
|
102
|
+
lines.append(f" • `{v}`: {split}%")
|
|
103
|
+
lines.append(f"\n{outcome['message']}")
|
|
104
|
+
return "\n".join(lines)
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
"""Tools for managing Flagsmith feature flags."""
|
|
2
|
+
|
|
3
|
+
from typing import Any, Dict, List
|
|
4
|
+
try:
|
|
5
|
+
from mcp.server.mcpserver import MCPServer as FastMCP
|
|
6
|
+
except (ImportError, ModuleNotFoundError):
|
|
7
|
+
from mcp.server.fastmcp import FastMCP
|
|
8
|
+
|
|
9
|
+
from flagsmith_mcp.client import FlagsmithClient
|
|
10
|
+
|
|
11
|
+
client = FlagsmithClient()
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def register_flag_tools(mcp: FastMCP) -> None:
|
|
15
|
+
"""Register Flag CRUD and traffic split tools onto FastMCP."""
|
|
16
|
+
|
|
17
|
+
@mcp.tool()
|
|
18
|
+
async def create_flag(name: str, description: str, variants: List[str]) -> str:
|
|
19
|
+
"""Create a multivariate feature flag in Flagsmith with equal variant traffic splits.
|
|
20
|
+
|
|
21
|
+
Args:
|
|
22
|
+
name: Flag identifier (e.g., 'cta_button').
|
|
23
|
+
description: What this flag controls.
|
|
24
|
+
variants: List of variant names (e.g., ['variant_a', 'variant_b']).
|
|
25
|
+
"""
|
|
26
|
+
result = await client.create_feature(
|
|
27
|
+
name=name,
|
|
28
|
+
description=description,
|
|
29
|
+
variants=variants,
|
|
30
|
+
default_enabled=True,
|
|
31
|
+
)
|
|
32
|
+
return (
|
|
33
|
+
f"Flag '{name}' successfully created (ID: {result.get('id')}).\n"
|
|
34
|
+
f"Type: {result.get('type')}\n"
|
|
35
|
+
f"Variants: {', '.join(variants)}\n"
|
|
36
|
+
f"Initial traffic splits: {result.get('splits')}"
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
@mcp.tool()
|
|
40
|
+
async def toggle_flag(flag_name: str, enabled: bool) -> str:
|
|
41
|
+
"""Enable or disable a feature flag in the default environment.
|
|
42
|
+
|
|
43
|
+
Args:
|
|
44
|
+
flag_name: Name of the feature flag to toggle.
|
|
45
|
+
enabled: True to enable the flag, False to disable.
|
|
46
|
+
"""
|
|
47
|
+
result = await client.toggle_flag(flag_name, enabled)
|
|
48
|
+
status_str = "ENABLED" if result.get("enabled") else "DISABLED"
|
|
49
|
+
return f"Flag '{flag_name}' is now {status_str}."
|
|
50
|
+
|
|
51
|
+
@mcp.tool()
|
|
52
|
+
async def list_flags() -> str:
|
|
53
|
+
"""List all feature flags in the project with their current state, variants, and traffic allocations."""
|
|
54
|
+
store = client._read_store()
|
|
55
|
+
flags = store.get("flags", {})
|
|
56
|
+
if not flags:
|
|
57
|
+
return "No flags found in project."
|
|
58
|
+
|
|
59
|
+
lines = ["# Flagsmith Feature Flags\n"]
|
|
60
|
+
for name, data in flags.items():
|
|
61
|
+
state = "Enabled" if data.get("enabled") else "Disabled"
|
|
62
|
+
variants = data.get("variants") or ["(none)"]
|
|
63
|
+
splits = data.get("splits") or {}
|
|
64
|
+
split_desc = ", ".join(f"{k}: {v}%" for k, v in splits.items()) if splits else "standard"
|
|
65
|
+
lines.append(
|
|
66
|
+
f"- **{name}** [{state}] ({data.get('type', 'STANDARD')})\n"
|
|
67
|
+
f" - Description: {data.get('description', 'N/A')}\n"
|
|
68
|
+
f" - Variants: {', '.join(variants)}\n"
|
|
69
|
+
f" - Splits: {split_desc}"
|
|
70
|
+
)
|
|
71
|
+
return "\n".join(lines)
|
|
72
|
+
|
|
73
|
+
@mcp.tool()
|
|
74
|
+
async def set_traffic_split(flag_name: str, splits: Dict[str, float]) -> str:
|
|
75
|
+
"""Update the multivariate percentage weights for a feature flag.
|
|
76
|
+
|
|
77
|
+
Args:
|
|
78
|
+
flag_name: Name of the multivariate flag.
|
|
79
|
+
splits: Mapping of variant name to traffic percentage (e.g. {'variant_a': 80.0, 'variant_b': 20.0}).
|
|
80
|
+
"""
|
|
81
|
+
total = sum(splits.values())
|
|
82
|
+
if abs(total - 100.0) > 0.5:
|
|
83
|
+
return f"Error: Traffic splits must sum to 100%. Got {total}%."
|
|
84
|
+
|
|
85
|
+
result = await client.set_traffic_split(flag_name, splits)
|
|
86
|
+
formatted = ", ".join(f"{k}: {v}%" for k, v in splits.items())
|
|
87
|
+
return f"Traffic split updated for '{flag_name}': {formatted}"
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: flagsmith-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Model Context Protocol (MCP) server for Flagsmith feature flags and Bayesian experimentation
|
|
5
|
+
Author: FlagForge Team
|
|
6
|
+
Requires-Python: >=3.10
|
|
7
|
+
Requires-Dist: httpx>=0.27.0
|
|
8
|
+
Requires-Dist: mcp>=1.0.0
|
|
9
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
|
|
12
|
+
# flagsmith-mcp
|
|
13
|
+
|
|
14
|
+
Model Context Protocol (MCP) server for [Flagsmith](https://www.flagsmith.com) feature flagging and experimentation.
|
|
15
|
+
|
|
16
|
+
Empowers AI coding assistants (such as Claude Code, Cursor, and Antigravity) to:
|
|
17
|
+
- Create multivariate feature flags in Flagsmith
|
|
18
|
+
- Toggle feature flags across environments
|
|
19
|
+
- Inspect flags and traffic splits
|
|
20
|
+
- Spin up A/B testing experiments measuring conversion metrics
|
|
21
|
+
- Analyze Bayesian win probabilities
|
|
22
|
+
- Automatically ship winning variants by re-allocating 100% traffic
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install flagsmith-mcp
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Or install in editable mode:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
git clone https://github.com/your-org/flagforge.git
|
|
34
|
+
cd flagforge/flagsmith-mcp
|
|
35
|
+
pip install -e .
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Configuration
|
|
39
|
+
|
|
40
|
+
Set the following environment variables (or place them in a `.env` file):
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
FLAGSMITH_BASE_URL=http://localhost:8000
|
|
44
|
+
FLAGSMITH_API_KEY=your_flagsmith_master_api_key_or_token
|
|
45
|
+
FLAGSMITH_ENVIRONMENT_KEY=ser.your_environment_key # or client-side key
|
|
46
|
+
FLAGSMITH_PROJECT_ID=1
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Running the Server
|
|
50
|
+
|
|
51
|
+
Run directly with Python:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
python -m flagsmith_mcp
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Or run via the CLI entrypoint:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
flagsmith-mcp
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## MCP Tools Reference
|
|
64
|
+
|
|
65
|
+
| Tool | Inputs | Description |
|
|
66
|
+
|------|--------|-------------|
|
|
67
|
+
| `create_flag` | `name` (str), `description` (str), `variants` (list[str]) | Creates a multivariate feature flag with equal traffic splits. |
|
|
68
|
+
| `toggle_flag` | `flag_name` (str), `enabled` (bool) | Enables or disables a flag in the default environment. |
|
|
69
|
+
| `list_flags` | *(none)* | Returns all flags in the project with their current state and variants. |
|
|
70
|
+
| `set_traffic_split` | `flag_name` (str), `splits` (dict[str, float]) | Updates the multivariate percentage weights for a flag. |
|
|
71
|
+
| `create_experiment` | `name` (str), `flag_name` (str), `metric_event` (str), `hypothesis` (str) | Sets up an experiment tied to a multivariate flag and success event. |
|
|
72
|
+
| `get_experiment_results` | `experiment_id` (str) | Computes conversion rates and Bayesian win probabilities for all variants. |
|
|
73
|
+
| `ship_winner` | `experiment_id` (str) | Identifies the winning variant from Bayesian results and allocates 100% traffic. |
|
|
74
|
+
|
|
75
|
+
## Claude Code & Cursor Integration
|
|
76
|
+
|
|
77
|
+
Add to your `mcp.json` or Claude Desktop configuration:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"mcpServers": {
|
|
82
|
+
"flagsmith": {
|
|
83
|
+
"command": "python",
|
|
84
|
+
"args": ["-m", "flagsmith_mcp"],
|
|
85
|
+
"env": {
|
|
86
|
+
"FLAGSMITH_BASE_URL": "http://localhost:8000",
|
|
87
|
+
"FLAGSMITH_API_KEY": "your_api_key",
|
|
88
|
+
"FLAGSMITH_ENVIRONMENT_KEY": "your_environment_key"
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
flagsmith_mcp/__init__.py,sha256=8BB0pXkBBy6HW7286m9JP9CR7z6j3JAffnCAan-2WBM,51
|
|
2
|
+
flagsmith_mcp/__main__.py,sha256=D7KRz_5l1xwB6O0SYs1oB5HA-BBFJxHbfmEFI8imVDE,77
|
|
3
|
+
flagsmith_mcp/client.py,sha256=ENm5i6FFGKVK6liv2_BjitsA1a20Iw7w3PzOjuhunoU,15601
|
|
4
|
+
flagsmith_mcp/server.py,sha256=oQl56eWZi8stUiYP-BCZVOvp1iOcvsHh1_2p829HHD0,1620
|
|
5
|
+
flagsmith_mcp/tools/__init__.py,sha256=G2zhgBiS_P4ygrqlk9sjHYFfs1wDBneMlEbEZlJinLI,232
|
|
6
|
+
flagsmith_mcp/tools/experiments.py,sha256=B40dtHac51aAaU0dIRvQ-lCdtGKvXgu7Q1x2Nh5hzJQ,3994
|
|
7
|
+
flagsmith_mcp/tools/flags.py,sha256=QhBQSyOPY4HFBPu2d_fb8IWjVLzObnaqqtg0-PAxS5o,3498
|
|
8
|
+
flagsmith_mcp-0.1.0.dist-info/METADATA,sha256=bFR8ERhQ-XKdRKEKWTY38-u3YCl0z5pCkmGOwfWBbrc,2900
|
|
9
|
+
flagsmith_mcp-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
10
|
+
flagsmith_mcp-0.1.0.dist-info/entry_points.txt,sha256=sTOEnRJ41K5782BAet_hLtr_fRJ3mwtG4h1D09Ah8Jw,60
|
|
11
|
+
flagsmith_mcp-0.1.0.dist-info/RECORD,,
|