varro-mcp 0.1.0__tar.gz

varro_mcp-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+node_modules/
+.sesskey
+
+# macOS metadata
+**/.DS_Store
+# plugin/*
+.DS_Store
+
+dasbhoard_design/*

varro_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: varro-mcp
+Version: 0.1.0
+Summary: SQL, persistent Jupyter, and markdown dashboard tooling for Codex.
+Project-URL: Homepage, https://github.com/josca42/varro_plugin
+Project-URL: Repository, https://github.com/josca42/varro_plugin
+Project-URL: Issues, https://github.com/josca42/varro_plugin/issues
+Author: josca42
+License-Expression: MIT
+Keywords: dashboards,data-analysis,jupyter,mcp,sql
+Requires-Python: >=3.13
+Requires-Dist: geopandas>=1.1.3
+Requires-Dist: ipython>=9.12.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: kaleido>=1.0.0
+Requires-Dist: logfire>=4.32.1
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: mcp[cli]>=1.27.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=3.0.2
+Requires-Dist: plotly>=6.7.0
+Requires-Dist: psycopg[binary]>=3.3.4
+Requires-Dist: pyarrow>=18.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-fasthtml>=0.12.0
+Requires-Dist: scikit-learn>=1.8.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: tabulate>=0.10.0
+Requires-Dist: uvicorn>=0.30.0
+Description-Content-Type: text/markdown
+
+# Varro
+
+SQL, persistent Jupyter, and markdown dashboard tooling for Codex.
+
+This package provides the Python runtime for the Varro plugin:
+
+- `varro-mcp` starts the MCP server with SQL, Jupyter, and dashboard snapshot tools.
+- `varro` starts the local dashboard HTTP server for a project workspace.
+
+The MCP server reads project state from the current working directory by default. Set
+`VARRO_PROJECT_DIR` when launching it from another location.

varro_mcp-0.1.0/README.md

@@ -0,0 +1,11 @@
+# Varro
+
+SQL, persistent Jupyter, and markdown dashboard tooling for Codex.
+
+This package provides the Python runtime for the Varro plugin:
+
+- `varro-mcp` starts the MCP server with SQL, Jupyter, and dashboard snapshot tools.
+- `varro` starts the local dashboard HTTP server for a project workspace.
+
+The MCP server reads project state from the current working directory by default. Set
+`VARRO_PROJECT_DIR` when launching it from another location.

varro_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "varro-mcp"
+version = "0.1.0"
+description = "SQL, persistent Jupyter, and markdown dashboard tooling for Codex."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [
+    { name = "josca42" },
+]
+keywords = ["mcp", "sql", "jupyter", "dashboards", "data-analysis"]
+dependencies = [
+    "ipython>=9.12.0",
+    "jinja2>=3.1.0",
+    "matplotlib>=3.10.8",
+    "mcp[cli]>=1.27.0",
+    "pandas>=3.0.2",
+    "plotly>=6.7.0",
+    "python-fasthtml>=0.12.0",
+    "kaleido>=1.0.0",
+    "uvicorn>=0.30.0",
+    "pydantic>=2.0.0",
+    "pyarrow>=18.0.0",
+    "logfire>=4.32.1",
+    "sqlalchemy>=2.0",
+    "psycopg[binary]>=3.3.4",
+    "scikit-learn>=1.8.0",
+    "geopandas>=1.1.3",
+    "tabulate>=0.10.0",
+    "openpyxl>=3.1.5",
+]
+
+[project.scripts]
+varro = "varro.cli:main"
+varro-mcp = "varro.main:main"
+
+[project.urls]
+Homepage = "https://github.com/josca42/varro_plugin"
+Repository = "https://github.com/josca42/varro_plugin"
+Issues = "https://github.com/josca42/varro_plugin/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["varro"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "README.md",
+    "pyproject.toml",
+    "varro/**/*.py",
+    "varro/dashboard/static/**/*",
+]

varro_mcp-0.1.0/varro/cli.py

@@ -0,0 +1,25 @@
+import argparse
+import os
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="varro", description="Run the varro dashboard HTTP server."
+    )
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=5011)
+    parser.add_argument("--project-dir", required=True, help="Project folder")
+    args = parser.parse_args()
+
+    os.environ["VARRO_PROJECT_DIR"] = str(Path(args.project_dir).resolve())
+
+    import uvicorn
+
+    from varro.dashboard import build_app
+
+    uvicorn.run(build_app(Path(args.project_dir)), host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

varro_mcp-0.1.0/varro/constants.py

@@ -0,0 +1,9 @@
+import os
+from pathlib import Path
+
+PROJECT_DIR = Path(os.environ.get("VARRO_PROJECT_DIR", Path.cwd())).resolve()
+DASHBOARDS_DIR = PROJECT_DIR / "dashboards"
+NOTEBOOKS_DIR = PROJECT_DIR / "notebooks"
+DATA_DIR = PROJECT_DIR / "data"
+VARRO_DIR = PROJECT_DIR / ".varro"
+SQL_CONNECTION_FILE = VARRO_DIR / "sql_connection.txt"

varro_mcp-0.1.0/varro/dashboard/__init__.py

@@ -0,0 +1,5 @@
+from varro.dashboard.models import Metric, output
+from varro.dashboard.server import build_app
+from varro.dashboard.snapshot import take_snapshot
+
+__all__ = ["Metric", "output", "build_app", "take_snapshot"]

varro_mcp-0.1.0/varro/dashboard/components.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+from urllib.parse import urlencode
+
+from fasthtml.common import (
+    A,
+    Aside,
+    Button,
+    Div,
+    Form as HtmlForm,
+    Img,
+    Main,
+    NotStr,
+    Span,
+)
+
+from varro.dashboard.filters import Filter, SelectFilter
+from varro.dashboard.helpers import FilterInput
+from varro.dashboard.loader import Dashboard, Page
+from varro.dashboard.parser import (
+    ASTNode,
+    ComponentNode,
+    ContainerNode,
+    MarkdownNode,
+)
+
+MARKDOWN_CLASS = "prose"
+
+PANEL_ICON = NotStr(
+    '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" '
+    'stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round">'
+    '<rect x="3" y="3" width="18" height="18" rx="2"/>'
+    '<line x1="15" y1="3" x2="15" y2="21"/></svg>'
+)
+
+TOGGLE_JS = NotStr(
+    """
+<script>
+(function(){
+  var t = document.getElementById('toc-toggle');
+  if (!t) return;
+  var app = document.querySelector('.app');
+
+  if (localStorage.getItem('toc-collapsed') === '1') {
+    app.classList.add('collapsed');
+  }
+
+  t.addEventListener('click', function(){
+    app.classList.toggle('collapsed');
+    localStorage.setItem(
+      'toc-collapsed',
+      app.classList.contains('collapsed') ? '1' : '0'
+    );
+    setTimeout(function(){
+      window.dispatchEvent(new Event('resize'));
+    }, 220);
+  });
+})();
+</script>
+"""
+)
+
+
+def _placeholder(
+    dash_name: str, output_type: str, output_name: str, attrs: dict[str, str]
+) -> Any:
+    query = {
+        f"__{key}": value
+        for key, value in attrs.items()
+        if key != "name"
+    }
+    suffix = f"?{urlencode(query)}" if query else ""
+    digest = hashlib.sha1(
+        repr((output_type, output_name, sorted(query.items()))).encode()
+    ).hexdigest()[:8]
+    return Div(
+        Div(Div(cls="loading-spinner"), cls="card loading-card"),
+        hx_get=f"/{dash_name}/_/{output_type}/{output_name}{suffix}",
+        hx_include="#filters",
+        hx_trigger="load, filtersChanged from:body",
+        hx_swap="innerHTML",
+        id=f"placeholder-{output_type}-{output_name}-{digest}",
+        cls="output-slot",
+        data_output_name=output_name,
+        data_output_type=output_type,
+    )
+
+
+def _render_filters(
+    filter_defs: list[Filter],
+    dash: Dashboard,
+    filters: dict[str, Any],
+    options: dict[str, list[Any]],
+) -> Any:
+    inputs = [Span("Filters", cls="filter-label")]
+    for f in filter_defs:
+        if isinstance(f, SelectFilter):
+            current = filters.get(f.name, f.default)
+            opts = options.get(f.name, [])
+            inputs.append(FilterInput(f, current, options=opts))
+        else:
+            inputs.append(FilterInput(f, filters))
+
+    return HtmlForm(
+        *inputs,
+        id="filters",
+        hx_get=_page_href(dash.name, dash.page) + "/_/filters",
+        hx_trigger="change delay:300ms",
+        hx_swap="none",
+        cls="filters",
+    )
+
+
+def _render_tabs(
+    tab_nodes: list[ContainerNode],
+    dash: Dashboard,
+    filters: dict[str, Any],
+    options: dict[str, list[Any]],
+) -> Any:
+    buttons = []
+    contents = []
+    for i, tab in enumerate(tab_nodes):
+        name = tab.attrs.get("name", f"Tab {i + 1}")
+        buttons.append(
+            Button(
+                name,
+                type="button",
+                role="tab",
+                cls="tab",
+                **{
+                    ":class": f"active === {i} && 'tab-active'",
+                    "@click": f"active = {i}",
+                },
+            )
+        )
+        contents.append(
+            Div(
+                *render_ast(tab.children, dash, filters, options),
+                x_show=f"active === {i}",
+                x_cloak=True,
+                role="tabpanel",
+            )
+        )
+    return Div(
+        Div(*buttons, role="tablist", cls="tabs-shadcn"),
+        *contents,
+        x_data="{ active: 0 }",
+        cls="tabs-block",
+    )
+
+
+def _grid_class(cols: str) -> str:
+    return f"grid-{cols}"
+
+
+def render_ast(
+    nodes: list[ASTNode],
+    dash: Dashboard,
+    filters: dict[str, Any],
+    options: dict[str, list[Any]],
+    page_header: bool = False,
+) -> list[Any]:
+    out: list[Any] = []
+    header_pending = page_header
+
+    for node in nodes:
+        if isinstance(node, MarkdownNode):
+            if header_pending:
+                out.append(_page_header(node, dash))
+                header_pending = False
+            else:
+                out.append(Div(node.content, cls=f"section-header {MARKDOWN_CLASS}"))
+
+        elif isinstance(node, ComponentNode):
+            if node.type in ("fig", "table", "metric"):
+                name = node.attrs.get("name", "")
+                if name:
+                    out.append(_placeholder(dash.name, node.type, name, node.attrs))
+
+        elif isinstance(node, ContainerNode):
+            if node.type == "filters":
+                filter_defs = [c for c in node.children if isinstance(c, Filter)]
+                out.append(_render_filters(filter_defs, dash, filters, options))
+
+            elif node.type == "grid":
+                children = render_ast(node.children, dash, filters, options)
+                out.append(Div(*children, cls=_container_grid_class(node)))
+
+            elif node.type == "tabs":
+                tab_nodes = [
+                    c
+                    for c in node.children
+                    if isinstance(c, ContainerNode) and c.type == "tab"
+                ]
+                if tab_nodes:
+                    out.append(_render_tabs(tab_nodes, dash, filters, options))
+
+            elif node.type != "tab":
+                out.extend(render_ast(node.children, dash, filters, options))
+
+    return out
+
+
+def _container_grid_class(node: ContainerNode) -> str:
+    if node.children and all(
+        isinstance(c, ComponentNode) and c.type == "metric" for c in node.children
+    ):
+        return "kpi-grid"
+    return _grid_class(node.attrs.get("cols", "2"))
+
+
+def _page_header(node: MarkdownNode, dash: Dashboard) -> Any:
+    return Div(
+        _crumbs(dash),
+        Div(node.content, cls=MARKDOWN_CLASS),
+        cls="page-header",
+    )
+
+
+def _crumbs(dash: Dashboard) -> Any:
+    parts: list[Any] = [Span("Dashboards")]
+    if dash.page.slug:
+        parts.extend([Span("/", cls="sep"), A(dash.title, href=f"/{dash.name}")])
+        parts.extend([Span("/", cls="sep"), Span(dash.page.title)])
+    else:
+        parts.extend([Span("/", cls="sep"), Span(dash.title)])
+    return Div(*parts, cls="crumbs")
+
+
+def _humanize(slug: str) -> str:
+    return slug.replace("-", " ").replace("_", " ").title()
+
+
+def _render_toc(
+    dash_name: str,
+    current_page: str | None,
+    site: list[dict[str, Any]],
+) -> Any:
+    items = []
+    for entry in site:
+        name = entry["name"]
+        pages = entry.get("pages", [])
+        is_active_dash = name == dash_name
+        children: list[Any] = [
+            A(Span(_humanize(name)), href=f"/{name}", cls="toc-dash-link")
+        ]
+        if is_active_dash:
+            children.append(_toc_pages(name, pages, current_page))
+        items.append(
+            Div(*children, cls=f"toc-dash{' active' if is_active_dash else ''}")
+        )
+
+    return Aside(
+        _render_toc_top(),
+        Div(*items, cls="toc-list"),
+        cls="toc",
+    )
+
+
+def _render_toc_top() -> Any:
+    return Div(
+        A(
+            Span(
+                Img(src="/static/varro_logo.png", alt=""),
+                cls="brand-mark",
+            ),
+            Span("VARRO", cls="brand-name"),
+            href="/",
+            cls="toc-brand",
+        ),
+        Button(
+            PANEL_ICON,
+            id="toc-toggle",
+            cls="toc-toggle",
+            aria_label="Toggle sidebar",
+            type="button",
+        ),
+        cls="toc-top",
+    )
+
+
+def _toc_pages(name: str, pages: list[str], current_page: str | None) -> Any:
+    links = [
+        A(
+            "Overview",
+            href=f"/{name}",
+            cls=f"toc-page{' active' if current_page is None else ''}",
+        )
+    ]
+    links.extend(
+        A(
+            _humanize(slug),
+            href=f"/{name}/{slug}",
+            cls=f"toc-page{' active' if slug == current_page else ''}",
+        )
+        for slug in pages
+    )
+    return Div(*links, cls="toc-pages")
+
+
+def render_shell(
+    dash: Dashboard,
+    filters: dict[str, Any],
+    options: dict[str, list[Any]],
+    site: list[dict[str, Any]] | None = None,
+    current_page: str | None = None,
+) -> Any:
+    content = render_ast(dash.ast, dash, filters, options, page_header=True)
+    return Div(
+        Main(*content),
+        _render_toc(dash.name, current_page, site or _default_site(dash)),
+        TOGGLE_JS,
+        cls="app",
+    )
+
+
+def _default_site(dash: Dashboard) -> list[dict[str, Any]]:
+    return [{"name": dash.name, "pages": [p.slug for p in dash.pages if p.slug]}]
+
+
+def _page_href(dash_name: str, page: Page) -> str:
+    return f"/{dash_name}" if page.slug is None else f"/{dash_name}/{page.slug}"

varro_mcp-0.1.0/varro/dashboard/executor.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from sqlalchemy.engine import Engine
+
+from varro.dashboard.loader import Dashboard
+from varro.dashboard.queries import execute_query
+
+
+def output_query_names(dash: Dashboard, output_name: str) -> set[str]:
+    if output_name not in dash.outputs:
+        raise KeyError(f"Unknown output {output_name!r} in dashboard {dash.name!r}")
+    return {
+        name
+        for name in inspect.signature(dash.outputs[output_name]).parameters
+        if name in dash.queries
+    }
+
+
+def execute_output(
+    dash: Dashboard,
+    output_name: str,
+    filters: dict[str, Any],
+    engine: Engine | None = None,
+) -> Any:
+    if output_name not in dash.outputs:
+        raise KeyError(f"Unknown output {output_name!r} in dashboard {dash.name!r}")
+
+    fn = dash.outputs[output_name]
+    kwargs: dict[str, Any] = {}
+
+    for param_name in inspect.signature(fn).parameters:
+        if param_name == "filters":
+            kwargs[param_name] = filters
+            continue
+
+        if param_name in dash.queries:
+            if engine is None:
+                raise RuntimeError(
+                    f"Output {output_name!r} requires SQL query {param_name!r}, "
+                    "but no SQL connection is configured."
+                )
+            kwargs[param_name] = execute_query(
+                dash.queries[param_name],
+                filters,
+                engine,
+            )
+            continue
+
+        known_queries = ", ".join(sorted(dash.queries)) or "none"
+        raise TypeError(
+            f"Unknown parameter {param_name!r} on output {output_name!r}. "
+            f"Use 'filters' or one of the dashboard query names: {known_queries}."
+        )
+
+    return fn(**kwargs)

varro_mcp-0.1.0/varro/dashboard/filters.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal, Mapping
+
+import pandas as pd
+from pydantic import BaseModel, ConfigDict, field_validator
+
+SelectOption = tuple[str, str]
+
+
+class Filter(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: str
+    name: str
+    label: str | None = None
+
+    @field_validator("label", mode="before")
+    @classmethod
+    def _default_label(cls, value: str | None, info) -> str | None:
+        if value is None or value == "":
+            return info.data.get("name") or None
+        return value
+
+    def parse_query_params(self, params: Mapping[str, str]) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def url_params(self, values: Mapping[str, Any]) -> dict[str, str]:
+        raise NotImplementedError
+
+
+class SelectFilter(Filter):
+    type: Literal["select"] = "select"
+    default: str = "all"
+    options_spec: str = ""
+
+    def parse_query_params(self, params: Mapping[str, str]) -> dict[str, Any]:
+        return {self.name: params.get(self.name, self.default)}
+
+    def url_params(self, values: Mapping[str, Any]) -> dict[str, str]:
+        v = values.get(self.name, self.default)
+        return {self.name: str(v)} if v != self.default else {}
+
+
+class DateRangeFilter(Filter):
+    type: Literal["daterange"] = "daterange"
+    default_from: str | None = None
+    default_to: str | None = None
+
+    def parse_query_params(self, params: Mapping[str, str]) -> dict[str, Any]:
+        fk, tk = f"{self.name}_from", f"{self.name}_to"
+        return {
+            fk: params.get(fk) or self.default_from,
+            tk: params.get(tk) or self.default_to,
+        }
+
+    def url_params(self, values: Mapping[str, Any]) -> dict[str, str]:
+        fk, tk = f"{self.name}_from", f"{self.name}_to"
+        out: dict[str, str] = {}
+        if (fv := values.get(fk)) and fv != self.default_from:
+            out[fk] = str(fv)
+        if (tv := values.get(tk)) and tv != self.default_to:
+            out[tk] = str(tv)
+        return out
+
+
+class CheckboxFilter(Filter):
+    type: Literal["checkbox"] = "checkbox"
+    default: bool = False
+
+    @field_validator("default", mode="before")
+    @classmethod
+    def _parse_default(cls, v: Any) -> bool:
+        if isinstance(v, str):
+            return v.lower() == "true"
+        return bool(v)
+
+    def parse_query_params(self, params: Mapping[str, str]) -> dict[str, Any]:
+        v = params.get(self.name)
+        if v is None:
+            return {self.name: self.default}
+        return {self.name: v.lower() == "true"}
+
+    def url_params(self, values: Mapping[str, Any]) -> dict[str, str]:
+        v = values.get(self.name, self.default)
+        return {self.name: "true" if v else "false"} if v != self.default else {}
+
+
+def filter_from_component(type_: str, attrs: dict[str, str]) -> Filter | None:
+    name = attrs.get("name", "")
+    if not name:
+        return None
+    label = attrs.get("label")
+
+    if type_ == "filter-select":
+        return SelectFilter(
+            name=name,
+            label=label,
+            default=attrs.get("default", "all"),
+            options_spec=attrs.get("options", ""),
+        )
+    if type_ == "filter-date":
+        return DateRangeFilter(
+            name=name,
+            label=label,
+            default_from=attrs.get("default_from"),
+            default_to=attrs.get("default_to"),
+        )
+    if type_ == "filter-check":
+        return CheckboxFilter(
+            name=name,
+            label=label,
+            default=attrs.get("default", "false"),
+        )
+    return None
+
+
+def resolve_select_options(spec: str, root: Path) -> list[SelectOption]:
+    spec = spec.strip()
+    if not spec:
+        return []
+
+    if spec.startswith("data:"):
+        rest = spec[len("data:"):]
+        path_part, _, col = rest.rpartition(":")
+        if not path_part or not col:
+            raise ValueError(
+                f"Bad select options spec {spec!r}: expected data:<path>:<column>"
+            )
+        file_path = root / "data" / path_part
+        suffix = file_path.suffix.lower()
+        if suffix == ".csv":
+            df = pd.read_csv(file_path)
+        elif suffix in (".parquet", ".pq"):
+            df = pd.read_parquet(file_path)
+        elif suffix == ".json":
+            df = pd.read_json(file_path)
+        else:
+            raise ValueError(f"Unsupported data file type: {suffix}")
+        values = sorted(df[col].astype(str).unique().tolist())
+        return [("all", "All")] + [(value, value) for value in values]
+
+    values = [s.strip() for s in spec.split(",") if s.strip()]
+    return [(value, "All" if value == "all" else value) for value in values]