@akira-tl/forgerelay 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [1.1.1] - 2026-09-10
+
+### Added
+
+- Added standalone global and Project External MCP registries in `mcp.json` with hot reload, Project-over-global precedence, explicit `disabled` masking, whole-source last-known-good behavior, and permanent discovery of the existing `mcp.external` Capability even when the registry starts empty.
+- Added human-operated External MCP OAuth through `forgerelay mcp auth/logout`, including machine-private Project-scoped credentials, desktop loopback and masked headless callback flows, silent refresh with cross-process rotation protection, scope step-up, DCR compatibility, and optional CIMD client metadata for authorization servers that require it.
+- Added `forgerelay mcp list/test` and passive External MCP `doctor` diagnostics for resolved source, authentication state, configuration health, negotiated MCP protocol, tool discovery, and actionable failure reporting.
+
+### Changed
+
+- Migrated ForgeRelay's MCP runtime to the split MCP SDK v2 and Apps SDK v2, supporting MCP 2026-07-28 modern stateless HTTP alongside the existing legacy sessionful Host path while preserving legacy External MCP and Workspace Relay interoperability.
+- Modern stateless Host Turns now use stable Host conversation metadata when supplied and otherwise remain request-scoped instead of inferring conversation identity from transport or process lifetime. Legacy compatibility retains its bounded transport/session fallback behavior.
+- `config.json.mcpServers` remains a deprecated compatibility source; new External MCP configuration uses `mcp.json`, and relayed External MCP configuration, credentials, refresh, process launch, and upstream calls remain owned by the Execution ForgeRelay.
+
+### Security
+
+- External MCP OAuth credentials stay in private `mcp-auth.json` state rather than Project files, are bound to their Project/global identity plus resource/issuer state, and are never exposed through normal diagnostics. Interactive authorization remains human-only; runtime refresh cannot open a browser, and headless callback input is masked.
+- Project-defined stdio MCP servers are explicitly documented as executable project configuration, while static header/env secrets remain user-managed and External MCP paths, URLs, and resource references continue to be pass-through unless the Agent or an explicit Transform Hook acts on them.
+
+## [1.1.0] - 2026-09-09
+
+### Added
+
+- Added first-class image transport to the existing `read` tool for PNG, JPEG, WebP, and GIF, with magic-byte detection, unchanged image bytes, mixed bulk Read support, and explicit rejection of text ranges on image targets.
+- Added registered external MCP servers through the existing workspace-scoped `capability` surface, including direct upstream `ImageContent` forwarding without expanding the always-visible core tool list.
+- Added opt-in `ExternalMcpBeforeForward` and `ExternalMcpAfterForward` transform Hooks for server/tool-specific request or result adaptation while keeping path/URL/resource references pass-through by default.
+
+### Changed
+
+- Workspace Relay now preserves MCP image content opaquely through Execution → Gateway routing and re-applies the Gateway media budget before Host delivery.
+- Media payloads are transient MCP content rather than Artifacts: the default decoded-media budget is 20 MiB per tool result, aggregate media is bounded, and structured output, Activity/Audit, UI state, and logs retain metadata instead of image base64.
+
+### Security
+
+- External MCP errors, Hook transforms, Relay ingress, and image Reads now enforce bounded media validation without persisting raw image payloads or credentials, and external path/URL/resource results are never implicitly dereferenced by ForgeRelay.
+
 ## [1.0.1] - 2026-09-09
 
 ### Fixed

package/README.md

@@ -108,6 +108,7 @@ ForgeRelay 不会默认为每个任务创建 worktree。只有你明确要求隔
 - 项目里的 `AGENTS.md`、`CLAUDE.md` 和 Agent Skills 按需加载，不会每次都把整套说明重新塞进上下文。
 - 需要并行开发时可以创建真实 Git worktree；集成回主分支时只接受安全的 fast-forward，不自动制造 merge conflict。
 - Workspace Relay 可以把执行放到另一台 ForgeRelay；Composite Workspace 可以同时协调几个独立环境。
+- `read` 可以直接把 PNG、JPEG、WebP 和 GIF 作为临时 MCP Media content 返回；外部 MCP 通过独立的 global/Project `mcp.json` 热加载到 `mcp.external` Capability，并支持人工 OAuth 认证，而不会自动打开它返回的路径或 URL。
 
 Lifecycle Hooks、Workspace Tasks、本地 Subagent、Activity/Audit、Checkpoint 和 Recovery 也已经包含在项目里，但第一次安装时不需要先学这些。需要哪个，再去 [Wiki](https://github.com/Akira-TL/forgerelay/wiki) 查哪个。
 
@@ -127,6 +128,7 @@ ForgeRelay 默认拒绝 elevated / administrator 启动。只有你显式选择
 
 - [快速开始](https://github.com/Akira-TL/forgerelay/wiki/Getting-Started)
 - [配置](https://github.com/Akira-TL/forgerelay/wiki/Configuration)
+- [External MCP](https://github.com/Akira-TL/forgerelay/wiki/External-MCP)
 - [安全模型](https://github.com/Akira-TL/forgerelay/wiki/Security)
 - [故障排查](https://github.com/Akira-TL/forgerelay/wiki/Troubleshooting)
 - [完整 Wiki](https://github.com/Akira-TL/forgerelay/wiki)
@@ -220,6 +222,7 @@ Long commands do not require tight polling either. Once the current wait window
 - `AGENTS.md`, `CLAUDE.md`, and Agent Skills are loaded as needed instead of being resent in full on every open.
 - Managed worktrees provide real Git isolation when you ask for parallel work, with fast-forward-only finalization.
 - Workspace Relay runs work on another ForgeRelay instance; Composite Workspaces coordinate several independent environments from one Host.
+- `read` can return PNG, JPEG, WebP, and GIF directly as transient MCP Media content; external MCP servers hot-reload from standalone global/Project `mcp.json` files into the `mcp.external` Capability, with explicit human OAuth when needed and no automatic dereferencing of returned paths or URLs.
 
 Lifecycle Hooks, Workspace Tasks, local Subagents, Activity/Audit, checkpoints, and recovery are included too. They are optional parts of the workflow; the [Wiki](https://github.com/Akira-TL/forgerelay/wiki) documents them when you need them.
 
@@ -239,6 +242,7 @@ See the [Security model](https://github.com/Akira-TL/forgerelay/wiki/Security) f
 
 - [Getting Started](https://github.com/Akira-TL/forgerelay/wiki/Getting-Started)
 - [Configuration](https://github.com/Akira-TL/forgerelay/wiki/Configuration)
+- [External MCP](https://github.com/Akira-TL/forgerelay/wiki/External-MCP)
 - [Security model](https://github.com/Akira-TL/forgerelay/wiki/Security)
 - [Troubleshooting](https://github.com/Akira-TL/forgerelay/wiki/Troubleshooting)
 - [Full Wiki](https://github.com/Akira-TL/forgerelay/wiki)

package/capabilities/host-integration/external-mcp/GUIDE.md

@@ -0,0 +1,29 @@
+# External MCP
+
+Use `mcp.external` only for MCP servers the user has already configured in ForgeRelay. The Host remains the orchestrator: discover the configured server/tool surface, then explicitly choose the server, tool, and arguments for each call.
+
+## Operations
+
+- `servers` — list configured server names and transport kinds. Connection details and credentials are not returned.
+- `tools` — list the tools advertised by one configured server.
+- `call` — invoke one tool that the selected configured server currently advertises.
+
+## Boundaries
+
+- A capability call cannot supply a new MCP command, URL, credential, or connection target. Those belong to user configuration.
+- ForgeRelay forwards the upstream MCP result. A path, URL, resource identifier, or textual file reference stays a reference; ForgeRelay does not automatically fetch it, call `read`, infer that it is an image, or create an Artifact.
+- When an upstream result names an accessible Workspace file and you need its contents, make an explicit ForgeRelay `read` call.
+- Direct upstream `ImageContent` for PNG, JPEG, WebP, and GIF is forwarded as transient Media content after MIME/base64 validation and the configured aggregate media budget. Image base64 exists only in the live MCP result; structured/Activity state keeps bounded MIME/byte metadata.
+- Audio and arbitrary binary-resource forwarding are outside this Media contract. A path, URL, `resource_link`, or other non-media reference is not upgraded into an image automatically.
+- ForgeRelay does not autonomously chain external MCP tools or retry through another configured server.
+- External MCP processes/services keep the operating-system and network authority with which the user configured them. Routing through ForgeRelay does not make them a ForgeRelay filesystem sandbox.
+- Hook policy may inspect or block Capability calls. Server/tool-specific transforms use the explicit `ExternalMcpBeforeForward` / `ExternalMcpAfterForward` contract; ordinary Hook stdout never rewrites MCP data.
+
+## Optional transform Hooks
+
+Transform Hooks are opt-in user policy for one configured external MCP server/tool. Match them with `tool: "capability"`, `capability: "mcp.external"`, `externalServer`, and `externalTool`. ForgeRelay passes the current transform value over stdin as versioned JSON and accepts one structured stdout envelope only.
+
+- Before forward: stdout must be `{"version":1,"request":{"arguments":{...}}}`. Only arguments can change; the configured server/tool target cannot.
+- After forward: stdout must be `{"version":1,"result":{...}}`. The transformed result is revalidated as an MCP result and any ImageContent is rechecked against the normal MIME/base64/media-budget rules.
+- A transform command may deliberately read a renderer-owned path or perform other work using the command's own OS authority. That is explicit Hook behavior, not an implicit ForgeRelay `read`, fetch, or Artifact operation.
+- Activity/log state records only bounded transform identity/status metadata. Transform stdin/stdout, arbitrary upstream payloads, credentials, and image base64 are not persisted by ForgeRelay.

package/capabilities/lifecycle-hooks/GUIDE.md

@@ -22,17 +22,27 @@
 - 可选 timeout；
 - 可选 `report`，默认 `true`。
 
-当前事件包括：`WorkspaceOpen`、`BeforeTool`、`AfterTool`、`AfterToolFailure`、`AfterFileChange`、`BeforeWorktreeClose`、`AfterWorktreeClose`、`SubagentStart`、`SubagentStop`。
+当前事件包括：`WorkspaceOpen`、`BeforeTool`、`AfterTool`、`AfterToolFailure`、`ExternalMcpBeforeForward`、`ExternalMcpAfterForward`、`AfterFileChange`、`BeforeWorktreeClose`、`AfterWorktreeClose`、`SubagentStart`、`SubagentStop`。
+
+External MCP transform 事件只用于 `mcp.external`。matcher 可额外使用 `capability`、`externalServer`、`externalTool`，从而绑定到已配置的 Capability/server/tool；这些字段只是现有目标的匹配条件，不能动态指定新的连接目标。
 
 ## 阻断与报告
 
-`BeforeTool` 和 `BeforeWorktreeClose` 是阻断事件。命中的 Hook 失败或超时后，原操作不会继续。其他 after-event 只观察已经发生的结果，失败不会伪装成能够回滚先前副作用。
+`BeforeTool`、`BeforeWorktreeClose` 以及两个 External MCP transform 事件都会在失败时令当前操作失败。Before-forward transform 失败时 upstream MCP call 不会发生；After-forward transform 失败时 upstream call 已经发生，只会阻止变换后结果继续交付并把 Capability 标成失败，不能声称回滚 upstream 已产生的副作用。其他普通 after-event 只观察已经发生的结果，失败也不会伪装成能够回滚先前副作用。
 
 Hook report 会随工具结果返回给 Host/Agent。`report: false` 只隐藏成功的高频报告；阻断失败始终可见。Agent 看到有意义的 Hook report 时必须告诉用户哪些 Hook 运行了、是否通过，以及操作是否被阻断；不能在 blocking Hook 阻止操作后声称原操作成功。
 
+## External MCP transform 协议
+
+普通 Hook 的 stdout 仍然只是命令输出，**不会**改写工具结果。只有 `ExternalMcpBeforeForward` / `ExternalMcpAfterForward` 使用显式 structured transform 协议：ForgeRelay 将 versioned JSON 写入 Hook stdin，并只接受 stdout 中一个合法 JSON envelope。
+
+- request phase 输入包含当前 `server`、`tool` 与 `request.arguments`；输出必须是 `{"version":1,"request":{"arguments":{...}}}`。server/tool 不能被改写。
+- result phase 输入包含当前 upstream MCP result；输出必须是 `{"version":1,"result":{...}}`。输出随后重新经过标准 MCP result、Media MIME/base64 与 `mediaMaxBytes` 校验。
+- Hook 环境中的 `FORGERELAY_HOOK_PAYLOAD` 只包含 Capability/server/tool/phase 等有界匹配元数据；任意 arguments、upstream payload 和 image base64 只通过 transform stdin/stdout 瞬态传递。
+
 ## 安全边界
 
-项目 Hook 属于项目执行约定，不需要额外审批，但不能扩大 allowed roots、覆盖认证边界或替换机器级全局规则。Hook command 与 shell 一样以运行 ForgeRelay 的本地用户权限执行；工作区文件边界不等于 OS sandbox。
+项目 Hook 属于项目执行约定，不需要额外审批，但不能扩大 allowed roots、覆盖认证边界或替换机器级全局规则。Hook command 与 shell 一样以运行 ForgeRelay 的本地用户权限执行；工作区文件边界不等于 OS sandbox。Transform Hook 如果主动读取文件或访问网络，那是该用户配置命令自身的 OS 权限，不代表 ForgeRelay 自动获得了新的 `read` 或网络权限。
 
 ## 检查入口
 

package/dist/activity/runtime/mcp-query-tools.js

@@ -1,5 +1,6 @@
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import * as z from "zod/v4";
+import { mcpHandlerRequestContext } from "../../mcp/request-context.js";
 import { logEvent, transportSessionIdPrefix } from "../../runtime/logging/logger.js";
 import { hostConversationScopeId } from "../../mcp/request-meta.js";
 import { ACTIVITY_PANEL_DEFAULT_EXPANDED_META_KEY, ACTIVITY_PANEL_WORKSPACE_META_KEY, } from "../ui/contract.js";
@@ -68,11 +69,12 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
             idempotentHint: false,
         },
     }, async ({ workspaceId }, extra) => {
+        const requestContext = mcpHandlerRequestContext(extra);
         const workspace = workspacePanelState?.(workspaceId);
         if (!workspace) {
             throw new Error(`No Workspace presentation is available for ${workspaceId}. Call open_workspace for that workspace before activity_panel.`);
         }
-        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const conversationScopeId = hostConversationScopeId(requestContext, connectionScopeId);
         const relayed = await relay?.panel(workspaceId, conversationScopeId);
         if (relayed) {
             return {
@@ -91,7 +93,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
                 revision: snapshot.revision,
                 state: snapshot.state,
                 workspaceId,
-                transportSessionIdPrefix: transportSessionIdPrefix(extra.sessionId),
+                transportSessionIdPrefix: transportSessionIdPrefix(requestContext.transportSessionId),
             });
         }
         return {
@@ -118,7 +120,8 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         _meta: { ui: { visibility: ["app"] } },
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, workspaceId, knownRevision }, extra) => {
-        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const requestContext = mcpHandlerRequestContext(extra);
+        const conversationScopeId = hostConversationScopeId(requestContext, connectionScopeId);
         const relayed = await relay?.snapshot({ turnId, workspaceId, knownRevision }, conversationScopeId);
         if (relayed) {
             const workspace = workspaceId ? workspacePanelState?.(workspaceId) : undefined;
@@ -149,7 +152,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
                 revision: snapshot.revision,
                 changed: snapshot.changed,
                 state: snapshot.state,
-                transportSessionIdPrefix: transportSessionIdPrefix(extra.sessionId),
+                transportSessionIdPrefix: transportSessionIdPrefix(requestContext.transportSessionId),
             });
         }
         const workspace = workspaceId ? workspacePanelState?.(workspaceId) : undefined;
@@ -176,7 +179,8 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         _meta: { ui: { visibility: ["app"] } },
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, knownRevision }, extra) => {
-        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const requestContext = mcpHandlerRequestContext(extra);
+        const conversationScopeId = hostConversationScopeId(requestContext, connectionScopeId);
         const relayed = await relay?.index(turnId, knownRevision, conversationScopeId);
         if (relayed)
             return relayed;
@@ -189,7 +193,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
                 changed: index.changed,
                 state: index.state,
                 activities: index.activities.length,
-                transportSessionIdPrefix: transportSessionIdPrefix(extra.sessionId),
+                transportSessionIdPrefix: transportSessionIdPrefix(requestContext.transportSessionId),
             });
         }
         return {
@@ -213,7 +217,8 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         _meta: { ui: { visibility: ["app"] } },
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, activityId }, extra) => {
-        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const requestContext = mcpHandlerRequestContext(extra);
+        const conversationScopeId = hostConversationScopeId(requestContext, connectionScopeId);
         const relayed = await relay?.detail(turnId, activityId, conversationScopeId);
         if (relayed)
             return relayed;
@@ -225,7 +230,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
                 tool: detail.activity.tool,
                 kind: detail.activity.kind,
                 state: detail.activity.state,
-                transportSessionIdPrefix: transportSessionIdPrefix(extra.sessionId),
+                transportSessionIdPrefix: transportSessionIdPrefix(requestContext.transportSessionId),
             });
         }
         return {
@@ -258,7 +263,8 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         _meta: { ui: { visibility: ["app"] } },
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, outputId, cursor }, extra) => {
-        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const requestContext = mcpHandlerRequestContext(extra);
+        const conversationScopeId = hostConversationScopeId(requestContext, connectionScopeId);
         const relayed = await relay?.output(turnId, outputId, conversationScopeId, cursor);
         if (relayed)
             return relayed;
@@ -273,7 +279,7 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
                 processId: output.processId,
                 status: output.status,
                 outputBytes: Buffer.byteLength(output.output),
-                transportSessionIdPrefix: transportSessionIdPrefix(extra.sessionId),
+                transportSessionIdPrefix: transportSessionIdPrefix(requestContext.transportSessionId),
             });
         }
         return {