Metadata-Version: 2.4
Name: wse-dev-mcp-client
Version: 0.1.0
Summary: Local stdio↔HTTP MCP proxy that talks to Iceberg Data's wse-dev MCP Cloud Run deploy. Auto-refreshes Google identity tokens via gcloud for transparent Cloud Run IAM auth — zero manual token juggling.
Project-URL: Homepage, https://pypi.org/project/wse-dev-mcp-client/
Project-URL: Issues, https://github.com/icebergdata-io/wse-dev-mcp-client/issues
Author-email: Iceberg Data <support@icebergdata.co>
License: MIT
License-File: LICENSE
Keywords: anthropic,claude,cloud-run,google-cloud,mcp,model-context-protocol,stdio-proxy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# wse-dev-mcp-client

**Local stdio ↔ HTTP MCP proxy for the Iceberg Data `wse-dev` MCP** deployed on Cloud Run.

This is the **client** side of a split MCP architecture. The server (with the real WSE-ops tools — Firestore queries, job debugging, test enqueue, etc.) runs on Cloud Run under IAM control; this tiny package runs on each developer's machine as a stdio MCP server and forwards every request to Cloud Run with an auto-refreshed Google identity token.

```
Claude Code (stdio) → wse-dev-mcp-client (local) → Cloud Run (HTTP + ID token)
                             │
                             └─ On each call: gcloud auth print-identity-token
                                              (cached 55 min; invisible refresh)
```

No tokens to paste. No wrapper scripts to rerun. Access is gated by Cloud Run IAM (`roles/run.invoker`) — if your Google identity has it, the proxy works; if not, Cloud Run returns 403.

## Prerequisites

- **Python 3.11+**
- **gcloud CLI** on your `PATH`, logged in with an identity that has `run.invoker` on the target MCP service.
  - One-time: `gcloud auth login`
- **Claude Code** (or any MCP-capable client)

## Install

With [pipx](https://pipx.pypa.io/) (recommended — keeps the proxy in its own isolated env):

```bash
pipx install wse-dev-mcp-client
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install wse-dev-mcp-client
```

Plain pip works too:

```bash
pip install --user wse-dev-mcp-client
```

## Register with Claude Code

```bash
claude mcp add wse-dev wse-dev-mcp-client \
  --scope user \
  -e WSE_DEV_MCP_URL=https://your-cloud-run-mcp-url
```

Replace `https://your-cloud-run-mcp-url` with the Cloud Run URL of **your** deployed MCP server. For Iceberg Data developers, ask a teammate or run:

```bash
gcloud run services describe wse-dev-mcp \
  --region=us-west1 --project=iceflow \
  --format='value(status.url)'
```

Verify with `claude mcp list` — you should see `wse-dev: ... ✓ Connected`.

## How it works

On each MCP call:

1. Claude Code writes a JSON-RPC message to the proxy's stdin.
2. The proxy consults its in-memory token cache (TTL 55 min). If expired or empty, it subprocesses `gcloud auth print-identity-token` to mint a fresh Google identity token.
3. The message is forwarded over HTTPS to the Cloud Run URL with `Authorization: Bearer <id-token>`.
4. Cloud Run IAM validates the token; if the caller has `roles/run.invoker` on the service, the MCP server handles the request and streams the response back.
5. The proxy pumps the response over stdout to Claude Code.

That's the whole package. ~150 lines of Python.

## Failure modes

| Symptom | Cause | Fix |
|---|---|---|
| `gcloud CLI not found` on startup | gcloud not on PATH | Install Google Cloud SDK and re-register |
| `gcloud identity-token fetch failed` | Not logged in | `gcloud auth login` |
| MCP calls return 403 | Your identity lacks `run.invoker` on the service | Ask the project admin to grant it |
| `WSE_DEV_MCP_URL env var not set` | Missing `-e` flag in `claude mcp add` | Re-register with the env var |

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `WSE_DEV_MCP_URL` | *(required)* | Base URL of the Cloud Run MCP, without trailing slash. The proxy appends `/mcp`. |

## Compatibility

- Python: 3.11, 3.12, 3.13, 3.14
- OS: Linux, macOS; Windows untested (should work with WSL)
- Claude Code: any version supporting stdio MCP transport (most recent clients)

## License

[MIT](./LICENSE). © 2026 Iceberg Data LLC.

## Related

- [Model Context Protocol](https://modelcontextprotocol.io)
- [Anthropic Claude Code](https://claude.com/claude-code)
- The server side lives in the private `agent-global-config` repo at `.agents/mcp-servers/wse-dev/`.
