Merge branch 'main' into fix/pi-config-dir-env

Author: dgokeeffe

.github/workflows/ci.yml

@@ -12,14 +12,23 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    env:
+      # uv.lock pins packages to Databricks' internal pypi-proxy, which hosted
+      # GitHub runners can't reach (downloads time out). Re-resolve against
+      # public PyPI at CI time: UV_INDEX_URL + a `uv lock` before install.
+      UV_INDEX_URL: https://pypi.org/simple
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+      - run: uv lock
       - run: uv run pytest --ignore=tests/test_e2e.py --ignore=tests/test_e2e_tracing.py
 
   e2e:
     runs-on: ubuntu-latest
     env:
+      # See the test job: hosted runners can't reach the internal pypi-proxy,
+      # so resolve against public PyPI (paired with the `uv lock` step below).
+      UV_INDEX_URL: https://pypi.org/simple
       UCODE_TEST_WORKSPACE: ${{ secrets.UCODE_TEST_WORKSPACE }}
       DATABRICKS_HOST: ${{ secrets.UCODE_TEST_WORKSPACE }}
       # DATABRICKS_BEARER is the CI escape hatch: `databricks auth token`
@@ -47,6 +56,7 @@ jobs:
           opencode-ai
           @github/copilot
           @earendil-works/pi-coding-agent
+      - run: uv lock
       - run: uv tool install .
       # Redirect stdin so any interactive `databricks auth login --no-browser`
       # fallback EOFs instead of hanging the runner. With DATABRICKS_BEARER

AGENTS.md

@@ -20,7 +20,7 @@ Tests live in `tests/`.
 
 - Use Python 3.12+.
 - Keep changes scoped to the requested behavior.
-- Follow the existing module boundaries: CLI orchestration in `cli.py`, agent-specific behavior in `agents/<name>.py`, shared agent dispatch in `agents/__init__.py`, Databricks calls in `databricks.py`, skill download (UC fetch client + on-disk writer + download orchestration) in `skills_download.py`, MCP-connection state glue in `mcp.py`, and presentation helpers in `ui.py`. Skill download persists no disk state — it writes files to `--path` (or the home dir) and registers only the schema-less skills MCP connection.
+- Follow the existing module boundaries: CLI orchestration in `cli.py`, agent-specific behavior in `agents/<name>.py`, shared agent dispatch in `agents/__init__.py`, Databricks calls in `databricks.py`, skill download (UC fetch client + on-disk writer + download orchestration) in `skills_download.py`, MCP-connection state glue in `mcp.py`, and presentation helpers in `ui.py`. Skill download persists no disk state — it writes files to `--path` (or the home dir) and registers only the schema-less skills MCP connection. `ucode configure skills` with no `--location` (or `--mcp` with no `--location`) registers that schema-less connection without downloading anything.
 - Prefer existing helpers for config file writes, state persistence, UI messages, and Databricks authentication.
 - Add or update focused tests for behavior changes.
 - Do not modify generated or lock files unless the dependency graph intentionally changes.

README.md

@@ -26,6 +26,7 @@ ucode gemini     # Gemini CLI
 ucode opencode   # OpenCode
 ucode copilot    # GitHub Copilot CLI
 ucode pi         # Pi
+ucode cursor     # Cursor Agent (MCP only — see below)
 ```
 
 On first launch, `ucode` will prompt for your Databricks workspace URL, authenticate, and configure that tool automatically. Subsequent launches go straight to the agent.
@@ -51,7 +52,7 @@ To configure specific tools without the picker, pass a comma-separated list:
 ucode configure --agents claude,codex
 ```
 
-Available agent names are `codex`, `claude`, `gemini`, `opencode`, `copilot`, and `pi`.
+Available agent names are `codex`, `claude`, `gemini`, `opencode`, `copilot`, and `pi`. `cursor` is also accepted (MCP-only — it registers Databricks MCP servers but configures no models).
 
 To configure without the workspace picker, pass a comma-separated list of workspaces:
 
@@ -81,16 +82,26 @@ ucode configure --profiles DEFAULT --agents claude,codex --use-pat --skip-valida
 ucode configure mcp
 ```
 
-Add Databricks MCP servers to installed MCP-capable tools: Codex, Claude Code, Gemini CLI, OpenCode, and GitHub Copilot CLI.
+Add Databricks MCP servers to installed MCP-capable tools: Codex, Claude Code, Gemini CLI, OpenCode, GitHub Copilot CLI, and Cursor Agent.
 Options are shown in this order:
 
 - Discovered external MCP connections
 - Databricks SQL
 - Managed Databricks MCPs (Vector Search, UC Functions, etc.)
 - Custom MCP server URL
 
-Discovered external MCP connections are listed directly. MCP auth uses a Databricks token that
-`ucode` sets when launching each tool.
+Discovered external MCP connections are listed directly.
+
+Every Databricks MCP server is registered as a local **stdio** server that runs `ucode mcp-proxy`
+— a small bridge (shipped with `ucode`) between the coding tool and the Databricks
+streamable-HTTP MCP endpoint. The proxy mints a fresh OAuth token from your Databricks CLI profile
+on every request, so MCP auth is handled uniformly for every client and never expires mid-session.
+The coding tool starts and stops the proxy as a child process; there's nothing extra to run.
+
+**Cursor** is MCP-only: `cursor-agent` runs models on your own Cursor account, so `ucode`
+configures no models for it — it only registers Databricks MCP servers in `~/.cursor/mcp.json`
+(via the same proxy). Include it with `ucode configure --agents cursor` or pick it in
+`ucode configure mcp`, then launch with `ucode cursor`.
 
 To set up an agent and its MCP server(s) in one command, pass `--mcp` with fully-qualified
 service name(s) to `ucode configure`:
@@ -104,25 +115,32 @@ then registers the servers); pass a comma-separated list to register several at
 
 ### Skills (optional)
 
-Configure Unity Catalog Skills for your coding tools with `ucode configure skills`. It has two
-mutually-exclusive modes, both scoped by `--location <catalog>.<schema>` (comma-separated for
-multiple schemas):
+Configure Unity Catalog Skills for your coding tools with `ucode configure skills`:
 
 ```bash
-# Download mode (default): fetch every skill in the schema to disk.
+# Utility tools only: register the schema-less skills MCP connection, no download.
+ucode configure skills
+
+# Download mode: fetch every skill in the schema to disk (and register the connection).
 ucode configure skills --location main.default --path /abs/project/dir
 
 # MCP mode: expose the schema's skills as MCP tools instead of downloading.
 ucode configure skills --location main.default,ml.prod --mcp
 ```
 
-- **Download mode** writes each skill flat as `<leaf>/SKILL.md` (plus its bundled files) into both
-  `.claude/skills/` and `.agents/skills/`. `--path` (an existing absolute directory) is optional;
-  when omitted, skills are written under your home directory. Any pre-existing skill dir prompts
-  before it's overwritten. It then registers a schema-less skills MCP connection (utility tools
-  only), leaving any prior `--mcp` scope untouched.
-- **MCP mode** sets the connection's location set to exactly `<list>` (override-only) and rebuilds
-  its `?schema=` URL; no files are downloaded and `--path` is rejected.
+- **Bare command** (no `--location`) registers the schema-less skills MCP connection — the
+  cross-schema utility tools only — and downloads nothing. `--mcp` with no `--location` does the
+  same.
+- **Download mode** (with `--location`, no `--mcp`) writes each skill flat as `<leaf>/SKILL.md`
+  (plus its bundled files) into both `.claude/skills/` and `.agents/skills/`. `--path` (an existing
+  absolute directory) is optional; when omitted, skills are written under your home directory. Any
+  pre-existing skill dir prompts before it's overwritten. It then registers a schema-less skills
+  MCP connection, leaving any prior `--mcp` scope untouched.
+- **MCP mode** (`--location … --mcp`) sets the connection's location set to exactly `<list>`
+  (override-only) and rebuilds its `?schema=` URL; no files are downloaded and `--path` is rejected.
+
+Each run prints the registered server, its URL, the configured agents, and its tools, and reminds
+you to run `ucode <agent>` (existing agent sessions need a restart before the MCP tools load).
 
 ---
 
@@ -140,6 +158,7 @@ ucode configure skills --location main.default,ml.prod --mcp
 | `ucode configure --profiles DEFAULT --use-pat` | Authenticate with the profile's personal access token — no browser login |
 | `ucode configure --skip-validate` | Write configs without sending a test message through each agent |
 | `ucode configure --agents claude --mcp system.ai.slack` | Configure an agent and register its Databricks MCP server(s) in one command |
+| `ucode configure skills` | Register the skills MCP connection (utility tools only); no skills download |
 | `ucode configure skills --location main.default [--path <dir>]` | Download a schema's skills to disk (under `<dir>`, or your home dir) and register a schema-less skills MCP connection |
 | `ucode configure skills --location main.default --mcp` | Expose a schema's skills as MCP tools (override-only) instead of downloading |
 
@@ -155,6 +174,7 @@ ucode configure skills --location main.default,ml.prod --mcp
 | `~/.config/opencode/opencode.json` | OpenCode |
 | `~/.copilot/.env` | GitHub Copilot CLI |
 | `~/.pi/agent/models.json` | Pi |
+| `~/.cursor/mcp.json` | Cursor Agent (MCP servers only) |
 
 Existing files are backed up before being overwritten. `ucode revert` restores backups.
 

pyproject.toml

@@ -10,6 +10,10 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
   "databricks-sql-connector>=3.6.0",
+  # `ucode mcp-proxy` bridges a client's stdio MCP transport to a Databricks
+  # streamable-HTTP MCP endpoint, injecting a freshly-minted OAuth bearer per
+  # request. Uses the official MCP SDK's stdio server + streamable-HTTP client.
+  "mcp>=1.28.0",
   "questionary>=2.0.0",
   "tomlkit>=0.13.0",
   "typer>=0.12.0",

src/ucode/agents/__init__.py

@@ -52,6 +52,10 @@
 
 TOOL_SPECS: dict[str, ToolSpec] = {name: module.SPEC for name, module in _MODULES.items()}
 
+# Model-routing agents ucode configures end to end. Cursor is deliberately NOT
+# here: it runs models on the user's own Cursor account, so `normalize_tool`
+# rejects it and the model-config paths never see it. The `configure`/MCP flows
+# handle "cursor" separately as an MCP-only client (see MCP_ONLY_CLIENTS).
 TOOL_ALIASES = {
     "codex": "codex",
     "claude": "claude",
@@ -278,25 +282,27 @@ def resolve_launch_model(
 
 def resolve_provider_models(
     tool: str, state: dict, provider: str | None
-) -> tuple[dict | None, str | None]:
+) -> tuple[dict | None, str | None, bool]:
     """Validate ``provider`` for ``tool`` and return the model ids to pin.
 
-    Returns ``(provider_models, error)``. ``provider_models`` is a
+    Returns ``(provider_models, error, relayed)``. ``provider_models`` is a
     ``{family: model_id}`` dict for a Bedrock-backed claude service (whose
     provider-side ids must be pinned explicitly), or None for an Anthropic/
-    canonical service or when ``provider`` is None. A non-None ``error`` means
-    the provider is invalid for the tool (wrong type, missing, feature off, or a
-    Bedrock service with no Claude models) and the caller should not launch.
+    canonical service or when ``provider`` is None. ``relayed`` is True for a
+    credential-less Anthropic subscription relay, which the launch path wires
+    with the relayed overlay + refresh proxy. A non-None ``error`` means the
+    provider is invalid for the tool and the caller should not launch.
     """
     if not provider:
-        return None, None
+        return None, None, False
     token = get_databricks_token(state["workspace"], state.get("profile"))
     service, error = resolve_provider_service(tool, provider, state["workspace"], token)
     if error or service is None:
-        return None, error
+        return None, error, False
+    relayed = bool(service.get("relayed"))
     if service["provider_type"] in BEDROCK_PROVIDER_TYPES:
-        return map_bedrock_claude_models(service.get("targets") or []), None
-    return None, None
+        return map_bedrock_claude_models(service.get("targets") or []), None, relayed
+    return None, None, relayed
 
 
 def configure_tool(
@@ -305,6 +311,7 @@ def configure_tool(
     model: str | None = None,
     provider: str | None = None,
     provider_models: dict[str, str] | None = None,
+    relayed: bool = False,
 ) -> dict:
     result: dict | tuple[dict, str]
     if tool == "codex":
@@ -315,7 +322,7 @@ def configure_tool(
         if not model and not provider:
             raise RuntimeError(f"A {tool} model must be selected before configuration.")
         result = claude.write_tool_config(
-            state, model, provider=provider, provider_models=provider_models
+            state, model, provider=provider, provider_models=provider_models, relayed=relayed
         )
     else:
         # provider routing is claude/codex-only; every other tool needs a model.
@@ -405,10 +412,12 @@ def configure_single_tool(tool: str, state: dict) -> dict:
 def _configure_one(tool: str, state: dict, provider: str | None) -> dict:
     """Write one tool's config, routing through ``provider`` when set."""
     if provider:
-        provider_models, error = resolve_provider_models(tool, state, provider)
+        provider_models, error, relayed = resolve_provider_models(tool, state, provider)
         if error:
             raise RuntimeError(error)
-        return configure_tool(tool, state, None, provider=provider, provider_models=provider_models)
+        return configure_tool(
+            tool, state, None, provider=provider, provider_models=provider_models, relayed=relayed
+        )
     if tool == "codex":
         return configure_tool("codex", state)
     state, model = resolve_launch_model(tool, state, None)
@@ -477,6 +486,10 @@ def validate_tool(tool: str) -> tuple[bool, str]:
     spec = TOOL_SPECS[tool]
     binary = spec["binary"]
     module = _MODULES[tool]
+    # Some configs (e.g. claude relayed) can't be probed with a live message —
+    # the proxy + subscription login only exist at launch. Trust the written config.
+    if hasattr(module, "skip_validation") and module.skip_validation(load_state()):
+        return True, ""
     cmd = module.validate_cmd(binary)
     env = None
     if hasattr(module, "validate_env"):