8000 MCP server face: let AI agents drive the real browser by adeelahmad · Pull Request #10 · adeelahmad/Tether · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ body:
options:
- HTTP proxy
- WebDriver
- MCP (planned)
- MCP
- Remote UI (planned)
- Core / sessions
- Docs / tooling
12 changes: 11 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`--token` or `--insecure-allow-public`, bearer/basic token auth, a
loopback Host/Origin guard against DNS rebinding, a per-session domain
allowlist policy seam, and log redaction of tokens and cookies.
- MCP and remote-browser UI faces as documented stubs on the shared core.
- MCP server face at `/mcp` (Streamable HTTP; MCP 2025-06-18, 2025-03-26 and
2024-11-05) with 16 browser tools: tabs, navigation, accessibility-style
snapshots with stable element refs, click, type, keys, select, scroll,
wait, JavaScript, screenshots and in-tab `fetch()` with the user's cookies.
Shares tabs, auth, the loopback guard and `--allow-domains` with the other
faces; `--mcp=false` turns it off. See `docs/MCP.md`.
- `tether mcp`: a stdio bridge for MCP clients that don't speak HTTP
(Claude Desktop, IDEs), local or across a tailnet.
- Remote-browser UI face as a documented stub on the shared core.
- Screenshots of idle background tabs no longer hang: Tether brings the tab
to the front and retries, as ChromeDriver does (WebDriver and MCP).
- Sprint Zero: Makefile, golangci-lint, CI (lint → test + coverage →
build matrix → govulncheck), CodeQL, Dependabot, GoReleaser (archives,
checksums, multi-arch Docker image, Homebrew cask), community docs.
Expand Down
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ Read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) first. In short:
| `internal/core` | The engine every face calls: `Do`, `Eval`, `Navigate`, `Policy` |
| `internal/proxy` | HTTP/HTTPS forward-proxy face |
| `internal/webdriver` | W3C WebDriver face |
| `internal/mcp`, `internal/remote` | Planned faces (stubs) |
| `internal/mcp` | MCP face and stdio bridge |
| `internal/remote` | Planned face (stub) |
| `internal/server`, `internal/api` | Listener, auth, guard, control API |

Faces stay thin. If a change needs browser logic, it almost certainly
Expand Down
32 changes: 25 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
### Your logged-in Chrome — as a proxy, from anywhere. No extension.

**Give your AI agent (or your script, or your other laptop) your real, logged-in browser.**<br/>
One self-contained binary. Speaks plain HTTP proxy and WebDriver. Drives Chrome over the DevTools Protocol.
One self-contained binary. Speaks MCP, plain HTTP proxy and WebDriver. Drives Chrome over the DevTools Protocol.

[![CI](https://github.com/adeelahmad/tether/actions/workflows/ci.yml/badge.svg)](https://github.com/adeelahmad/tether/actions/workflows/ci.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/adeelahmad/tether)](https://goreportcard.com/report/github.com/adeelahmad/tether)
Expand All @@ -31,9 +31,12 @@ Chrome already speaks, and turns each tab into something any client can use:
storage, real JavaScript. You get the rendered page back.
- 🤖 **A WebDriver endpoint.** Point Selenium at it and most scripts just
work — against your actual signed-in profile.
- 🧩 **One core, four faces.** The proxy and WebDriver ship today; an MCP
server for agents and a live remote-browser UI are designed in and
stubbed ([architecture](docs/ARCHITECTURE.md)).
- 🧠 **An MCP server for agents.** Claude, Cursor or your own agent get
tools to read, click, type, screenshot and fetch in your real browser
([docs/MCP.md](docs/MCP.md)).
- 🧩 **One core, four faces.** Proxy, WebDriver and MCP ship today on the
same tab sessions; a live remote-browser UI is designed in and stubbed
([architecture](docs/ARCHITECTURE.md)).
- 🔒 **Safe by default.** Loopback-only unless you set a token. Built to sit
on a private [Tailscale](https://tailscale.com) tailnet, not the internet.

Expand Down Expand Up @@ -73,8 +76,9 @@ screen for everyone else. 🎉

```mermaid
flowchart LR
A["curl / requests / agent"] -- "HTTP proxy" --> T
A["curl / requests"] -- "HTTP proxy" --> T
B["Selenium"] -- "WebDriver" --> T
D["AI agent"] -- "MCP" --> T
T["tether serve<br/>sessions · policy · auth"] -- "DevTools Protocol" --> C
subgraph C["Your Chrome (logged in)"]
T1["tab: github.com"]
Expand Down Expand Up @@ -126,6 +130,19 @@ Responses carry `X-Tether-Tab-ID`, `X-Tether-Final-URL` (after redirects)
and, on errors, a stable `X-Tether-Error` code (`tab_gone`, `forbidden`,
`navigation_failed`, `timeout`, …).

### MCP (AI agents)

```sh
claude mcp add --transport http tether http://127.0.0.1:8787/mcp
```

Then ask: *"Open my GitHub notifications and summarise what needs me."* The
agent gets `browser_navigate`, `browser_snapshot`, `browser_click`,
`browser_type`, `browser_screenshot`, `browser_fetch` and more, all in your
signed-in Chrome. Claude Desktop and other stdio clients use the bundled
bridge (`"command": "tether", "args": ["mcp"]`). Setup for every client,
the full tool list and the security notes: [docs/MCP.md](docs/MCP.md).

### WebDriver

```python
Expand Down Expand Up @@ -201,6 +218,7 @@ Every flag has a `TETHER_*` environment variable; flags win.
| `--policy-file` | — | JSON file with per-token rules and tokens — see [docs/POLICIES.md](docs/POLICIES.md) |
| `--data-dir` | user config dir | Local CA and launched profile |
| `--no-mitm` | `false` | Refuse HTTPS `CONNECT` instead of intercepting |
| `--mcp` | `true` | Serve the MCP face at `/mcp` |
| `--log-level`, `--log-format` | `info`, `text` | `json` for machines; secrets are always redacted |

Docker (headless Chromium inside the image):
Expand All @@ -220,7 +238,7 @@ local CA, and it only drives Chromium-family browsers.
| Needs a browser extension | **No** | Yes | No | No |
| Plain HTTP proxy (curl, any language) | ✅ | ❌ | Rarely | ❌ |
| W3C WebDriver / Selenium | ✅ incl. frames, alerts, windows, uploads, PDF | ❌ | Often | ✅ |
| MCP for agents | Planned | Often | Often | Via wrappers |
| MCP for agents | ✅ | Often | Often | Via wrappers |
| Runs entirely on your machine | ✅ | ✅ | ❌ | ✅ |
| Remote access | Tailscale + token | Usually local only | ✅ | DIY |
| Single static binary | ✅ | ❌ | n/a | ❌ (driver + runtime) |
Expand All @@ -231,7 +249,7 @@ local CA, and it only drives Chromium-family browsers.
- [x] Tab-session core, HTTP/HTTPS proxy, WebDriver common set, control API
- [x] WebDriver Actions: hover, drag and drop, key chords, wheel, multi-touch
- [x] Safe-by-default exposure, token auth, domain allowlist seam
- [ ] MCP server face (tools over the same core) — stubbed at `/mcp`
- [x] MCP server face: 16 browser tools over the same core, plus a stdio bridge
- [ ] Remote-browser UI with live screencast and input — stubbed at `/remote`
- [x] Per-token and per-session domain policies, enforced in the browser ([docs/POLICIES.md](docs/POLICIES.md))
- [x] Per-tab console and browser log capture (control API + WebDriver `get_log`)
Expand Down
3 changes: 2 additions & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,10 @@ a sandbox against a determined attacker who also shares the browser profile
| Token leaks via logs | Redacting log handler; secrets never logged | Tokens passed on the command line are visible in `ps`; prefer `TETHER_TOKEN` or `--token-file`. |
| Token leaks via `curl -x http://user:token@…` history | — | Shell history; prefer `--proxy-header "Proxy-Authorization: Bearer $TETHER_TOKEN"`. |
| Local CA key theft | Key written `0600` in the per-user config dir | Anyone with your user account already has your browser. Only trust the CA in clients that use Tether; don't add it to your OS trust store unless you understand the implication. |
| An agent/script navigates somewhere it shouldn't | Global, per-token and per-tab rules, checked in the core and enforced in the browser for top-level navigations (including redirects, clicks and script) | Subresources and `fetch()` from page script are not restricted; give agents `"scripts": false`. |
| An agent/script navigates somewhere it shouldn't | Global, per-token and per-tab rules, checked in the core and enforced in the browser for top-level navigations (including redirects, clicks and script); MCP tools also check the page's current URL before reading or acting on it | Subresources and `fetch()` from page script are not restricted; give agents `"scripts": false`. |
| One agent reads or steers another agent's tab | Per-token ownership: non-admin tokens only resolve their own tabs, including via cookie, header and WebDriver session ID | Admin tokens see everything by design. |
| Tether used to read a page the user has open | Only tabs Tether opened, or tabs explicitly addressed by ID, are driven; adopting requires an admin token | Any admin token can address any tab by ID. |
| Prompt injection: a web page steers an AI agent connected over MCP | Server instructions tell the model page content is untrusted; tool annotations mark destructive tools; `--allow-domains` bounds where it can go; password values and `Set-Cookie` are never returned | An agent with access to your browser can be talked into acting as you. Use an allowlist and a client that confirms destructive tool calls. See [docs/MCP.md](docs/MCP.md#security). |
| Chrome DevTools port exposed | `--launch` binds it to loopback; Tether never re-exposes it | If you start Chrome yourself with `--remote-debugging-address=0.0.0.0`, that is outside Tether's control. |
| A client attaches local files to a page (WebDriver file inputs) | Clients are fully trusted (see above); remote uploads land in a per-session temp dir deleted when the session ends | A token holder can make a page upload any file the Tether user can read. |
| Automation rearranges the person's screen | Window resize/maximise/minimise/fullscreen only act on windows holding nothing but Tether tabs | — |
Expand Down
51 changes: 49 additions & 2 deletions cmd/tether/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,22 @@ import (
"io"
"os"
"os/signal"
"strings"
"syscall"

"github.com/adeelahmad/tether/internal/app"
"github.com/adeelahmad/tether/internal/certs"
"github.com/adeelahmad/tether/internal/config"
"github.com/adeelahmad/tether/internal/logx"
"github.com/adeelahmad/tether/internal/mcp"
"github.com/adeelahmad/tether/internal/version"
)

const usage = `tether — your logged-in Chrome, as a proxy, from anywhere. No extension.

Usage:
tether serve [flags] start the proxy + WebDriver server
tether serve [flags] start the proxy, WebDriver and MCP server
tether mcp [flags] bridge a stdio MCP client (Claude Desktop, IDEs) to a running Tether
tether ca [--data-dir] print the local CA certificate path (trust it for HTTPS)
tether version print version information

Expand All @@ -47,6 +50,8 @@ func run(args []string, stdout, stderr io.Writer) int {
return 0
case "ca":
return ca(args[1:], stdout, stderr)
case "mcp":
return mcpBridge(args[1:], os.Stdin, stdout, stderr)
case "help", "-h", "--help":
fmt.Fprint(stdout, usage)
return 0
Expand Down Expand Up @@ -87,7 +92,11 @@ func serve(args []string, stdout, stderr io.Writer) int {
)
fmt.Fprintf(stdout, "\n Tether %s is serving %s on http://%s\n", version.Version, a.Browser, a.Addr)
fmt.Fprintf(stdout, " Proxy: curl -x http://%s --cacert <(curl -s http://%s/tether/v1/ca.pem) https://example.com\n", a.Addr, a.Addr)
fmt.Fprintf(stdout, " WebDriver: http://%s (Selenium remote URL)\n\n", a.Addr)
fmt.Fprintf(stdout, " WebDriver: http://%s (Selenium remote URL)\n", a.Addr)
if cfg.MCP {
fmt.Fprintf(stdout, " MCP: http://%s/mcp (claude mcp add --transport http tether http://%s/mcp)\n", a.Addr, a.Addr)
}
fmt.Fprintln(stdout)

if err := a.Serve(ctx); err != nil {
log.Error("server stopped", "err", err)
Expand Down Expand Up @@ -118,3 +127,41 @@ func ca(args []string, stdout, stderr io.Writer) int {
fmt.Fprintln(stdout, certs.CertPath(*dir))
return 0
}

// mcpBridge runs `tether mcp`: stdio on one side, Tether's /mcp endpoint on
// the other. stdout carries protocol messages only; diagnostics go to stderr.
func mcpBridge(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
fs := flag.NewFlagSet("tether mcp", flag.ContinueOnError)
fs.SetOutput(stderr)
env := func(k, def string) string {
if v, ok := os.LookupEnv(k); ok {
return v
}
return def
}
url := fs.String("url", env("TETHER_MCP_URL", "http://"+config.DefaultAddr+mcp.Prefix), "Tether MCP endpoint [$TETHER_MCP_URL]")
token := fs.String("token", env("TETHER_TOKEN", ""), "Tether bearer token [$TETHER_TOKEN]")
tokenFile := fs.String("token-file", env("TETHER_TOKEN_FILE", ""), "read the bearer token from this file [$TETHER_TOKEN_FILE]")
if err := fs.Parse(args); err != nil {
if errors.Is(err, flag.ErrHelp) {
return 0
}
return 2
}
if *tokenFile != "" && *token == "" {
b, err := os.ReadFile(*tokenFile)
if err != nil {
fmt.Fprintln(stderr, "tether:", err)
return 2
}
*token = strings.TrimSpace(string(b))
}
log, _ := logx.New(stderr, "warn", "text")
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := mcp.Bridge(ctx, mcp.BridgeOptions{URL: *url, Token: *token, Logger: log}, stdin, stdout); err != nil {
fmt.Fprintln(stderr, "tether mcp:", err)
return 1
}
return 0
}
3 changes: 3 additions & 0 deletions cmd/tether/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@ func TestRun(t *testing.T) {
{[]string{"bogus"}, 2, "", "unknown command"},
{[]string{"serve", "--token", "short"}, 2, "", "at least 16"},
{[]string{"serve", "-h"}, 0, "", "-insecure-allow-public"},
{[]string{"serve", "-h"}, 0, "", "-mcp"},
{[]string{"mcp", "-h"}, 0, "", "TETHER_MCP_URL"},
{[]string{"mcp", "--token-file", "/nonexistent/token"}, 2, "", "tether: open"},
{[]string{"serve", "--addr", "0.0.0.0:0", "--chrome", "127.0.0.1:1"}, 1, "", "refusing to listen"},
}
for _, tt := range tests {
Expand Down
11 changes: 6 additions & 5 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ flowchart LR
G[auth · loopback guard · recover]
P[Proxy face<br/>HTTP + CONNECT/MITM]
W[WebDriver face<br/>W3C common set]
M[MCP face<br/><i>stub</i>]
M[MCP face<br/>Streamable HTTP tools]
R[Remote UI face<br/><i>stub</i>]
A[Control API<br/>/tether/v1]
subgraph core[core]
Expand All @@ -35,7 +35,7 @@ flowchart LR

C1 --> G --> P
C2 --> G --> W
C3 -.-> G -.-> M
C3 --> G --> M
C4 -.-> G -.-> R
G --> A
P & W & M & R & A --> E
Expand All @@ -50,7 +50,7 @@ flowchart LR

| Package | Role |
|---|---|
| `cmd/tether` | CLI: `serve`, `ca`, `version`. Parses config, wires logging and signals. |
| `cmd/tether` | CLI: `serve`, `mcp` (stdio bridge), `ca`, `version`. Parses config, wires logging and signals. |
| `internal/app` | Assembles a running Tether from a `Config`: Chrome, core, faces, server. Used by the CLI and the integration tests. |
| `internal/cdp` | The only package that speaks CDP. `Browser` and `Tab` interfaces; `Chrome` implementation over a single flattened websocket; endpoint discovery and `Launch`. `cdptest` holds fakes. |
| `internal/session` | `Session` = one page target. `Manager` resolves requests to sessions, opens/adopts/closes tabs, reaps idle ones, and serialises work per tab. |
Expand All @@ -60,7 +60,8 @@ flowchart LR
| `internal/webdriver` | W3C WebDriver face (see [WEBDRIVER.md](WEBDRIVER.md)). |
| `internal/api` | Control plane: health, whoami, tabs, tab policies, eval, CA download. |
| `internal/server` | Listener, routing, per-token auth, loopback guard, graceful shutdown, exposure checks. |
| `internal/mcp`, `internal/remote` | Planned faces, mounted and answering `501` today. |
| `internal/mcp` | MCP face: Streamable HTTP transport, per-agent sessions, browser tools, and the stdio bridge (see [MCP.md](MCP.md)). |
| `internal/remote` | Planned face, mounted and answering `501` today. |
| `internal/certs`, `internal/logx`, `internal/config`, `internal/version`, `internal/httpx` | Supporting pieces. |

## The session model
Expand Down Expand Up @@ -148,7 +149,7 @@ proxy auth and Tether control headers never reach the page.
|---|---|---|
| HTTP proxy | **Shipping** | `Sessions.Resolve`, `Core.Do` |
| WebDriver | **Shipping** | `Sessions.Create/Get/Close`, `Core.Navigate`, `cdp.Tab` primitives |
| MCP server | Stub (`/mcp` → 501) | Will map tools (`navigate`, `read_page`, `click`, `type`, `eval`, `screenshot`, `tabs`) onto the same calls. Each agent authenticates with its own token, so per-token policies and tab ownership apply unchanged. Streamable HTTP transport on the same listener, so it inherits auth and Tailscale exposure. |
| MCP server | **Shipping** | `Sessions.Create/Get/Close`, `Core.Navigate`, `Core.Eval`, `Core.Do` (fetch mode), `core.Policy`, `cdp.Tab` primitives. Streamable HTTP on the same listener, so it inherits auth and Tailscale exposure. Each MCP session tracks one current tab and the tabs it opened; `core.Policy` is checked against the page's current URL before every page tool. Each agent authenticates with its own token, so per-token policies and tab ownership apply unchanged. |
| Remote UI | Stub (`/remote` → 501) | Will stream a tab with `Page.startScreencast` (WebRTC later) and forward input through `cdp.Tab.Click`/`Key`, letting a person watch or take over exactly the tab an agent is driving. |

Every face implements `core.Face` (`Name()` + `http.Handler`) and is mounted
Expand Down
Loading
Loading
0