OpenFace v0.4.0

OpenFace v0.4.0 covers the changes from v0.3.0 through the main commit that becomes the release tag. The center of this release is a usable agent boundary: MCP clients can read OpenFace through scoped tools and resources, perform narrowly defined writes with durable safety checks, and connect through either stateless Streamable HTTP or a local stdio adapter.

Highlights

• Discover published Pages from the home screen: OpenFace inspects the pages topic and recent repositories, reserves room for topic-less gh-pages and docs/ sites, checks publication state within a bounded budget, and distinguishes an empty directory from an unavailable upstream.
• Expose a caller-bound MCP contract: the official server provides catalog, repository, Knowledge, Issue, Space, Pages, Pipeline, metrics, and OpenAPI reads through scoped Tools and Resources. Every repository request rechecks the caller's current Forgejo access; unauthorized and absent private repositories remain indistinguishable.
• Make writes previewable, replayable, and non-duplicating: Issue, Space environment, Pages, and Pipeline controls use preview, confirmation, idempotency, operation ownership, durable leases, reconciliation, and secret-free audit records. An unknown upstream outcome stays non-dispatchable until an operator reconciles it.
• Package the endpoint for real clients: the openface-mcp distribution includes server, configuration validation, and a stateless stdio bridge. The bridge forwards each request independently, does not pass through MCP session headers, keeps credentials out of CLI arguments and diagnostics, and applies bounded forwarding and cancellation behavior.
• Keep two MCP replicas interchangeable: the Compose MCP profile runs two independent server processes behind the gateway. Shared write-safety, policy, audit, and operation state provides the coordination boundary, while stateless HTTP requests allow failover without sticky sessions.
• Operate token, policy, and audit state visibly: the administrator-only /admin/mcp console uses Forgejo administrator membership, fresh reauthentication, an internal secret bridge, allowlisted Forgejo token references, policy revisions, connection diagnostics, lifecycle operations, and filtered audit evidence.
• Verify clients and deployment paths: live evidence covers Codex, Claude Desktop, and VS Code startup/configuration paths, plus two-replica failover. The repository also adds reproducible MCP package and HA contract fixtures alongside the bilingual operator guides.

Operator impact

• The MCP services are opt-in under the mcp Compose profile. A deployment that does not enable that profile does not need an MCP service migration; enabling it adds the openface-mcp-state coordination volume and the registry, service-account, and administrator secret files described in the runbook.
• Grant each MCP subject only the required scopes and repository permissions. Keep the registry and state directory outside the repository, use an explicit OPENFACE_MCP_ALLOWED_ORIGINS allowlist for browser clients, and back up the state and its HMAC key together.
• Writes require the caller's current Forgejo permissions in addition to the MCP scope. Load Secret values from a trusted secret store and pass them directly to the protected tool; never put them in chat, Issues, source, shell history, logs, screenshots, or client configuration committed to Git.
• The local stdio path is the compatibility option for command-based clients. The remote static-Bearer endpoint does not claim Claude Desktop's remote custom connector/OAuth compatibility; use the documented stdio launcher for that client path.
• Roll out Space environment writers with a single writer or a fenced deployment while mixed generations are present. The existing Space environment guide now documents the expected_kind guard and generation-migration constraint.

Documentation

Read the OpenFace MCP Server guide, MCP high-availability guide, live MCP client QA record, MCP administration runbook, Unified API and authentication contract, and Space environment guide. The v0.4.0 walkthrough explains the design choices as one operator story.

Tooling and validation

The release candidate is checked with the bilingual documentation validator and VitePress production build, frontend lint/automation/build suites, MCP and Space runner tests, repository contract tests, Docker Compose validation, the MCP package workflow contract, SVG asset validation, and the release QA inventory. The final GitHub Release is published only after the docs deployment and live release URLs are verified.

Upgrade notes

No Forgejo repository or PostgreSQL migration is required for the documented MCP profile. Before enabling it, create the registry and secret files, set the absolute state path and allowed origins, start openface-mcp and mcp-admin through Compose, and issue least-privileged client tokens from the administrator flow. Existing clients should use the package's validate-config command and keep their token source in an OS secret store.

Upgrade contract

• Target path: v0.3.0 or a fresh install; do not skip the backup and verification steps.
• Breaking changes: none declared for the release; review the target diff and environment changes before upgrading.
• Data migration: v0.4.0 on the current develop base retains pipeline audit/history in the legacy SQLite file; it has no automatic PostgreSQL pipeline migration. A target release that explicitly includes PR #163 must stop the runner and follow the explicit pipeline_migration.py procedure before accepting new pipeline writes.
• Backup: dump forgejo, openface_metrics, and openface_maintenance, and archive the Forgejo, metrics, maintenance, shared-token, runner, and MCP state volumes plus the configured OPENFACE_MCP_STATE_DIR bind mount and protected MCP credential source files.
• Compose/volume: do not use docker compose down --volumes during an upgrade.
• Rollback: restore the previous images when schema-compatible; after a schema/data migration, restore the verified PostgreSQL dumps and named volumes instead of downgrading in place.
• Post-upgrade: compare repository/LFS, user, organization, Issue/PR/comment, Space, metrics, maintenance, and pipeline audit/history counts and representative IDs.
• Known issues: runtime desktop/mobile screenshots and real deployment queue/restore timings remain operator checks.

Follow the upgrade and data retention runbook and keep the Japanese release page in sync.