{
  "markdown": "# sncro-relay\n\nOpen-source components of [sncro](https://sncro.net) — the MCP relay, the browser-side agent, and the framework plugins that let AI coding assistants inspect a live browser.\n\n## What this repo contains\n\n| Path | What |\n|---|---|\n| `relay/` | FastAPI app that exposes an [MCP](https://modelcontextprotocol.io) server plus long-poll endpoints for agent.js |\n| `relay/static/agent.js` | Browser-side script injected by the middleware; pushes console + DOM data to the relay |\n| `middleware/sncro_middleware.py` | FastAPI / Starlette plugin — drop-in middleware for FastAPI apps |\n| `middleware/sncro_flask.py` | Flask plugin — drop-in middleware for Flask apps |\n| `trysncro/` | `try.sncro.net` — a deliberately-broken demo app for exercising sncro end-to-end |\n\n## How it works\n\n```\n ┌──────────────┐    MCP     ┌──────────┐   long-poll   ┌─────────────┐\n │ Claude Code  │──tools────▶│  relay   │◀──────────────│  agent.js   │\n │ (or other    │            │ (relay/) │   snapshots   │ (injected   │\n │  MCP client) │◀──results──│          │──────────────▶│  by plugin) │\n └──────────────┘            └──────────┘               └─────────────┘\n                                                              ▲\n                                                              │ same-origin\n                                                              │ cookies\n                                                       ┌─────────────┐\n                                                       │  your app   │\n                                                       │ (plugin is  │\n                                                       │  installed) │\n                                                       └─────────────┘\n```\n\n1. Claude calls `create_session` (MCP tool) → relay returns a 9-digit session key + URL\n2. User visits the URL in the browser where their app is running → confirms via \"Allow sncro debugging?\"\n3. The plugin drops a cookie, agent.js is injected into subsequent HTML responses on that origin\n4. agent.js pushes baseline data (console, errors) and long-polls for on-demand queries (`query_element`, `get_page_snapshot`, etc.)\n\n## Using sncro\n\nMost 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](https://sncro.net) and grab your project key.\n\n**FastAPI:** drop [middleware/sncro_middleware.py](middleware/sncro_middleware.py) into your project, then:\n```python\nfrom middleware.sncro_middleware import SncroMiddleware, sncro_routes\n\napp = FastAPI(debug=True)  # sncro only loads when debug=True\nif app.debug:\n    app.include_router(sncro_routes)\n    app.add_middleware(SncroMiddleware, relay_url=\"https://relay.sncro.net\")\n```\n\n**Flask:** drop [middleware/sncro_flask.py](middleware/sncro_flask.py) into your project, then:\n```python\nfrom sncro_flask import init_sncro\n\napp = Flask(__name__)\nif app.debug:\n    init_sncro(app, relay_url=\"https://relay.sncro.net\")\n```\n\nBoth middlewares only activate in debug mode — zero overhead in production.\n\n## Contributing\n\nWe love new framework plugins. [CONTRIBUTING.md](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.\n\nBug reports and security issues: see [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nThe dashboard at [sncro.net](https://sncro.net) (project management, billing, admin) lives in a separate proprietary repo.\n",
  "bytes": 3547,
  "sha": "80698ebf4dd9195f5e1268c1900589592143e8eab24b59655bf22f9b9f5bb28e",
  "repo_slug": "scottconfusedgorilla/sncro-relay",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_scottconfusedgorilla_sncro_c319421a/readme"
}