diff --git a/docs/getting_started_with_claude_code.md b/docs/getting_started_with_claude_code.md index 71d7c4cb5..0391b71af 100644 --- a/docs/getting_started_with_claude_code.md +++ b/docs/getting_started_with_claude_code.md @@ -33,7 +33,7 @@ This installs the following skills into `~/.claude/skills/`: | Skill | Purpose | |-------|---------| | `wren-quickstart` | End-to-end guided setup | -| `wren-connection-info` | Configure database credentials | +| `wren-connection-info` | Connection field reference per data source | | `generate-mdl` | Generate MDL from a live database | | `wren-project` | Save and build MDL as YAML files | | `wren-mcp-setup` | Start the Docker container and register MCP | @@ -156,9 +156,29 @@ docker logs wren-mcp > **Database on localhost?** If your database runs on your host machine, replace `localhost` / `127.0.0.1` with `host.docker.internal` in your connection settings — the container cannot reach the host's `localhost` directly. -### Phase 3 — Generate the MDL +### Phase 3 — Configure connection and register MCP server -In Claude Code, run: +Configure connection info in the Web UI at `http://localhost:9001` — select the data source type and enter credentials. Use `/wren-connection-info` in Claude Code for field reference per data source. + +> **Connection info can only be configured through the Web UI.** Do not attempt to set it programmatically. + +Then register the MCP server with Claude Code: + +```bash +claude mcp add --transport http wren http://localhost:9000/mcp +``` + +Verify it was added: + +```bash +claude mcp list +``` + +**Start a new Claude Code session** — MCP servers are only loaded at session start. + +### Phase 4 — Generate the MDL + +In the new session, run: ``` /generate-mdl @@ -166,13 +186,13 @@ In Claude Code, run: The skill will: -1. Run `health_check()` to verify the connection is configured +1. Run `health_check()` to verify the connection is working 2. Ask for your data source type (PostgreSQL, BigQuery, Snowflake, etc.) and optional schema filter -3. Call `list_remote_tables()` and `list_remote_constraints()` via the MCP server to introspect your database schema +3. Call `list_remote_tables()` and `list_remote_constraints()` via MCP tools to introspect your database schema 4. Build the MDL JSON (models, columns, relationships) 5. Validate the manifest with `deploy_manifest()` + `dry_run()` -> **Connection info** must be configured in the Web UI (`http://localhost:9001`) before running `/generate-mdl`. Use `/wren-connection-info` in Claude Code for field reference per data source. +> **Prerequisite:** The MCP server must be registered and a new session started (Phase 3). The `/generate-mdl` skill uses MCP tools — do not call ibis-server API directly. Then save the MDL as a versioned YAML project: @@ -182,22 +202,6 @@ Then save the MDL as a versioned YAML project: This writes human-readable YAML files to your workspace and compiles `target/mdl.json`. -### Phase 4 — Register the MCP server - -Add Wren to Claude Code's MCP configuration: - -```bash -claude mcp add --transport http wren http://localhost:9000/mcp -``` - -Verify it was added: - -```bash -claude mcp list -``` - -**Start a new Claude Code session** — MCP servers are only loaded at session start. - --- ## Verify and start querying @@ -250,9 +254,10 @@ docker restart wren-mcp # restart | `health_check()` | Verify Wren Engine is reachable | | `query(sql=...)` | Execute SQL against the deployed MDL | | `deploy(mdl_file_path=...)` | Load a compiled `mdl.json` | -| `setup_connection(...)` | Configure data source credentials | | `list_remote_tables(...)` | Introspect database schema | +> **Note:** Connection info is configured exclusively through the Web UI at `http://localhost:9001` — there is no MCP tool for setting credentials. + --- ## Troubleshooting @@ -289,3 +294,20 @@ To update a single skill: ```bash curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash -s -- --force generate-mdl ``` + +--- + +## Locking down with read-only mode + +Once you have confirmed that queries are returning correct results and the MDL is working as expected, enable **read-only mode** in the Web UI: + +1. Open `http://localhost:9001` +2. Toggle **Read-Only Mode** to on + +When read-only mode is enabled: + +- The AI agent can **query data** and **read metadata** through the deployed MDL as usual +- The AI agent **cannot** modify connection info, change the data source, or call `list_remote_tables()` / `list_remote_constraints()` to introspect the database directly +- This limits the agent to operating within the boundaries of the MDL you have defined, preventing it from accessing tables or schemas you have not explicitly modeled + +We recommend enabling read-only mode for day-to-day use. Turn it off temporarily when you need to regenerate the MDL or change connection settings. diff --git a/docs/quickstart.md b/docs/quickstart.md index 5c8e1c8d5..39c3be5b2 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -141,9 +141,9 @@ docker ps --filter name=wren-mcp curl http://localhost:8000/health ``` -#### Phase 2 — Configure the connection and generate the MDL +#### Phase 2 — Configure connection and register MCP server -Before generating the MDL, configure the DuckDB connection via the Web UI at `http://localhost:9001`: +Configure the DuckDB connection via the Web UI at `http://localhost:9001`: 1. Open `http://localhost:9001` in your browser 2. Select data source type: **DUCKDB** @@ -161,33 +161,37 @@ The JSON looks like: > **Common mistake:** Do not point `url` to the `.duckdb` file directly (e.g. `/data/jaffle_shop.duckdb`). The ibis-server expects a **directory** — it scans for all `.duckdb` files in that directory and attaches them automatically. Pointing to the binary file causes a UTF-8 decode error. -After saving the connection, run the skills in sequence in Claude Code: +Then register the MCP server with Claude Code: -```text -/generate-mdl +```bash +claude mcp add --transport http wren http://localhost:9000/mcp ``` -Then save the MDL as a versioned YAML project: +Verify it was added: -```text -/wren-project +```bash +claude mcp list ``` -This writes human-readable YAML files to `~/wren-workspace/` and compiles `target/mdl.json`. +**Start a new Claude Code session** — MCP servers are only loaded at session start. -#### Phase 3 — Register the MCP server +#### Phase 3 — Generate the MDL -```bash -claude mcp add --transport http wren http://localhost:9000/mcp +In the new session, run the skills in sequence: + +```text +/generate-mdl ``` -Verify it was added: +The skill uses MCP tools (`health_check()`, `list_remote_tables()`, etc.) to introspect the database — these tools are only available after the MCP server is registered and a new session is started. -```bash -claude mcp list +Then save the MDL as a versioned YAML project: + +```text +/wren-project ``` -**Start a new Claude Code session** — MCP servers are only loaded at session start. +This writes human-readable YAML files to `~/wren-workspace/` and compiles `target/mdl.json`. @@ -273,7 +277,24 @@ Check container logs: `docker logs wren-mcp`. Confirm ports are listening: `curl |------|---------| | Add or edit MDL models | `/wren-project` | | Write custom SQL | `/wren-sql` | -| Connect a different database | `/wren-connection-info` | +| Connect a different database | Web UI at `http://localhost:9001` (use `/wren-connection-info` for field reference) | | Day-to-day usage guide | `/wren-usage` | For a deeper dive into how skills work or how to connect a cloud database, see [Getting Started with Claude Code](./getting_started_with_claude_code.md). + +--- + +## Locking down with read-only mode + +Once you have confirmed that queries are returning correct results and the MDL is working as expected, enable **read-only mode** in the Web UI: + +1. Open `http://localhost:9001` +2. Toggle **Read-Only Mode** to on + +When read-only mode is enabled: + +- The AI agent can **query data** and **read metadata** through the deployed MDL as usual +- The AI agent **cannot** modify connection info, change the data source, or call `list_remote_tables()` / `list_remote_constraints()` to introspect the database directly +- This limits the agent to operating within the boundaries of the MDL you have defined, preventing it from accessing tables or schemas you have not explicitly modeled + +We recommend enabling read-only mode for day-to-day use. Turn it off temporarily when you need to regenerate the MDL or change connection settings. diff --git a/mcp-server/README.md b/mcp-server/README.md index 161c8eab4..c5e0f3230 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -203,13 +203,15 @@ schema discovery. No local database drivers need to be installed on the MCP serv ### How it works -The agent calls ibis-server tools in sequence: +The agent calls MCP tools in sequence: ``` User → "Generate an MDL for my PostgreSQL ecommerce database" -Agent → setup_connection(datasource="POSTGRES", - conn_info={"host":"localhost","port":"5432","user":"...","database":"shop"}) +User → (configures connection info via Web UI at http://localhost:9001) + +Agent → health_check() + ← "Wren Engine is reachable." Agent → list_remote_tables() ← [{"name":"orders","columns":[...]}, {"name":"customers","columns":[...]}, ...] @@ -227,6 +229,8 @@ Agent → deploy_manifest({"catalog":"wren","schema":"public","dataSource":"POST ← "MDL deployed successfully (5 models, 23 columns)" ``` +> **Note:** Connection info can only be configured through the Web UI — there is no MCP tool for setting credentials. + ### Environment Variables | Variable | Required | Description | diff --git a/skills/generate-mdl/SKILL.md b/skills/generate-mdl/SKILL.md index 56c2d5490..6b3c1c15d 100644 --- a/skills/generate-mdl/SKILL.md +++ b/skills/generate-mdl/SKILL.md @@ -5,7 +5,7 @@ compatibility: Requires a running ibis-server (default port 8000). No local data license: Apache-2.0 metadata: author: wren-engine - version: "1.3" + version: "1.4" --- # Generate Wren MDL @@ -13,10 +13,10 @@ metadata: ## Version check Silently fetch `https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json`. -Compare the `generate-mdl` key with this skill's version (`1.3`). +Compare the `generate-mdl` key with this skill's version (`1.4`). If the remote version is newer, notify the user before proceeding: -> A newer version of the **generate-mdl** skill is available (remote: X.Y, installed: 1.3). +> A newer version of the **generate-mdl** skill is available (remote: X.Y, installed: 1.4). > Update with: > ```bash > curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash -s -- --force generate-mdl @@ -34,13 +34,15 @@ Follow these steps in order. Do not skip steps or ask unnecessary questions betw ### Step 1 — Verify connection and choose data source +> **Connection info can ONLY be configured through the Web UI at `http://localhost:9001`.** Do not attempt to set connection info programmatically via ibis-server API calls, curl, or any other method. The ibis-server does not expose a public API for writing connection info — only the Web UI can do this. + Confirm the MCP server has a working connection before proceeding: ```text health_check() ``` -If the health check fails, ask the user to configure the connection via the Web UI at `http://localhost:9001` before continuing. +If the health check fails, or if the user has not yet configured a connection, direct them to the Web UI at `http://localhost:9001` to enter their data source credentials. Wait for the user to confirm the connection is saved before continuing. Ask the user for: 1. **Data source type** (e.g. `POSTGRES`, `BIGQUERY`, `SNOWFLAKE`, …) — needed to set `dataSource` in the MDL @@ -207,6 +209,6 @@ When in doubt, use `VARCHAR` as a safe fallback. ## Connection setup -Connection info is configured via the MCP server Web UI at `http://localhost:9001`. See the **wren-mcp-setup** skill for Docker setup instructions. +Connection info is configured **exclusively** via the MCP server Web UI at `http://localhost:9001`. There is no API endpoint for setting connection info — do not attempt to configure it programmatically. See the **wren-mcp-setup** skill for Docker setup instructions. > **Note:** If the Web UI is disabled (`WEB_UI_ENABLED=false`), connection info must be pre-configured in `~/.wren/connection_info.json` before starting the container. Use `/wren-connection-info` in Claude Code for the required fields per data source. diff --git a/skills/index.json b/skills/index.json index cc5af38c9..ac25a6641 100644 --- a/skills/index.json +++ b/skills/index.json @@ -7,7 +7,7 @@ "skills": [ { "name": "wren-connection-info", - "version": "1.3", + "version": "1.4", "description": "Reference guide for Wren Engine connection info — required fields, sensitive values, Docker host hints, and BigQuery credential encoding.", "tags": [ "wren", @@ -20,7 +20,7 @@ }, { "name": "generate-mdl", - "version": "1.3", + "version": "1.4", "description": "Generate a Wren MDL manifest from a live database using MCP server introspection tools.", "tags": [ "wren", @@ -82,7 +82,7 @@ }, { "name": "wren-quickstart", - "version": "1.2", + "version": "1.3", "description": "End-to-end quickstart for Wren Engine — from zero to querying.", "tags": [ "wren", @@ -100,7 +100,7 @@ }, { "name": "wren-usage", - "version": "1.0", + "version": "1.1", "description": "Daily usage guide for Wren Engine — connect, query, manage MDL, and operate the MCP server via AI agents.", "tags": [ "wren", diff --git a/skills/versions.json b/skills/versions.json index d70a9e683..1e29a8b80 100644 --- a/skills/versions.json +++ b/skills/versions.json @@ -1,9 +1,9 @@ { - "generate-mdl": "1.3", - "wren-connection-info": "1.3", + "generate-mdl": "1.4", + "wren-connection-info": "1.4", "wren-project": "1.5", "wren-sql": "1.0", "wren-mcp-setup": "1.3", - "wren-quickstart": "1.2", - "wren-usage": "1.0" + "wren-quickstart": "1.3", + "wren-usage": "1.1" } diff --git a/skills/wren-connection-info/SKILL.md b/skills/wren-connection-info/SKILL.md index e79e694de..7f67e34af 100644 --- a/skills/wren-connection-info/SKILL.md +++ b/skills/wren-connection-info/SKILL.md @@ -4,14 +4,14 @@ description: Reference guide for Wren Engine connection info — explains requir license: Apache-2.0 metadata: author: wren-engine - version: "1.3" + version: "1.4" --- # Wren Connection Info Reference This skill answers questions about how to configure connection info for each data source in Wren Engine. Use it to explain required fields, flag sensitive values, and guide the user through any data-source-specific setup steps. -The connection info is entered by the user — in the MCP server Web UI (`http://localhost:9001`) for normal use, or directly in API calls for advanced workflows. +Connection info can **only** be configured through the MCP server Web UI at `http://localhost:9001`. There is no ibis-server API for writing connection info — do not attempt to set it programmatically via API calls, curl, or any other method. Always direct the user to the Web UI to enter or update credentials. --- diff --git a/skills/wren-quickstart/SKILL.md b/skills/wren-quickstart/SKILL.md index 5de4788ac..0867d1009 100644 --- a/skills/wren-quickstart/SKILL.md +++ b/skills/wren-quickstart/SKILL.md @@ -5,7 +5,7 @@ compatibility: Requires Docker Desktop (or Docker Engine). No local database dri license: Apache-2.0 metadata: author: wren-engine - version: "1.2" + version: "1.3" --- # Wren Quickstart @@ -13,10 +13,10 @@ metadata: ## Version check Silently fetch `https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json`. -Compare the `wren-quickstart` key with this skill's version (`1.2`). +Compare the `wren-quickstart` key with this skill's version (`1.3`). If the remote version is newer, notify the user before proceeding: -> A newer version of the **wren-quickstart** skill is available (remote: X.Y, installed: 1.2). +> A newer version of the **wren-quickstart** skill is available (remote: X.Y, installed: 1.3). > Update with: > ```bash > curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash -s -- --force wren-quickstart @@ -74,86 +74,85 @@ Recommended workspace layout after the quickstart completes: --- -## Phase 2 — Generate MDL and save project +## Phase 2 — Start Docker container and register MCP server -### 2a — Generate MDL - -Invoke the **generate-mdl** skill to introspect the user's database and build the MDL manifest: +Invoke the **wren-mcp-setup** skill to start the Docker container and register the MCP server with the AI client: ``` -@generate-mdl +@wren-mcp-setup ``` -The generate-mdl skill will: -1. Ask for data source type and connection credentials -2. Call ibis-server to fetch table schema and foreign key constraints -3. Build the MDL JSON (models, columns, relationships) -4. Validate the manifest with a dry-plan +Pass `` as the workspace mount path when the skill asks. -> **Important:** At this stage ibis-server may not be running yet. If the user has not started a container, proceed to Phase 3 first (start the container), then come back to generate the MDL using the running ibis-server on port 8000. -> -> Alternatively, if the user already has a running ibis-server, run Phase 2 before Phase 3. +The wren-mcp-setup skill will: +1. Start the container with `-v :/workspace` +2. Set `MDL_PATH=/workspace/target/mdl.json` +3. Register the MCP server with the AI client (`claude mcp add`) +4. Verify the container is running -### 2b — Save as YAML project +### 2b — Configure connection info via Web UI -After the MDL is generated, invoke the **wren-project** skill to save it as a versioned YAML project inside the workspace: +Once the container is running, open the MCP server Web UI to configure connection info: -``` -@wren-project +```text +http://localhost:9001 ``` -Direct the skill to write the project files into ``: +Enter the data source credentials (host, port, database, user, password, etc.) in the UI form and save. The MCP server stores and applies the connection info without exposing credentials to this conversation. -- `/wren_project.yml` -- `/models/*.yml` -- `/relationships.yml` -- `/views.yml` +> **Tip:** If your database is running locally, use `host.docker.internal` instead of `localhost` as the host address. -Then build the compiled target: +### 2c — Start a new session -- `/target/mdl.json` +The user must **start a new Claude Code session** for the Wren MCP tools to be loaded. Instruct the user to do this now and come back to continue with Phase 3. -The Docker container will auto-load this file at startup. +> **Important:** Do not proceed to Phase 3 until the new session is started. The `generate-mdl` skill requires MCP tools (`health_check()`, `list_remote_tables()`, etc.) which are only available after the MCP server is registered and a new session is started. --- -## Phase 3 — Start and register the MCP server +## Phase 3 — Generate MDL and save project -Invoke the **wren-mcp-setup** skill to start the Docker container and register the MCP server with the AI client: +> **Prerequisite:** The MCP server must be registered and a new session started (Phase 2c). The `generate-mdl` skill uses MCP tools — do not call ibis-server API directly. + +### 3a — Generate MDL + +Invoke the **generate-mdl** skill to introspect the user's database and build the MDL manifest: ``` -@wren-mcp-setup +@generate-mdl ``` -Pass `` as the workspace mount path when the skill asks. +The generate-mdl skill will: +1. Run `health_check()` to verify the connection is working +2. Ask for data source type and optional schema filter +3. Call `list_remote_tables()` and `list_remote_constraints()` via MCP to fetch schema +4. Build the MDL JSON (models, columns, relationships) +5. Validate the manifest with `deploy_manifest()` + `dry_run()` -The wren-mcp-setup skill will: -1. Start the container with `-v :/workspace` -2. Set `MDL_PATH=/workspace/target/mdl.json` -3. Register the MCP server with the AI client (`claude mcp add`) -4. Verify the container is running +### 3b — Save as YAML project -> If `/target/mdl.json` already exists before the container starts, it is loaded automatically at boot. No separate `deploy` call is needed. +After the MDL is generated, invoke the **wren-project** skill to save it as a versioned YAML project inside the workspace: -### 3b — Configure connection info via Web UI +``` +@wren-project +``` -Once the container is running, open the MCP server Web UI to configure connection info: +Direct the skill to write the project files into ``: -```text -http://localhost:9001 -``` +- `/wren_project.yml` +- `/models/*.yml` +- `/relationships.yml` +- `/views.yml` -Enter the data source credentials (host, port, database, user, password, etc.) in the UI form and save. The MCP server stores and applies the connection info without exposing credentials to this conversation. +Then build the compiled target: -> **Tip:** If your database is running locally, use `host.docker.internal` instead of `localhost` as the host address. +- `/target/mdl.json` --- -## Phase 4 — Verify and confirm - -Once the MCP server is registered, the user must **start a new session** for the Wren MCP tools to be loaded. Instruct the user to do this now. +## Phase 4 — Verify and start querying -In the new session, ask the AI agent to run a health check: +Run a health check to confirm everything is working: ``` Use health_check() to verify Wren Engine is reachable. @@ -164,7 +163,7 @@ Expected response: `SELECT 1` returns successfully. If the health check passes: - Tell the user setup is complete. -- In this session, they can start querying immediately: +- They can start querying immediately: ``` Query: How many orders are in the orders table? @@ -178,24 +177,22 @@ If the health check fails, follow the troubleshooting steps in the **wren-mcp-se | Phase | Skill | Purpose | |-------|-------|---------| -| 2a | `@generate-mdl` | Introspect database and build MDL JSON | -| 2b | `@wren-project` | Save MDL as YAML project + compile to `target/` | -| 3 | `@wren-mcp-setup` | Start Docker container and register MCP server | +| 2 | `@wren-mcp-setup` | Start Docker container and register MCP server | +| 3a | `@generate-mdl` | Introspect database and build MDL JSON | +| 3b | `@wren-project` | Save MDL as YAML project + compile to `target/` | --- ## Troubleshooting -**Container not finding MDL at startup:** -- Confirm `/target/mdl.json` exists before starting the container. -- Check container logs: `docker logs wren-mcp` - -**generate-mdl fails because ibis-server is not yet running:** -- Start the container first (Phase 3), then return to Phase 2. -- ibis-server is available at `http://localhost:8000` once the container is up. - -**MCP tools not available after registration:** +**MCP tools not available:** - The MCP server is only loaded at session start. Start a new Claude Code session after registering. +- Do not attempt to call ibis-server API directly — always use MCP tools. + +**generate-mdl fails:** +- Ensure the container is running: `docker ps --filter name=wren-mcp` +- Ensure connection info is configured in the Web UI (`http://localhost:9001`) +- Ensure a new session was started after `claude mcp add` **Database connection refused inside Docker:** - Change `localhost` / `127.0.0.1` to `host.docker.internal` in connection credentials. diff --git a/skills/wren-usage/SKILL.md b/skills/wren-usage/SKILL.md index 2f341258f..f1155c839 100644 --- a/skills/wren-usage/SKILL.md +++ b/skills/wren-usage/SKILL.md @@ -4,7 +4,7 @@ description: Daily usage guide for Wren Engine — connect to a database, write license: Apache-2.0 metadata: author: wren-engine - version: "1.0" + version: "1.1" --- # Wren Engine — Usage Guide @@ -89,10 +89,9 @@ For type-specific patterns (ARRAY, STRUCT, JSON), date/time arithmetic, or BigQu ### Update connection credentials -Invoke `@wren-connection-info` to: -- Change the data source type or credentials -- Produce a new `connection.yml` + `target/connection.json` -- Switch between `connectionFilePath` (secure) and inline dict +To change credentials, direct the user to the MCP server Web UI at `http://localhost:9001`. Connection info can only be configured through the Web UI — do not attempt to set it programmatically. + +Invoke `@wren-connection-info` for a reference of required fields per data source (so you can guide the user on what to enter in the Web UI). ---