notebridge (Atharvagashe Tamu)

光标笔记本桥

在光标中编辑。在云硬件上执行。保留一个实时笔记本工件。

光标笔记本桥 是一个开源的Cursor/VS Code扩展，它将您的本地编辑器连接到远程笔记本运行时——从Google Colab开始，旨在支持任何 ipynb-兼容后端。

______________________________________________________________________

为什么存在

当你在Cursor中使用人工智能辅助代码生成时，你经常遇到问题：代码很好，但在本地运行很慢，或者你需要一个GPU，或者你想要一个可重复的 .ipynb 与他人分享的人工制品。将代码复制粘贴到Colab中会杀死流。

这个项目消除了这种摩擦。您可以在Cursor中编写和编辑；该桥在Colab（或任何兼容Jupyter的后端）上运行您的代码，并实时流式传输结果。

______________________________________________________________________

功能（MVP）

• 附加到笔记本会话 --连接到打开的Colab笔记本或创建新笔记本
• 在远程上运行选择 — Ctrl+Shift+Enter 运行所选块或整个文件
• 推/拉笔记本 --同步 .ipynb 游标和遥控器之间的状态
• 流输出 --日志、错误和丰富的输出显示在“输出”面板中
• 状态栏 --始终显示会话状态（已断开连接→ 附上→ 运行）
• 后端不可知 --添加Kaggle、JupyterHub或本地Jupyter是一个单一的适配器文件

______________________________________________________________________

入门指南

选项A——自动设置（推荐）

安装脚本检查每个必备项，安装任何缺失的内容，以及 一步构建所有包。他们还永久添加了所需的 将目录添加到系统PATH中，以便Cursor扩展主机可以找到 git 和 uv 在运行时。

视窗 （以管理员身份运行PowerShell）：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\setup.ps1

macOS/Linux:

bash scripts/setup.sh

在脚本完成之后， 关闭并重新打开游标 因此，更新的PATH 生效，然后按 F5 启动扩展开发主机。

选项B——手动设置

Colab MCP包装规格： 默认情况下，网桥运行 uvx 带着一个 钉住 git+https://github.com/googlecolab/colab-mcp@v1.0.0 因此uv缓存一个环境，而不是更新Git HEAD 在每次会议上。要使用另一个引用，请设置环境变量 COLAB_MCP_SPEC 在运行网桥的机器上，或在光标设置中 notebookBridge.colabMcpUvxSpec （传递的值与 COLAB_MCP_SPEC).

# Clone and build
git clone https://github.com/cursor-notebook-bridge/cursor-notebook-bridge
cd cursor-notebook-bridge
pnpm install
pnpm build

# Open a Colab notebook in Chrome, then press F5 in Cursor
# Cmd/Ctrl+Shift+P → "Notebook Bridge: Attach to Session"
# Paste your Colab URL → Ctrl+Shift+Enter to run selected code

______________________________________________________________________

回购布局

packages/
  core/            Contracts, notebook model, events, sync engine
  bridge/          Local HTTP + WebSocket service
  backend-colab/   Google Colab adapter (Colab MCP protocol)
  extension/       Cursor/VS Code extension
docs/
  architecture.md  System design and component diagram
  colab-spike.md   Colab MCP validation findings
examples/
  hello_colab.py   Example script with # %% cell separators

______________________________________________________________________

运作原理

Cursor Extension
    │ REST / WebSocket
    ▼
Local Bridge (port 52000)
    │
    ├── SessionManager
    ├── NotebookSyncEngine
    │
    └── ColabBackend
          │ MCP over stdio
          ▼
       colab-mcp server  ──→  Colab browser tab

详细信息： docs/architecture.md

______________________________________________________________________

添加新后端

这 NotebookBackend 接口 packages/core/src/contracts.ts 是您需要执行的唯一合同：

class MyBackend implements NotebookBackend {
  readonly id = "my-backend";
  readonly displayName = "My Jupyter Server";
  // ... implement connect, pullNotebook, pushCells, runCells, etc.
}

在中注册 packages/bridge/src/server.ts 你完了。其他包没有变化。

______________________________________________________________________

发展

# Typecheck all packages
pnpm typecheck

# Build
pnpm build

# Launch extension in Cursor's Extension Development Host
# Open packages/extension in Cursor → F5

______________________________________________________________________

路线图

• \[x\] 核心合同和笔记本电脑模型
• \[x\] 本地网桥服务（HTTP+WebSocket）
• \[x\] Colab后端通过官方MCP服务器
• \[x\] 带有run/push/lull命令的光标扩展
• \[x\] 脚本到笔记本同步引擎(# %% 分离器支撑）
• \[x\] 丰富的输出Web视图——matplotlib图、pandas DataFrames、Cursor中的HTML内联渲染
• \[x\] 根据实时服务器验证Colab MCP工具名称（请参阅 docs/colab-spike.md)

______________________________________________________________________

贡献

欢迎发布问题和PR。请阅读 docs/architecture.md 首先要了解设计边界。

______________________________________________________________________

许可证

麻省理工学院