sncro-relay

Open-source components of sncro — the MCP relay, the browser-side agent, and the framework plugins that let AI coding assistants inspect a live browser.

What this repo contains

Path	What
`relay/`	FastAPI app that exposes an MCP server plus long-poll endpoints for agent.js
`relay/static/agent.js`	Browser-side script injected by the middleware; pushes console + DOM data to the relay
`middleware/sncro_middleware.py`	FastAPI / Starlette plugin — drop-in middleware for FastAPI apps
`middleware/sncro_flask.py`	Flask plugin — drop-in middleware for Flask apps
`trysncro/`	`try.sncro.net` — a deliberately-broken demo app for exercising sncro end-to-end

How it works

Code

 ┌──────────────┐    MCP     ┌──────────┐   long-poll   ┌─────────────┐
 │ Claude Code  │──tools────▶│  relay   │◀──────────────│  agent.js   │
 │ (or other    │            │ (relay/) │   snapshots   │ (injected   │
 │  MCP client) │◀──results──│          │──────────────▶│  by plugin) │
 └──────────────┘            └──────────┘               └─────────────┘
                                                              ▲
                                                              │ same-origin
                                                              │ cookies
                                                       ┌─────────────┐
                                                       │  your app   │
                                                       │ (plugin is  │
                                                       │  installed) │
                                                       └─────────────┘

Claude calls create_session (MCP tool) → relay returns a 9-digit session key + URL
User visits the URL in the browser where their app is running → confirms via "Allow sncro debugging?"
The plugin drops a cookie, agent.js is injected into subsequent HTML responses on that origin
agent.js pushes baseline data (console, errors) and long-polls for on-demand queries (query_element, get_page_snapshot, etc.)

Using sncro

Most users don't need to run the relay yourself — the hosted version at relay.sncro.net is free-tier friendly. Register your project at sncro.net and grab your project key.

FastAPI: drop middleware/sncro_middleware.py into your project, then:

server.ts

from middleware.sncro_middleware import SncroMiddleware, sncro_routes

app = FastAPI(debug=True)  # sncro only loads when debug=True
if app.debug:
    app.include_router(sncro_routes)
    app.add_middleware(SncroMiddleware, relay_url="https://relay.sncro.net")

Flask: drop middleware/sncro_flask.py into your project, then:

server.ts

from sncro_flask import init_sncro

app = Flask(__name__)
if app.debug:
    init_sncro(app, relay_url="https://relay.sncro.net")

Both middlewares only activate in debug mode — zero overhead in production.

Contributing

We love new framework plugins. CONTRIBUTING.md has the full spec for what a plugin must do — cookies, routes, security headers — plus the test template. Django, Rails, Express, Next.js, ASP.NET, Go — all welcome.

Bug reports and security issues: see SECURITY.md.

License

MIT. See LICENSE.

The dashboard at sncro.net (project management, billing, admin) lives in a separate proprietary repo.