OpenFace v0.4.0

OpenFace v0.4.0は、v0.3.0から今回のrelease tagになるmain commitまでの変更をまとめます。中心にあるのは、agentが使える安全な境界です。MCP clientはscope付きTool／ResourceでOpenFaceをreadし、durableな安全確認を通した狭いwriteを実行し、statelessなStreamable HTTPまたはlocal stdio adapterで接続できます。

ハイライト

• ホームから公開Pagesを探す: pages topicと最近のrepositoryを調べ、topicのないgh-pages／docs/サイト用の枠も確保します。有限budget内で公開状態を確認し、空の一覧とupstream取得不能を区別します。
• callerに紐づいたMCP contract: 公式serverはcatalog、repository、Knowledge、Issue、Space、Pages、Pipeline、metrics、OpenAPIのreadを、scope付きTool／Resourceとして提供します。全repository requestで現在のForgejo権限を再確認し、権限のないprivate repositoryと存在しないrepositoryを同じ形で扱います。
• writeをpreview可能・replay可能・重複なしにする: Issue、Space environment、Pages、Pipelineのcontrolは、preview、confirmation、idempotency、operation ownership、durable lease、reconciliation、Secretを含まないaudit recordを使います。upstreamの結果が不明な場合は、operatorがreconcileするまで再dispatchできません。
• 実際のclient向けにpackage化: openface-mcp distributionにはserver、configuration validation、stateless stdio bridgeが含まれます。bridgeはrequestごとに独立してforwardし、MCP session headerを透過せず、CLI引数やdiagnosticへcredentialを出さず、forwarding queueとcancellationを有限に扱います。
• 2つのMCP replicaを入れ替え可能にする: ComposeのMCP profileはgatewayの背後で独立したserver processを2つ動かします。共有されたwrite-safety、policy、audit、operation stateをcoordination boundaryとし、stateless HTTPによってsticky sessionなしにfailoverできます。
• token、policy、audit stateを見える形で運用: administrator専用/admin/mcp consoleは、Forgejo administrator membership、fresh reauthentication、internal secret bridge、allowlist済みForgejo token reference、policy revision、connection diagnostics、lifecycle操作、filter付きaudit evidenceを使います。
• clientと配備経路を検証: Codex、Claude Desktop、VS Codeの起動／設定経路と2-replica failoverのlive evidenceを追加しました。MCP packageとHAのcontract fixture、日英のoperator guideも揃えています。

運用への影響

• MCP serviceはmcp Compose profileでopt-inです。profileを有効にしない既存配備にはMCP serviceのmigrationは不要です。有効化すると、runbookに記載したopenface-mcp-state coordination volume、registry、service-account／administrator Secret fileが必要になります。
• 各MCP subjectには必要なscopeとrepository権限だけを付与してください。registryとstate directoryはrepository外に置き、browser clientには明示的なOPENFACE_MCP_ALLOWED_ORIGINS allowlistを使い、stateとHMAC keyを一緒にbackupします。
• writeにはMCP scopeだけでなく、現在のForgejo permissionも必要です。Secret値はtrusted secret storeから直接protected toolへ渡し、chat、Issue、source、shell history、log、screenshot、Gitへcommitするclient configへ入れないでください。
• local stdio pathはcommand型client向けのcompatibility経路です。remote static-Bearer endpointはClaude Desktopのremote custom connector／OAuth compatibilityを保証しません。Claude Desktopではdocumented stdio launcherを使ってください。
• Space environment writerを混在世代のままroll outしないでください。single writerに限定するかdeployment中のwriteをfenceし、expected_kind guardとgeneration migrationの制約を既存Space environment guideで確認します。

ドキュメント

OpenFace MCP Server guide、MCP high availability guide、実MCP client QA記録、MCP管理Runbook、統一APIと認証contract、Space environment guideを参照してください。v0.4.0解説では、これらの設計判断を一つの運用storyとして説明します。

toolingと検証

release candidateは、日英documentation validatorとVitePress production build、frontend lint／automation／build、MCPとSpace runnerのtest、repository contract test、Docker Compose validation、MCP package workflow contract、SVG asset validation、release QA inventoryで確認します。GitHub Releaseはdocs deploymentと公開release URLを確認してから公開します。

Upgrade notes

記載したMCP profileのためにForgejo repositoryやPostgreSQLのmigrationは必要ありません。有効化前にregistryとSecret fileを作成し、absoluteなstate pathとallowed originsを設定し、Composeからopenface-mcpとmcp-adminを起動し、administrator flowで最小権限のclient tokenを発行してください。既存clientはpackageのvalidate-config commandを使い、token sourceはOSのsecret storeで管理します。

Upgrade契約

• 対象経路: v0.3.0からの更新またはfresh install。backupと確認を省略しない。
• Breaking change: このreleaseで宣言するbreaking changeはない。更新前にtarget diffとenvironment変更を確認する。
• Data migration: 現在のdevelop baseのv0.4.0ではpipeline audit/historyはlegacy SQLiteに残り、PostgreSQLへのautomatic migrationはありません。PR #163を明示的に含むtarget releaseだけ、runnerを停止し、新しいpipeline writeを受け付ける前に明示的なpipeline_migration.py手順を実行します。
• Backup: forgejo、openface_metrics、openface_maintenance dumpと、Forgejo、metrics、maintenance、shared-token、runner、MCP state volume、設定済みOPENFACE_MCP_STATE_DIR bind mount、保護されたMCP credential source fileのarchiveを作成します。
• Compose/volume: 更新中にdocker compose down --volumesを使わない。
• Rollback: schema互換なら旧imageへ戻す。schema/data migration後はin-place downgradeせず、検証済みPostgreSQL dumpとnamed volumeをrestoreする。
• 更新後: repository/LFS、user、organization、Issue/PR/comment、Space、metrics、maintenance、pipeline audit/historyの件数と代表IDを比較する。
• 既知の注意: 実runtimeのdesktop/mobile screenshotと、実deploymentのqueue／restore時間は運用者確認とする。

Upgradeとデータ保持のrunbookを使い、日本語／英語のrelease pageを同期します。