SideButton

SideButton

面向 Agentic 编码的开源 AI Agent 平台——MCP 服务、知识包和 AI 工作流自动化。

sidebutton.com · docs.sidebutton.com

借助 Agentic 工作流、知识包和真实浏览器控制运行 AI 编码 Agent。连接 Claude Code、Codex、Cursor、ChatGPT 或任何 MCP 客户端。

npx sidebutton@latest
# Dashboard at http://localhost:9876

你将获得

MCP 服务	用于浏览器控制、工作流执行和知识包访问的 AI Agent 工具。支持 Stdio 和 SSE 传输。
REST API	通过 Webhook、定时任务、移动应用或其他 Agent 远程触发工作流。
工作流引擎	支持浏览器、git、问题跟踪、LLM、shell 和控制流步骤的 AI 工作流自动化。使用 YAML 定义 Agentic 工作流。
知识包	可安装的领域知识——CSS 选择器、数据模型、状态机。角色手册可将编码 Agent 转变为 AI 软件工程师、QA 或 PM。
Chrome 扩展	通过 WebSocket 使用浏览器命令直接访问真实 DOM，而非截图。支持录制模式。
控制面板	Svelte UI——工作流浏览器、运行日志、技能包管理器、系统状态。

快速开始

# Install and start
npx sidebutton@latest

# Or from source
pnpm install && pnpm build && pnpm start

# Open http://localhost:9876

CLI

pnpm cli serve          # Start server with dashboard
pnpm cli serve --stdio  # Start with stdio transport (for Claude Desktop)
pnpm cli list           # List available workflows
pnpm cli status         # Check server status

# Skill pack management
pnpm cli registry add <path|url>   # Install skill packs from a registry
pnpm cli registry update [name]    # Update installed packs
pnpm cli registry remove <name>    # Uninstall packs and remove registry
pnpm cli search [query]            # Search available skill packs

# Creating skill packs
pnpm cli init [domain]             # Scaffold a new skill pack
pnpm cli validate [path]           # Validate pack structure
pnpm cli publish [source]          # Publish to a registry

MCP 服务

SideButton 是一款开源的面向 AI 编码 Agent 的 MCP 服务。Agent 可直接连接该服务，以控制浏览器、自动化工作流并访问领域知识。

适用于 Claude Code、Codex、Cursor、Claude Desktop、VS Code、Windsurf、ChatGPT——以及任何 MCP 客户端。

Claude Code

claude mcp add sidebutton --transport http http://localhost:9876/mcp

配置会写入 ~/.claude.json；添加 --scope project 可改为写入 ./.mcp.json。完整指南：Claude Code SideButton MCP 设置。

Codex

添加到 ~/.codex/config.toml：

[mcp_servers.sidebutton]
command = "sidebutton"
args = ["serve", "--stdio"]

完整指南：OpenAI Codex SideButton MCP 设置。

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "sidebutton": {
      "command": "npx",
      "args": ["sidebutton", "--stdio"]
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "sidebutton": {
      "url": "http://localhost:9876/mcp"
    }
  }
}

MCP 工具

工具	描述
run_workflow	按 ID 执行工作流
get_run_log	获取某次运行的执行日志
list_workflows	列出所有可用工作流
get_workflow	获取工作流 YAML 定义
list_run_logs	列出最近的工作流执行记录
publish_artifact	发布会话中的证据（截图、报告）
get_browser_status	检查浏览器扩展连接状态
capture_page	从当前页面捕获选择器
navigate	将浏览器导航至 URL
snapshot	获取页面无障碍快照
click	点击元素
type	在元素中输入文本
press_key	发送键盘按键
scroll	滚动页面
extract	从元素中提取文本
screenshot	截取页面截图（传入 path 可写入 PNG 文件，而非返回图像字节）
select_option	选择下拉选项
fill	填入输入值（兼容 React）
wait	等待元素或延迟
exists	检查元素是否存在
extract_all	提取所有匹配的元素
extract_map	从重复元素中提取结构化数据
scroll_into_view	将元素滚动至视口内
hover	将鼠标悬停在元素上
inject_css	向页面注入 CSS（在截图前模糊或隐藏元素）
evaluate	在浏览器中执行 JavaScript
browser_batch	一次调用中运行一系列浏览器操作
set_basic_auth	为已连接的标签页设置 HTTP Basic Auth 凭据
clear_basic_auth	清除已存储的 HTTP Basic Auth 凭据

REST API

用于外部集成的 JSON 端点。相同的工作流可通过本地 MCP 和远程 REST 使用。

# Run a workflow
curl -X POST http://localhost:9876/api/workflows/check_ticket/run \
  -H "Content-Type: application/json" \
  -d '{"params": {"ticket_id": "PROJ-123"}}'

# List workflows
curl http://localhost:9876/api/workflows

# Get run log
curl http://localhost:9876/api/runs/latest

从 Webhook、定时任务、移动应用或其他设备上的 Agent 触发工作流。

工作流引擎

以 YAML 为先的 Agent 工作流编排。按类别划分的步骤类型：

步骤类型

类别	步骤
browser.*	navigate、click、type、fill、extract、extractAll、extractMap、snapshot、screenshot、wait、exists、hover、key、scroll、scrollIntoView、select_option、injectCSS、injectJS
git.*	createPR、getPR、listPRs、getIssue、listIssues
issues.*	create、get、search、comment、attach、transition
llm.*	classify、decide、generate
control.*	if、foreach、retry、stop
shell / terminal	shell.run、terminal.open、terminal.run
data.*	first、get
workflow.call	使用参数调用另一个工作流

LLM 步骤支持 Ollama（本地）、OpenAI 和 Anthropic。

示例

id: check_ticket_status
title: "Check Jira ticket and classify"
steps:
  - type: browser.navigate
    url: "https://your-org.atlassian.net/browse/{{ticket_id}}"
  - type: browser.extract
    selector: "[data-testid='status-field']"
    as: current_status
  - type: control.if
    condition: "{{current_status}} != 'Done'"
    then:
      - type: llm.classify
        prompt: "Should this ticket be closed? Context: {{current_status}}"
        classes: [close, keep_open]
        as: decision

变量插值

使用 {{variable}} 语法引用提取的值或参数：

steps:
  - type: browser.extract
    selector: ".username"
    as: user
  - type: shell.run
    cmd: "echo 'Hello, {{user}}!'"

知识包

适用于各个 Web 应用或领域、可安装的领域知识（技能包）。知识包为 AI 代码审查、自动化测试和企业级 AI Agent 部署提供支持。

在代码和 CLI 命令中也称为技能包。

• 选择器 — UI 元素的 CSS 选择器
• 数据模型 — 实体类型、字段、关系、有效状态
• 状态机 — 各状态的有效转换
• 角色手册 — 特定角色的流程（QA、SE、PM、SD）
• 常见任务 — 分步流程、注意事项、边缘情况

sidebutton install github.com
sidebutton install atlassian.net

打开包含热门 Web 应用已发布知识包的注册表。为任何领域构建和分享知识包。

Chrome Extension

从 Chrome 应用商店安装 SideButton Chrome Extension。

• 浏览器命令——导航、点击、输入、提取、滚动、等待、快照
• 通过 CSS 选择器直接访问真实 DOM——无需像素坐标或截图
• 录制模式——将手动操作录制为工作流
• 嵌入按钮——向任意网页注入操作按钮
• WebSocket 连接——稳定重连，支持本地或远程服务

安装后：

1. 导航到任意网站
2. 点击 SideButton 扩展图标
3. 点击 "连接此标签页"

仪表板与可观测性

位于 http://localhost:9876 的 Svelte UI：

• 工作流浏览器——列出、搜索、运行工作流
• 运行日志——包含耗时、变量和错误的逐步执行跟踪
• 技能包管理器——安装、浏览、查看详情
• 系统状态——扩展连接、LLM 配置、服务运行状况

SideButton 负责处理多 Agent 编排——从工作流执行到知识注入。

架构

┌──────────────────────────────────────────────────────────────────────────┐
│                          @sidebutton/server                               │
│                                                                          │
│  ┌─────────────────────┐   ┌──────────────────────────────────────────┐  │
│  │  stdio Transport    │   │    Fastify HTTP + WebSocket (port 9876)  │  │
│  │  ─────────────────  │   │    ────────────────────────────────────  │  │
│  │  stdin → JSON-RPC   │   │  GET  /        → Dashboard (Svelte)      │  │
│  │  stdout ← JSON-RPC  │   │  GET  /ws      → Chrome Extension WS     │  │
│  │  (Claude Desktop)   │   │  POST /mcp     → MCP JSON-RPC (SSE)      │  │
│  └──────────┬──────────┘   │  GET  /api/*   → REST API                │  │
│             │              └──────────────────────┬───────────────────┘  │
│             │                                     │                      │
│             └──────────────────┬──────────────────┘                      │
│                                ▼                                         │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │                       @sidebutton/core                              │  │
│  │                                                                     │  │
│  │  - Workflow types & parser (YAML)                                  │  │
│  │  - Step executors (YAML step types)                                │  │
│  │  - Variable interpolation                                          │  │
│  │  - Execution context & events                                      │  │
│  └────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
      ▲                ▲                      ▲                      ▲
      │ stdio          │ WebSocket            │ HTTP POST            │ REST
      ▼                ▼                      ▼                      ▼
┌──────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────────┐
│Claude Desktop│ │ Chrome Extension│ │   Claude Code   │ │   Mobile App      │
│ (MCP stdio)  │ │ (Browser Auto)  │ │   (MCP SSE)     │ │   (REST Client)   │
└──────────────┘ └─────────────────┘ └─────────────────┘ └───────────────────┘

项目结构

sidebutton/
├── packages/
│   ├── core/              # @sidebutton/core — workflow engine
│   │   └── src/
│   │       ├── types.ts       # Workflow types
│   │       ├── parser.ts      # YAML loader
│   │       ├── executor.ts    # Workflow runner
│   │       └── steps/         # Step implementations
│   ├── server/            # @sidebutton/server — MCP + HTTP + CLI
│   │   ├── bin/               # CLI entry point
│   │   └── src/
│   │       ├── server.ts      # Fastify HTTP server
│   │       ├── stdio-mode.ts  # stdio transport entry point
│   │       ├── extension.ts   # WebSocket client
│   │       ├── mcp/           # MCP handlers
│   │       │   ├── handler.ts    # MCP JSON-RPC logic
│   │       │   ├── stdio.ts      # stdio transport adapter
│   │       │   └── tools.ts      # Tool definitions
│   │       └── cli.ts         # Commander CLI
│   └── dashboard/         # Svelte web UI
│       └── src/
│           ├── App.svelte
│           └── lib/
├── extension/             # Chrome extension
├── workflows/             # Public workflow library
├── actions/               # User-created workflows
├── skills/                # Installed skill packs
└── run_logs/              # Execution history

环境变量

变量	必需用途	描述
OPENAI_API_KEY	llm.* 步骤	用于 LLM 工作流的 OpenAI API 密钥
ANTHROPIC_API_KEY	llm.* 步骤	Anthropic API 密钥（替代项）

开发

pnpm install       # Install dependencies
pnpm build         # Build all packages
pnpm start         # Start server
pnpm cli list      # List workflows
pnpm cli status    # Check status

监视模式

pnpm dev              # Full dev mode (all packages)
pnpm dev:server       # Server with auto-restart on :9876
pnpm dev:dashboard    # Dashboard watch build
pnpm dev:core         # Core library watch build

平台自动化免责声明

SideButton 是一个通用浏览器自动化框架。自动化第三方平台时：

• 查看服务条款： 许多平台禁止或限制自动化。你有责任遵守所自动化平台的条款。
• 账户风险： 在某些平台上，自动化可能导致账户受限或被停用。
• 负责任地使用： 仅自动执行你会手动进行的操作。遵守速率限制和平台指南。

作者不认可或鼓励违反第三方服务条款的行为。

许可证

本项目采用混合许可——详见 LICENSING.md：

• 引擎、服务、CLI、仪表板 — Apache-2.0
• 浏览器扩展 — FSL-1.1-Apache-2.0（于 2029-03-15 转为 Apache-2.0）