furlow-mcp

FURLOW

宣言型 Discord ボットフレームワーク

YAML で高機能な Discord ボットを構築できます。コードは不要です。

commands:
  - name: ping
    description: Check bot latency
    actions:
      - reply:
          content: "Pong! ${client.ws.ping}ms"

特長

• 85 個のアクション：メッセージ、モデレーション、ボイス、チャンネルなど
• 71 個の式関数：日付、数学、文字列、配列の操作
• 50 個の変換：パイプベースのデータ変換
• Discord ゲートウェイ、ボイスの遷移、コンポーネントのインタラクション、FURLOW の高レベルイベント（automod、scheduler、pipes）にわたる 59 個のイベント
• スコープ付き状態：グローバル、ギルド、チャンネル、ユーザー、メンバーのスコープ
• フロー：パラメーターを使用した再利用可能なアクションシーケンス
• 外部連携：HTTP、WebSocket、MQTT、TCP/UDP、Webhook

クイックスタート

# Install the CLI
npm install -g @furlow/cli

# Create a bot
furlow init my-bot
cd my-bot

# Add your Discord credentials to .env
echo "DISCORD_TOKEN=your_token_here" > .env
echo "DISCORD_CLIENT_ID=your_client_id_here" >> .env

# Start
furlow start

例

version: "0.1"

identity:
  name: "My Bot"

presence:
  status: online
  activity:
    type: playing
    text: "with FURLOW"

commands:
  - name: hello
    description: Greet someone
    options:
      - name: user
        type: user
        description: Who to greet
    actions:
      - reply:
          content: "Hello, ${options.user.display_name || options.user.username}!"

  - name: roll
    description: Roll a dice
    options:
      - name: sides
        type: integer
        description: Number of sides
        min_value: 2
        max_value: 100
    actions:
      - reply:
          content: "🎲 You rolled **${random(1, options.sides || 6)}**"

events:
  - event: member_join
    actions:
      - send_message:
          channel: "${env.WELCOME_CHANNEL}"
          content: "Welcome ${member.displayName}!"

CLI コマンド

コマンド	説明
furlow init [name]	新しいボットプロジェクトを作成します
furlow start [path]	ボットを実行します
furlow dev [path]	ホットリロードを使用する開発モードで実行します
furlow validate <path>	YAML 仕様を検証します
furlow add <builtin>	ビルトインモジュールを追加します
furlow build [path]	デプロイ用にバンドルします
furlow export <path>	Discord コマンドの JSON をエクスポートします

ドキュメント

ガイド	説明
インストール	セットアップと要件
クイックスタート	最初のボット
設定	YAML 仕様
アクションリファレンス	85 個すべてのアクション
式リファレンス	関数と変換
イベントリファレンス	イベントの種類
CLI リファレンス	コマンドラインインターフェース
Pipes リファレンス	外部連携
例	ボットの完全な例

パッケージ

パッケージ	説明
furlow	CLI ツール
@furlow/core	ランタイムエンジン
@furlow/discord	Discord.js アダプター
@furlow/schema	TypeScript 型
@furlow/storage	データベースアダプター
@furlow/builtins	事前構築済みモジュール
@furlow/pipes	HTTP、WebSocket、MQTT、TCP/UDP、Webhook、データベース、ファイル
@furlow/testing	テストユーティリティ

本番環境へのデプロイ

ボットを本番環境にリリースするための簡単なチェックリストです。各項目はランタイムの保証に対応しています。項目を省略すると、後になってデータが気づかれないまま失われたり、機能がスケジュールどおりに動作しなかったり、セッションが公開状態で偽造可能になったりすることがあります。

必須環境変数

# Discord
DISCORD_TOKEN=...
DISCORD_CLIENT_ID=...

# Storage (pick one)
DATABASE_URL=postgres://user:pass@host:5432/furlow   # production
# or for single-server bots:
SQLITE_PATH=/var/lib/furlow/bot.db

# Dashboard (only if running the web UI)
DASHBOARD_SECRET=$(openssl rand -hex 32)             # required in NODE_ENV=production
DISCORD_CLIENT_SECRET=...
DISCORD_CALLBACK_URL=https://dashboard.example.com/auth/discord/callback

ダッシュボードは、DASHBOARD_SECRET が設定されていない状態で NODE_ENV=production の場合、起動を拒否します。フォールバックのデフォルト値はありません。WebSocket 接続にも認証済みセッションが必要です。認証されていないクライアントはアップグレード時に拒否され、ギルドストリームを購読できません。

ストレージ

• 複数のプロセスを実行するデプロイ、または特定時点への復旧が必要なデプロイでは、Postgres を使用してください。SQLite アダプターは単一サーバーのボットやテストには適していますが、アクティブユーザーが数千人を超えると、書き込み競合によってパフォーマンスが急速に低下します。
• デプロイ時にデータベースのマイグレーションを実行してください。SQLite アダプターは必要に応じてテーブルを作成しますが、Postgres のデプロイでは state.tables: ブロックで定義されたテーブルを事前に作成してください。
• データベースをバックアップしてください。ビルトインは実際の状態（警告、レベル、AFK ステータス、チケットの記録）を永続化します。これらはどれも再構築できません。

スケジュールと音声

• CLI は CronScheduler を起動し、60 秒ごとに scheduler_tick を発行します。 これに依存する組み込み機能（giveaways、polls、reminders）を利用するには、スケジューラーが実行されている必要があります。別個の cron プロセスはありません。
• 音声再生には、@discordjs/voice のピア依存関係と、PATH 上の ffmpeg が必要です。 music 組み込み機能が使用する voice_track_start / voice_track_end イベントは、音声マネージャーが初期化されている場合にのみ発生します。

プロセスの監視

• furlow start は、終了時に再起動するプロセス監視ツール（systemd、pm2、Kubernetes Deployment）で実行してください。ボットは自身をデーモン化しません。
• SIGTERM を転送して、ゲートウェイ接続が正常に終了するようにしてください。CLI はシャットダウン時に保留中の状態をフラッシュします。SIGKILL で強制終了すると、最後のバッチ書き込みが失われる可能性があります。

ダッシュボードのセキュリティ強化

• ダッシュボードの前段で TLS を終端してください（nginx、Caddy、ロードバランサー）。 本番環境ではセッション Cookie に secure: true が設定され、平文 HTTP では送信されません。
• Discord 開発者ポータルで、OAuth コールバック URL を実際に使用する DISCORD_CALLBACK_URL の完全一致に制限してください。
• POST エンドポイントでは、受け付けるフィールドをホワイトリストに登録し、不明なキーや型が異なるキーを 400 で拒否します。設定の構造を拡張する場合は、apps/dashboard/server/routes/api.ts のホワイトリストを更新してください。

可観測性

• /health はプロセスの稼働時間を返します。これをライブネスプローブに接続してください。
• /metrics は Prometheus 形式のカウンターを公開します。ダッシュボードプロセスを対象とするスクレイプジョブを追加してください。
• CLI は、インシデントのトリアージ中にイベントごとの構造化ログを記録するための --verbose をサポートしています。

ライセンス

MIT