# Banana Peel MCP — OpenRouter for browser agents
# @banana-peel/mcp

Official [Model Context Protocol](https://modelcontextprotocol.io) server for [Banana Peel](https://bananapeel.com).

Coding agents call Banana Peel as native MCP tools instead of hand-rolling `curl`.

Docs: https://bananapeel.com/docs/mcp

**Vocabulary:** `routing` is what you request; `banana_peel.runner` is the **runner** that executed.

## One-line install

```bash
npx -y @banana-peel/mcp
```

Also: `npm install -g @banana-peel/mcp` (runs as `bananapeel-mcp`).

### Publish (maintainers)

```bash
# requires npm login with rights to @banana-peel (and bare bananapeel for the alias)
cd mcp && npm publish --access public
cd alias && npm publish --access public   # after @banana-peel/mcp is live
```

## Auth

```bash
export BANANA_PEEL_API_KEY=bp_live_…   # or BANANAPEEL_API_KEY
export BANANA_PEEL_BASE=https://bananapeel.com  # optional
```

## Cursor

`~/.cursor/mcp.json` (or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "bananapeel": {
      "command": "npx",
      "args": ["-y", "@banana-peel/mcp"],
      "env": {
        "BANANA_PEEL_API_KEY": "bp_live_…"
      }
    }
  }
}
```

## Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bananapeel": {
      "command": "npx",
      "args": ["-y", "@banana-peel/mcp"],
      "env": {
        "BANANA_PEEL_API_KEY": "bp_live_…"
      }
    }
  }
}
```

## Tools

| Tool | API |
| --- | --- |
| `create_response` | `POST /api/v1/responses` (optional **Output normalization**: `normalize` + `output_schema`, +$0.10 / run) |
| `get_response` | `GET /api/v1/responses/:id` (optional poll until terminal / `requires_action`) |
| `submit_input` | `POST /api/v1/responses/:id/input` (MFA/OTP/text) |
| `cancel_response` | `POST /api/v1/responses/:id/cancel` (stop an in-flight run) |
| `list_runs` | `GET /api/v1/runs` |
| `list_rankings` | `GET /api/v1/rankings` |
| `list_capabilities` | `GET /api/v1/capabilities` |

Tool names and HTTP mapping are defined in `src/tool-catalog.ts` (the MCP server registry).

### Output normalization (+$0.10)

Pass `normalize: true` with `output_schema` (JSON Schema or property map) on `create_response` to reshape the runner result after the run. Flat +$0.10 on that run. Schema builder: Console → Normalize (`/normalize`).

## Develop from this repo

```bash
npm install
npm run build
npm start
# or: npm run dev
```

## MFA flow

1. `create_response` with `background: true`
2. `get_response` with `wait: true` until `status: "requires_action"`
3. `submit_input` with `{ "code": "123456" }` or `{ "answer": "…" }`
4. `get_response` with `wait: true` until `completed` / `failed`