Merge pull request #43 from lynnswap:codex/proxy-handshake-config

feat(proxy): add configurable upstream handshake

Author: lynnswap

Docs/troubleshooting.md

@@ -82,8 +82,5 @@ When the proxy runs in `--refresh-code-issues-mode upstream`, Xcode's live diagn
 - If a client bursts too many queued refreshes for the same tab in `upstream` mode, the proxy may return `refresh queue overloaded` instead of letting the queue grow without bound.
 - If you need Xcode's native live diagnostics behavior, start the proxy with `--refresh-code-issues-mode upstream` (or `MCP_XCODE_REFRESH_CODE_ISSUES_MODE=upstream`).
 
-## Xcode dialog does not appear
-Make sure `--lazy-init` is not set (when enabled, the dialog appears on the first request instead of at startup).
-
 ## `session not found`
 Ensure the client is using the same session.

Package.resolved

@@ -35,6 +35,7 @@ let package = Package(
     dependencies: [
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.5.0"),
+        .package(url: "https://github.com/dduan/TOMLDecoder.git", from: "0.4.3"),
     ],
     targets: [
         .target(
@@ -51,6 +52,7 @@ let package = Package(
                 .product(name: "Logging", package: "swift-log"),
                 .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
                 .product(name: "NIO", package: "swift-nio"),
+                .product(name: "TOMLDecoder", package: "TOMLDecoder"),
             ],
             path: "Sources/ProxyCore",
             swiftSettings: strictSwiftSettings

Package.swift

@@ -116,32 +116,47 @@ claude mcp add --transport stdio xcode -- xcode-mcp-proxy
 - max body size: `1048576` bytes
 - initialization: eager at startup
 - discovery: `~/Library/Caches/XcodeMCPProxy/endpoint.json`
+
+#### オプション
+
+| オプション | 説明 |
+|--------|-------------|
+| `--upstream-command cmd` | `mcpbridge` 実行コマンド |
+| `--upstream-args a,b,c` | `mcpbridge` 引数（カンマ区切り） |
+| `--upstream-arg value` | `mcpbridge` 引数の追加（単一項目） |
+| `--upstream-processes n` | アップストリーム `mcpbridge` プロセスの起動数（デフォルト: 1、最大: 10） |
+| `--session-id id` | 明示的な Xcode MCP セッション ID |
+| `--max-body-bytes n` | リクエストボディの最大サイズ |
+| `--request-timeout seconds` | リクエストタイムアウト設定（`0` で初期化以外のタイムアウトを無効化。`initialize` 時のハンドシェイクには固定のタイムアウトが適用されます） |
+| `--config path` | アップストリームのハンドシェイクを上書きするためのプロキシ設定（TOML）のパス |
+| `--refresh-code-issues-mode mode` | `XcodeRefreshCodeIssuesInFile` の提供モード。プロキシ側のナビゲーター問題として処理（`proxy`、デフォルト）、または Xcode のライブ診断へパススルー（`upstream`） |
+| `--force-restart` | ポートが使用中の場合、既存の `xcode-mcp-proxy-server` を終了して再起動 |
+
 #### 環境変数
 
-- `MCP_XCODE_PID`（`--xcode-pid` の代替）
-- `MCP_XCODE_SESSION_ID`（Xcode MCP セッション ID を固定。通常は不要）
-- `MCP_XCODE_REFRESH_CODE_ISSUES_MODE`（`proxy` または `upstream`。`XcodeRefreshCodeIssuesInFile` の実装モードを切り替え）
-- `MCP_LOG_LEVEL`（ログレベル: trace|debug|info|notice|warning|error|critical）
+| 変数 | 説明 |
+|------|------|
+| `LISTEN` | listen アドレス。例: `127.0.0.1:8765` |
+| `HOST` | listen ホスト。`LISTEN` 未指定時に `PORT` と組み合わせて使用 |
+| `PORT` | listen ポート。`LISTEN` 未指定時に `HOST` と組み合わせて使用 |
+| `MCP_XCODE_PID` | upstream `mcpbridge` へそのまま渡す互換 env。proxy 自身は解釈しない |
+| `MCP_XCODE_SESSION_ID` | 任意の明示的 upstream session ID |
+| `MCP_XCODE_CONFIG` | proxy config TOML のパス。`--config` が優先 |
+| `MCP_XCODE_REFRESH_CODE_ISSUES_MODE` | `proxy` または `upstream` |
+| `MCP_LOG_LEVEL` | ログレベル: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical` |
 
 ログは stderr に出力されます。
 
-Note: `--upstream-processes` > 1 を使う場合、`--session-id` / `MCP_XCODE_SESSION_ID` でセッション ID を固定すると、Xcode の許可ダイアログを減らせる場合があります。
+#### Proxy Config
 
-#### オプション
+| キー | 型 | 既定値 |
+|------|----|--------|
+| `upstream_handshake.protocolVersion` | string | `"2025-03-26"` |
+| `upstream_handshake.clientName` | string | `"XcodeMCPKit"` |
+| `upstream_handshake.clientVersion` | string | `"dev"` |
+| `upstream_handshake.capabilities` | table | `{}` |
 
-| オプション | 説明 |
-|-----------|------|
-| `--upstream-command cmd` | `mcpbridge` コマンド |
-| `--upstream-args a,b,c` | `mcpbridge` 引数（カンマ区切り） |
-| `--upstream-arg value` | `mcpbridge` 引数を1つ追加 |
-| `--upstream-processes n` | upstream `mcpbridge` を `n` プロセス起動（default: 1, max: 10） |
-| `--xcode-pid pid` | 対象 Xcode の PID |
-| `--session-id id` | Xcode MCP セッション ID（通常は不要） |
-| `--max-body-bytes n` | 最大ボディサイズ |
-| `--request-timeout seconds` | リクエストタイムアウト（`0` で無制限） |
-| `--refresh-code-issues-mode proxy|upstream` | `XcodeRefreshCodeIssuesInFile` を proxy 側の navigator issues 経由（既定）で返すか、Xcode の live diagnostics へ直通するかを切り替え |
-| `--lazy-init` | 初回リクエストまで初期化を遅延 |
-| `--force-restart` | listen ポートが使用中の場合、既存の `xcode-mcp-proxy-server` を終了して起動し直す |
+`clientVersion` を省略した場合、`clientName` に対応する Xcode の `IDEChat*Version` があれば、その version を自動で使います。
 
 ### アダプタ: `xcode-mcp-proxy`
 
@@ -154,7 +169,9 @@ Note: `--upstream-processes` > 1 を使う場合、`--session-id` / `MCP_XCODE_S
 
 #### 環境変数
 
-- `XCODE_MCP_PROXY_ENDPOINT`（上流 URL を上書き。`--url` が優先）
+| 変数 | 説明 |
+|------|------|
+| `XCODE_MCP_PROXY_ENDPOINT` | 上流 URL を上書き。`--url` が優先 |
 
 ## トラブルシューティング
 

README.ja.md

@@ -117,17 +117,6 @@ See Quick Start for how to launch.
 - initialization: eager at startup
 - discovery: `~/Library/Caches/XcodeMCPProxy/endpoint.json`
 
-#### Environment Variables
-
-- `MCP_XCODE_PID` (alternative to `--xcode-pid`)
-- `MCP_XCODE_SESSION_ID` (fixes the Xcode MCP session ID; usually not needed)
-- `MCP_XCODE_REFRESH_CODE_ISSUES_MODE` (`proxy` or `upstream`; controls how `XcodeRefreshCodeIssuesInFile` is served)
-- `MCP_LOG_LEVEL` (log level: trace|debug|info|notice|warning|error|critical)
-
-Logs are written to stderr.
-
-Note: when using `--upstream-processes` > 1, fixing the session id via `--session-id` / `MCP_XCODE_SESSION_ID` can help reduce permission dialog prompts in Xcode.
-
 #### Options
 
 | Option | Description |
@@ -136,14 +125,39 @@ Note: when using `--upstream-processes` > 1, fixing the session id via `--sessio
 | `--upstream-args a,b,c` | `mcpbridge` args (comma-separated) |
 | `--upstream-arg value` | Append a single `mcpbridge` arg |
 | `--upstream-processes n` | Spawn `n` upstream `mcpbridge` processes (default: 1, max: 10) |
-| `--xcode-pid pid` | Xcode PID |
-| `--session-id id` | Xcode MCP session ID (usually not needed) |
+| `--session-id id` | Explicit Xcode MCP session ID |
 | `--max-body-bytes n` | Max request body size |
-| `--request-timeout seconds` | Request timeout (`0` disables) |
-| `--refresh-code-issues-mode proxy|upstream` | Serve `XcodeRefreshCodeIssuesInFile` via proxy navigator issues (`proxy`, default) or pass through to Xcode live diagnostics (`upstream`) |
-| `--lazy-init` | Delay initialization until first request |
+| `--request-timeout seconds` | Request timeout (`0` disables non-initialize timeouts; `initialize` still uses a bounded handshake timeout) |
+| `--config path` | Path to proxy config TOML for overriding the upstream handshake |
+| `--refresh-code-issues-mode mode` | Serve `XcodeRefreshCodeIssuesInFile` via proxy navigator issues (`proxy`, default) or pass through to Xcode live diagnostics (`upstream`) |
 | `--force-restart` | If the listen port is in use, terminate an existing `xcode-mcp-proxy-server` and restart |
 
+#### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LISTEN` | Listen address; example: `127.0.0.1:8765` |
+| `HOST` | Listen host; used with `PORT` when `LISTEN` is unset |
+| `PORT` | Listen port; used with `HOST` when `LISTEN` is unset |
+| `MCP_XCODE_PID` | Passed through to upstream `mcpbridge`; the proxy itself does not parse it |
+| `MCP_XCODE_SESSION_ID` | Optional explicit upstream session ID |
+| `MCP_XCODE_CONFIG` | Proxy config TOML path; `--config` takes precedence |
+| `MCP_XCODE_REFRESH_CODE_ISSUES_MODE` | `proxy` or `upstream` |
+| `MCP_LOG_LEVEL` | Log level: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical` |
+
+Logs are written to stderr.
+
+#### Proxy Config
+
+| Key | Type | Default |
+|-----|------|---------|
+| `upstream_handshake.protocolVersion` | string | `"2025-03-26"` |
+| `upstream_handshake.clientName` | string | `"XcodeMCPKit"` |
+| `upstream_handshake.clientVersion` | string | `"dev"` |
+| `upstream_handshake.capabilities` | table | `{}` |
+
+If `clientVersion` is omitted, the proxy auto-resolves it from the Xcode `IDEChat*Version` entry matching `clientName` when available.
+
 ### Adapter: `xcode-mcp-proxy`
 
 #### Options
@@ -155,7 +169,9 @@ Note: when using `--upstream-processes` > 1, fixing the session id via `--sessio
 
 #### Environment Variables
 
-- `XCODE_MCP_PROXY_ENDPOINT` (override upstream URL; `--url` takes precedence)
+| Variable | Description |
+|----------|-------------|
+| `XCODE_MCP_PROXY_ENDPOINT` | Override upstream URL; `--url` takes precedence |
 
 ## Troubleshooting
 

README.md

@@ -25,6 +25,11 @@ package struct CLICommandRuntime {
             return 1
         }
 
+        if let removedFlagMessage = invocation.removedFlagMessage {
+            logSink.error(removedFlagMessage)
+            return 1
+        }
+
         if invocation.serverOnlyFlag != nil {
             logSink.error(
                 "This option is only supported by xcode-mcp-proxy-server (proxy server)."

Sources/ProxyCLI/CLICommandRuntime.swift

@@ -1,8 +1,10 @@
 import Foundation
+import XcodeMCPProxy
 
 package struct ProxyCLIAdapterScan {
     package var showHelp = false
     package var usesRemovedURLHelper = false
+    package var removedFlagMessage: String?
     package var hasExplicitURL = false
     package var hasStdioFlag = false
     package var serverOnlyFlag: String?
@@ -14,8 +16,7 @@ package struct ProxyCLIServerScan {
     package var hasListenFlag = false
     package var hasHostFlag = false
     package var hasPortFlag = false
-    package var hasXcodePIDFlag = false
-    package var hasLazyInitFlag = false
+    package var hasConfigFlag = false
     package var hasRefreshCodeIssuesModeFlag = false
     package var forceRestart = false
     package var dryRun = false
@@ -27,6 +28,7 @@ package struct ProxyCLIInstallScan {
 
 package enum ProxyCLIInvocationScanner {
     private static let serverOnlyFlags: Set<String> = [
+        "--config",
         "--listen",
         "--host",
         "--port",
@@ -35,13 +37,12 @@ package enum ProxyCLIInvocationScanner {
         "--upstream-args",
         "--upstream-arg",
         "--upstream-processes",
-        "--xcode-pid",
         "--session-id",
         "--refresh-code-issues-mode",
-        "--lazy-init",
     ]
 
     private static let serverOnlyValueFlags: Set<String> = [
+        "--config",
         "--listen",
         "--host",
         "--port",
@@ -50,20 +51,19 @@ package enum ProxyCLIInvocationScanner {
         "--upstream-args",
         "--upstream-arg",
         "--upstream-processes",
-        "--xcode-pid",
         "--session-id",
         "--refresh-code-issues-mode",
     ]
 
     private static let serverForwardedValueFlags: Set<String> = [
+        "--config",
         "--listen",
         "--host",
         "--port",
         "--upstream-command",
         "--upstream-args",
         "--upstream-arg",
         "--upstream-processes",
-        "--xcode-pid",
         "--session-id",
         "--max-body-bytes",
         "--request-timeout",
@@ -94,6 +94,16 @@ package enum ProxyCLIInvocationScanner {
             case "--stdio":
                 scan.hasStdioFlag = true
                 cursor.advancePastCurrentAndOptionalValue(where: { !$0.hasPrefix("-") })
+            case "--lazy-init":
+                if scan.removedFlagMessage == nil {
+                    scan.removedFlagMessage = CLIParser.removedLazyInitMessage
+                }
+                cursor.advance()
+            case "--xcode-pid":
+                if scan.removedFlagMessage == nil {
+                    scan.removedFlagMessage = CLIParser.removedXcodePIDMessage
+                }
+                cursor.advancePastCurrentAndOptionalValue(where: { _ in true })
             case "--request-timeout":
                 cursor.advancePastCurrentAndOptionalValue(where: shouldConsumeRequestTimeoutValue)
             case let flag where serverOnlyFlags.contains(flag):
@@ -138,19 +148,18 @@ package enum ProxyCLIInvocationScanner {
                 throw ProxyServerCommandError.message(
                     "--url is not supported in server mode (use xcode-mcp-proxy)"
                 )
+            case "--xcode-pid":
+                throw ProxyServerCommandError.message(CLIParser.removedXcodePIDMessage)
             case "--lazy-init":
-                scan.hasLazyInitFlag = true
-                scan.forwardedArgs.append(arg)
-                cursor.advance()
-                continue
+                throw ProxyServerCommandError.message(CLIParser.removedLazyInitMessage)
             case "--listen":
                 scan.hasListenFlag = true
             case "--host":
                 scan.hasHostFlag = true
             case "--port":
                 scan.hasPortFlag = true
-            case "--xcode-pid":
-                scan.hasXcodePIDFlag = true
+            case "--config":
+                scan.hasConfigFlag = true
             case "--refresh-code-issues-mode":
                 scan.hasRefreshCodeIssuesModeFlag = true
             default:

Sources/ProxyCLI/ProxyCLIInvocationScanner.swift

@@ -15,12 +15,7 @@ package struct ProxyServerCommandRuntime {
                 dependencies.stdout(XcodeMCPProxyServerCommand.serverUsage())
                 return 0
             }
-        XcodeMCPProxyServerCommand.applyDefaults(
-            from: environment,
-            to: &options,
-            resolveXcodePID: dependencies.resolveXcodePID,
-            stderr: dependencies.stderr
-        )
+            try XcodeMCPProxyServerCommand.applyDefaults(from: environment, to: &options)
 
             let isDryRun = options.dryRun || XcodeMCPProxyServerCommand.isTruthy(environment["DRY_RUN"])
             if isDryRun {

Sources/ProxyCLI/ProxyServerCommandRuntime.swift

@@ -7,6 +7,7 @@ extension XcodeMCPProxyCLICommand {
         var invocation = CLICommandInvocation()
         invocation.showHelp = scan.showHelp
         invocation.usesRemovedURLHelper = scan.usesRemovedURLHelper
+        invocation.removedFlagMessage = scan.removedFlagMessage
         invocation.hasExplicitURL = scan.hasExplicitURL
         invocation.hasStdioFlag = scan.hasStdioFlag
         invocation.serverOnlyFlag = scan.serverOnlyFlag
@@ -79,6 +80,7 @@ extension XcodeMCPProxyCLICommand {
 
         Notes:
           - Proxy server: xcode-mcp-proxy-server
+          - --config is only supported by xcode-mcp-proxy-server
           - Discovery file: \(discoveryFileURL.path)
         """
     }

Sources/ProxyCLI/XcodeMCPProxyCLICommand+Parsing.swift

@@ -20,6 +20,7 @@ package struct CLICommandLogSink {
 package struct CLICommandInvocation {
     package var showHelp = false
     package var usesRemovedURLHelper = false
+    package var removedFlagMessage: String?
     package var hasExplicitURL = false
     package var hasStdioFlag = false
     package var serverOnlyFlag: String?