SideButton MCP Server

SideButton

エージェント型コーディング向けのオープンソース AI エージェントプラットフォーム — MCP サーバー、ナレッジパック、AI ワークフロー自動化を提供します。

sidebutton.com · docs.sidebutton.com

エージェント型ワークフロー、ナレッジパック、実際のブラウザー操作を使って、AI コーディングエージェントを実行できます。Claude Code、Codex、Cursor、ChatGPT、または任意の MCP クライアントを接続できます。

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

利用できる機能

MCP サーバー	ブラウザー操作、ワークフロー実行、ナレッジパックへのアクセスを行う AI エージェントツールです。Stdio および SSE トランスポートに対応しています。
REST API	Webhook、cron ジョブ、モバイルアプリ、その他のエージェントから、リモートでワークフローをトリガーできます。
ワークフローエンジン	ブラウザー、git、課題追跡、LLM、シェル、制御フローの各ステップを使った AI ワークフロー自動化です。エージェント型ワークフローを YAML で定義できます。
ナレッジパック	インストール可能なドメイン知識です。CSS セレクター、データモデル、状態マシンなどが含まれます。役割別プレイブックを使って、コーディングエージェントを 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 コーディングエージェント向けのオープンソース MCP サーバーです。エージェントは直接接続し、ブラウザー操作、ワークフロー自動化、ドメイン知識を利用できます。

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 に保存されます。代わりに ./.mcp.json に書き込むには、--scope project を追加してください。詳しい手順は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	ページのスクリーンショットを取得します（画像バイト列を返す代わりに PNG ファイルを書き込むには、path を渡します）
select_option	ドロップダウンのオプションを選択します
fill	入力値を設定します（React 対応）
wait	要素または指定時間を待ちます
exists	要素が存在するか確認します
extract_all	条件に一致するすべての要素から抽出します
extract_map	繰り返し表示される要素から構造化データを抽出します
scroll_into_view	要素がビューポート内に入るまでスクロールします
hover	要素にカーソルを合わせます
inject_css	ページに CSS を挿入します（スクリーンショットを撮る前に要素をぼかす／非表示にします）
evaluate	ブラウザーで JavaScript を実行します
browser_batch	1 回の呼び出しで一連のブラウザー操作を実行します
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、cron ジョブ、モバイルアプリ、または別のマシン上にある他のエージェントからワークフローを起動できます。

ワークフローエンジン

エージェント型ワークフロー向けの YAML ファーストなオーケストレーションです。ファミリー別のステップタイプ：

ステップタイプ

ファミリー	ステップ
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 エージェントのデプロイを支援します。

コードや CLI コマンドでは、スキルパックとも呼ばれます。

• セレクター — UI 要素の CSS セレクター
• データモデル — エンティティの種類、フィールド、関係、有効な状態
• 状態マシン — 状態ごとの有効な遷移
• ロール別プレイブック — ロール固有の手順（QA、SE、PM、SD）
• 一般的なタスク — 手順ごとの説明、注意点、エッジケース

sidebutton install github.com
sidebutton install atlassian.net

人気の Web アプリ向けに公開済みのパックを登録したレジストリを開きます。あらゆるドメイン向けにパックを作成して共有できます。

Chrome 拡張機能

Chrome ウェブストアから SideButton Chrome Extension をインストールします。

• ブラウザーコマンド — 移動、クリック、入力、抽出、スクロール、待機、スナップショット
• CSS セレクターによる実際の DOM へのアクセス — ピクセル座標やスクリーンショットは使用しません
• 記録モード — 手動操作をワークフローとして記録
• ボタンの埋め込み — 任意のウェブページにアクションボタンを挿入
• WebSocket 接続 — 安定した再接続が可能で、ローカルサーバーとリモートサーバーの両方に対応

インストール後：

1. 任意のウェブサイトに移動します
2. SideButton 拡張機能のアイコンをクリックします
3. 「このタブを接続」 をクリックします

ダッシュボードと可観測性

http://localhost:9876 に Svelte UI があります。

• ワークフローブラウザー — 一覧表示、検索、実行
• 実行ログ — タイミング、変数、エラーを含むステップごとの実行トレース
• スキルパックマネージャー — インストール、閲覧、確認
• システムステータス — 拡張機能の接続、LLM 設定、サーバーの状態

SideButton は、ワークフローの実行からナレッジの注入まで、複数のエージェントのオーケストレーションを処理します。

アーキテクチャ

┌──────────────────────────────────────────────────────────────────────────┐
│                          @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 に移行）