vizro-mcp 0.0.1.dev0__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.
- vizro_mcp/__init__.py +19 -0
- vizro_mcp/_schemas/__init__.py +29 -0
- vizro_mcp/_schemas/schemas.py +297 -0
- vizro_mcp/_utils/__init__.py +33 -0
- vizro_mcp/_utils/utils.py +300 -0
- vizro_mcp/py.typed +0 -0
- vizro_mcp/server.py +400 -0
- vizro_mcp-0.0.1.dev0.dist-info/METADATA +212 -0
- vizro_mcp-0.0.1.dev0.dist-info/RECORD +12 -0
- vizro_mcp-0.0.1.dev0.dist-info/WHEEL +4 -0
- vizro_mcp-0.0.1.dev0.dist-info/entry_points.txt +2 -0
- vizro_mcp-0.0.1.dev0.dist-info/licenses/LICENSE.txt +202 -0
vizro_mcp/server.py
ADDED
|
@@ -0,0 +1,400 @@
|
|
|
1
|
+
"""MCP server for Vizro-AI chart and dashboard creation."""
|
|
2
|
+
|
|
3
|
+
import mimetypes
|
|
4
|
+
import webbrowser
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any, Literal, Optional
|
|
8
|
+
|
|
9
|
+
import vizro.models as vm
|
|
10
|
+
from mcp.server.fastmcp import FastMCP
|
|
11
|
+
from pydantic import ValidationError
|
|
12
|
+
from vizro import Vizro
|
|
13
|
+
|
|
14
|
+
from vizro_mcp._schemas import (
|
|
15
|
+
AgGridEnhanced,
|
|
16
|
+
ChartPlan,
|
|
17
|
+
ContainerSimplified,
|
|
18
|
+
DashboardSimplified,
|
|
19
|
+
FilterSimplified,
|
|
20
|
+
GraphEnhanced,
|
|
21
|
+
PageSimplified,
|
|
22
|
+
ParameterSimplified,
|
|
23
|
+
TabsSimplified,
|
|
24
|
+
get_overview_vizro_models,
|
|
25
|
+
get_simple_dashboard_config,
|
|
26
|
+
)
|
|
27
|
+
from vizro_mcp._utils import (
|
|
28
|
+
GAPMINDER,
|
|
29
|
+
IRIS,
|
|
30
|
+
SAMPLE_DASHBOARD_CONFIG,
|
|
31
|
+
STOCKS,
|
|
32
|
+
TIPS,
|
|
33
|
+
DFInfo,
|
|
34
|
+
DFMetaData,
|
|
35
|
+
convert_github_url_to_raw,
|
|
36
|
+
create_pycafe_url,
|
|
37
|
+
get_dataframe_info,
|
|
38
|
+
get_python_code_and_preview_link,
|
|
39
|
+
load_dataframe_by_format,
|
|
40
|
+
path_or_url_check,
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
# PyCafe URL for Vizro snippets
|
|
44
|
+
PYCAFE_URL = "https://py.cafe"
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass
|
|
48
|
+
class ValidationResults:
|
|
49
|
+
"""Results of the validation tool."""
|
|
50
|
+
|
|
51
|
+
valid: bool
|
|
52
|
+
message: str
|
|
53
|
+
python_code: str
|
|
54
|
+
pycafe_url: Optional[str]
|
|
55
|
+
browser_opened: bool
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
@dataclass
|
|
59
|
+
class DataAnalysisResults:
|
|
60
|
+
"""Results of the data analysis tool."""
|
|
61
|
+
|
|
62
|
+
valid: bool
|
|
63
|
+
message: str
|
|
64
|
+
df_info: Optional[DFInfo]
|
|
65
|
+
df_metadata: Optional[DFMetaData]
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
# TODO: what do I need to do here, as things are already set up?
|
|
69
|
+
mcp = FastMCP(
|
|
70
|
+
"MCP server to help create Vizro dashboards and charts.",
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
@mcp.tool()
|
|
75
|
+
def get_sample_data_info(data_name: Literal["iris", "tips", "stocks", "gapminder"]) -> DFMetaData:
|
|
76
|
+
"""If user provides no data, use this tool to get sample data information.
|
|
77
|
+
|
|
78
|
+
Use the following data for the below purposes:
|
|
79
|
+
- iris: mostly numerical with one categorical column, good for scatter, histogram, boxplot, etc.
|
|
80
|
+
- tips: contains mix of numerical and categorical columns, good for bar, pie, etc.
|
|
81
|
+
- stocks: stock prices, good for line, scatter, generally things that change over time
|
|
82
|
+
- gapminder: demographic data, good for line, scatter, generally things with maps or many categories
|
|
83
|
+
|
|
84
|
+
Args:
|
|
85
|
+
data_name: Name of the dataset to get sample data for
|
|
86
|
+
|
|
87
|
+
Returns:
|
|
88
|
+
Data info object containing information about the dataset.
|
|
89
|
+
"""
|
|
90
|
+
if data_name == "iris":
|
|
91
|
+
return IRIS
|
|
92
|
+
elif data_name == "tips":
|
|
93
|
+
return TIPS
|
|
94
|
+
elif data_name == "stocks":
|
|
95
|
+
return STOCKS
|
|
96
|
+
elif data_name == "gapminder":
|
|
97
|
+
return GAPMINDER
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
@mcp.tool()
|
|
101
|
+
def validate_model_config(
|
|
102
|
+
config: dict[str, Any],
|
|
103
|
+
data_infos: list[DFMetaData], # Should be Optional[..]=None, but Cursor complains..
|
|
104
|
+
auto_open: bool = True,
|
|
105
|
+
) -> ValidationResults:
|
|
106
|
+
"""Validate Vizro model configuration. Run ALWAYS when you have a complete dashboard configuration.
|
|
107
|
+
|
|
108
|
+
If successful, the tool will return the python code and, if it is a remote file, the py.cafe link to the chart.
|
|
109
|
+
The PyCafe link will be automatically opened in your default browser if auto_open is True.
|
|
110
|
+
|
|
111
|
+
Args:
|
|
112
|
+
config: Either a JSON string or a dictionary representing a Vizro model configuration
|
|
113
|
+
data_infos: List of DFMetaData objects containing information about the data files
|
|
114
|
+
auto_open: Whether to automatically open the PyCafe link in a browser
|
|
115
|
+
|
|
116
|
+
Returns:
|
|
117
|
+
ValidationResults object with status and dashboard details
|
|
118
|
+
"""
|
|
119
|
+
Vizro._reset()
|
|
120
|
+
|
|
121
|
+
try:
|
|
122
|
+
dashboard = vm.Dashboard.model_validate(config)
|
|
123
|
+
except ValidationError as e:
|
|
124
|
+
return ValidationResults(
|
|
125
|
+
valid=False,
|
|
126
|
+
message=f"Validation Error: {e!s}",
|
|
127
|
+
python_code="",
|
|
128
|
+
pycafe_url=None,
|
|
129
|
+
browser_opened=False,
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
else:
|
|
133
|
+
result = get_python_code_and_preview_link(dashboard, data_infos)
|
|
134
|
+
|
|
135
|
+
pycafe_url = result.pycafe_url if all(info.file_location_type == "remote" for info in data_infos) else None
|
|
136
|
+
browser_opened = False
|
|
137
|
+
|
|
138
|
+
if pycafe_url and auto_open:
|
|
139
|
+
try:
|
|
140
|
+
browser_opened = webbrowser.open(pycafe_url)
|
|
141
|
+
except Exception:
|
|
142
|
+
browser_opened = False
|
|
143
|
+
|
|
144
|
+
return ValidationResults(
|
|
145
|
+
valid=True,
|
|
146
|
+
message="Configuration is valid for Dashboard!",
|
|
147
|
+
python_code=result.python_code,
|
|
148
|
+
pycafe_url=pycafe_url,
|
|
149
|
+
browser_opened=browser_opened,
|
|
150
|
+
)
|
|
151
|
+
|
|
152
|
+
finally:
|
|
153
|
+
Vizro._reset()
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
@mcp.tool()
|
|
157
|
+
def get_model_json_schema(model_name: str) -> dict[str, Any]:
|
|
158
|
+
"""Get the JSON schema for the specified Vizro model.
|
|
159
|
+
|
|
160
|
+
Args:
|
|
161
|
+
model_name: Name of the Vizro model to get schema for (e.g., 'Card', 'Dashboard', 'Page')
|
|
162
|
+
|
|
163
|
+
Returns:
|
|
164
|
+
JSON schema of the requested Vizro model
|
|
165
|
+
"""
|
|
166
|
+
# Dictionary mapping model names to their simplified versions
|
|
167
|
+
modified_models = {
|
|
168
|
+
"Page": PageSimplified,
|
|
169
|
+
"Dashboard": DashboardSimplified,
|
|
170
|
+
"Graph": GraphEnhanced,
|
|
171
|
+
"AgGrid": AgGridEnhanced,
|
|
172
|
+
"Table": AgGridEnhanced,
|
|
173
|
+
"Tabs": TabsSimplified,
|
|
174
|
+
"Container": ContainerSimplified,
|
|
175
|
+
"Filter": FilterSimplified,
|
|
176
|
+
"Parameter": ParameterSimplified,
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
# Check if model_name is in the simplified models dictionary
|
|
180
|
+
if model_name in modified_models:
|
|
181
|
+
return modified_models[model_name].model_json_schema()
|
|
182
|
+
|
|
183
|
+
# Check if model exists in vizro.models
|
|
184
|
+
if not hasattr(vm, model_name):
|
|
185
|
+
return {"error": f"Model '{model_name}' not found in vizro.models"}
|
|
186
|
+
|
|
187
|
+
# Get schema for standard model
|
|
188
|
+
model_class = getattr(vm, model_name)
|
|
189
|
+
return model_class.model_json_schema()
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
@mcp.tool()
|
|
193
|
+
def get_vizro_chart_or_dashboard_plan(user_plan: Literal["chart", "dashboard"]) -> str:
|
|
194
|
+
"""Get instructions for creating a Vizro chart or dashboard. Call FIRST when asked to create Vizro things."""
|
|
195
|
+
if user_plan == "chart":
|
|
196
|
+
return """
|
|
197
|
+
IMPORTANT:
|
|
198
|
+
- KEEP IT SIMPLE: rather than iterating yourself, ask the user for more instructions
|
|
199
|
+
- ALWAYS VALIDATE:if you iterate over a valid produced solution, make sure to ALWAYS call the
|
|
200
|
+
validate_chart_code tool to validate the chart code, display the figure code to the user
|
|
201
|
+
- DO NOT modify the background (with plot_bgcolor) or color sequences unless explicitly asked for
|
|
202
|
+
|
|
203
|
+
Instructions for creating a Vizro chart:
|
|
204
|
+
- analyze the datasets needed for the chart using the load_and_analyze_data tool - the most important
|
|
205
|
+
information here are the column names and column types
|
|
206
|
+
- if the user provides no data, but you need to display a chart or table, use the get_sample_data_info
|
|
207
|
+
tool to get sample data information
|
|
208
|
+
- create a chart using plotly express and/or plotly graph objects, and call the function `custom_chart`
|
|
209
|
+
- call the validate_chart_code tool to validate the chart code, display the figure code to the user (as artifact)
|
|
210
|
+
- do NOT call any other tool after, especially do NOT create a dashboard
|
|
211
|
+
"""
|
|
212
|
+
elif user_plan == "dashboard":
|
|
213
|
+
return f"""
|
|
214
|
+
IMPORTANT:
|
|
215
|
+
- KEEP IT SIMPLE: rather than iterating yourself, ask the user for more instructions
|
|
216
|
+
- ALWAYS VALIDATE:if you iterate over a valid produced solution, make sure to ALWAYS call the
|
|
217
|
+
validate_model_config tool again to ensure the solution is still valid
|
|
218
|
+
- DO NOT show any code or config to the user until you have validated the solution, do not say you are preparing
|
|
219
|
+
a solution, just do it and validate it
|
|
220
|
+
- IF STUCK: try enquiring the schema of the component in question
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
Instructions for creating a Vizro dashboard:
|
|
224
|
+
- IF the user has no plan (ie no components or pages), use the config at the bottom of this prompt
|
|
225
|
+
and validate that solution without any additions, OTHERWISE:
|
|
226
|
+
- analyze the datasets needed for the dashboard using the load_and_analyze_data tool - the most
|
|
227
|
+
important information here are the column names and column types
|
|
228
|
+
- if the user provides no data, but you need to display a chart or table, use the get_sample_data_info
|
|
229
|
+
tool to get sample data information
|
|
230
|
+
- make a plan of what components you would like to use, then request all necessary schemas
|
|
231
|
+
using the get_model_json_schema tool
|
|
232
|
+
- assemble your components into a page, then add the page or pages to a dashboard, DO NOT show config or code
|
|
233
|
+
to the user until you have validated the solution
|
|
234
|
+
- ALWAYS validate the dashboard configuration using the validate_model_config tool
|
|
235
|
+
- if you display any code artifact, you must use the above created code, do not add new config to it
|
|
236
|
+
|
|
237
|
+
Models you can use:
|
|
238
|
+
{get_overview_vizro_models()}
|
|
239
|
+
|
|
240
|
+
Very simple dashboard config:
|
|
241
|
+
{get_simple_dashboard_config()}
|
|
242
|
+
"""
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
@mcp.tool()
|
|
246
|
+
def load_and_analyze_data(path_or_url: str) -> DataAnalysisResults:
|
|
247
|
+
"""Load data from various file formats into a pandas DataFrame and analyze its structure.
|
|
248
|
+
|
|
249
|
+
Supported formats:
|
|
250
|
+
- CSV (.csv)
|
|
251
|
+
- JSON (.json)
|
|
252
|
+
- HTML (.html, .htm)
|
|
253
|
+
- Excel (.xls, .xlsx)
|
|
254
|
+
- OpenDocument Spreadsheet (.ods)
|
|
255
|
+
- Parquet (.parquet)
|
|
256
|
+
|
|
257
|
+
Args:
|
|
258
|
+
path_or_url: Local file path or URL to a data file
|
|
259
|
+
|
|
260
|
+
Returns:
|
|
261
|
+
DataAnalysisResults object containing DataFrame information and metadata
|
|
262
|
+
"""
|
|
263
|
+
# Handle files and URLs
|
|
264
|
+
path_or_url_type = path_or_url_check(path_or_url)
|
|
265
|
+
mime_type, _ = mimetypes.guess_type(str(path_or_url))
|
|
266
|
+
processed_path_or_url = path_or_url
|
|
267
|
+
|
|
268
|
+
if path_or_url_type == "remote":
|
|
269
|
+
processed_path_or_url = convert_github_url_to_raw(path_or_url)
|
|
270
|
+
elif path_or_url_type == "local":
|
|
271
|
+
processed_path_or_url = Path(path_or_url)
|
|
272
|
+
else:
|
|
273
|
+
return DataAnalysisResults(valid=False, message="Invalid path or URL", df_info=None, df_metadata=None)
|
|
274
|
+
|
|
275
|
+
try:
|
|
276
|
+
df, read_fn = load_dataframe_by_format(processed_path_or_url, mime_type)
|
|
277
|
+
|
|
278
|
+
except Exception as e:
|
|
279
|
+
return DataAnalysisResults(valid=False, message=f"Failed to load data: {e!s}", df_info=None, df_metadata=None)
|
|
280
|
+
|
|
281
|
+
df_info = get_dataframe_info(df)
|
|
282
|
+
df_metadata = DFMetaData(
|
|
283
|
+
file_name=Path(path_or_url).stem if isinstance(processed_path_or_url, Path) else Path(path_or_url).name,
|
|
284
|
+
file_path_or_url=str(processed_path_or_url),
|
|
285
|
+
file_location_type=path_or_url_type,
|
|
286
|
+
read_function_string=read_fn,
|
|
287
|
+
)
|
|
288
|
+
|
|
289
|
+
return DataAnalysisResults(valid=True, message="Data loaded successfully", df_info=df_info, df_metadata=df_metadata)
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
@mcp.prompt()
|
|
293
|
+
def create_starter_dashboard():
|
|
294
|
+
"""Prompt template for getting started with Vizro."""
|
|
295
|
+
content = f"""
|
|
296
|
+
Create a super simple Vizro dashboard with one page and one chart and one filter:
|
|
297
|
+
- No need to call any tools except for validate_model_config
|
|
298
|
+
- Call this tool with the precise config as shown below
|
|
299
|
+
- The PyCafe link will be automatically opened in your default browser
|
|
300
|
+
- THEN show the python code after validation, but do not show the PyCafe link
|
|
301
|
+
- Be concise, do not explain anything else, just create the dashboard
|
|
302
|
+
- Finally ask the user what they would like to do next, then you can call other tools to get more information,
|
|
303
|
+
you should then start with the get_chart_or_dashboard_plan tool
|
|
304
|
+
|
|
305
|
+
{SAMPLE_DASHBOARD_CONFIG}
|
|
306
|
+
"""
|
|
307
|
+
return content
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
@mcp.prompt()
|
|
311
|
+
def create_eda_dashboard(
|
|
312
|
+
file_path_or_url: str,
|
|
313
|
+
) -> str:
|
|
314
|
+
"""Prompt template for creating an EDA dashboard based on one dataset."""
|
|
315
|
+
content = f"""
|
|
316
|
+
Create an EDA dashboard based on the following dataset:{file_path_or_url}. Proceed as follows:
|
|
317
|
+
1. Analyze the data using the load_and_analyze_data tool first, passing the file path or github url {file_path_or_url}
|
|
318
|
+
to the tool.
|
|
319
|
+
2. Create a dashboard with 4 pages:
|
|
320
|
+
- Page 1: Summary of the dataset using the Card component and the dataset itself using the plain AgGrid component.
|
|
321
|
+
- Page 2: Visualizing the distribution of all numeric columns using the Graph component with a histogram.
|
|
322
|
+
- use a Parameter that targets the Graph component and the x argument, and you can select the column to
|
|
323
|
+
be displayed
|
|
324
|
+
- IMPORTANT:remember that you target the chart like: <graph_id>.x and NOT <graph_id>.figure.x
|
|
325
|
+
- do not use any color schemes etc.
|
|
326
|
+
- add filters for all categorical columns
|
|
327
|
+
- Page 3: Visualizing the correlation between all numeric columns using the Graph component with a scatter plot.
|
|
328
|
+
- Page 4: Two interesting charts side by side, use the Graph component for this. Make sure they look good
|
|
329
|
+
but do not try something beyond the scope of plotly express
|
|
330
|
+
"""
|
|
331
|
+
return content
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
@mcp.tool()
|
|
335
|
+
def validate_chart_code(
|
|
336
|
+
config: ChartPlan,
|
|
337
|
+
data_info: DFMetaData,
|
|
338
|
+
auto_open: bool = True,
|
|
339
|
+
) -> ValidationResults:
|
|
340
|
+
"""Validate the chart code created by the user and optionally open the PyCafe link in a browser.
|
|
341
|
+
|
|
342
|
+
Args:
|
|
343
|
+
config: A ChartPlan object with the chart configuration
|
|
344
|
+
data_info: Metadata for the dataset to be used in the chart
|
|
345
|
+
auto_open: Whether to automatically open the PyCafe link in a browser
|
|
346
|
+
|
|
347
|
+
Returns:
|
|
348
|
+
ValidationResults object with status and dashboard details
|
|
349
|
+
"""
|
|
350
|
+
Vizro._reset()
|
|
351
|
+
|
|
352
|
+
try:
|
|
353
|
+
chart_plan_obj = ChartPlan.model_validate(config)
|
|
354
|
+
except ValidationError as e:
|
|
355
|
+
return ValidationResults(
|
|
356
|
+
valid=False,
|
|
357
|
+
message=f"Validation Error: {e!s}",
|
|
358
|
+
python_code="",
|
|
359
|
+
pycafe_url=None,
|
|
360
|
+
browser_opened=False,
|
|
361
|
+
)
|
|
362
|
+
else:
|
|
363
|
+
dashboard_code = chart_plan_obj.get_dashboard_template(data_info=data_info)
|
|
364
|
+
|
|
365
|
+
# Generate PyCafe URL if all data is remote
|
|
366
|
+
pycafe_url = create_pycafe_url(dashboard_code) if data_info.file_location_type == "remote" else None
|
|
367
|
+
browser_opened = False
|
|
368
|
+
|
|
369
|
+
if auto_open and pycafe_url:
|
|
370
|
+
try:
|
|
371
|
+
browser_opened = webbrowser.open(pycafe_url)
|
|
372
|
+
except Exception:
|
|
373
|
+
browser_opened = False
|
|
374
|
+
|
|
375
|
+
return ValidationResults(
|
|
376
|
+
valid=True,
|
|
377
|
+
message="Chart only dashboard created successfully!",
|
|
378
|
+
python_code=chart_plan_obj.get_chart_code(vizro=True),
|
|
379
|
+
pycafe_url=pycafe_url,
|
|
380
|
+
browser_opened=browser_opened,
|
|
381
|
+
)
|
|
382
|
+
|
|
383
|
+
finally:
|
|
384
|
+
Vizro._reset()
|
|
385
|
+
|
|
386
|
+
|
|
387
|
+
@mcp.prompt()
|
|
388
|
+
def create_vizro_chart(
|
|
389
|
+
chart_type: str,
|
|
390
|
+
file_path_or_url: Optional[str] = None,
|
|
391
|
+
) -> str:
|
|
392
|
+
"""Prompt template for creating a Vizro chart."""
|
|
393
|
+
content = f"""
|
|
394
|
+
- Create a chart using the following chart type: {chart_type}.
|
|
395
|
+
- You MUST name the function containing the fig `custom_chart`
|
|
396
|
+
- Make sure to analyze the data using the load_and_analyze_data tool first, passing the file path or github url
|
|
397
|
+
{file_path_or_url} OR choose the most appropriate sample data using the get_sample_data_info tool.
|
|
398
|
+
Then you MUST use the validate_chart_code tool to validate the chart code.
|
|
399
|
+
"""
|
|
400
|
+
return content
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: vizro-mcp
|
|
3
|
+
Version: 0.0.1.dev0
|
|
4
|
+
Summary: MCP server to help create Vizro dashboards and charts
|
|
5
|
+
Author: Vizro Team
|
|
6
|
+
License-File: LICENSE.txt
|
|
7
|
+
Classifier: Programming Language :: Python
|
|
8
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
12
|
+
Requires-Python: >=3.10
|
|
13
|
+
Requires-Dist: click>=8.1.7
|
|
14
|
+
Requires-Dist: httpx>=0.28.1
|
|
15
|
+
Requires-Dist: mcp[cli]>=1.6.0
|
|
16
|
+
Requires-Dist: pandas[excel,html,parquet]
|
|
17
|
+
Requires-Dist: vizro==0.1.38
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
|
|
20
|
+
# Vizro MCP server
|
|
21
|
+
|
|
22
|
+
Vizro-MCP is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, which works alongside a LLM to help you create Vizro dashboards and charts.
|
|
23
|
+
|
|
24
|
+
## Features of Vizro-MCP
|
|
25
|
+
|
|
26
|
+
Vizro-MCP provides tools and templates to create a functioning Vizro chart or dashboard step by step. Benefits include:
|
|
27
|
+
|
|
28
|
+
✅ One consistent framework for charts and dashboards with one common design language. ✅ Validated config output that is readable and easy to alter or maintain. ✅ Live preview of the dashboard to iterate the design until the dashboard is perfect. ✅ Use of local or remote datasets simply by providing a path or URL.
|
|
29
|
+
|
|
30
|
+
### Without Vizro-MCP
|
|
31
|
+
|
|
32
|
+
Without Vizro-MCP, if you try to make a dashboard using an LLM, it could choose any framework, and use it without specific guidance, design principles, or consistency. The results are:
|
|
33
|
+
|
|
34
|
+
❌ A random choice of frontend framework or charting library. ❌ A vibe-coded mess that may or may not run, but certainly is not very maintainable. ❌ No way to easily preview the dashboard. ❌ No easy way to connect to real data.
|
|
35
|
+
|
|
36
|
+
## 🛠️ Get started
|
|
37
|
+
|
|
38
|
+
If you are a **developer** and need instructions for running Vizro-MCP from source, skip to the end of this page to [Development or running from source](#development-or-running-from-source).
|
|
39
|
+
|
|
40
|
+
### Prerequisites
|
|
41
|
+
|
|
42
|
+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
|
|
43
|
+
- [Claude Desktop](https://claude.ai/download) or [Cursor](https://www.cursor.com/downloads)
|
|
44
|
+
|
|
45
|
+
In principle, the Vizro MCP server works with _any_ MCP enabled LLM applications but we recommend Claude Desktop or Cursor as popular choices.
|
|
46
|
+
|
|
47
|
+
> 🐛 **Note:** There are currently some known issues with [VS Code](https://code.visualstudio.com/) but we are working on this and hope to have Copilot working soon.
|
|
48
|
+
|
|
49
|
+
> ⚠️ **Warning:** In some hosts (like Claude Desktop) the free plan might be less performant, which may cause issues when the request is too complex. In cases where the request causes the UI to crash, opt for using a paid plan, or reduce your request's complexity.
|
|
50
|
+
|
|
51
|
+
## Setup Instructions
|
|
52
|
+
|
|
53
|
+
<details>
|
|
54
|
+
<summary><strong>Claude</strong></summary>
|
|
55
|
+
|
|
56
|
+
Add the following to your `claude_desktop_config.json` [found via Developer Settings](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server).
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"vizro-mcp": {
|
|
62
|
+
"command": "uvx",
|
|
63
|
+
"args": [
|
|
64
|
+
"vizro-mcp"
|
|
65
|
+
]
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
> ⚠️ **Warning:** In some cases you may need to provide the full path to your `uv` executable, so instead of `uv` would use something like `/Users/<your-username>/.local/bin/uv`. To discover the path of `uv` on your machine, in your terminal app, type `which uv`.
|
|
72
|
+
|
|
73
|
+
If you are using Claude Desktop, restart it, and after a few moments, you should see the vizro-mcp menu when opening the settings/context menu:
|
|
74
|
+
|
|
75
|
+
<img src="assets/claude_working.png" alt="Claude Desktop MCP Server Icon" width="150"/>
|
|
76
|
+
|
|
77
|
+
</details>
|
|
78
|
+
|
|
79
|
+
<details>
|
|
80
|
+
<summary><strong>Cursor</strong></summary>
|
|
81
|
+
|
|
82
|
+
Add the following to `mcp.json` [found via the Cursor Settings](https://docs.cursor.com/context/model-context-protocol#configuration-locations).
|
|
83
|
+
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"mcpServers": {
|
|
87
|
+
"vizro-mcp": {
|
|
88
|
+
"command": "uvx",
|
|
89
|
+
"args": [
|
|
90
|
+
"vizro-mcp"
|
|
91
|
+
]
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
> ⚠️ **Warning:** In some cases you may need to provide the full path to your `uv` executable, so instead of `uv` would use something like `/Users/<your-username>/.local/bin/uv`. To discover the path of `uv` on your machine, in your terminal app, type `which uv`.
|
|
98
|
+
|
|
99
|
+
Similarly, when using Cursor, after a short pause, you should see a green light in the MCP menu:
|
|
100
|
+
|
|
101
|
+
<img src="assets/cursor_working.png" alt="Cursor MCP Server Icon" width="400"/>
|
|
102
|
+
|
|
103
|
+
</details>
|
|
104
|
+
|
|
105
|
+
In principle, the Vizro MCP server works with _any_ MCP enabled LLM applications but we recommend Claude Desktop or Cursor as popular choices. Different AI tools may use different setup methods or connection settings. Check each tool's docs for details.
|
|
106
|
+
|
|
107
|
+
## 💻 Usage
|
|
108
|
+
|
|
109
|
+
### Use prompt templates to get specific dashboards quickly
|
|
110
|
+
|
|
111
|
+
Prompt templates are not available in all MCP hosts, but when they are, you can use them to get specific dashboards quickly. To access them (e.g. in Claude Desktop), click on the plus icon below the chat, and choose _`Add from vizro-mcp`_.
|
|
112
|
+
|
|
113
|
+
<img src="assets/claude_prompt.png" alt="Claude Desktop MCP Server Icon" width="300"/>
|
|
114
|
+
|
|
115
|
+
The **easiest** way to get started with Vizro dashboards is to choose the template `create_starter_dashboard` and just send the prompt. This will create a super simple dashboard with one page, one chart, and one filter. Take it from there!
|
|
116
|
+
|
|
117
|
+
### Create a Vizro dashboard based on local or remote data
|
|
118
|
+
|
|
119
|
+
You can also ask the LLM to create specific dashboards based on local or remote data if you already have an idea of what you want. Example prompts could be:
|
|
120
|
+
|
|
121
|
+
> _Create a Vizro dashboard with one page, a scatter chart, and a filter based on `<insert absolute file path or public URL>` data._
|
|
122
|
+
|
|
123
|
+
> _Create a simple two page Vizro dashboard, with first page being a correlation analysis of `<insert absolute file path or public URL>` data, and the second page being a map plot of `<insert absolute file path or public URL>` data_
|
|
124
|
+
|
|
125
|
+
You can even ask for a dashboard without providing data:
|
|
126
|
+
|
|
127
|
+
> _Create a Vizro dashboard with one page, a scatter chart, and a filter._
|
|
128
|
+
|
|
129
|
+
In general, it helps to specify Vizro in the prompt and to keep it as precise (and simple) as possible.
|
|
130
|
+
|
|
131
|
+
### Get a live preview of your dashboard
|
|
132
|
+
|
|
133
|
+
When the LLM chooses to use the tool `validate_model_config`, and the tool executes successfully, the LLM will return a link to a live preview of the dashboard if only public data accessed via URL is used. By default, the LLM will even open the link in your browser for you unless you tell it not to. In Claude Desktop, you can see the output of the tool by opening the tool collapsible and scrolling down to the very bottom.
|
|
134
|
+
|
|
135
|
+
<img src="assets/claude_validate.png" width="300"/>
|
|
136
|
+
|
|
137
|
+
You can also ask the model to give you the link, but it will attempt to regenerate it, which is very error prone and slow.
|
|
138
|
+
|
|
139
|
+
### Create Vizro charts
|
|
140
|
+
|
|
141
|
+
The **easiest** way to get started with Vizro charts is to choose the template `create_vizro_chart` and just send the prompt. This will create a simple chart that you can alter. Take it from there!
|
|
142
|
+
|
|
143
|
+
Alternatively, you can just ask in the chat things like:
|
|
144
|
+
|
|
145
|
+
> _Create a scatter based on the iris dataset._
|
|
146
|
+
|
|
147
|
+
> _Create a bar chart based on `<insert absolute file path or public URL>` data._
|
|
148
|
+
|
|
149
|
+
## 🔍 Transparency and trust
|
|
150
|
+
|
|
151
|
+
MCP servers are a relatively new concept, and it is important to be transparent about what the tools are capable of so you can make an informed choice as a user. Overall, the Vizro MCP server only reads data, and never writes, deletes or modifies any data on your machine.
|
|
152
|
+
|
|
153
|
+
In general the most critical part of the process is the `load_and_analyze_data` tool. This tool, running on your machine, will load local or remote data into a pandas DataFrame and provide a detailed analysis of its structure and content. It only uses `pd.read_xxx`, so in general there is no need to worry about privacy or data security.
|
|
154
|
+
|
|
155
|
+
The second most critical part is the `validate_model_config` tool. This tool will attempt to instantiate the Vizro model configuration and return the Python code and visualization link for valid configurations. If the configuration is valid, it will also return and attempt to open a link to a live preview of the dashboard, which will take you to [PyCafe](https://py.cafe). If you don't want to open the link, you can tell the LLM to not do so.
|
|
156
|
+
|
|
157
|
+
## Available Tools (if client allows)
|
|
158
|
+
|
|
159
|
+
The Vizro MCP server provides the following tools. In general you should not need to use them directly, but in special cases you could ask the LLM to call them directly to help it find its way.
|
|
160
|
+
|
|
161
|
+
- `get_vizro_chart_or_dashboard_plan` - Get a structured step-by-step plan for creating either a chart or dashboard. Provides guidance on the entire creation process.
|
|
162
|
+
- `get_model_JSON_schema` - Retrieves the complete JSON schema for any specified Vizro model, useful for understanding required and optional parameters.
|
|
163
|
+
- `validate_model_config` - Tests Vizro model configurations by attempting to instantiate them. Returns Python code and visualization links for valid configurations.
|
|
164
|
+
- `load_and_analyze_csv` - Loads a CSV file from a local path or URL into a pandas DataFrame and provides detailed analysis of its structure and content.
|
|
165
|
+
- `validate_chart_code` - Validates the code created for a chart and returns feedback on its correctness.
|
|
166
|
+
- `get_sample_data_info` - Provides information about sample datasets that can be used for testing and development.
|
|
167
|
+
|
|
168
|
+
## Available Prompts (if client allows)
|
|
169
|
+
|
|
170
|
+
- `create_starter_dashboard` - Use this prompt template to get started with Vizro dashboards.
|
|
171
|
+
- `create_EDA_dashboard` - Use this prompt template to create an Exploratory Data Analysis (EDA) dashboard based on a local or remote CSV dataset
|
|
172
|
+
- `create_vizro_chart` - Use this prompt template to create a Vizro styled plotly chart based on a local or remote CSV dataset
|
|
173
|
+
|
|
174
|
+
## Sample data
|
|
175
|
+
|
|
176
|
+
You can find a set of sample CSVs to try out in the [Plotly repository](https://github.com/plotly/datasets/tree/master).
|
|
177
|
+
|
|
178
|
+
## Development or running from source
|
|
179
|
+
|
|
180
|
+
If you are a developer, or if you are running Vizro-MCP from source, you need to clone the Vizro repo. To configure the Vizro MCP server details:
|
|
181
|
+
|
|
182
|
+
**For Claude**: Add the following to your `claude_desktop_config.json` [found via Developer Settings](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server):
|
|
183
|
+
|
|
184
|
+
**For Cursor**: Add the following to `mcp.json` [found via the Cursor Settings](https://docs.cursor.com/context/model-context-protocol#configuration-locations):
|
|
185
|
+
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"mcpServers": {
|
|
189
|
+
"vizro-mcp": {
|
|
190
|
+
"command": "uv",
|
|
191
|
+
"args": [
|
|
192
|
+
"run",
|
|
193
|
+
"--directory",
|
|
194
|
+
"<PATH TO VIZRO>/vizro-mcp/",
|
|
195
|
+
"vizro-mcp"
|
|
196
|
+
]
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Replace `<PATH TO VIZRO>` with the actual path to your Vizro repository. You may also need to provide the full path to your `uv` executable, so instead of `"uv"` you would use something like `"/Users/<your-username>/.local/bin/uv"`. To discover the path of `uv` on your machine, in your terminal app, type `which uv`.
|
|
203
|
+
|
|
204
|
+
## Other cool MCP Servers
|
|
205
|
+
|
|
206
|
+
Here are some other awesome MCP servers you might want to check out:
|
|
207
|
+
|
|
208
|
+
- [Context7](https://github.com/upstash/context7) - Provides up-to-date code documentation for any library directly in your prompts. Great for getting the latest API references and examples without relying on outdated training data.
|
|
209
|
+
|
|
210
|
+
- [Everything MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/everything) - A development-focused MCP server that combines multiple capabilities including web search, code search, and more. Useful for testing and prototyping MCP features. Part of the official MCP servers collection.
|
|
211
|
+
|
|
212
|
+
You can find more MCP servers in the [official MCP servers repository](https://github.com/modelcontextprotocol/servers/tree/main).
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
vizro_mcp/__init__.py,sha256=rARL6i447w01mUjVtn3WBb3noEgTzbrNqBinR5SUyrs,384
|
|
2
|
+
vizro_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
3
|
+
vizro_mcp/server.py,sha256=cINRBPr0hkN5S5tD_Gf6dYu8vC7QviYCOrCtiAxYYwU,14813
|
|
4
|
+
vizro_mcp/_schemas/__init__.py,sha256=przXt7ukurnDlj3SLRW-K0VO1ksnDDFuS8Njf80xepo,610
|
|
5
|
+
vizro_mcp/_schemas/schemas.py,sha256=r_0i9fRtyMh7W3q3KgnpCbRUDlBaFjG6XQjCtahgEXc,11625
|
|
6
|
+
vizro_mcp/_utils/__init__.py,sha256=q-xdwiyRCaOWWTeG5NC_1CzHWXBH4sUKpIBXbUaKg_Y,670
|
|
7
|
+
vizro_mcp/_utils/utils.py,sha256=gIuKXONR2SvOgA3Vo3ONnkh8Qcc-RLfrexJAjan12zk,9217
|
|
8
|
+
vizro_mcp-0.0.1.dev0.dist-info/METADATA,sha256=nCTKmpfHmHJ6h5TjlZ5zKVqk-CMhal9Ca1QhakaJITo,11747
|
|
9
|
+
vizro_mcp-0.0.1.dev0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
10
|
+
vizro_mcp-0.0.1.dev0.dist-info/entry_points.txt,sha256=iSUzPHvx4Ogsn91tK2C0OHxI44SNCHT1F1zUqbTj5O0,45
|
|
11
|
+
vizro_mcp-0.0.1.dev0.dist-info/licenses/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
|
|
12
|
+
vizro_mcp-0.0.1.dev0.dist-info/RECORD,,
|