model2data-studio 0.4.0__tar.gz → 0.5.0__tar.gz

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: model2data-studio
-Version: 0.4.0
+Version: 0.5.0
 Summary: Generate a model2data studio project's data from the command line, so CI can rebuild fixtures instead of committing them.
 Project-URL: Homepage, https://www.jbanalytica.com/model2data/
 Project-URL: Studio, https://studio.jbanalytica.com
@@ -52,7 +52,10 @@ uvx model2data-studio --help
 
 It needs an API key from a **Pro** account on the studio: see
 [pricing](https://www.jbanalytica.com/model2data/pricing/). The client is MIT
-licensed; the studio it talks to is not open source.
+licensed; the studio it talks to is not open source. (To use the studio from
+Claude or another MCP client without a key, see [the MCP
+server](#the-mcp-server-generating-from-an-agent-instead-of-a-shell): the
+studio's own endpoint needs only a sign-in.)
 
 ## Configuration
 
@@ -362,11 +365,44 @@ would compare against rows anchored on today and fail at the first midnight.
 
 ## The MCP server: generating from an agent instead of a shell
 
-The same account, the same key, the same API — for the editor rather than the
-terminal. The studio is where a schema is *designed*, with a diagram and a
-preview to design it against; the agent in your editor is where the data is
-wanted, and asking it for "two hundred believable orders from my webshop model"
-should not mean pasting DBML into a chat.
+The same account, the same API — for an agent rather than the terminal. The
+studio is where a schema is *designed*, with a diagram and a preview to design
+it against; the agent in your editor or chat is where the data is wanted, and
+asking it for "two hundred believable orders from my webshop model" should not
+mean pasting DBML into a chat.
+
+There are two ways to connect, with the same tools behind both.
+
+### One URL: the studio's own MCP endpoint
+
+The studio serves these tools itself at `https://studio.jbanalytica.com/mcp`.
+Add that URL to your MCP client and sign in to the studio in your browser when
+it asks; there is no key to copy, nothing to install and no config file. It
+works with a free account, within the free plan's limits.
+
+- **Claude** (web, desktop and mobile): *Settings → Connectors → Add custom
+  connector*, paste `https://studio.jbanalytica.com/mcp`, then *Connect* and
+  approve the connection in the studio.
+- **Claude Code**:
+
+  ```bash
+  claude mcp add --transport http model2data-studio https://studio.jbanalytica.com/mcp
+  ```
+
+  then run `/mcp` in Claude Code and pick the server to sign in.
+- **Anything else** that speaks Streamable HTTP with OAuth: the same URL.
+
+A connected app appears in the studio under *API keys* in the account menu,
+marked *Connected app*; *Disconnect* there takes its access away at once. It can
+read your projects, create them and save their models, metrics files and
+dashboards, and generate previews and metric values. It cannot delete a project,
+share one, or manage your keys. `write_data` is not offered there: a server on
+the studio would write the files to the studio's disk, not yours.
+
+### Local: this package, with an API key
+
+For CI, for a self-hosted studio, or for writing fixtures straight to disk with
+`write_data`, run the server from this package with an API key (Pro):
 
 ```bash
 uvx --from 'model2data-studio[mcp]' model2data-studio mcp   # the SDK is an extra, see below
@@ -398,7 +434,7 @@ and for anything that reads a JSON config (Claude Desktop, Cursor, Zed):
 
 `MODEL2DATA_STUDIO_URL` works here too, for a self-hosted studio.
 
-Nineteen tools:
+Nineteen tools (eighteen at the studio's own endpoint, which has no `write_data`):
 
 | | |
 | --- | --- |

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/README.md

@@ -23,7 +23,10 @@ uvx model2data-studio --help
 
 It needs an API key from a **Pro** account on the studio: see
 [pricing](https://www.jbanalytica.com/model2data/pricing/). The client is MIT
-licensed; the studio it talks to is not open source.
+licensed; the studio it talks to is not open source. (To use the studio from
+Claude or another MCP client without a key, see [the MCP
+server](#the-mcp-server-generating-from-an-agent-instead-of-a-shell): the
+studio's own endpoint needs only a sign-in.)
 
 ## Configuration
 
@@ -333,11 +336,44 @@ would compare against rows anchored on today and fail at the first midnight.
 
 ## The MCP server: generating from an agent instead of a shell
 
-The same account, the same key, the same API — for the editor rather than the
-terminal. The studio is where a schema is *designed*, with a diagram and a
-preview to design it against; the agent in your editor is where the data is
-wanted, and asking it for "two hundred believable orders from my webshop model"
-should not mean pasting DBML into a chat.
+The same account, the same API — for an agent rather than the terminal. The
+studio is where a schema is *designed*, with a diagram and a preview to design
+it against; the agent in your editor or chat is where the data is wanted, and
+asking it for "two hundred believable orders from my webshop model" should not
+mean pasting DBML into a chat.
+
+There are two ways to connect, with the same tools behind both.
+
+### One URL: the studio's own MCP endpoint
+
+The studio serves these tools itself at `https://studio.jbanalytica.com/mcp`.
+Add that URL to your MCP client and sign in to the studio in your browser when
+it asks; there is no key to copy, nothing to install and no config file. It
+works with a free account, within the free plan's limits.
+
+- **Claude** (web, desktop and mobile): *Settings → Connectors → Add custom
+  connector*, paste `https://studio.jbanalytica.com/mcp`, then *Connect* and
+  approve the connection in the studio.
+- **Claude Code**:
+
+  ```bash
+  claude mcp add --transport http model2data-studio https://studio.jbanalytica.com/mcp
+  ```
+
+  then run `/mcp` in Claude Code and pick the server to sign in.
+- **Anything else** that speaks Streamable HTTP with OAuth: the same URL.
+
+A connected app appears in the studio under *API keys* in the account menu,
+marked *Connected app*; *Disconnect* there takes its access away at once. It can
+read your projects, create them and save their models, metrics files and
+dashboards, and generate previews and metric values. It cannot delete a project,
+share one, or manage your keys. `write_data` is not offered there: a server on
+the studio would write the files to the studio's disk, not yours.
+
+### Local: this package, with an API key
+
+For CI, for a self-hosted studio, or for writing fixtures straight to disk with
+`write_data`, run the server from this package with an API key (Pro):
 
 ```bash
 uvx --from 'model2data-studio[mcp]' model2data-studio mcp   # the SDK is an extra, see below
@@ -369,7 +405,7 @@ and for anything that reads a JSON config (Claude Desktop, Cursor, Zed):
 
 `MODEL2DATA_STUDIO_URL` works here too, for a self-hosted studio.
 
-Nineteen tools:
+Nineteen tools (eighteen at the studio's own endpoint, which has no `write_data`):
 
 | | |
 | --- | --- |

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/model2data_studio/__init__.py

@@ -12,6 +12,6 @@ the studio's API does all of that, and this only knows how to ask.
 
 from __future__ import annotations
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = ["__version__"]

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/model2data_studio/cli.py

@@ -969,7 +969,8 @@ def metrics_values(
     described = {metric.get("name"): metric for metric in listed}
     typer.echo(
         f"{found.name}: seed {resolved.seed}, dates anchored on {resolved.anchor:%Y-%m-%d}, "
-        f"{resolved.body.get('rows')} rows a table"
+        f"{resolved.body.get('rows')} rows a table unless the model or project sets a "
+        "table's own count"
     )
     typer.echo(
         _table(

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/model2data_studio/mcp_server.py

@@ -57,6 +57,11 @@ rows.
 
 Run it as `model2data-studio-mcp`, with MODEL2DATA_STUDIO_KEY in the
 environment; see the README for the client configuration.
+
+The studio also serves these same tools itself, at `<studio>/mcp`, for clients
+that connect with a URL and a browser sign-in instead of a key: it calls
+`build` with a client factory of its own, and without `write_data`, which
+writes to the disk of the machine the server runs on.
 """
 
 from __future__ import annotations
@@ -66,6 +71,7 @@ import functools
 import io
 import os
 import zipfile
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
@@ -353,13 +359,33 @@ def preview(archive: bytes, *, rows: int = PREVIEW_ROWS, budget: int = PREVIEW_C
     return "\n\n".join(sections)
 
 
-def build() -> Any:
+ClientFactory = Callable[..., StudioClient]
+
+
+def build(
+    client_factory: ClientFactory | None = None,
+    *,
+    local_files: bool = True,
+    thread_limiter: Any = None,
+) -> Any:
     """The server, built on first use.
 
     A function rather than a module-level object so that importing this module
     -- which the tests do, to call the logic above directly -- does not require
     the MCP SDK to be installed. It is an optional dependency: this package is
     installed on CI runners that want the CLI and nothing else.
+
+    The arguments are for a server that is not this process's own (the
+    studio's remote endpoint); the defaults are the local server, unchanged.
+
+    - `client_factory(required=...)` makes each tool call's `StudioClient`;
+      by default `_client`, from the environment's key.
+    - `local_files=False` leaves out `write_data`: written by a server
+      somewhere else, the files would land on that server.
+    - `thread_limiter`, an `anyio.CapacityLimiter`, runs each tool on a worker
+      thread under that limiter instead of the default one. A tool that calls
+      back into the same process's API must not hold one of the threads that
+      API needs to answer it.
     """
     try:
         # `MCPServer` since mcp 2.0, where it was renamed from `FastMCP`.
@@ -372,6 +398,10 @@ def build() -> Any:
 
     from mcp.server.mcpserver.exceptions import ToolError
 
+    def make_client(*, required: bool = True) -> StudioClient:
+        # `_client` looked up per call, so a test patching it still reaches here.
+        return (client_factory or _client)(required=required)
+
     def reported(tool):
         """Let the studio's own sentence reach the model.
 
@@ -390,15 +420,26 @@ def build() -> Any:
             except StudioError as error:
                 raise ToolError(str(error)) from error
 
-        return wrapper
+        if thread_limiter is None:
+            return wrapper
+
+        import anyio.to_thread
+
+        @functools.wraps(tool)
+        async def threaded(*args: Any, **kwargs: Any) -> Any:
+            call = functools.partial(wrapper, *args, **kwargs)
+            return await anyio.to_thread.run_sync(call, limiter=thread_limiter)
+
+        return threaded
 
     server = MCPServer(
         "model2data-studio",
         instructions=(
             "Realistic fake data from a schema designed in model2data studio. "
             "`list_projects` first if no project id is at hand, `describe_project` to see what "
-            "a project holds, `preview_data` to read rows, `write_data` to put them on disk, "
-            "`metric_values` for the known answers a query over those rows must return. "
+            "a project holds, `preview_data` to read rows, "
+            + ("`write_data` to put them on disk, " if local_files else "")
+            + "`metric_values` for the known answers a query over those rows must return. "
             "Models, metrics and dashboards are files in model2data's open specs; each has a "
             "guide, a check and a save tool. " + RECIPE
         ),
@@ -412,7 +453,7 @@ def build() -> Any:
         Worth reading before asking for a lot of rows: the caps are per plan,
         and a refusal is a 402 rather than a smaller answer.
         """
-        with _client() as client:
+        with make_client() as client:
             usage = client.get_usage()
             plan = client.get_plan() or {}
         lines = [f"Plan: {plan.get('name', usage.get('plan', 'unknown'))}"]
@@ -433,7 +474,7 @@ def build() -> Any:
     def list_projects() -> str:
         """The account's saved projects: the id to pass to the other tools,
         the name, and when it was last saved."""
-        with _client() as client:
+        with make_client() as client:
             projects = client.list_projects()
         if not projects:
             return "This account has no saved projects yet."
@@ -455,7 +496,7 @@ def build() -> Any:
         (`{"min": 5.99, "max": 999.99}`, `{"null_rate": 0.4}`). Either way the
         hints are what decide the values a column comes out with.
         """
-        with _client() as client:
+        with make_client() as client:
             saved = client.get_project(project_id)
             text = describe(saved)
             try:
@@ -477,7 +518,7 @@ def build() -> Any:
         the ones the model implies (a sum per measure column, a count per
         fact). `metric_values` gives their known values over generated data.
         """
-        with _client() as client:
+        with make_client() as client:
             saved = client.get_project(project_id)
             checked = export.check_project(client, saved)
         return f"{saved.get('name') or 'Untitled'}\n\n{metrics_section(checked)}"
@@ -499,7 +540,7 @@ def build() -> Any:
         checked against them. Leave the arguments out and the project's own
         settings are used. Values are Pro, except on a bundled example.
         """
-        with _client() as client:
+        with make_client() as client:
             saved = client.get_project(project_id)
             checked = export.check_project(client, saved)
             if any(i.get("severity") != "warning" for i in checked.get("issues") or []):
@@ -515,7 +556,8 @@ def build() -> Any:
         described = {metric.get("name"): metric for metric in checked.get("metrics") or []}
         head = (
             f"{saved.get('name') or 'Untitled'}: known values, seed {resolved.seed}, dates "
-            f"anchored on {resolved.anchor:%Y-%m-%d}, {resolved.body.get('rows')} rows a table"
+            f"anchored on {resolved.anchor:%Y-%m-%d}, {resolved.body.get('rows')} rows a table "
+            "unless the model or project sets a table's own count"
         )
         if resolved.picked_seed:
             head += "\n(No saved seed, so one was picked. Pass it back as `seed` to reproduce.)"
@@ -544,7 +586,7 @@ def build() -> Any:
         overrides the project's. Leave them out and the project's own settings
         are used, which are the ones the studio previewed.
         """
-        with _client() as client:
+        with make_client() as client:
             saved = client.get_project(project_id)
             resolved = export.resolve(
                 saved,
@@ -562,8 +604,6 @@ def build() -> Any:
             head += "to generate these same rows again.)"
         return f"{head}\n\n{preview(archive)}"
 
-    @server.tool()
-    @reported
     def write_data(
         project_id: str,
         out_dir: str,
@@ -582,7 +622,7 @@ def build() -> Any:
         """
         if export_format not in {"csv", "dbt"}:
             raise StudioError(f'export_format is "csv" or "dbt", not {export_format!r}.')
-        with _client() as client:
+        with make_client() as client:
             saved = client.get_project(project_id)
             resolved = export.resolve(
                 saved,
@@ -600,6 +640,9 @@ def build() -> Any:
         lines.append(f"Seed {resolved.seed}, dates anchored on {resolved.anchor:%Y-%m-%d}.")
         return "\n".join(lines)
 
+    if local_files:
+        server.tool()(reported(write_data))
+
     @server.tool()
     @reported
     def get_model_guide() -> str:
@@ -608,7 +651,7 @@ def build() -> Any:
         with examples, then what the studio adds. Read it first when building a
         project: the model comes before metrics and dashboards. Needs no API key.
         """
-        with _client(required=False) as client:
+        with make_client(required=False) as client:
             return client.model_guide()
 
     @server.tool()
@@ -621,7 +664,7 @@ def build() -> Any:
         `create_project` or `save_model`. A model without errors is summarised
         (tables, columns).
         """
-        with _client(required=False) as client:
+        with make_client(required=False) as client:
             return checked_model_text(client.check_model(text))
 
     @server.tool()
@@ -637,7 +680,7 @@ def build() -> Any:
         `save_metrics`. Needs a key with save access that is not limited to one
         project; the plan's project limit applies.
         """
-        with _client() as client:
+        with make_client() as client:
             try:
                 created = building.create_project(client, name, model_text, metrics_text)
             except building.Rejected as error:
@@ -672,7 +715,7 @@ def build() -> Any:
         metrics file still reads against the new model. Needs a key with save
         access.
         """
-        with _client() as client:
+        with make_client() as client:
             try:
                 saved = building.save_model(client, project_id, text)
             except building.Rejected as error:
@@ -703,7 +746,7 @@ def build() -> Any:
         with examples, then what the studio adds. Read it after the model is
         written and before writing metrics. Needs no API key.
         """
-        with _client(required=False) as client:
+        with make_client(required=False) as client:
             return client.metrics_guide()
 
     @server.tool()
@@ -720,7 +763,7 @@ def build() -> Any:
         """
         if (project_id is None) == (model_text is None):
             raise StudioError("Pass project_id or model_text, one of the two.")
-        with _client(required=project_id is not None) as client:
+        with make_client(required=project_id is not None) as client:
             checked = client.check_metrics(model_text, text, project_id=project_id)
         return checked_metrics_text(checked)
 
@@ -734,7 +777,7 @@ def build() -> Any:
         and removed. Next: `metric_values` to see their numbers, then the
         dashboard tools. Needs a key with save access.
         """
-        with _client() as client:
+        with make_client() as client:
             try:
                 saved = building.save_metrics(client, project_id, text)
             except building.Rejected as error:
@@ -756,7 +799,7 @@ def build() -> Any:
         A dashboard is a file, `<name>.dashboard.yml`; `get_dashboard` gives one
         file's text and `get_dashboard_guide` says how to write one.
         """
-        with _client() as client:
+        with make_client() as client:
             dashboards = client.list_dashboards(project_id)
             where = client.project_url(project_id)
         if not dashboards:
@@ -774,7 +817,7 @@ def build() -> Any:
         """One dashboard file's text, exactly as stored: edit it and pass it back
         to `save_dashboard` to change the dashboard. `name` is the file name
         without `.dashboard.yml`."""
-        with _client() as client:
+        with make_client() as client:
             return str(client.get_dashboard(project_id, name).get("text") or "")
 
     @server.tool()
@@ -788,7 +831,7 @@ def build() -> Any:
         With `project_id`, it ends with what that project offers a dashboard: its
         model name, metrics (with labels) and `table.column` dimensions.
         """
-        with _client(required=project_id is not None) as client:
+        with make_client(required=project_id is not None) as client:
             return client.dashboard_guide(project_id)
 
     @server.tool()
@@ -801,7 +844,7 @@ def build() -> Any:
         `project_id`, names the project does not have come back as warnings,
         which do not stop a save.
         """
-        with _client(required=project_id is not None) as client:
+        with make_client(required=project_id is not None) as client:
             checked = client.check_dashboard(text, project_id)
         issues = dashboard_issues(checked)
         if checked.get("errors") or checked.get("ok") is False:
@@ -822,7 +865,7 @@ def build() -> Any:
         the same. The last step of building a project: give the user the
         studio URL (and share link) it answers with. Needs a key with save access.
         """
-        with _client() as client:
+        with make_client() as client:
             checked = client.check_dashboard(text, project_id)
             issues = dashboard_issues(checked)
             if checked.get("errors") or checked.get("ok") is False:

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "model2data-studio"
-version = "0.4.0"
+version = "0.5.0"
 description = "Generate a model2data studio project's data from the command line, so CI can rebuild fixtures instead of committing them."
 readme = "README.md"
 license = "MIT"

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/server.json

@@ -2,15 +2,15 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.JB-Analytica/model2data-studio",
   "title": "model2data studio",
-  "description": "Realistic fake data from a schema designed in model2data studio: preview rows, write seeds.",
+  "description": "Design a data model, metrics and dashboards; generate realistic data and check known answers.",
   "websiteUrl": "https://www.jbanalytica.com/model2data/",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "model2data-studio",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "runtimeHint": "uvx",
       "runtimeArguments": [
         {
@@ -46,5 +46,11 @@
         }
       ]
     }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://studio.jbanalytica.com/mcp"
+    }
   ]
 }

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/tests/test_building.py

@@ -601,3 +601,35 @@ class TestCli:
 
         assert result.exit_code == 0, result.output
         assert json.loads(fake.sent[0].content) == {"metrics": METRICS, "projectId": EXISTING["id"]}
+
+
+@pytest.mark.anyio
+class TestAServerBuiltForSomewhereElse:
+    """What the studio's own endpoint builds: its own clients, no `write_data`,
+    tools on a limiter of their own."""
+
+    async def test_it_uses_the_factory_and_leaves_out_write_data(self, monkeypatch):
+        import anyio
+
+        fake = FakeStudio()
+        made: list[bool] = []
+
+        def factory(*, required: bool = True) -> StudioClient:
+            made.append(required)
+            return _client(fake)
+
+        monkeypatch.delenv(mcp_server.KEY_ENV, raising=False)
+        server = mcp_server.build(
+            factory, local_files=False, thread_limiter=anyio.CapacityLimiter(1)
+        )
+
+        names = {tool.name for tool in await server.list_tools()}
+        assert "write_data" not in names
+        assert "create_project" in names
+        assert await call(server, "get_model_guide") == "# The model spec\n"
+        assert made == [False]
+
+    async def test_the_local_default_is_unchanged(self):
+        names = {tool.name for tool in await mcp_server.build().list_tools()}
+        assert "write_data" in names
+        assert len(names) == 19

{model2data_studio-0.4.0 → model2data_studio-0.5.0}/uv.lock

@@ -248,7 +248,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -438,7 +438,7 @@ wheels = [
 
 [[package]]
 name = "model2data-studio"
-version = "0.4.0"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
@@ -1159,8 +1159,8 @@ name = "uvicorn"
 version = "0.53.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "click" },
-    { name = "h11" },
+    { name = "click", marker = "python_full_version < '3.12' or python_full_version >= '3.14' or sys_platform != 'emscripten'" },
+    { name = "h11", marker = "python_full_version < '3.12' or python_full_version >= '3.14' or sys_platform != 'emscripten'" },
     { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/5d/ad/04bbb797c84fc1f26cb171f7394716f4865ffb8d8c5e1eef42565c2dfa6b/uvicorn-0.53.0.tar.gz", hash = "sha256:a9356f0cb89b3b8621529c5d5eebd69bfe154f4c3f68b4cf2de47e45fa855c2e", size = 110881, upload-time = "2026-09-14T07:44:23.815Z" }