multi client support

docs/mcp.md

@@ -1,19 +1,18 @@
 # `wlens mcp` — Model Context Protocol server
 
 `wlens mcp` starts an MCP server that exposes wlens over HTTP. Teammates
-connect from Claude Desktop (or any MCP-speaking client) to query the
-warehouse without each installing wlens locally.
+connect from any MCP-speaking client to query the warehouse without each
+installing wlens locally.
 
 Two modes, one binary:
 
 - **Production**: `wlens mcp` — you host it on your infra.
 - **Demo**: `wlens mcp --dangerously-share` — temporary ngrok tunnel +
-  drop-in config files for Claude Desktop and Claude Code. Not for
-  daily use.
+  drop-in config files for every major MCP client. Not for daily use.
 
 ## What the server exposes
 
-### Tools (the primary interface — what Claude Desktop surfaces to the agent)
+### Tools (the primary interface — what most clients surface to the agent)
 
 | Tool | Purpose |
 |---|---|
@@ -107,15 +106,8 @@ What happens:
 
 1. A random 32-character bearer token is generated in-process.
 2. wlens opens a pyngrok HTTPS tunnel to `127.0.0.1:<port>`.
-3. Three drop-in files are written under `wlens/share/`:
-   - `wlens.mcpb` — self-contained Claude Desktop extension bundle
-     (pre-bundled with the Python `mcp` SDK + `httpx`; recipient needs
-     nothing but Claude Desktop).
-   - `claude_desktop_config.json` — full Claude Desktop config JSON
-     that uses your **locally-installed** `wlens` as an mcp-proxy
-     (works if you have wlens on your machine).
-   - `.mcp.json` — Claude Code native HTTP config (no proxy needed).
-4. A banner prints the URL + token + paths.
+3. Drop-in files are written under `wlens/share/` (see next section).
+4. A banner prints the URL + token + paths + per-client install hints.
 5. When you Ctrl-C the process: tunnel closes, `wlens/share/` cleared,
    server exits.
 
@@ -130,22 +122,61 @@ demoing, sign up at [dashboard.ngrok.com](https://dashboard.ngrok.com),
 grab the authtoken, and `export NGROK_AUTHTOKEN=...`. pyngrok picks it
 up automatically.
 
-## Connecting clients
+## What `wlens mcp --dangerously-share` writes
 
-### Claude Desktop — drag-and-drop `.mcpb`
+Five drop-in files land under `wlens/share/`. wlens never writes outside
+the project repo — references to `~/.gemini/...`, `~/.codex/...`,
+`~/Library/Application Support/Claude/...`, etc. are paste targets,
+not files wlens touches.
 
-Double-click `wlens/share/wlens.mcpb`. Claude Desktop extracts the bundle
-and registers it as an extension — mcp-remote equivalent (Python) is
-vendored inside, URL and bearer token are baked into the manifest.
+| File | Format | For |
+|---|---|---|
+| `.mcp.json` | JSON, `mcpServers` with `url` + `type: "http"` | Claude Code (drop into project root). **Universal donor**: same shape works for Cursor, GitHub Copilot in VS Code, Cline, Zed at their own paths. |
+| `claude_desktop_config.json` | JSON, `mcpServers` with `command` + `args` | Claude Desktop (stdio via `wlens mcp-proxy` — Claude Desktop doesn't speak HTTP MCP). |
+| `wlens.mcpb` | Zip (Python bundle, MCPB v0.3) | Claude Desktop standalone install. Vendors `mcp` + `httpx` + `anyio` so the recipient needs nothing beyond Claude Desktop. Skipped if `uv` and `pip` are both unavailable at build time. |
+| `gemini_settings.json` | JSON, `mcpServers` with `httpUrl` | Gemini CLI / Antigravity (different field name from Claude Code). |
+| `codex_config.toml` | TOML, `[mcp_servers.<name>]` | Codex CLI (TOML, not JSON). |
+
+## Per-client setup
+
+Each client picks one of the files above (or pastes from one). The
+demo banner prints the exact CLI commands when applicable.
+
+### Claude Code
+
+Move `wlens/share/.mcp.json` into a project root and Claude Code picks
+it up on next launch. Or run:
+
+```bash
+claude mcp add --transport http --scope project wlens \
+  https://abc.ngrok-free.app/mcp \
+  --header "Authorization: Bearer ..."
+```
+
+File shape (Claude Code speaks HTTP MCP natively):
+
+```json
+{
+  "mcpServers": {
+    "wlens": {
+      "type": "http",
+      "url": "https://abc.ngrok-free.app/mcp",
+      "headers": { "Authorization": "Bearer ..." }
+    }
+  }
+}
+```
 
-### Claude Desktop — manual config
+### Claude Desktop
 
-Paste the contents of `wlens/share/claude_desktop_config.json` into
-`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
-or merge the `wlens` entry into an existing file with other MCPs.
-Restart Claude Desktop.
+**Preferred:** double-click `wlens/share/wlens.mcpb`. Claude Desktop
+extracts the bundle and registers it as an extension — Python proxy is
+vendored inside, URL and bearer token are baked into the manifest.
 
-The file looks like:
+**Manual fallback:** paste `wlens/share/claude_desktop_config.json` into
+`~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or merge the `wlens` entry into an existing file with other
+MCPs. Restart Claude Desktop.
 
 ```json
 {
@@ -162,38 +193,146 @@ The file looks like:
 Uses your installed `wlens` binary as a stdio↔HTTP bridge (the
 `mcp-proxy` subcommand). No Node, no npx — pure Python.
 
-### Claude Code — drop-in `.mcp.json`
+### Gemini CLI
+
+Run:
 
-Move `wlens/share/.mcp.json` into any project root. Claude Code reads
-it automatically on next launch. File shape (Claude Code speaks HTTP MCP
-natively):
+```bash
+gemini mcp add --transport http wlens \
+  https://abc.ngrok-free.app/mcp \
+  --header "Authorization: Bearer ..."
+```
+
+Or merge `wlens/share/gemini_settings.json` into `~/.gemini/settings.json`
+(global) or `.gemini/settings.json` (project). Field name is `httpUrl`,
+not `url`:
 
 ```json
 {
   "mcpServers": {
     "wlens": {
-      "type": "http",
-      "url": "https://abc.ngrok-free.app/mcp",
+      "httpUrl": "https://abc.ngrok-free.app/mcp",
       "headers": { "Authorization": "Bearer ..." }
     }
   }
 }
 ```
 
-Or via CLI:
+### Antigravity (Google's IDE)
 
-```bash
-claude mcp add --transport http --scope project wlens \
-  https://abc.ngrok-free.app/mcp \
-  --header "Authorization: Bearer ..."
+Settings → MCP Servers → Manage MCP Servers → View raw config → paste
+the contents of `wlens/share/gemini_settings.json`. Same Gemini-shape
+JSON.
+
+### Codex CLI (OpenAI)
+
+Merge the `[mcp_servers.wlens]` block from `wlens/share/codex_config.toml`
+into `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.wlens]
+url = "https://abc.ngrok-free.app/mcp"
+http_headers = { Authorization = "Bearer ..." }
 ```
 
-### Other MCP clients
+Codex doesn't have a per-project MCP config (everything lives in
+`~/.codex/config.toml`).
+
+### ChatGPT (web / desktop, Apps)
+
+ChatGPT installs MCP servers via UI, not a config file:
+
+1. Settings → Connectors → Developer Mode (Plus/Pro/Team/Enterprise/Edu only).
+2. **Add custom MCP** (or **Add a custom Apps connector**).
+3. URL: `https://abc.ngrok-free.app/mcp`
+4. Authentication: Bearer token, paste the token from the share banner.
+
+Custom MCP Apps live behind Developer Mode; free ChatGPT does not
+support them.
+
+### Cursor
+
+Copy `wlens/share/.mcp.json` to one of:
+
+- `.cursor/mcp.json` (project-scoped — only this project)
+- `~/.cursor/mcp.json` (global — all your Cursor workspaces)
+
+Same shape as the Claude Code file works unchanged.
+
+### GitHub Copilot in VS Code
+
+Copy `wlens/share/.mcp.json` to `.vscode/mcp.json` in your project
+(or merge into your VS Code user `settings.json` under
+`chat.mcp.servers`). The Claude Code shape is accepted unchanged.
+
+### Windsurf
+
+Paste the contents of `wlens/share/.mcp.json` into
+`~/.codeium/windsurf/mcp_config.json`, merging the `wlens` entry into
+the `mcpServers` map.
+
+### Cline (VS Code extension)
 
-Any MCP-speaking client (Cursor, Continue, etc.) can reach the same URL
-as long as it supports bearer auth headers. For clients that speak
-stdio only, run `wlens mcp-proxy <url>` locally as the bridge — it's
-the same shim the Claude Desktop config uses.
+Open Cline's MCP settings (in the extension panel) → Edit MCP Settings
+JSON → paste the `mcpServers.wlens` entry from `wlens/share/.mcp.json`.
+
+### Zed
+
+Open `~/.config/zed/settings.json` and paste the `mcpServers.wlens`
+entry under the `assistant.mcp_servers` map (Zed's exact key may evolve
+— check Zed's docs if it doesn't pick up).
+
+### Continue
+
+Continue uses YAML (`.continue/config.yaml`), not JSON. Hand-translate
+from `.mcp.json`:
+
+```yaml
+mcpServers:
+  - name: wlens
+    type: http
+    url: https://abc.ngrok-free.app/mcp
+    headers:
+      Authorization: "Bearer ..."
+```
+
+### Pi.dev
+
+Pi has no native MCP. Two options:
+
+- **MCP via adapter:** install
+  [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter)
+  and reuse the `wlens/share/.mcp.json` shape — the adapter reads
+  standard MCP files automatically.
+- **Filesystem mode (no adapter):** Pi has shell + read tools, so it
+  works with the bundled SKILL.md. Pi scans **user-level**
+  `~/.agents/skills/` only. To make wlens discoverable across every
+  project you open Pi in, run a one-time symlink (`wlens` itself
+  never writes outside the repo):
+
+  ```bash
+  ln -s "$(pwd)/.agents/skills/wlens" ~/.agents/skills/wlens
+  ```
+
+## Filesystem mode (no MCP)
+
+Any shell-capable agent works without an MCP server: the agent uses
+its built-in `Grep` + `Read` against `wlens/schema/*.md`, then shells
+out to `wlens query "SELECT …"`.
+
+`wlens init` plants the SKILL.md into two project-level discovery
+paths so any major agent finds it:
+
+| Path | Picked up by |
+|---|---|
+| `.claude/skills/wlens/SKILL.md` | Claude Code (which doesn't scan `.agents/skills/`) |
+| `.agents/skills/wlens/SKILL.md` | Gemini CLI, Antigravity, Codex CLI (walks up from cwd to repo root), Cursor, GitHub Copilot in VS Code, anything else following the [Agent Skills open standard](https://agentskills.io) |
+
+The Agent Skills format went open-standard in December 2025, so the
+list of tools that read `.agents/skills/` is growing. Both files are
+byte-identical — wlens writes one template to two destinations. (Note:
+Gemini CLI scans `.agents/skills/` directly; it does **not** scan
+`.gemini/skills/`, contrary to some older third-party docs.)
 
 ## `wlens mcp-proxy` — the stdio bridge
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wlens"
-version = "0.1.0"
+version = "0.1.1"
 description = "Warehouse lens for AI agents — per-table markdown docs + read-only SQL adaptor, zero-runtime schema exploration for Claude Code, Cursor, Continue."
 readme = "README.md"
 license = { file = "LICENSE" }