Ray Bridge

雷布里奇

将Raycast扩展桥接到任何MCP兼容客户端的MCP服务器。

发现本地安装的Raycast扩展，加载其工具定义，并通过 模型上下文协议 通过stdio或HTTP。

RayBridge TUI

运作原理

1. 扫描 ~/.config/raycast/extensions/ 对于已安装的扩展 tools 定义
2. 从Raycast的加密SQLite数据库加载OAuth令牌
3. 将工具注册为任何MCP客户端都可以访问的MCP工具

使用Raycast UI API的扩展(List, Detail, FormUI组件被调整为无操作，因此底层工具逻辑可以无头执行。其工具执行后台工作（API调用、数据查找、转换）的扩展效果最好。

设置

先决条件

• 包子
• 光线投射 已安装扩展
• sqlcipher CLI（用于OAuth令牌访问）： brew install sqlcipher

安装

bun install

配置MCP客户端

克劳德代码 (~/.claude/settings.json):

{
  "mcpServers": {
    "raybridge": {
      "command": "bun",
      "args": ["run", "src/index.ts"],
      "cwd": "/path/to/raybridge"
    }
  }
}

光标 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "raybridge": {
      "command": "bun",
      "args": ["run", "src/index.ts"],
      "cwd": "/path/to/raybridge"
    }
  }
}

HTTP传输

该服务器还可以作为远程MCP客户端的HTTP服务器运行。

启动服务器：

# Default: http://0.0.0.0:3000
bun run start:http

# Custom host/port
MCP_PORT=8080 MCP_HOST=0.0.0.0 bun run start:http

# With API key authentication
MCP_API_KEY=your-secret-key bun run start:http

# CLI flags also work
bun run src/index.ts --http --port 8080 --host 0.0.0.0

终点：

身份验证：

当 MCP_API_KEY 已设置，请求 /mcp 必须包含一个Bearer令牌（根据MCP规范）：

Authorization: Bearer your-secret-key

示例会话：

# 1. Initialize session (capture session ID from response header)
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-secret-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
    "protocolVersion":"2024-11-05",
    "capabilities":{},
    "clientInfo":{"name":"my-client","version":"1.0"}
  }}'
# Response includes: mcp-session-id header

# 2. List available tools
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-secret-key" \
  -H "mcp-session-id: " \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 3. Call a tool
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-secret-key" \
  -H "mcp-session-id: " \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
    "name":"web",
    "arguments":{"tool_name":"read_page","input":{"url":"https://example.com"}}
  }}'

会话在30分钟不活动后自动过期。

命令行界面

RayBridge包括一个CLI，用于管理公开的扩展和工具：

bun link                    # Register the raybridge command (one-time setup)

raybridge                   # Launch interactive TUI
raybridge config            # Launch interactive TUI
raybridge list              # List all extensions and their status
raybridge help              # Show help

TUI允许您：

• 打开/关闭扩展
• 展开扩展以切换单个工具
• 在阻止列表模式（默认情况下全部启用）和允许列表模式之间切换
• 将配置保存到 ~/.config/raybridge/tools.json

配置

工具配置

控制通过以下方式公开哪些扩展和工具 ~/.config/raybridge/tools.json:

{
  "mode": "blocklist",
  "extensions": {
    "extension-name": {
      "enabled": false
    },
    "another-extension": {
      "enabled": true,
      "tools": ["specific-tool-1", "specific-tool-2"]
    }
  }
}

• 阻止列表模式 （默认）：除非明确禁用，否则启用所有扩展
• 满负荷模式：除非明确启用，否则禁用所有扩展

扩展首选项

需要配置的扩展（API密钥、个人访问令牌等）读取自：

~/.config/raybridge/preferences.json

{
  "extension-name": {
    "personalAccessToken": "your-token",
    "apiKey": "your-key"
  }
}

扩展名与 name 扩展中的字段 package.json.

建筑

src/
├── index.ts       # MCP server, tool registration, request dispatch
├── http-server.ts # HTTP transport with session management
├── cli.ts         # CLI entry point (config, list, help commands)
├── tui.tsx        # Interactive TUI for extension configuration
├── config.ts      # Tools configuration (blocklist/allowlist)
├── discovery.ts   # Scans ~/.config/raycast/extensions/ for tool definitions
├── loader.ts      # Executes local tools with Raycast API shims
├── shims.ts       # Fake @raycast/api, react, react/jsx-runtime modules
├── auth.ts        # Keychain access, SQLcipher DB decryption, OAuth tokens
└── watcher.ts     # Watches extension directories for changes, triggers reloads

工具发现

从以下位置发现本地扩展 ~/.config/raycast/extensions/.每个扩展 package.json 必须有一个 tools 使用名称、描述和输入模式定义可用工具的数组。编译的工具代码位于 tools/{toolName}.js 在每个扩展目录中。

当存在重复项（多个目录中的扩展名相同）时，最新修改的版本获胜。

工具执行

加载工具的方法是将Raycast API垫片安装到Node的模块系统中，然后需要该工具的编译JS文件，并使用提供的输入调用其默认导出。

射线铸造API垫片

以下 @raycast/api 特征被填隙：

React和JSX运行时也使用了最小的模拟(createElement → null，钩子不是操作）。

认证

OAuth令牌从Raycast的加密SQLite数据库中读取，地址为：

~/Library/Application Support/com.raycast.macos/raycast-enc.sqlite

数据库密钥从macOS Keychain检索，并通过SHA256使用盐导出。每个扩展都提取令牌，并通过 OAuth.PKCEClient 垫片。

MCP工具模式

扩展被分组——每个扩展都成为一个MCP工具。输入模式遵循以下模式：

{
  "tool_name": "which-tool-to-run",
  "input": { "param": "value" }
}

工具描述包括每个工具的文档、参数详细信息以及来自扩展的任何扩展范围的AI指令 ai.instructions 现场。

局限性

• 无交互式用户界面 --依赖于向用户呈现列表、窗体或其他视觉组件的扩展将不会有意义地运行
• 无持久本地存储 --垫片为无op；依赖它的扩展在调用之间失去状态
• OAuth令牌未刷新 --过期的令牌将导致失败，直到Raycast刷新它们
• 仅限macOS --取决于macOS Keychain和Raycast的macOS应用程序路径