vizro-mcp 0.1.2__py3-none-any.whl → 0.1.4__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 +1 -1
- vizro_mcp/_schemas/__init__.py +2 -0
- vizro_mcp/_schemas/schemas.py +18 -2
- vizro_mcp/_utils/configs.py +2 -2
- vizro_mcp/_utils/prompts.py +36 -10
- vizro_mcp/_utils/utils.py +5 -2
- vizro_mcp/server.py +65 -51
- vizro_mcp-0.1.4.dist-info/METADATA +202 -0
- vizro_mcp-0.1.4.dist-info/RECORD +14 -0
- {vizro_mcp-0.1.2.dist-info → vizro_mcp-0.1.4.dist-info}/WHEEL +1 -1
- vizro_mcp-0.1.2.dist-info/METADATA +0 -323
- vizro_mcp-0.1.2.dist-info/RECORD +0 -14
- {vizro_mcp-0.1.2.dist-info → vizro_mcp-0.1.4.dist-info}/entry_points.txt +0 -0
- {vizro_mcp-0.1.2.dist-info → vizro_mcp-0.1.4.dist-info}/licenses/LICENSE.txt +0 -0
vizro_mcp/__init__.py
CHANGED
vizro_mcp/_schemas/__init__.py
CHANGED
vizro_mcp/_schemas/schemas.py
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
"""Schema defining pydantic models for usage in the MCP server."""
|
|
2
2
|
|
|
3
|
-
from typing import Annotated, Any
|
|
3
|
+
from typing import Annotated, Any
|
|
4
4
|
|
|
5
|
+
import vizro.figures as vf
|
|
5
6
|
import vizro.models as vm
|
|
6
7
|
from pydantic import AfterValidator, BaseModel, Field, PrivateAttr, ValidationInfo
|
|
7
8
|
|
|
@@ -58,6 +59,21 @@ The only difference to the dash version is that:
|
|
|
58
59
|
)
|
|
59
60
|
|
|
60
61
|
|
|
62
|
+
FIGURE_NAMESPACE_FUNCTION_DOCS = {func: vf.__dict__[func].__doc__ for func in vf.__all__}
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class FigureEnhanced(vm.Figure):
|
|
66
|
+
"""Figure model that allows to use dynamic figure functions."""
|
|
67
|
+
|
|
68
|
+
figure: dict[str, Any] = Field(
|
|
69
|
+
description=f"""This is the figure function to be displayed.
|
|
70
|
+
|
|
71
|
+
Only use arguments from the below mapping of _target_ to figure function documentation:
|
|
72
|
+
|
|
73
|
+
{FIGURE_NAMESPACE_FUNCTION_DOCS}"""
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
|
|
61
77
|
###### Chart functionality ######
|
|
62
78
|
def _strip_markdown(code_string: str) -> str:
|
|
63
79
|
"""Remove any code block wrappers (markdown or triple quotes)."""
|
|
@@ -137,7 +153,7 @@ class ChartPlan(BaseModel):
|
|
|
137
153
|
imports = [imp for imp in imports if "vizro" not in imp]
|
|
138
154
|
return "\n".join(imports) + "\n"
|
|
139
155
|
|
|
140
|
-
def get_chart_code(self, chart_name:
|
|
156
|
+
def get_chart_code(self, chart_name: str | None = None, vizro: bool = False):
|
|
141
157
|
chart_code = self.chart_code
|
|
142
158
|
if vizro:
|
|
143
159
|
chart_code = chart_code.replace(f"def {self.chart_name}", f"@capture('graph')\ndef {self.chart_name}")
|
vizro_mcp/_utils/configs.py
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"""Pre-set configs for the Vizro MCP."""
|
|
2
2
|
|
|
3
3
|
from dataclasses import dataclass
|
|
4
|
-
from typing import Any, Literal
|
|
4
|
+
from typing import Any, Literal
|
|
5
5
|
|
|
6
6
|
|
|
7
7
|
@dataclass
|
|
@@ -10,7 +10,7 @@ class DFMetaData:
|
|
|
10
10
|
file_path_or_url: str
|
|
11
11
|
file_location_type: Literal["local", "remote"]
|
|
12
12
|
read_function_string: Literal["pd.read_csv", "pd.read_json", "pd.read_html", "pd.read_parquet", "pd.read_excel"]
|
|
13
|
-
column_names_types:
|
|
13
|
+
column_names_types: dict[str, str] | None = None
|
|
14
14
|
|
|
15
15
|
|
|
16
16
|
@dataclass
|
vizro_mcp/_utils/prompts.py
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
"""Prompts for the Vizro MCP."""
|
|
2
2
|
# ruff: noqa: E501 #Ignore line length only in prompts
|
|
3
3
|
|
|
4
|
-
from typing import Literal,
|
|
4
|
+
from typing import Literal, Protocol
|
|
5
5
|
|
|
6
6
|
import vizro
|
|
7
|
+
import vizro.actions as va
|
|
8
|
+
import vizro.figures as vf
|
|
7
9
|
import vizro.models as vm
|
|
8
10
|
|
|
9
11
|
from vizro_mcp._utils.configs import SAMPLE_DASHBOARD_CONFIG
|
|
@@ -28,7 +30,9 @@ IMPORTANT:
|
|
|
28
30
|
- ALWAYS CHECK SCHEMA: to start with, or when stuck, try enquiring the schema of the component in question with the `get_model_json_schema` tool (available models see below)
|
|
29
31
|
|
|
30
32
|
- IF the user has no plan (ie no components or pages), use the config at the bottom of this prompt, OTHERWISE:
|
|
31
|
-
- make a plan of what components you would like to use, then request all necessary schemas using the `get_model_json_schema` tool
|
|
33
|
+
- make a plan of what components you would like to use, then request all necessary schemas using the `get_model_json_schema` tool
|
|
34
|
+
- start with `Dashboard`, don't forget `Graph`,
|
|
35
|
+
- MUST explicitly set layout (layout setting is NOT optional, contrary to what schema says)
|
|
32
36
|
- assemble your components into a page, then add the page or pages to a dashboard, DO NOT show config or code to the user until you have validated the solution
|
|
33
37
|
- ALWAYS validate the dashboard configuration using the `validate_dashboard_config` tool
|
|
34
38
|
- using `custom_chart` is encouraged for advanced visualizations, no need to call the planner tool in advanced mode
|
|
@@ -50,24 +54,46 @@ GENERIC_HOST_INSTRUCTIONS = """
|
|
|
50
54
|
instead and explain how to run it
|
|
51
55
|
"""
|
|
52
56
|
|
|
57
|
+
|
|
58
|
+
# Protocol class does not seem to matter for static type checkers - implemented nonetheless for correctness
|
|
59
|
+
# TODO: Check why type errors in MODEL_GROUPS would not be picked up by mypy
|
|
60
|
+
class HasNameAndDoc(Protocol):
|
|
61
|
+
"""Protocol for objects that have a name and a docstring."""
|
|
62
|
+
|
|
63
|
+
__name__: str
|
|
64
|
+
__doc__: str | None
|
|
65
|
+
|
|
66
|
+
|
|
53
67
|
# This dict is used to give the model and overview of what is available in the vizro.models namespace.
|
|
54
68
|
# It helps it to narrow down the choices when asking for a model.
|
|
55
|
-
|
|
69
|
+
# Intentionally omitted: Accordion, Action, Table, Layout and VizroBaseModel
|
|
70
|
+
MODEL_GROUPS: dict[str, list[type[HasNameAndDoc]]] = {
|
|
56
71
|
"main": [vm.Dashboard, vm.Page],
|
|
57
|
-
"components": [
|
|
72
|
+
"static components": [
|
|
73
|
+
vm.Card,
|
|
74
|
+
vm.Button,
|
|
75
|
+
vm.Text,
|
|
76
|
+
vm.Container,
|
|
77
|
+
vm.Tabs,
|
|
78
|
+
],
|
|
79
|
+
"dynamic components - ie reactive to controls": [vm.Figure, vm.Graph, vm.AgGrid],
|
|
58
80
|
"layouts": [vm.Grid, vm.Flex],
|
|
59
|
-
"controls": [vm.Filter, vm.Parameter],
|
|
60
|
-
"selectors": [
|
|
81
|
+
"controls - control display of dynamic components": [vm.Filter, vm.Parameter],
|
|
82
|
+
"selectors - input mechanisms for controls": [
|
|
61
83
|
vm.Dropdown,
|
|
62
84
|
vm.RadioItems,
|
|
63
85
|
vm.Checklist,
|
|
64
86
|
vm.DatePicker,
|
|
65
87
|
vm.Slider,
|
|
66
88
|
vm.RangeSlider,
|
|
67
|
-
vm.
|
|
89
|
+
vm.Switch,
|
|
68
90
|
],
|
|
69
91
|
"navigation": [vm.Navigation, vm.NavBar, vm.NavLink],
|
|
70
|
-
"additional_info": [vm.Tooltip],
|
|
92
|
+
"additional_info - info about the component": [vm.Tooltip],
|
|
93
|
+
"actions available for the actions argument of a model": [
|
|
94
|
+
getattr(va, func) for func in va.__all__ if not hasattr(getattr(va, func), "__deprecated__")
|
|
95
|
+
],
|
|
96
|
+
"functions available for vm.Figure(...,figure=...) model": [getattr(vf, func) for func in vf.__all__],
|
|
71
97
|
}
|
|
72
98
|
|
|
73
99
|
|
|
@@ -134,7 +160,7 @@ Create a super simple Vizro dashboard with one page and one chart and one filter
|
|
|
134
160
|
"""
|
|
135
161
|
|
|
136
162
|
|
|
137
|
-
def get_dashboard_prompt(file_path_or_url: str, user_context:
|
|
163
|
+
def get_dashboard_prompt(file_path_or_url: str, user_context: str | None = None) -> str:
|
|
138
164
|
"""Get a prompt for creating a Vizro dashboard."""
|
|
139
165
|
USER_INSTRUCTIONS = f"""
|
|
140
166
|
3. Create a Vizro dashboard that follows the user context:
|
|
@@ -165,7 +191,7 @@ Create a dashboard based on the following dataset: `{file_path_or_url}`. Proceed
|
|
|
165
191
|
"""
|
|
166
192
|
|
|
167
193
|
|
|
168
|
-
def get_chart_prompt(file_path_or_url: str, user_context:
|
|
194
|
+
def get_chart_prompt(file_path_or_url: str, user_context: str | None = None) -> str:
|
|
169
195
|
"""Get a prompt for creating a Vizro chart."""
|
|
170
196
|
FALLBACK_INSTRUCTIONS = """
|
|
171
197
|
- Think what chart could reflect this data-set best, ideally the chart shows some insights about the data-set
|
vizro_mcp/_utils/utils.py
CHANGED
|
@@ -7,7 +7,7 @@ import json
|
|
|
7
7
|
import re
|
|
8
8
|
from dataclasses import dataclass
|
|
9
9
|
from pathlib import Path
|
|
10
|
-
from typing import TYPE_CHECKING, Literal
|
|
10
|
+
from typing import TYPE_CHECKING, Literal
|
|
11
11
|
from urllib.parse import quote, urlencode
|
|
12
12
|
|
|
13
13
|
import pandas as pd
|
|
@@ -44,7 +44,7 @@ def convert_github_url_to_raw(path_or_url: str) -> str:
|
|
|
44
44
|
|
|
45
45
|
|
|
46
46
|
def load_dataframe_by_format(
|
|
47
|
-
path_or_url:
|
|
47
|
+
path_or_url: str | Path, mime_type: str | None = None
|
|
48
48
|
) -> tuple[pd.DataFrame, Literal["pd.read_csv", "pd.read_json", "pd.read_html", "pd.read_excel", "pd.read_parquet"]]:
|
|
49
49
|
"""Load a dataframe based on file format determined by MIME type or file extension."""
|
|
50
50
|
file_path_str_lower = str(path_or_url).lower()
|
|
@@ -152,6 +152,9 @@ def get_python_code_and_preview_link(
|
|
|
152
152
|
"from vizro import Vizro",
|
|
153
153
|
"import pandas as pd",
|
|
154
154
|
"from vizro.managers import data_manager",
|
|
155
|
+
"import vizro.figures as vf",
|
|
156
|
+
# TODO: Temporary workaround for Figure model support; required until vizro>=0.1.46
|
|
157
|
+
# Remove this import once minimum supported vizro version is >=0.1.46.
|
|
155
158
|
]
|
|
156
159
|
custom_imports = [
|
|
157
160
|
imp for custom_chart in custom_charts for imp in custom_chart.get_imports(vizro=True).split("\n") if imp.strip()
|
vizro_mcp/server.py
CHANGED
|
@@ -4,8 +4,9 @@ import mimetypes
|
|
|
4
4
|
import webbrowser
|
|
5
5
|
from dataclasses import dataclass
|
|
6
6
|
from pathlib import Path
|
|
7
|
-
from typing import Any, Literal
|
|
7
|
+
from typing import Any, Literal
|
|
8
8
|
|
|
9
|
+
import vizro
|
|
9
10
|
import vizro.models as vm
|
|
10
11
|
from mcp.server.fastmcp import FastMCP
|
|
11
12
|
from pydantic import Field, ValidationError
|
|
@@ -14,6 +15,7 @@ from vizro import Vizro
|
|
|
14
15
|
from vizro_mcp._schemas import (
|
|
15
16
|
AgGridEnhanced,
|
|
16
17
|
ChartPlan,
|
|
18
|
+
FigureEnhanced,
|
|
17
19
|
GraphEnhanced,
|
|
18
20
|
)
|
|
19
21
|
from vizro_mcp._utils import (
|
|
@@ -45,7 +47,7 @@ class ValidateResults:
|
|
|
45
47
|
valid: bool
|
|
46
48
|
message: str
|
|
47
49
|
python_code: str
|
|
48
|
-
pycafe_url:
|
|
50
|
+
pycafe_url: str | None
|
|
49
51
|
browser_opened: bool
|
|
50
52
|
|
|
51
53
|
|
|
@@ -55,8 +57,8 @@ class DataAnalysisResults:
|
|
|
55
57
|
|
|
56
58
|
valid: bool
|
|
57
59
|
message: str
|
|
58
|
-
df_info:
|
|
59
|
-
df_metadata:
|
|
60
|
+
df_info: DFInfo | None
|
|
61
|
+
df_metadata: DFMetaData | None
|
|
60
62
|
|
|
61
63
|
|
|
62
64
|
@dataclass
|
|
@@ -70,28 +72,28 @@ class ModelJsonSchemaResults:
|
|
|
70
72
|
|
|
71
73
|
# TODO: check on https://github.com/modelcontextprotocol/python-sdk what new things are possible to do here
|
|
72
74
|
mcp = FastMCP(
|
|
73
|
-
"MCP server to help create Vizro dashboards and charts.",
|
|
75
|
+
name=f"MCP server to help create Vizro dashboards and charts. Server Vizro version: {vizro.__version__}",
|
|
74
76
|
)
|
|
75
77
|
|
|
76
78
|
|
|
77
79
|
@mcp.tool()
|
|
78
80
|
def get_vizro_chart_or_dashboard_plan(
|
|
79
|
-
user_plan: Literal["chart", "dashboard"],
|
|
80
|
-
user_host: Literal["generic_host", "ide"]
|
|
81
|
-
|
|
81
|
+
user_plan: Literal["chart", "dashboard"] = Field(description="The type of Vizro thing the user wants to create"),
|
|
82
|
+
user_host: Literal["generic_host", "ide"] = Field(
|
|
83
|
+
description="The host the user is using, if 'ide' you can use the IDE/editor to run python code"
|
|
84
|
+
),
|
|
85
|
+
advanced_mode: bool = Field(
|
|
86
|
+
default=False,
|
|
87
|
+
description="""Only call if you need to use custom CSS, custom components or custom actions.
|
|
88
|
+
No need to call this with advanced_mode=True if you need advanced charts,
|
|
89
|
+
use `custom_charts` in the `validate_dashboard_config` tool instead.""",
|
|
90
|
+
),
|
|
82
91
|
) -> str:
|
|
83
92
|
"""Get instructions for creating a Vizro chart or dashboard. Call FIRST when asked to create Vizro things.
|
|
84
93
|
|
|
85
94
|
Must be ALWAYS called FIRST with advanced_mode=False, then call again with advanced_mode=True
|
|
86
95
|
if the JSON config does not suffice anymore.
|
|
87
96
|
|
|
88
|
-
Args:
|
|
89
|
-
user_plan: The type of Vizro thing the user wants to create
|
|
90
|
-
user_host: The host the user is using, if "ide" you can use the IDE/editor to run python code
|
|
91
|
-
advanced_mode: Only call if you need to use custom CSS, custom components or custom actions.
|
|
92
|
-
No need to call this with advanced_mode=True if you need advanced charts, use `custom_charts` in
|
|
93
|
-
the `validate_dashboard_config` tool instead.
|
|
94
|
-
|
|
95
97
|
Returns:
|
|
96
98
|
Instructions for creating a Vizro chart or dashboard
|
|
97
99
|
"""
|
|
@@ -101,20 +103,29 @@ def get_vizro_chart_or_dashboard_plan(
|
|
|
101
103
|
return f"{get_dashboard_instructions(advanced_mode, user_host)}"
|
|
102
104
|
|
|
103
105
|
|
|
104
|
-
@mcp.tool()
|
|
105
|
-
def get_model_json_schema(
|
|
106
|
+
@mcp.tool(description=f"Get the JSON schema for the specified Vizro model. Server Vizro version: {vizro.__version__}")
|
|
107
|
+
def get_model_json_schema(
|
|
108
|
+
model_name: str = Field(
|
|
109
|
+
description="Name of the Vizro model to get schema for (e.g., 'Card', 'Dashboard', 'Page')"
|
|
110
|
+
),
|
|
111
|
+
) -> ModelJsonSchemaResults:
|
|
106
112
|
"""Get the JSON schema for the specified Vizro model.
|
|
107
113
|
|
|
108
|
-
Args:
|
|
109
|
-
model_name: Name of the Vizro model to get schema for (e.g., 'Card', 'Dashboard', 'Page')
|
|
110
|
-
|
|
111
114
|
Returns:
|
|
112
115
|
JSON schema of the requested Vizro model
|
|
113
116
|
"""
|
|
117
|
+
if not hasattr(vm, model_name):
|
|
118
|
+
return ModelJsonSchemaResults(
|
|
119
|
+
model_name=model_name,
|
|
120
|
+
json_schema={},
|
|
121
|
+
additional_info=f"Model '{model_name}' not found in vizro.models",
|
|
122
|
+
)
|
|
123
|
+
|
|
114
124
|
modified_models = {
|
|
115
125
|
"Graph": GraphEnhanced,
|
|
116
126
|
"AgGrid": AgGridEnhanced,
|
|
117
127
|
"Table": AgGridEnhanced,
|
|
128
|
+
"Figure": FigureEnhanced,
|
|
118
129
|
}
|
|
119
130
|
|
|
120
131
|
if model_name in modified_models:
|
|
@@ -124,15 +135,23 @@ def get_model_json_schema(model_name: str) -> ModelJsonSchemaResults:
|
|
|
124
135
|
additional_info="""LLM must remember to replace `$ref` with the actual config. Request the schema of
|
|
125
136
|
that model if necessary. Do NOT forget to call `validate_dashboard_config` after each iteration.""",
|
|
126
137
|
)
|
|
127
|
-
|
|
128
|
-
if
|
|
138
|
+
deprecated_models = {"filter_interaction": "set_control", "Layout": "Grid"}
|
|
139
|
+
if model_name in deprecated_models:
|
|
129
140
|
return ModelJsonSchemaResults(
|
|
130
141
|
model_name=model_name,
|
|
131
142
|
json_schema={},
|
|
132
|
-
additional_info=f"Model '{model_name}'
|
|
143
|
+
additional_info=f"Model '{model_name}' is deprecated. Use {deprecated_models[model_name]} instead.",
|
|
133
144
|
)
|
|
134
145
|
|
|
135
146
|
model_class = getattr(vm, model_name)
|
|
147
|
+
if model_name in {"Grid", "Flex"}:
|
|
148
|
+
return ModelJsonSchemaResults(
|
|
149
|
+
model_name=model_name,
|
|
150
|
+
json_schema=model_class.model_json_schema(schema_generator=NoDefsGenerateJsonSchema),
|
|
151
|
+
additional_info="""Grid layout: use integers starting from 0 to reference elements.
|
|
152
|
+
Elements can't overlap, must be rectangular, and rows must have equal column counts.""",
|
|
153
|
+
)
|
|
154
|
+
|
|
136
155
|
return ModelJsonSchemaResults(
|
|
137
156
|
model_name=model_name,
|
|
138
157
|
json_schema=model_class.model_json_schema(schema_generator=NoDefsGenerateJsonSchema),
|
|
@@ -142,7 +161,11 @@ that model if necessary. Do NOT forget to call `validate_dashboard_config` after
|
|
|
142
161
|
|
|
143
162
|
|
|
144
163
|
@mcp.tool()
|
|
145
|
-
def get_sample_data_info(
|
|
164
|
+
def get_sample_data_info(
|
|
165
|
+
data_name: Literal["iris", "tips", "stocks", "gapminder"] = Field(
|
|
166
|
+
description="Name of the dataset to get sample data for"
|
|
167
|
+
),
|
|
168
|
+
) -> DFMetaData:
|
|
146
169
|
"""If user provides no data, use this tool to get sample data information.
|
|
147
170
|
|
|
148
171
|
Use the following data for the below purposes:
|
|
@@ -151,9 +174,6 @@ def get_sample_data_info(data_name: Literal["iris", "tips", "stocks", "gapminder
|
|
|
151
174
|
- stocks: stock prices, good for line, scatter, generally things that change over time
|
|
152
175
|
- gapminder: demographic data, good for line, scatter, generally things with maps or many categories
|
|
153
176
|
|
|
154
|
-
Args:
|
|
155
|
-
data_name: Name of the dataset to get sample data for
|
|
156
|
-
|
|
157
177
|
Returns:
|
|
158
178
|
Data info object containing information about the dataset.
|
|
159
179
|
"""
|
|
@@ -168,7 +188,9 @@ def get_sample_data_info(data_name: Literal["iris", "tips", "stocks", "gapminder
|
|
|
168
188
|
|
|
169
189
|
|
|
170
190
|
@mcp.tool()
|
|
171
|
-
def load_and_analyze_data(
|
|
191
|
+
def load_and_analyze_data(
|
|
192
|
+
path_or_url: str = Field(description="Absolute (important!) local file path or URL to a data file"),
|
|
193
|
+
) -> DataAnalysisResults:
|
|
172
194
|
"""Use to understand local or remote data files. Must be called with absolute paths or URLs.
|
|
173
195
|
|
|
174
196
|
Supported formats:
|
|
@@ -179,9 +201,6 @@ def load_and_analyze_data(path_or_url: str) -> DataAnalysisResults:
|
|
|
179
201
|
- OpenDocument Spreadsheet (.ods)
|
|
180
202
|
- Parquet (.parquet)
|
|
181
203
|
|
|
182
|
-
Args:
|
|
183
|
-
path_or_url: Absolute (important!) local file path or URL to a data file
|
|
184
|
-
|
|
185
204
|
Returns:
|
|
186
205
|
DataAnalysisResults object containing DataFrame information and metadata
|
|
187
206
|
"""
|
|
@@ -225,22 +244,22 @@ column types for passing along to the `validate_dashboard_config` or `validate_c
|
|
|
225
244
|
# - data_infos: check we are referring to the correct dataframe, or at least A DF
|
|
226
245
|
@mcp.tool()
|
|
227
246
|
def validate_dashboard_config(
|
|
228
|
-
dashboard_config: dict[str, Any]
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
247
|
+
dashboard_config: dict[str, Any] = Field(
|
|
248
|
+
description="Either a JSON string or a dictionary representing a Vizro dashboard model configuration"
|
|
249
|
+
),
|
|
250
|
+
data_infos: list[DFMetaData] = Field(
|
|
251
|
+
description="List of DFMetaData objects containing information about the data files"
|
|
252
|
+
),
|
|
253
|
+
custom_charts: list[ChartPlan] = Field(
|
|
254
|
+
description="List of ChartPlan objects containing information about the custom charts in the dashboard"
|
|
255
|
+
),
|
|
256
|
+
auto_open: bool = Field(default=True, description="Whether to automatically open the PyCafe link in a browser"),
|
|
232
257
|
) -> ValidateResults:
|
|
233
258
|
"""Validate Vizro model configuration. Run ALWAYS when you have a complete dashboard configuration.
|
|
234
259
|
|
|
235
260
|
If successful, the tool will return the python code and, if it is a remote file, the py.cafe link to the chart.
|
|
236
261
|
The PyCafe link will be automatically opened in your default browser if auto_open is True.
|
|
237
262
|
|
|
238
|
-
Args:
|
|
239
|
-
dashboard_config: Either a JSON string or a dictionary representing a Vizro dashboard model configuration
|
|
240
|
-
data_infos: List of DFMetaData objects containing information about the data files
|
|
241
|
-
custom_charts: List of ChartPlan objects containing information about the custom charts in the dashboard
|
|
242
|
-
auto_open: Whether to automatically open the PyCafe link in a browser
|
|
243
|
-
|
|
244
263
|
Returns:
|
|
245
264
|
ValidationResults object with status and dashboard details
|
|
246
265
|
"""
|
|
@@ -296,7 +315,7 @@ def create_starter_dashboard():
|
|
|
296
315
|
@mcp.prompt()
|
|
297
316
|
def create_dashboard(
|
|
298
317
|
file_path_or_url: str = Field(description="The absolute path or URL to the data file you want to use."),
|
|
299
|
-
context:
|
|
318
|
+
context: str | None = Field(default=None, description="(Optional) Describe the dashboard you want to create."),
|
|
300
319
|
) -> str:
|
|
301
320
|
"""Prompt template for creating an EDA dashboard based on one dataset."""
|
|
302
321
|
return get_dashboard_prompt(file_path_or_url, context)
|
|
@@ -304,17 +323,12 @@ def create_dashboard(
|
|
|
304
323
|
|
|
305
324
|
@mcp.tool()
|
|
306
325
|
def validate_chart_code(
|
|
307
|
-
chart_config: ChartPlan,
|
|
308
|
-
data_info: DFMetaData,
|
|
309
|
-
auto_open: bool = True,
|
|
326
|
+
chart_config: ChartPlan = Field(description="A ChartPlan object with the chart configuration"),
|
|
327
|
+
data_info: DFMetaData = Field(description="Metadata for the dataset to be used in the chart"),
|
|
328
|
+
auto_open: bool = Field(default=True, description="Whether to automatically open the PyCafe link in a browser"),
|
|
310
329
|
) -> ValidateResults:
|
|
311
330
|
"""Validate the chart code created by the user and optionally open the PyCafe link in a browser.
|
|
312
331
|
|
|
313
|
-
Args:
|
|
314
|
-
chart_config: A ChartPlan object with the chart configuration
|
|
315
|
-
data_info: Metadata for the dataset to be used in the chart
|
|
316
|
-
auto_open: Whether to automatically open the PyCafe link in a browser
|
|
317
|
-
|
|
318
332
|
Returns:
|
|
319
333
|
ValidationResults object with status and dashboard details
|
|
320
334
|
"""
|
|
@@ -358,7 +372,7 @@ def validate_chart_code(
|
|
|
358
372
|
@mcp.prompt()
|
|
359
373
|
def create_vizro_chart(
|
|
360
374
|
file_path_or_url: str = Field(description="The absolute path or URL to the data file you want to use."),
|
|
361
|
-
context:
|
|
375
|
+
context: str | None = Field(default=None, description="(Optional) Describe the chart you want to create."),
|
|
362
376
|
) -> str:
|
|
363
377
|
"""Prompt template for creating a Vizro chart."""
|
|
364
378
|
return get_chart_prompt(file_path_or_url, context)
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: vizro-mcp
|
|
3
|
+
Version: 0.1.4
|
|
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
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Requires-Dist: click>=8.1.7
|
|
15
|
+
Requires-Dist: httpx>=0.28.1
|
|
16
|
+
Requires-Dist: mcp[cli]>=1.6.0
|
|
17
|
+
Requires-Dist: pandas[excel,html,parquet]
|
|
18
|
+
Requires-Dist: vizro>=0.1.46
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
<!-- <a href="https://glama.ai/mcp/servers/@mckinsey/vizro">
|
|
22
|
+
<img width="380" height="200" src="https://glama.ai/mcp/servers/@mckinsey/vizro/badge" />
|
|
23
|
+
</a> -->
|
|
24
|
+
|
|
25
|
+
# Vizro-MCP
|
|
26
|
+
|
|
27
|
+
Vizro-MCP is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, which works alongside an LLM to help you create Vizro dashboards and charts.
|
|
28
|
+
|
|
29
|
+
<img src="docs/assets/images/vizro-mcp.gif" width="600" alt="Vizro-MCP Demo">
|
|
30
|
+
|
|
31
|
+
To find out more, consult the [Vizro-MCP documentation](https://vizro.readthedocs.io/projects/vizro-mcp/).
|
|
32
|
+
|
|
33
|
+
## Set up Vizro-MCP
|
|
34
|
+
|
|
35
|
+
Vizro-MCP is best used with Claude Desktop, Cursor or VS Code. However, it can be used with most LLM products that enable configuration of MCP server usage.
|
|
36
|
+
|
|
37
|
+
> 💡 Tip: For best performance, we recommend using the `claude-4-sonnet` model, or another high-performing model of your choice. Using the often offered `auto` setting may lead to inconsistent or unexpected results.
|
|
38
|
+
|
|
39
|
+
Our documentation offers separate, detailed steps for [Claude Desktop](https://vizro.readthedocs.io/projects/vizro-mcp/en/latest/pages/guides/set-up-vizro-mcp-with-claude/), [Cursor](https://vizro.readthedocs.io/projects/vizro-mcp/en/latest/pages/guides/set-up-vizro-mcp-with-cursor/) and [VS Code](https://vizro.readthedocs.io/projects/vizro-mcp/en/latest/pages/guides/set-up-vizro-mcp-with-vscode/).
|
|
40
|
+
|
|
41
|
+
### Basic configuration
|
|
42
|
+
|
|
43
|
+
The following is for those familiar with MCP server setup who are comfortable with basic configuration settings. You must have downloaded and installed the LLM app you want to configure and use as a MCP host.
|
|
44
|
+
|
|
45
|
+
<details>
|
|
46
|
+
<summary><strong>Quick setup for Vizro-MCP using uv</strong></summary>
|
|
47
|
+
|
|
48
|
+
You must first install [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
49
|
+
|
|
50
|
+
Next, open a terminal window and type `uv` to confirm that is available. To get the path to `uvx`, type the following:
|
|
51
|
+
|
|
52
|
+
```shell
|
|
53
|
+
which uv
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Copy the path returned, and add the following to the JSON file used to configure MCP servers for your LLM app. Be sure to substitute your path to uv as returned above, for the placeholder given:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"vizro-mcp": {
|
|
62
|
+
"command": "/placeholder-path/uvx",
|
|
63
|
+
"args": [
|
|
64
|
+
"vizro-mcp"
|
|
65
|
+
]
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**Quick install**
|
|
72
|
+
|
|
73
|
+
| Host | Prerequisite | Link |
|
|
74
|
+
| ----------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
75
|
+
| [Cursor](https://www.cursor.com/) | [uv](https://docs.astral.sh/uv/getting-started/installation/) | [](https://cursor.com/en/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoidXZ4IHZpenJvLW1jcCJ9) |
|
|
76
|
+
| [VS Code](https://code.visualstudio.com/) | [uv](https://docs.astral.sh/uv/guides/tools/) | [](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22vizro-mcp%22%5D%7D) |
|
|
77
|
+
|
|
78
|
+
</details>
|
|
79
|
+
|
|
80
|
+
<details>
|
|
81
|
+
<summary><strong>Quick setup for Vizro-MCP using Docker</strong></summary>
|
|
82
|
+
|
|
83
|
+
You must first install [Docker](https://www.docker.com/get-started/).
|
|
84
|
+
|
|
85
|
+
Next, add the following to the JSON file used to configure MCP servers for your LLM app.
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
{
|
|
89
|
+
"mcpServers": {
|
|
90
|
+
"vizro-mcp": {
|
|
91
|
+
"command": "docker",
|
|
92
|
+
"args": [
|
|
93
|
+
"run",
|
|
94
|
+
"-i",
|
|
95
|
+
"--rm",
|
|
96
|
+
"mcp/vizro"
|
|
97
|
+
]
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
**To use local data with Docker**
|
|
104
|
+
|
|
105
|
+
Mount your data directory or directories into the container with the following extended configuration. Replace `</absolute/path/to/allowed/dir>` (syntax for folders) or `</absolute/path/to/data.csv>` (syntax for files) with the absolute path to your data on your machine. For consistency, we recommend that the `dst` path matches the `src` path.
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
{
|
|
109
|
+
"mcpServers": {
|
|
110
|
+
"vizro-mcp": {
|
|
111
|
+
"command": "docker",
|
|
112
|
+
"args": [
|
|
113
|
+
"run",
|
|
114
|
+
"-i",
|
|
115
|
+
"--rm",
|
|
116
|
+
"--mount",
|
|
117
|
+
"type=bind,src=</absolute/path/to/allowed/dir>,dst=</absolute/path/to/allowed/dir>",
|
|
118
|
+
"--mount",
|
|
119
|
+
"type=bind,src=</absolute/path/to/data.csv>,dst=</absolute/path/to/data.csv>",
|
|
120
|
+
"mcp/vizro"
|
|
121
|
+
]
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**Quick install**
|
|
128
|
+
|
|
129
|
+
| Host | Prerequisite | Link | Notes |
|
|
130
|
+
| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
131
|
+
| [Cursor](https://www.cursor.com/) | [Docker](https://www.docker.com/get-started/) | [](https://cursor.com/en/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoiZG9ja2VyIHJ1biAtaSAtLXJtIG1jcC92aXpybyIsImVudiI6e319) | For local data access, [mount your data directory](#setup-instructions) |
|
|
132
|
+
| [VS Code](https://code.visualstudio.com/) | [Docker](https://www.docker.com/get-started/) | [](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Fvizro%22%5D%7D) | For local data access, [mount your data directory](#setup-instructions) |
|
|
133
|
+
|
|
134
|
+
</details>
|
|
135
|
+
|
|
136
|
+
## Disclaimers
|
|
137
|
+
|
|
138
|
+
### Transparency and trust
|
|
139
|
+
|
|
140
|
+
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.
|
|
141
|
+
|
|
142
|
+
### Third party API
|
|
143
|
+
|
|
144
|
+
Users are responsible for anything done via their host LLM application.
|
|
145
|
+
|
|
146
|
+
Users are responsible for procuring any and all rights necessary to access any third-party generative AI tools and for complying with any applicable terms or conditions thereof.
|
|
147
|
+
|
|
148
|
+
Users are wholly responsible for the use and security of the third-party generative AI tools and of Vizro.
|
|
149
|
+
|
|
150
|
+
### Legal information
|
|
151
|
+
|
|
152
|
+
<details>
|
|
153
|
+
<summary><strong>User acknowledgments</strong></summary>
|
|
154
|
+
|
|
155
|
+
Users acknowledge and agree that:
|
|
156
|
+
|
|
157
|
+
Any results, options, data, recommendations, analyses, code, or other information (“Outputs”) generated by any third-party generative AI tools (“GenAI Tools”) may contain some inaccuracies, biases, illegitimate, potentially infringing, or otherwise inappropriate content that may be mistaken, discriminatory, or misleading.
|
|
158
|
+
|
|
159
|
+
McKinsey & Company:
|
|
160
|
+
|
|
161
|
+
(i) expressly disclaims the accuracy, adequacy, timeliness, reliability, merchantability, fitness for a particular purpose, non-infringement, safety or completeness of any Outputs,
|
|
162
|
+
|
|
163
|
+
(ii) shall not be liable for any errors, omissions, or other defects in, delays or interruptions in such Outputs, or for any actions taken in reliance thereon, and
|
|
164
|
+
|
|
165
|
+
(iii) shall not be liable for any alleged violation or infringement of any right of any third party resulting from the users’ use of the GenAI Tools and the Outputs.
|
|
166
|
+
|
|
167
|
+
The Outputs shall be verified and validated by the users and shall not be used without human oversight and as a sole basis for making decisions impacting individuals.
|
|
168
|
+
|
|
169
|
+
Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case, as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output. Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-MCP and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights.
|
|
170
|
+
|
|
171
|
+
</details>
|
|
172
|
+
|
|
173
|
+
<details>
|
|
174
|
+
<summary><strong>Warning and safety usage for generative AI models</strong></summary>
|
|
175
|
+
|
|
176
|
+
Vizro-MCP is used by generative AI models because large language models (LLMs) represent significant advancements in the AI field. However, as with any powerful tool, there are potential risks associated with connecting to a generative AI model.
|
|
177
|
+
|
|
178
|
+
We recommend users research and understand the selected model before using Vizro-MCP. We also recommend users to check the MCP server code before using it.
|
|
179
|
+
|
|
180
|
+
Users are encouraged to treat AI-generated content as supplementary, always apply human judgment, approach with caution, review the relevant disclaimer page, and consider the following:
|
|
181
|
+
|
|
182
|
+
<ol>
|
|
183
|
+
<li>Hallucination and misrepresentation</li>
|
|
184
|
+
Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading.
|
|
185
|
+
|
|
186
|
+
The vendor models might lack real-time knowledge or events beyond its last updates. Vizro-MCP output may vary and you should always verify critical information. It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content.
|
|
187
|
+
|
|
188
|
+
<li>Unintended and sensitive output</li>
|
|
189
|
+
The outputs from these models can be unexpected, inappropriate, or even harmful. Users as human in the loop is an essential part. Users must check and interpret the final output. It is necessary to approach the generated content with caution, especially when shared or applied in various contexts.
|
|
190
|
+
|
|
191
|
+
<li>Data privacy</li>
|
|
192
|
+
Your data is sent to model vendors if you connect to LLMs via their APIs. For example, if you connect to the model from OpenAI, your data will be sent to OpenAI via their API. Users should be cautious about sharing or inputting any personal or sensitive information.
|
|
193
|
+
|
|
194
|
+
<li>Bias and fairness</li>
|
|
195
|
+
Generative AI can exhibit biases present in their training data. Users need to be aware of and navigate potential biases in generated outputs and be cautious when interpreting the generated content.
|
|
196
|
+
|
|
197
|
+
<li>Malicious use</li>
|
|
198
|
+
These models can be exploited for various malicious activities. Users should be cautious about how and where they deploy and access such models.
|
|
199
|
+
</ol>
|
|
200
|
+
It's crucial for users to remain informed, cautious, and ethical in their applications.
|
|
201
|
+
|
|
202
|
+
</details>
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
vizro_mcp/__init__.py,sha256=b07rnAb9ypm8N9O4fLH5LYOeVC48ncU5k_xesNH0zmc,379
|
|
2
|
+
vizro_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
3
|
+
vizro_mcp/server.py,sha256=DoD1B_-EeHcTJSAog6lyaAi-_AA4u1dXAsHLgq0ku3Y,13689
|
|
4
|
+
vizro_mcp/_schemas/__init__.py,sha256=0lk_CiNjo4QFyX0i-VuSeL7EMM6sD_2p836y-ftM3Gs,196
|
|
5
|
+
vizro_mcp/_schemas/schemas.py,sha256=6XCNSTag7RL0xL3SkRVMlJ2GOW0nbm73drhcKRpNfOU,8795
|
|
6
|
+
vizro_mcp/_utils/__init__.py,sha256=ucPbfXe8kEFT7chz6ed_BeqAw71MnoWlZTYyCp4tPYY,1130
|
|
7
|
+
vizro_mcp/_utils/configs.py,sha256=DH5B-RbtLuAkq6cgVL7oBOg3J-T_Mi4ovU430h5iUus,3614
|
|
8
|
+
vizro_mcp/_utils/prompts.py,sha256=TJ--Tpv_tw2L8Tbt6PtaCA435HhUPpqUibNoEryKu94,10767
|
|
9
|
+
vizro_mcp/_utils/utils.py,sha256=1CAD1U27Uca_9KmR3SolimFqMrWVlWApKOFSWDvpeRY,8173
|
|
10
|
+
vizro_mcp-0.1.4.dist-info/METADATA,sha256=3iHwiGkUAQpUM0zX0X47G5_0F6sSQARAcLa-eetlgXU,12413
|
|
11
|
+
vizro_mcp-0.1.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
12
|
+
vizro_mcp-0.1.4.dist-info/entry_points.txt,sha256=iSUzPHvx4Ogsn91tK2C0OHxI44SNCHT1F1zUqbTj5O0,45
|
|
13
|
+
vizro_mcp-0.1.4.dist-info/licenses/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
|
|
14
|
+
vizro_mcp-0.1.4.dist-info/RECORD,,
|
|
@@ -1,323 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: vizro-mcp
|
|
3
|
-
Version: 0.1.2
|
|
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.42
|
|
18
|
-
Description-Content-Type: text/markdown
|
|
19
|
-
|
|
20
|
-
<!-- <a href="https://glama.ai/mcp/servers/@mckinsey/vizro">
|
|
21
|
-
<img width="380" height="200" src="https://glama.ai/mcp/servers/@mckinsey/vizro/badge" />
|
|
22
|
-
</a> -->
|
|
23
|
-
|
|
24
|
-
# Vizro MCP server
|
|
25
|
-
|
|
26
|
-
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.
|
|
27
|
-
|
|
28
|
-
<img src="assets/vizro-mcp.gif" width="600" alt="Vizro MCP Demo">
|
|
29
|
-
|
|
30
|
-
### Quick install
|
|
31
|
-
|
|
32
|
-
| Host | Prerequisite | Link | Notes |
|
|
33
|
-
| ----------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
34
|
-
| [Cursor](https://www.cursor.com/) | [uv](https://docs.astral.sh/uv/getting-started/installation/) | [](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoidXZ4IHZpenJvLW1jcCJ9) | |
|
|
35
|
-
| [VS Code](https://code.visualstudio.com/) | [uv](https://docs.astral.sh/uv/guides/tools/) | [](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22vizro-mcp%22%5D%7D) | |
|
|
36
|
-
| [Cursor](https://www.cursor.com/) | [Docker](https://www.docker.com/get-started/) | [](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoiZG9ja2VyIHJ1biAtaSAtLXJtIG1jcC92aXpybyJ9) | For local data access, [mount your data directory](#setup-instructions) |
|
|
37
|
-
| [VS Code](https://code.visualstudio.com/) | [Docker](https://www.docker.com/get-started/) | [](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Fvizro%22%5D%7D) | For local data access, [mount your data directory](#setup-instructions) |
|
|
38
|
-
|
|
39
|
-
## Features of Vizro-MCP
|
|
40
|
-
|
|
41
|
-
Vizro-MCP provides tools and templates to create a functioning Vizro chart or dashboard step by step. Benefits include:
|
|
42
|
-
|
|
43
|
-
✅ One consistent framework for charts and dashboards with one common design language.
|
|
44
|
-
|
|
45
|
-
✅ Validated config output that is readable and easy to alter or maintain.
|
|
46
|
-
|
|
47
|
-
✅ Live preview of the dashboard to iterate the design until the dashboard is perfect.
|
|
48
|
-
|
|
49
|
-
✅ Use of local or remote datasets simply by providing a path or URL.
|
|
50
|
-
|
|
51
|
-
### Without Vizro-MCP
|
|
52
|
-
|
|
53
|
-
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:
|
|
54
|
-
|
|
55
|
-
❌ A random choice of frontend framework or charting library.
|
|
56
|
-
|
|
57
|
-
❌ A vibe-coded mess that may or may not run, but certainly is not very maintainable.
|
|
58
|
-
|
|
59
|
-
❌ No way to easily preview the dashboard.
|
|
60
|
-
|
|
61
|
-
❌ No easy way to connect to real data.
|
|
62
|
-
|
|
63
|
-
## 🛠️ Get started
|
|
64
|
-
|
|
65
|
-
Vizro-MCP can be run in two ways: using [`uvx`](https://docs.astral.sh/uv/guides/tools/) or using [`Docker`](https://www.docker.com/get-started/). It works with any MCP-enabled LLM client such as Cursor or Claude Desktop.
|
|
66
|
-
|
|
67
|
-
If you want to run Vizro-MCP directly from source, skip to the end of this page to [Development or running from source](#development-or-running-from-source).
|
|
68
|
-
|
|
69
|
-
### Prerequisites
|
|
70
|
-
|
|
71
|
-
- [uv](https://docs.astral.sh/uv/getting-started/installation/) **or** [Docker](https://www.docker.com/get-started/)
|
|
72
|
-
- Any LLM application that supports MCP, such as [Claude Desktop](https://claude.ai/download) or [Cursor](https://www.cursor.com/downloads)
|
|
73
|
-
|
|
74
|
-
### Setup Instructions
|
|
75
|
-
|
|
76
|
-
The general server config is mostly the same for all hosts:
|
|
77
|
-
|
|
78
|
-
#### 1. Set up configuration
|
|
79
|
-
|
|
80
|
-
**Using `uvx`**
|
|
81
|
-
|
|
82
|
-
```json
|
|
83
|
-
{
|
|
84
|
-
"mcpServers": {
|
|
85
|
-
"vizro-mcp": {
|
|
86
|
-
"command": "uvx",
|
|
87
|
-
"args": [
|
|
88
|
-
"vizro-mcp"
|
|
89
|
-
]
|
|
90
|
-
}
|
|
91
|
-
}
|
|
92
|
-
}
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
**Using `Docker`**
|
|
96
|
-
|
|
97
|
-
```json
|
|
98
|
-
{
|
|
99
|
-
"mcpServers": {
|
|
100
|
-
"vizro-mcp": {
|
|
101
|
-
"command": "docker",
|
|
102
|
-
"args": [
|
|
103
|
-
"run",
|
|
104
|
-
"-i",
|
|
105
|
-
"--rm",
|
|
106
|
-
"--mount",
|
|
107
|
-
"type=bind,src=</absolute/path/to/allowed/dir>,dst=</absolute/path/to/allowed/dir>",
|
|
108
|
-
"--mount",
|
|
109
|
-
"type=bind,src=</absolute/path/to/data.csv>,dst=</absolute/path/to/data.csv>",
|
|
110
|
-
"mcp/vizro"
|
|
111
|
-
]
|
|
112
|
-
}
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
> To use local data with Vizro-MCP, mount your data directory or directories into the container. Replace `</absolute/path/to/allowed/dir>` (syntax for folders) or `</absolute/path/to/data.csv>` (syntax for files) with the absolute path to your data on your machine. For consistency, it is recommended that the `dst` path matches the `src` path.
|
|
118
|
-
|
|
119
|
-
#### 2. Add the Configuration to MCP enabled LLM applications
|
|
120
|
-
|
|
121
|
-
In principle, the Vizro MCP server works with _any_ MCP enabled LLM applications but we recommend Claude Desktop or Cursor as popular choices (see more detailed instructions below). Different AI tools may use different setup methods or connection settings. Check each tool's docs for details.
|
|
122
|
-
|
|
123
|
-
<details>
|
|
124
|
-
<summary><strong>Claude Desktop</strong></summary>
|
|
125
|
-
|
|
126
|
-
- Add the configuration to your `claude_desktop_config.json` ([found via Developer Settings](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server)).
|
|
127
|
-
|
|
128
|
-
- Restart Claude Desktop. After a few moments, you should see the vizro-mcp menu in the settings/context menu:
|
|
129
|
-
|
|
130
|
-
<img src="assets/claude_working.png" alt="Claude Desktop MCP Server Icon" width="300"/>
|
|
131
|
-
|
|
132
|
-
> ⚠️ **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.
|
|
133
|
-
|
|
134
|
-
</details>
|
|
135
|
-
|
|
136
|
-
<details>
|
|
137
|
-
<summary><strong>Cursor</strong></summary>
|
|
138
|
-
<br >
|
|
139
|
-
|
|
140
|
-
[](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoidXZ4IHZpenJvLW1jcCJ9)
|
|
141
|
-
|
|
142
|
-
- Add the above configuration to your `mcp.json` ([see Cursor Settings](https://docs.cursor.com/context/model-context-protocol#configuration-locations)) or click the button above.
|
|
143
|
-
|
|
144
|
-
- After a short pause, you should see a green light in the MCP menu:
|
|
145
|
-
|
|
146
|
-

|
|
147
|
-
|
|
148
|
-
</details>
|
|
149
|
-
|
|
150
|
-
<details>
|
|
151
|
-
<summary><strong>Other MCP Clients</strong></summary>
|
|
152
|
-
|
|
153
|
-
<br />
|
|
154
|
-
|
|
155
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22vizro-mcp%22%5D%7D)
|
|
156
|
-
|
|
157
|
-
- Add the configuration as per your client's documentation.
|
|
158
|
-
|
|
159
|
-
- Check your client's documentation for where to place the config and how to verify the server is running.
|
|
160
|
-
|
|
161
|
-
</details>
|
|
162
|
-
|
|
163
|
-
## 💻 Usage
|
|
164
|
-
|
|
165
|
-
The MCP server is designed to get you started on Vizro dashboards and charts by creating beautiful working dashboards based on the core Vizro features. It is not designed to replace a human developer when going beyond the core features, e.g. when building an application that requires custom CSS or bespoke Dash components.
|
|
166
|
-
|
|
167
|
-
### Use prompt templates to get specific dashboards quickly
|
|
168
|
-
|
|
169
|
-
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`_.
|
|
170
|
-
|
|
171
|
-
<img src="assets/claude_prompt.png" alt="Claude Desktop MCP Server Icon" width="300"/>
|
|
172
|
-
|
|
173
|
-
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!
|
|
174
|
-
|
|
175
|
-
### Create a Vizro dashboard based on local or remote data
|
|
176
|
-
|
|
177
|
-
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:
|
|
178
|
-
|
|
179
|
-
> _Create a Vizro dashboard with one page, a scatter chart, and a filter based on `<insert absolute file path or public URL>` data._
|
|
180
|
-
|
|
181
|
-
> _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_
|
|
182
|
-
|
|
183
|
-
You can find a set of sample CSVs to try out in the [Plotly repository](https://github.com/plotly/datasets/tree/master).
|
|
184
|
-
|
|
185
|
-
You can even ask for a dashboard without providing data:
|
|
186
|
-
|
|
187
|
-
> _Create a Vizro dashboard with one page, a scatter chart, and a filter._
|
|
188
|
-
|
|
189
|
-
In general, it helps to specify Vizro in the prompt and to keep it as precise (and simple) as possible.
|
|
190
|
-
|
|
191
|
-
### Get a live preview of your dashboard
|
|
192
|
-
|
|
193
|
-
When the LLM chooses to use the tool `validate_dashboard_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.
|
|
194
|
-
|
|
195
|
-
<img src="assets/claude_validate.png" width="300"/>
|
|
196
|
-
|
|
197
|
-
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.
|
|
198
|
-
|
|
199
|
-
### Create Vizro charts
|
|
200
|
-
|
|
201
|
-
If you don't want to create an entire Vizro dashboard, you can still use Vizro-MCP to create the code for a single chart. If you're not sure what kind of chart you want, check out the [Vizro Visual Vocabulary](https://huggingface.co/spaces/vizro/demo-visual-vocabulary) for ideas.
|
|
202
|
-
|
|
203
|
-
The **easiest** way to create a Vizro chart 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!
|
|
204
|
-
|
|
205
|
-
Alternatively, you can just ask in the chat, for example:
|
|
206
|
-
|
|
207
|
-
> _Create a scatter based on the iris dataset._
|
|
208
|
-
|
|
209
|
-
> _Create a bar chart based on `<insert absolute file path or public URL>` data._
|
|
210
|
-
|
|
211
|
-
## 🔍 Transparency and trust
|
|
212
|
-
|
|
213
|
-
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.
|
|
214
|
-
|
|
215
|
-
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. However, you should only run Vizro-MCP locally, not as a hosted server, because there is currently no authentication to manage access.
|
|
216
|
-
|
|
217
|
-
The second most critical part is the `validate_dashboard_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.
|
|
218
|
-
|
|
219
|
-
## Available Tools (if client allows)
|
|
220
|
-
|
|
221
|
-
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.
|
|
222
|
-
|
|
223
|
-
- `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.
|
|
224
|
-
- `get_model_json_schema` - Retrieves the complete JSON schema for any specified Vizro model, useful for understanding required and optional parameters.
|
|
225
|
-
- `validate_dashboard_config` - Tests Vizro model configurations by attempting to instantiate them. Returns Python code and visualization links for valid configurations.
|
|
226
|
-
- `load_and_analyze_data` - Loads a CSV file from a local path or URL into a pandas DataFrame and provides detailed analysis of its structure and content.
|
|
227
|
-
- `validate_chart_code` - Validates the code created for a chart and returns feedback on its correctness.
|
|
228
|
-
- `get_sample_data_info` - Provides information about sample datasets that can be used for testing and development.
|
|
229
|
-
|
|
230
|
-
## Available Prompts (if client allows)
|
|
231
|
-
|
|
232
|
-
- `create_starter_dashboard` - Use this prompt template to get started with Vizro dashboards.
|
|
233
|
-
- `create_dashboard` - Use this prompt template to create a dashboard based on a local or remote CSV dataset.
|
|
234
|
-
- `create_vizro_chart` - Use this prompt template to create a Vizro styled plotly chart based on a local or remote CSV dataset.
|
|
235
|
-
|
|
236
|
-
## Development or running from source
|
|
237
|
-
|
|
238
|
-
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:
|
|
239
|
-
|
|
240
|
-
Add the following to your MCP configuration:
|
|
241
|
-
|
|
242
|
-
```json
|
|
243
|
-
{
|
|
244
|
-
"mcpServers": {
|
|
245
|
-
"vizro-mcp": {
|
|
246
|
-
"command": "uv",
|
|
247
|
-
"args": [
|
|
248
|
-
"run",
|
|
249
|
-
"--directory",
|
|
250
|
-
"<PATH TO VIZRO>/vizro-mcp/",
|
|
251
|
-
"vizro-mcp"
|
|
252
|
-
]
|
|
253
|
-
}
|
|
254
|
-
}
|
|
255
|
-
}
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
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`.
|
|
259
|
-
|
|
260
|
-
## Disclaimers
|
|
261
|
-
|
|
262
|
-
<details>
|
|
263
|
-
<summary><strong>Third party API</strong></summary>
|
|
264
|
-
|
|
265
|
-
Users are responsible for anything done via their host LLM application.
|
|
266
|
-
|
|
267
|
-
Users are responsible for procuring any and all rights necessary to access any third-party generative AI tools and for complying with any applicable terms or conditions thereof.
|
|
268
|
-
|
|
269
|
-
Users are wholly responsible for the use and security of the third-party generative AI tools and of Vizro.
|
|
270
|
-
|
|
271
|
-
</details>
|
|
272
|
-
|
|
273
|
-
<details>
|
|
274
|
-
<summary><strong>User acknowledgments</strong></summary>
|
|
275
|
-
|
|
276
|
-
Users acknowledge and agree that:
|
|
277
|
-
|
|
278
|
-
Any results, options, data, recommendations, analyses, code, or other information (“Outputs”) generated by any third-party generative AI tools (“GenAI Tools”) may contain some inaccuracies, biases, illegitimate, potentially infringing, or otherwise inappropriate content that may be mistaken, discriminatory, or misleading.
|
|
279
|
-
|
|
280
|
-
McKinsey & Company:
|
|
281
|
-
|
|
282
|
-
(i) expressly disclaims the accuracy, adequacy, timeliness, reliability, merchantability, fitness for a particular purpose, non-infringement, safety or completeness of any Outputs,
|
|
283
|
-
|
|
284
|
-
(ii) shall not be liable for any errors, omissions, or other defects in, delays or interruptions in such Outputs, or for any actions taken in reliance thereon, and
|
|
285
|
-
|
|
286
|
-
(iii) shall not be liable for any alleged violation or infringement of any right of any third party resulting from the users’ use of the GenAI Tools and the Outputs.
|
|
287
|
-
|
|
288
|
-
The Outputs shall be verified and validated by the users and shall not be used without human oversight and as a sole basis for making decisions impacting individuals.
|
|
289
|
-
|
|
290
|
-
Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case, as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output. Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-MCP and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights.
|
|
291
|
-
|
|
292
|
-
</details>
|
|
293
|
-
|
|
294
|
-
<details>
|
|
295
|
-
<summary><strong>Warning and safety usage for generative AI models</strong></summary>
|
|
296
|
-
|
|
297
|
-
Vizro-MCP is used by generative AI models because large language models (LLMs) represent significant advancements in the AI field. However, as with any powerful tool, there are potential risks associated with connecting to a generative AI model.
|
|
298
|
-
|
|
299
|
-
We recommend users research and understand the selected model before using Vizro-MCP.
|
|
300
|
-
|
|
301
|
-
Users are encouraged to treat AI-generated content as supplementary, always apply human judgment, approach with caution, review the relevant disclaimer page, and consider the following:
|
|
302
|
-
|
|
303
|
-
<ol>
|
|
304
|
-
<li>Hallucination and misrepresentation</li>
|
|
305
|
-
Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading.
|
|
306
|
-
|
|
307
|
-
The vendor models might lack real-time knowledge or events beyond its last updates. Vizro-MCP output may vary and you should always verify critical information. It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content.
|
|
308
|
-
|
|
309
|
-
<li>Unintended and sensitive output</li>
|
|
310
|
-
The outputs from these models can be unexpected, inappropriate, or even harmful. Users as human in the loop is an essential part. Users must check and interpret the final output. It is necessary to approach the generated content with caution, especially when shared or applied in various contexts.
|
|
311
|
-
|
|
312
|
-
<li>Data privacy</li>
|
|
313
|
-
Your data is sent to model vendors if you connect to LLMs via their APIs. For example, if you connect to the model from OpenAI, your data will be sent to OpenAI via their API. Users should be cautious about sharing or inputting any personal or sensitive information.
|
|
314
|
-
|
|
315
|
-
<li>Bias and fairness</li>
|
|
316
|
-
Generative AI can exhibit biases present in their training data. Users need to be aware of and navigate potential biases in generated outputs and be cautious when interpreting the generated content.
|
|
317
|
-
|
|
318
|
-
<li>Malicious use</li>
|
|
319
|
-
These models can be exploited for various malicious activities. Users should be cautious about how and where they deploy and access such models.
|
|
320
|
-
</ol>
|
|
321
|
-
It's crucial for users to remain informed, cautious, and ethical in their applications.
|
|
322
|
-
|
|
323
|
-
</details>
|
vizro_mcp-0.1.2.dist-info/RECORD
DELETED
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
vizro_mcp/__init__.py,sha256=7rO7QeDAQXQ4DcfmJpU0uGgW7R0TMp2xgbAYNViFACE,379
|
|
2
|
-
vizro_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
3
|
-
vizro_mcp/server.py,sha256=m4IQQlYve1p4fCkAPa5Cgtv9hnxykA7UHItrRVCVBWQ,12647
|
|
4
|
-
vizro_mcp/_schemas/__init__.py,sha256=sCAIowgWm-qq8N3aMpVPx9WnbgoBal15AR3cg9rw8Yw,154
|
|
5
|
-
vizro_mcp/_schemas/schemas.py,sha256=fWsx7iz99kIlff0d2TUGGUnlQ8lHez--gXkIFwbQ1pQ,8348
|
|
6
|
-
vizro_mcp/_utils/__init__.py,sha256=ucPbfXe8kEFT7chz6ed_BeqAw71MnoWlZTYyCp4tPYY,1130
|
|
7
|
-
vizro_mcp/_utils/configs.py,sha256=28ALgRgKYzRnPunSTjZxHFz2kyQy8yW4ZLhDgCUkE0s,3627
|
|
8
|
-
vizro_mcp/_utils/prompts.py,sha256=YPk7fEVWkb1VGcRQ5uoFG8mGBnln65IK87GB0MXw9Fk,9754
|
|
9
|
-
vizro_mcp/_utils/utils.py,sha256=XQcUBtyEd7eHCxQp4N92VUGsJ7bLwj9jSJVTgYCFRSc,7990
|
|
10
|
-
vizro_mcp-0.1.2.dist-info/METADATA,sha256=fvXDcNLZq5Z1JEWjIFoId-shcR-6b-yOo-YoGUlGfS0,20077
|
|
11
|
-
vizro_mcp-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
12
|
-
vizro_mcp-0.1.2.dist-info/entry_points.txt,sha256=iSUzPHvx4Ogsn91tK2C0OHxI44SNCHT1F1zUqbTj5O0,45
|
|
13
|
-
vizro_mcp-0.1.2.dist-info/licenses/LICENSE.txt,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
|
|
14
|
-
vizro_mcp-0.1.2.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|