opencode-workbench

OpenCode Workbench

再現可能で、自己文書化され、復旧可能な OpenCode 開発ワークステーション — 設定、エージェントスキル、MCP スタック、およびローカルまたは SSH 経由でセットアップ全体を任意の Linux マシンに複製する MCP サーバーです。

ホームページとリモート MCP： https://opencode-workbench.simonmak.com · POST https://opencode-workbench.simonmak.com/mcp

概要

このリポジトリは、完全なクラウド開発ワークステーションの唯一の信頼できる情報源です。ゼロから再構築するために必要なすべてのものが、ここでバージョン管理されています。

• ワークステーションの設定と自動化
• OpenCode の設定（モデル、プロバイダー、MCP サーバー）
• エージェントスキル（調査、開発、データ、科学、運用で使える45個の再利用可能な AI 指示）
• 運用プロンプト（災害復旧、バックアップ、セキュリティ）
• 復旧手順（プレイブック、チェックリスト、ギャップ分析）
• セキュリティガバナンス（シークレット管理、脅威モデル）
• OpenCode サンドボックス（bubblewrap）— 読み取り専用のシステムとシークレットのマウントなしでエージェントを実行します
• opencode-workbench — このプロファイルを任意の Linux マシンにインストールする MCP サーバー

重要な知識が人間の記憶だけに存在することはありません。

この Workbench を別の Linux マシンに複製する

OpenCode に MCP サーバーを登録します。

{
  "mcp": {
    "opencode-workbench": {
      "type": "local",
      "command": ["npx", "-y", "@simonmak-ascent/opencode-workbench"],
      "enabled": true,
      "timeout": 600000
    }
  }
}

次に、エージェントに { "mode": "local" } または { "mode": "ssh", "host": "<your-box>", "user": "<your-user>" } を指定して、inspect_target → plan_clone → apply_clone { confirm: true } → verify_clone の順に実行するよう依頼します。apply_clone は同意を必須とします。confirm:true がない場合は、計画（コンポーネントと特権コマンドのプレビュー）を返し、何も変更しません。list_required_credentials を実行すると、そのマシンで不足しているキーとその取得方法を確認できます。また、bash scripts/selftest/run-selftest.sh を実行して動作を検証できます。mcp-server/README.md と docs/architecture/clone-mcp.md を参照してください。

複製はキーの有無に左右されません。モデルキーがなくても OpenCode Zen の無料プランで起動し、認証情報がない MCP サーバーは無効化され、そのことが報告されます（実行時に失敗する状態のままにはなりません）。

コネクターがシークレットの値を読み取ったり送信したりすることはありません。入力用の空の ~/.env.workbench テンプレートを作成します。

クイックスタート（5分以内）

最短の方法： マシンは不要です。この Workbench を複製するの設定を使って、npx -y @simonmak-ascent/opencode-workbench で MCP サーバーを登録するだけです。または、新しいマシンをプロビジョニングします。

# Create a new build box
gh SWAS create --repo simonmak-ascent/opencode-workbench --machine basicLinux32gb

# Wait for postCreate (3-5 min) — installs everything automatically
# Then start coding:
opencode

アーキテクチャ

flowchart TB
  AGENT["OpenCode agent"] -->|"npx @simonmak-ascent/opencode-workbench"| MCP["opencode-workbench MCP<br/>inspect · plan · apply · verify"]
  REPO[("Git repo — single source of truth")] --> MCP
  MCP -->|"local or SSH"| BOX["Target Linux box"]
  BOX --> PROF["Workstation profile<br/>OpenCode CLI · 35 MCP servers · 45 skills · Docker infra"]

複製のライフサイクル

apply_clone は同意を必須とします。confirm: true がない場合は計画を返し、何も変更しません。

sequenceDiagram
    autonumber
    participant A as OpenCode agent
    participant M as opencode-workbench MCP
    participant B as Target box (local or SSH)
    A->>M: inspect_target
    M-->>A: OS, toolchain, Docker, existing config
    A->>M: plan_clone
    M-->>A: components + privileged-command preview
    A->>M: apply_clone { confirm: true }
    M->>B: install components · write ~/.env.workbench template
    B-->>M: result
    A->>M: verify_clone
    M-->>A: pass/fail + missing credentials

MCP ツール一覧

flowchart LR
    A["OpenCode agent"] --> D["Discovery<br/>describe_workbench · inspect_target"]
    A --> C["Clone<br/>plan_clone · apply_clone · verify_clone"]
    A --> K["Components<br/>install · remove · update_component"]
    A --> S["Credentials<br/>list_required_credentials · run_auth_flow"]

opencode-workbench/
├── mcp-server/                     # opencode-workbench: clone this profile onto Linux
│   ├── src/                        # inspect / plan / apply / verify, local + SSH
│   ├── test/                       # unit tests (vitest)
│   └── README.md
├── connector.json                  # MCP connector manifest / registration snippet
├── plugins/                        # memory.ts + doc-tools.ts OpenCode plugins
├── package.json                    # thin launcher for opencode-workbench (bin + prepare)
├── .devcontainer/                  # build box definition & bootstrap
│   ├── devcontainer.json           # Container image, features, ports, remoteEnv
│   ├── setup.sh                    # Post-create: installs opencode, MCPs, Docker infra
│   └── aliases.sh                  # Shell aliases sourced at runtime
├── .opencode/
│   └── skills/                     # 28 custom agent skills (10 research, 10 dev, 8 publishing)
├── vendor/                         # Vendored MCP source code
│   ├── perplexity-agent-mcp/
│   └── browserless-mcp/
├── configs/                        # Reference configurations
│   ├── mcp/                        # MCP server inventory & architecture
│   ├── opencode/                   # OpenCode settings documentation
│   ├── shell/                      # Shell configuration
│   ├── git/                        # Git configuration & hooks
│   └── providers/                  # AI provider configuration
├── docs/                           # Complete documentation system
│   ├── WORKBENCH_CHARTER.md        # Governance: mission, principles, requirements
│   ├── security-model.md           # Security architecture & threat model
│   ├── IMPROVEMENT_BACKLOG.md      # Tracked improvements and fixes
│   ├── CHANGELOG_WORKBENCH.md      # Append-only change history
│   ├── architecture/               # System documentation (incl. clone-mcp.md)
│   ├── recovery/                   # Recovery procedures (4 docs)
│   ├── prompts/                    # Operational prompt library (9 prompts)
│   └── backup-reports/             # Dated backup snapshots
├── scripts/                        # Automation scripts
│   ├── backup/                     # Master backup script
│   ├── inventory/                  # Auto-generate inventories (software, env, MCP, OpenCode)
│   ├── security/                   # Secret pattern scanner
│   ├── recovery/                   # Recovery validation
│   └── maintenance/                # Config sync, routine tasks
├── .github/workflows/              # CI (docs, inventory, gitleaks, mcp-server)
├── opencode.json                   # OpenCode configuration (MCP servers)
├── AGENTS.md                       # OpenCode agent instructions
└── README.md                       # This file

含まれるもの

カテゴリ	詳細
OpenCode	最新の安定版 CLI、DeepSeek V4 Pro モデル、LSP 有効
MCP サーバー	35 個設定済み（33 個有効、2 個無効）、リモート 9 個 + ローカル 26 個
エージェントスキル	.opencode/skills/ に再利用可能なスキルを 45 個配置
インフラストラクチャ	PostgreSQL 16（Docker）、Browserless Chromium（Docker）
ツール	pandoc、jq、miller、sqlite3、GitHub CLI、Playwright Chromium
プロンプト	docs/prompts/ に運用プロンプトを 9 個配置

ワークステーションのガバナンス

このワークステーションは正式な憲章に基づいて運用されています。主な原則は次のとおりです。

• 信頼できる唯一の情報源：ランタイムはリポジトリと一致している必要があります。差異はバグです。
• シークレットをディスクに保存しない：すべてのシークレットはビルドボックスの Secrets を通じて受け渡します。
• 変更履歴は不変：変更履歴は追記のみです。すべての変更を追跡できます。
• ドキュメントはコードとともに管理：ドキュメントには、想定ではなく実際のシステムを記述します。

憲章の全文はこちら：docs/WORKBENCH_CHARTER.md

バックアップのワークフロー

# Master backup — full inventory, security scan, commit prep
bash scripts/backup/run-master-backup.sh

# Quick backup — save state before risky operations
bash scripts/maintenance/sync-runtime-config.sh && \
  git diff > /tmp/quick-backup-$(date +%Y%m%d).diff

または OpenCode のプロンプトを使用します。

• docs/prompts/RUN_MASTER_BACKUP.md — AI を使用してバックアップを実行
• docs/prompts/QUICK_BACKUP.md — 状態をすばやく保存

復旧のワークフロー

ビルドボックスが削除された状態を想定します。残るのは Git リポジトリとビルドボックスの Secrets のみです。

# 1. Create new build box
gh SWAS create --repo simonmak-ascent/opencode-workbench --machine basicLinux32gb

# 2. Wait for automation (3-5 min)

# 3. If needed (usually done by setup.sh):
npx playwright install chromium
# Vercel MCP uses VERCEL_ACCESS_TOKEN (token auth — no OAuth step)

# 4. Validate recovery
bash scripts/recovery/validate-recovery.sh

詳細はこちら：docs/recovery/RECOVERY_PLAYBOOK.md

MCP アーキテクチャ

種類	数	備考
リモート	9	context7、gh_grep、vdd、exa、cloudflare、clerk、vercel（トークン認証）、sentry、stripe
ローカル	26	npm／ベンダー提供／バイナリの stdio サーバー

合計：35 個設定済み（33 個有効、2 個無効：google-search、google-workspace）。

参照：docs/architecture/mcp-inventory.md

シークレット管理

すべてのシークレットはビルドボックスの Secrets に保存します。リポジトリ内のファイルには保存しません。

#	シークレット	使用先
1	DEEPSEEK_API_KEY	OpenCode（プライマリモデル）
2	OPENCODE_API_KEY	OpenCode Zen／Console Go プロバイダー
3	SIMONMAK_ASCENT_PAT	GitHub MCP、shadcn MCP、gh
4	PERPLEXITY_API_KEY	Perplexity MCP
5	BRAVE_API_KEY	Brave Search MCP
6	BROWSERLESS_TOKEN	Browserless MCP + コンテナー
7	SENTRY_AUTH_TOKEN	Sentry MCP
8	VERCEL_ACCESS_TOKEN	Vercel MCP（トークン認証）

オプトインサーバー用の追加キー（EXA_API_KEY、CLOUDFLARE_API_TOKEN、 STRIPE_SECRET_KEY、SURREAL_*、ALIBABA_CLOUD_*、AZURE_*、FIRECRAWL_API_KEY、 FRED_API_KEY、COMPANIES_HOUSE_API_KEY）は、値ではなく名前を docs/architecture/secrets.md に記載しています。

参照：docs/architecture/secrets.md

ドキュメント一覧

ドキュメント	目的
docs/WORKBENCH_CHARTER.md	ミッション、原則、ガバナンス
docs/security-model.md	セキュリティアーキテクチャ、脅威モデル、インシデント対応
docs/IMPROVEMENT_BACKLOG.md	追跡中の改善項目と技術的負債
docs/CHANGELOG_WORKBENCH.md	完全な変更履歴
docs/architecture/	システムドキュメント（インベントリ文書 10 件）
docs/recovery/	復旧手順書、災害復旧、チェックリスト、ギャップ分析
docs/prompts/	インデックス付きの運用プロンプト 9 件
docs/backup-reports/	日付付きバックアップスナップショット

ワークベンチへの追加

1. MCP サーバー：.devcontainer/setup.sh に npm パッケージを追加し、opencode.json に追加して、docs/architecture/mcp-inventory.md に記載します
2. エージェントスキル：.opencode/skills/<name>/SKILL.md を作成し、命名規則に従います
3. ツール：scripts/bootstrap-tools.sh に追加します
4. プロンプト：docs/prompts/ に作成し、prompt-index.md を更新します
5. 変更後は必ず CHANGELOG_WORKBENCH.md を更新し、マスターバックアップを実行します

復旧スコア：94/100

リポジトリとビルドボックスの Secrets のみを使用し、10 分未満での災害復旧を検証済みです。

Context7 での利用

最新の OpenCode Workbench ドキュメントは Context7 にインデックス化されているため、コーディングエージェントは必要に応じてコンテキストに取り込めます。Context7 MCP サーバーまたは ctx7 CLI をインストールしたら、プロンプトでライブラリ名を指定してください：

use library /simonmak-ascent/opencode-workbench for API and docs

ライセンス

MIT — LICENSE を参照してください。

---

Simon Mak によるツールです。

このツールが時間の節約に役立ったら、GitHub で ⭐ を付けていただけると、ほかの人にも見つけてもらいやすくなります。