Metadata-Version: 2.4
Name: vibedasher-mcp
Version: 0.1.1
Summary: MCP server exposing the Vibedasher data engine (datasets, query, viz) to a customer's AI.
Project-URL: Homepage, https://vibedasher.com
Project-URL: Source, https://github.com/JulienGdnr/vibedasher
Author: Vibedasher
License: MIT
Keywords: analytics,bi,eject,mcp,model-context-protocol,vibedasher
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx<0.29.0,>=0.23.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: vibedasher>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# vibedasher-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes the **Vibedasher data
engine** — datasets, CSV upload + ETL, headless SQL query, and dashboard (viz)
management — as tools a customer's AI (Claude Code, Cursor, ...) can drive directly.

This is the **control plane** (VD-601, PIVOT/PLAN.md EP-6). It wraps the published
[`vibedasher` Python SDK](https://pypi.org/project/vibedasher/) and calls only the public, metered `/api/v1/*`
API.

**Install:** `pip install vibedasher-mcp` — live on PyPI since 2026-08-09, as are
`vibedasher` (PyPI) and `@vibedasher/client` (npm).

The **eject tools (VD-602) ship in this package**, not separately: `eject_viz`,
`eject_instructions` and `get_viz_files` are registered by `register_eject_tools()`
in `eject.py`. They pull a viz's code plus an SDK-wiring manifest so your AI can
recreate the dashboard natively in your stack.

## Tools

| Tool | What it does |
|------|--------------|
| `list_datasets` | List datasets the key can read (id, name, `cleanSQLName`, status). |
| `get_dataset(dataset_id)` | One dataset's metadata + column schema. |
| `upload_dataset(name, csv_content, ...)` | Create a CSV dataset, upload, load, poll to READY. |
| `run_query(dataset_ids, sql, params)` | Inline alias-only SQL across your datasets (plural `datasetIds`, joins allowed) → typed columns + rows. |
| `list_vizzes(include_unpublished=False)` | List dashboards. |
| `get_viz(viz_id)` | One viz's metadata. |
| `create_viz(name, dataset_ids, seed_id/dashboard_config, ...)` | Create a viz (AI dashboard-build entry). |
| `build_viz(viz_id, branch)` | Compile a viz branch into a renderable bundle. |
| `eject_viz(viz_id, branch)` | **(eject)** The viz's runnable source tree + package.json + Tailwind config + wiring manifest. |
| `eject_instructions()` | **(eject)** How to recreate an ejected dashboard in your app — the query contract, auth modes, region sharding, and the host-bundler traps. |
| `get_viz_files(viz_id, branch)` | **(eject)** Raw file tree for a viz branch. |

`run_query` reuses the SDK's hand-written `query()` transport (VD-301): the caller
never sees inline-vs-presigned delivery, MessagePack, or retries — one call in,
typed rows out. Each dataset id resolves server-side to that dataset's
`cleanSQLName` alias under the VD-203 RLS/alias-rewrite; SQL references only aliases.

## Auth

API key only, via `X-Api-Key` (handled by the SDK's `create_client`). Set:

```bash
export VIBEDASHER_API_KEY=...           # mint via `POST /v1/api-keys` or the console
export VIBEDASHER_REGION=eu-central-1   # or us-east-1
# export VIBEDASHER_BASE_URL=...        # optional override (on-prem/staging)
```

The key is read once at first tool call and is never logged or echoed in any
tool result.

## Metering

Every tool hits the public, metered endpoints (`create_dataset` is credit-gated;
`run_query` is metered via the usage/credits event). The MCP adds no side channel
and bypasses no metering.

## Run

```bash
pip install vibedasher-mcp        # (monorepo dev: also make `vibedasher` importable)
vibedasher-mcp                    # stdio MCP server
# or:  python -m vibedasher_mcp
```

MCP client config (Claude Code / Cursor):

```json
{
  "mcpServers": {
    "vibedasher": {
      "command": "vibedasher-mcp",
      "env": { "VIBEDASHER_API_KEY": "...", "VIBEDASHER_REGION": "eu-central-1" }
    }
  }
}
```

## Development

The package depends on the sibling SDK at `../sdk/py`. Tests wire that path
automatically (`tests/conftest.py`), so from `packages/mcp`:

```bash
python -m pytest tests/ -q
```

> Note: `fastmcp` is a **client-side** dependency of this standalone package; it is
> not bundled into the API Lambdas, so the `export_requirements.py` step in the root
> `CLAUDE.md` does not apply here.
