Sncro

sncro-relay

s ncro 的开源组件——MCP 中继、浏览器端 Agent，以及让 AI 编码助手能够检查实时浏览器的框架插件。

此仓库包含的内容

路径	内容
relay/	FastAPI 应用，提供 MCP 服务以及供 agent.js 使用的长轮询端点
relay/static/agent.js	由中间件注入的浏览器端脚本；将控制台和 DOM 数据推送到中继
middleware/sncro_middleware.py	FastAPI / Starlette 插件——可直接用于 FastAPI 应用的中间件
middleware/sncro_flask.py	Flask 插件——可直接用于 Flask 应用的中间件
trysncro/	try.sncro.net——用于端到端体验 sncro 的故意设有缺陷的演示应用

工作原理

 ┌──────────────┐    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) │
                                                       └─────────────┘

1. Claude 调用 create_session（MCP 工具）→ 中继返回 9 位会话密钥和 URL
2. 用户在应用运行所在的浏览器中访问该 URL → 通过“允许 sncro 调试？”确认
3. 插件设置 Cookie，agent.js 会被注入该源后续返回的 HTML 响应中
4. agent.js 推送基线数据（控制台、错误），并长轮询等待按需查询（query_element、get_page_snapshot 等）

使用 sncro

大多数用户无需自行运行中继——托管版本 relay.sncro.net 提供免费套餐。请在 sncro.net 注册项目并获取项目密钥。

FastAPI： 将 middleware/sncro_middleware.py 放入项目，然后：

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： 将 middleware/sncro_flask.py 放入项目，然后：

from sncro_flask import init_sncro

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

这两种中间件仅在调试模式下启用——生产环境中不会产生任何开销。

贡献

我们欢迎新的框架插件。CONTRIBUTING.md 中提供了插件必须遵循的完整规范——包括 Cookie、路由、安全标头——以及测试模板。欢迎 Django、Rails、Express、Next.js、ASP.NET、Go 等框架。

如需报告 Bug 或安全问题，请参阅 SECURITY.md。

许可证

MIT。请参阅 LICENSE。

sncro.net 上的仪表板（项目管理、账单、管理）位于单独的专有仓库中。