# Webget MCP

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **Increff Webget** — the internal SQL/MongoDB query portal at `saas.increff.com/webget`.

It lets AI coding agents (Claude Code, opencode, Cursor, Windsurf, etc.) run database queries through Webget **directly via natural language**, with no manual website clicking, no copy-pasting results, and no UI automation fragility.

```
You:     "Run this on meeshopackagingcenter: SELECT warehouse_id FROM wms.wms_wms_order WHERE order_id = 43486094"
Agent:   queries Webget through this MCP server → returns the row in chat
```

## Why this exists

| | Webget website (manual) | webget-mcp |
|---|---|---|
| One query | open browser → pick server from 150+ dropdown → type SQL → click Run | say the query |
| Time per query | ~15–30 s of clicking | ~0.6 s |
| Results | rendered HTML table, agent must scrape | clean TSV/JSON text |
| Auth | re-login when session expires | one Google login, then automatic forever |

## How it works (30-second version)

1. The first time a tool is called, the server opens a Chrome window with a **dedicated persistent profile** (`~/.webget-mcp/chrome-profile`) on the Webget login page.
2. You log in with Google **once** in that window. The profile remembers the session.
3. The server harvests the `__Secure_Id_Token_Ref` session cookie and stores it in `~/.webget-mcp/auth.json`.
4. Every query after that is a plain HTTPS call — fast, headless, no browser involvement.
5. If the session cookie ever expires, the server silently re-issues it via the login endpoint (the Chrome profile still has your Google session). Only if the Google session itself dies does the login window appear again — log in once more, done for months.

No passwords or tokens are ever typed into the agent or stored in a repo. Everything lives in your home directory.

## Tools provided

| Tool | What it does |
|---|---|
| `list_databases` | List database servers you can access, with `dbId` and type (MYSQL/MONGODB) |
| `get_schemas` | List schemas (MySQL) or databases (MongoDB) on a server |
| `get_tables` | List tables→columns (MySQL) or collections→fields (MongoDB) in a schema |
| `run_query` | Execute a SQL or MongoDB query, returns TSV / JSON text |
| `login` | Manually trigger the browser login flow (rarely needed — automatic on first call) |

## Prerequisites

- **Node.js 18 or newer** — check with `node --version` (install from [nodejs.org](https://nodejs.org) if missing)
- **Google Chrome** installed at the default location:
  - macOS: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
  - Linux/Windows: set the `WEBGET_CHROME_PATH` environment variable (see below)
- A browser login to Webget that works (i.e. you are authorized on the Webget portal)

## Setup

### 1. Get the code

```bash
git clone <your-repo-url> webget-mcp
cd webget-mcp
npm install
npm run build
```

After the build there is a `build/` folder — that is the compiled server. Verify it starts:

```bash
node build/index.js
```

It prints nothing and waits — that is correct, it speaks MCP over stdin/stdout. Press `Ctrl+C` to stop.

> **Windows note:** run all commands in PowerShell or Git Bash. Replace `node build/index.js` paths with the absolute path, e.g. `C:\Users\you\webget-mcp\build\index.js`, in the configs below.

### 2. Add to your MCP client

Pick the section for your tool. Use the **absolute path** to wherever you cloned the repo.

---

#### Claude Code

```bash
claude mcp add webget -- node /absolute/path/to/webget-mcp/build/index.js
```

Or edit `~/.claude.json` → `"mcpServers"`:

```json
{
  "mcpServers": {
    "webget": {
      "command": "node",
      "args": ["/absolute/path/to/webget-mcp/build/index.js"]
    }
  }
}
```

---

#### opencode

Edit `~/.config/opencode/opencode.json` (or `opencode.jsonc`), add under `"mcp"`:

```json
{
  "mcp": {
    "webget": {
      "type": "local",
      "command": ["node", "/absolute/path/to/webget-mcp/build/index.js"],
      "enabled": true
    }
  }
}
```

---

#### Cursor

Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):

```json
{
  "mcpServers": {
    "webget": {
      "command": "node",
      "args": ["/absolute/path/to/webget-mcp/build/index.js"]
    }
  }
}
```

---

#### Generic MCP config (Windsurf, VS Code extensions, etc.)

Any client that supports **stdio** MCP servers:

```json
{
  "mcpServers": {
    "webget": {
      "command": "node",
      "args": ["/absolute/path/to/webget-mcp/build/index.js"]
    }
  }
}
```

---

### 3. First run — the one-time login

1. Restart your MCP client (Claude Code / opencode / Cursor) so it loads the server.
2. Ask the agent anything that needs the DB, e.g. *"list my webget databases"*.
3. A **Chrome window opens** on the Webget login page. Log in with Google.
4. The window closes itself within a few seconds. Done.
5. Ask: *"run SELECT 1 on meeshopackagingcenter"* — you should get a result in the chat.

From now on the login window only reappears if your Google session fully expires.

## Environment variables (optional)

| Variable | Default | Purpose |
|---|---|---|
| `WEBGET_BASE_URL` | `https://saas.increff.com/webget/in/api` | Webget API base URL (change for staging environments) |
| `WEBGET_CHROME_PATH` | macOS default Chrome path | Chrome binary location on Linux/Windows |

Example with env vars in Claude Code:

```bash
claude mcp add webget -e WEBGET_CHROME_PATH=/usr/bin/google-chrome -- node /absolute/path/to/webget-mcp/build/index.js
```

## Usage examples

Ask your agent:

- *"List my webget databases"*
- *"What schemas are on meeshopackagingcenter?"* (or the dbId)
- *"Show me the tables in the wms schema of meeshopackagingcenter"*
- *"Run on meeshopackagingcenter: SELECT channel_order_id FROM wms.wms_wms_order WHERE order_id = 43486094"*

MongoDB servers work the same way:

- *"Run on services-prod-mongodb: db.orders.find({status: 'PENDING'}).limit(5)"*

## Troubleshooting

**"Authorization cancelled or failed" / login window never appears**
The server could not launch Chrome. Check the Chrome path; on non-macOS set `WEBGET_CHROME_PATH`.

**Queries suddenly return auth errors**
The stored cookie expired and silent re-login failed. Just retry the tool call — it re-harvests automatically. If it keeps failing, run the `login` tool once.

**"Timed out waiting for Webget login"**
You had 10 minutes to log in and the window was left idle. Retry the call, log in when the window opens.

**Port 9222 already in use**
Another program uses the debugging port. Stop it, or nothing breaks — the server attaches to the existing Chrome if compatible.

**Want a clean slate**
```bash
rm -rf ~/.webget-mcp
```
Deletes the saved cookie AND the Chrome profile. Next call = fresh login flow.

## Security notes

- Your session cookie is stored **only** in `~/.webget-mcp/auth.json` on your machine — never in a repo, never sent anywhere except `saas.increff.com`.
- All queries go through Webget's server-side authorization: you can only reach databases your account already has access to. This MCP adds no privileges.
- Queries are logged by Webget exactly as if you ran them in the website (same audit trail).

## Uninstall

Remove the MCP entry from your client config, then:

```bash
rm -rf ~/webget-mcp ~/.webget-mcp
```

## Development

```bash
npm install
npm run build     # compile TypeScript → build/
npm run dev       # watch mode
```

Source layout:

```
src/
  index.ts            # MCP server entry (stdio)
  auth.ts             # login flow + cookie harvest + persistence
  client.ts           # axios client, auth retry logic
  config.ts          # (reserved)
  tools/
    index.ts          # tool definitions + dispatch
    dbTools.ts        # list_databases, get_schemas, get_tables
    queryTools.ts     # run_query
```

## License

MIT