# Getir WebMCP

An injectable JavaScript script that gives AI agents the ability to shop on [Getir](https://getir.com) using the [WebMCP](https://github.com/webmachinelearning/webmcp) browser API.

WebMCP (Web Model Context Protocol) is a proposed W3C standard that lets websites expose structured, callable tools to AI agents directly through the browser. This project demonstrates how you can **inject WebMCP tools into any existing website** — even ones that don't natively support it.

## What It Does

The script registers **10 tools** on `navigator.modelContext` that let an AI agent:

- Search for products
- Browse results
- Add items to cart
- Manage the basket
- Proceed to checkout and payment

All interactions happen through DOM manipulation — no API tokens or authentication needed.

## Tools

### Search & Browse

| Tool | Parameters | Description |
|------|-----------|-------------|
| `getir_search` | `keyword` (string) | Types a keyword into the search bar and returns matching products |
| `getir_list_results` | — | Returns currently visible search results without re-searching |
| `getir_view_product` | `index` (number) | Opens the detail view for a product |
| `getir_clear_search` | — | Clears the search bar |

### Cart

| Tool | Parameters | Description |
|------|-----------|-------------|
| `getir_add_to_cart` | `index` (number), `quantity`? (number) | Adds a product to cart from search results |
| `getir_open_basket` | — | Opens the basket panel and lists all items |
| `getir_list_basket` | — | Returns items in the already-open basket panel |
| `getir_basket_update` | `index` (number), `action` ("increase" / "decrease"), `times`? (number) | Changes quantity of a basket item |

### Checkout

| Tool | Parameters | Description |
|------|-----------|-------------|
| `getir_go_to_checkout` | — | Clicks "Sepete git" to navigate to `/sepet/` |
| `getir_proceed_to_payment` | — | Clicks "Odemeye Gec" on the basket page |

## Prerequisites

- **Chrome 146+** (Canary or Dev channel)
- **Experimental Web Platform Features** flag enabled:
  1. Open `chrome://flags`
  2. Search for "Experimental Web Platform Features"
  3. Set to **Enabled**
  4. Restart Chrome

## Usage

1. Go to [getir.com](https://getir.com) and log in to your account
2. Open Chrome DevTools (`Cmd+Option+I` / `F12`)
3. Go to the **Console** tab
4. Copy the contents of [`getir-webmcp-inject.js`](./getir-webmcp-inject.js) and paste it into the console
5. Press Enter

You should see:

```
[WebMCP] Injecting Getir tools...
[WebMCP] Registered 10 Getir tools: getir_search, getir_list_results, ...
```

The tools are now available for any AI agent that supports WebMCP.

### Verifying with the Inspector Extension

Install the [Model Context Tool Inspector](https://chromewebstore.google.com/detail/model-context-tool-inspec/gbpdfapgefenggkahomfgkhfehlcenpd) Chrome extension to visually inspect and test your registered WebMCP tools. After injecting the script, open the extension to see all 10 tools listed with their schemas — you can invoke them directly from the inspector panel to verify they work before connecting an AI agent.

## Example Agent Flow

```
Agent: getir_search({ keyword: "su" })
  → Found 20 products: [0] Erikli Su 1.5L — 24,50 TL ...

Agent: getir_add_to_cart({ index: 0, quantity: 2 })
  → Added 2x "Erikli Su 1.5L" (24,50 TL) to cart.

Agent: getir_open_basket()
  → Basket opened (1 item, total: 49,00 TL): [0] Erikli Su — 2 — 49,00 TL

Agent: getir_go_to_checkout()
  → Navigated to basket page (/sepet/). Total: 49,00 TL.

Agent: getir_proceed_to_payment()
  → Clicked "Odemeye Gec". Navigated to payment page.
```

## How It Works

### DOM-Based Approach

Instead of intercepting API calls (which would require managing auth tokens), the script interacts entirely through the DOM — the same way a user would. It:

- Sets input values using React-compatible `setNativeValue()` to bypass React's synthetic event system
- Clicks buttons using native `.click()` calls
- Reads product data by parsing rendered DOM elements

### SPA Navigation Handling

Getir is a React single-page application. Page "navigations" are client-side route changes, meaning:

- The JS context (and registered tools) **survive** across page transitions
- But the DOM updates asynchronously after route changes

The script uses two strategies to handle this:

- **`waitForElement(selector)`** — Uses `MutationObserver` to wait until a specific element appears in the DOM
- **`waitForNavigation()`** — Watches DOM mutations and resolves once the page is stable for 800ms, indicating React has finished rendering

This is more reliable than fixed `sleep()` delays because it adapts to actual network and render conditions.

### WebMCP Spec Notes

Per the [WebMCP proposal](https://github.com/webmachinelearning/webmcp/blob/main/docs/proposal.md):

- Tools registered via `registerTool()` persist for the lifetime of the page
- For SPAs, `provideContext()` can be called multiple times — "useful for single-page web apps that frequently change UI state"
- A `.well-known/webmcp` manifest for pre-navigation tool discovery is being discussed for future spec versions

## Try WebMCP Locally (Demo Page)

The repo includes [`index.html`](./index.html) — a standalone demo page with 7 pre-registered WebMCP tools (counter, todo list, greeting form, note creator) that you can use to learn the API without injecting anything.

### Quick Start

1. Open `index.html` in Chrome 146+ (with Experimental Web Platform Features enabled)
2. Install the [Model Context Tool Inspector](https://chromewebstore.google.com/detail/model-context-tool-inspec/gbpdfapgefenggkahomfgkhfehlcenpd) extension
3. Enter your **Gemini API key** in the extension settings
4. Open the extension — you'll see all registered tools listed
5. Ask the AI to interact with the page (e.g. "set the counter to 42" or "add a todo for buying groceries")

This is the easiest way to see WebMCP in action before trying the Getir injection.

## Project Structure

```
getir-webmcp-inject.js   # The injectable script (paste into DevTools console on getir.com)
index.html               # Standalone WebMCP demo page with built-in tools
```

## Limitations

- **Class selectors may break** — Getir uses CSS-in-JS (styled-components) with hashed class names like `.sc-47015d0-6`. These can change across deployments. If tools stop finding elements, the selectors need updating.
- **Single tab only** — Tools are registered in the page context of one tab. Opening a new tab requires re-injection.
- **No full-page navigations** — If Getir does a hard page reload (not SPA navigation), the injected tools are lost and must be re-injected.
- **Getir account required** — You must be logged in for cart and checkout functionality to work.

## Disclaimer

This is an **experimental proof-of-concept** for testing WebMCP capabilities. It is not affiliated with or endorsed by Getir. Use responsibly and in accordance with Getir's terms of service.

## References

- [WebMCP Spec (W3C Web ML Community Group)](https://github.com/webmachinelearning/webmcp)
- [WebMCP Proposal](https://github.com/webmachinelearning/webmcp/blob/main/docs/proposal.md)
- [Chrome 146 WebMCP Announcement](https://venturebeat.com/infrastructure/google-chrome-ships-webmcp-in-early-preview-turning-every-website-into-a)

## License

MIT