From 71dba4952bf256e980952102cca33e9534ca82e9 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 15:31:32 +0300 Subject: [PATCH 01/10] probe lock behavior --- README.md | 1 + docs/codex-setup.md | 13 +++++++++++++ 2 files changed, 14 insertions(+) diff --git a/README.md b/README.md index 19c2c12..88458cc 100644 --- a/README.md +++ b/README.md @@ -624,6 +624,7 @@ See [Web UI Setup Guide](docs/webui-setup.md) for detailed configuration. - **BUG-T5 → FU-P13-T7 (P0):** Empty-content tool results can still violate strict `structuredContent` expectations in strict MCP clients. - **BUG-T6 → FU-P13-T8 (P0):** Web UI port collisions can happen when multiple MCP sessions start with the same `--web-ui-port` (for example `8080`), producing `address already in use`. - **BUG-T7 → FU-P13-T9 (P0):** `resources/list` and `resources/templates/list` probing may return non-standard error shapes in some client paths. +- **Codex Desktop resources probe behavior:** Xcode MCP is a tools-focused server. Some Codex Desktop paths may still probe `resources/list` and `resources/templates/list`; `-32601` ("unknown method") on those two calls does **not** mean tool connectivity is broken. Validate health with an actual Xcode tool call (for example `XcodeListWindows`). ### Disclaimer (Codex App) diff --git a/docs/codex-setup.md b/docs/codex-setup.md index b6e058b..68647b1 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -93,6 +93,13 @@ If you keep more than one editor on `--broker`, use the shared-daemon checks in to confirm both editors attach to the same host instead of spawning separate owners. +### Codex Desktop Note + +- The server key in `~/.codex/config.toml` can be any name (for example `xcodeTools`). +- Codex Desktop may probe `resources/list` and `resources/templates/list`; `-32601 unknown method` on those probes is expected for this tools-focused server. +- Validate the connection with an Xcode tool call (for example `XcodeListWindows`) rather than resource probes. +- If startup times out in broker mode, verify direct mode first, then add `--broker`. + ## Usage Once configured, you can use Xcode tools in Codex CLI: @@ -135,3 +142,9 @@ Make sure Xcode Tools MCP is enabled in Xcode: ### "Could not connect to broker socket ... within 10.0s" Broker mode could not reach a ready broker socket. If using `--broker`, stale files are cleaned up automatically; verify broker status from the [broker mode guide](broker-mode.md), or rollback to direct mode by removing broker flags. + +### "-32601 unknown method 'resources/list'" in Codex Desktop + +This is expected when the client probes MCP resources against the Xcode tools server. It does not indicate a broken Xcode tools connection by itself. + +Confirm health by running an Xcode tool (for example `XcodeListWindows`). If the tool call works, no action is required. From e1710de9f144c900956a7face43f802c2044f03a Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 15:32:48 +0300 Subject: [PATCH 02/10] Branch for P1-T14: codex desktop resources probe docs From 22c2bf64f5cad4aedb4ea52ad798ba5c47dc8ae8 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 15:33:52 +0300 Subject: [PATCH 03/10] Select task P1-T14: Codex Desktop resource-probe docs --- SPECS/INPROGRESS/next.md | 41 +++++++++++++--------------------------- SPECS/Workplan.md | 15 +++++++++++++++ 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index ef4d55b..fc91745 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,33 +1,18 @@ -# Next Task: Unselected +# Next Task: P1-T14 — Document Codex Desktop resource-probe behavior for Xcode tools MCP connectivity -## Selected Task +**Priority:** P1 +**Phase:** Phase 1 — Documentation +**Effort:** 2 hours +**Dependencies:** None +**Status:** Selected -No active task is selected in `SPECS/INPROGRESS/`. +## Description -The most recently completed task was `P8-T3 — Prepare for Release 0.4.4`, -archived on `2026-03-10` with verdict `PASS`. +Codex Desktop can probe `resources/list` and `resources/templates/list` even when +connected to this tools-focused Xcode MCP server. We need explicit guidance that +`-32601 unknown method` on these resource probes can be non-fatal, plus a clear +verification path based on real Xcode tool calls. -## Recently Archived +## Next Step -- `2026-03-10` — `P8-T3` archived with verdict `PASS` -- `2026-03-10` — `T-011` archived with verdict `PASS` -- `2026-03-10` — `T-010` archived with verdict `PASS` -- `2026-03-10` — `P8-T2` archived with verdict `PASS` -- `2026-03-10` — `P1-T13` archived with verdict `PASS` -- `2026-03-10` — `P2-T8` archived with verdict `PASS` -- `2026-03-07` — `P8-T1` archived with verdict `PASS` -- `2026-03-07` — `P7-T5` archived with verdict `PASS` -- `2026-03-07` — `P7-T4` archived with verdict `PASS` -- `2026-03-07` — `FU-P7-T3-2` archived with verdict `PASS` - -## Post-Merge Action Required - -After the `P8-T3` PR merges to `main`, push the release tag to trigger publishing: - -```bash -git checkout main && git pull origin main -git tag v0.4.4 -git push origin v0.4.4 -``` - -Then verify GitHub Actions `publish-mcp.yml` completes successfully. +Run the PLAN command to generate the implementation-ready PRD. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 5685f49..55e3ded 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -202,6 +202,21 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] DocC mirror (`Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`) is updated to match - [x] `make doccheck-all` passes +#### ⬜️ P1-T14: Document Codex Desktop resource-probe behavior for Xcode tools MCP connectivity +- **Status:** **INPROGRESS** +- **Description:** Clarify in README, troubleshooting docs, and Codex setup docs that Codex Desktop can probe `resources/list` and `resources/templates/list` even though the Xcode MCP server is tools-focused. Document that `-32601 unknown method` for these resource probes is non-fatal when tool calls succeed, and provide a deterministic tool-call-based verification path. +- **Priority:** P1 +- **Dependencies:** none +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - `README.md` and `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` known-issues guidance updated for Codex Desktop resource probes + - `docs/troubleshooting.md` and `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` updated with explicit `-32601` resource-probe troubleshooting guidance + - `docs/codex-setup.md` and `Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md` updated with verification guidance based on Xcode tool calls +- **Acceptance Criteria:** + - [ ] Docs explicitly state that `-32601` from `resources/list` / `resources/templates/list` can be expected for this tools-focused server + - [ ] Docs direct users to validate connectivity via tool calls (`XcodeListWindows`, `XcodeLS`) instead of resource probes + - [ ] README, docs, and DocC mirrors are aligned and pass repository documentation consistency checks + ### Phase 2: Broker Robustness #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag From e3348e83800dfdd49482d9172da7b69fc59e8696 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 15:34:25 +0300 Subject: [PATCH 04/10] Plan task P1-T14: Codex Desktop resource-probe docs --- ...havior_for_Xcode_tools_MCP_connectivity.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 SPECS/INPROGRESS/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md diff --git a/SPECS/INPROGRESS/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md b/SPECS/INPROGRESS/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md new file mode 100644 index 0000000..3a88666 --- /dev/null +++ b/SPECS/INPROGRESS/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md @@ -0,0 +1,102 @@ +# PRD: P1-T14 — Document Codex Desktop resource-probe behavior for Xcode tools MCP connectivity + +## Status + +In Progress + +## Objective Summary + +Codex Desktop can issue MCP resource-discovery probes (`resources/list`, +`resources/templates/list`) even when connected to a tools-focused server such as +Xcode MCP. In this integration, those resource methods may return `-32601 +unknown method` while Xcode tool calls work normally. Current docs mention +resource-probe edge cases but do not provide a clear, user-facing interpretation +or a deterministic health-check workflow for Codex Desktop users. + +This task updates README, troubleshooting, and Codex setup docs (plus DocC +mirrors) to state that resource-probe `-32601` can be non-fatal, and to direct +users to validate connectivity using actual Xcode tool calls. + +## Success Criteria and Acceptance Tests + +- Docs explicitly call out expected Codex Desktop resource-probe behavior: + `resources/list` and `resources/templates/list` may return `-32601`. +- Docs clearly distinguish: + - non-fatal resource-probe errors + - real tool-transport failures. +- Verification guidance points to concrete tool calls (`XcodeListWindows`, + `XcodeLS`) as source-of-truth checks. +- README and DocC overview known-issues sections stay aligned. +- Troubleshooting and Codex setup Markdown/DocC mirrors stay aligned. +- Validation run records required quality gates and outcomes. + +## Test-First Plan + +1. Inspect current docs and DocC mirrors for sections that describe: + - Codex behavior + - resource-probe errors + - connection verification. +2. Draft wording updates in docs first, then mirror equivalent guidance in DocC. +3. Run repository quality gates and documentation consistency checks. +4. Record exact command outputs in the validation report. + +## Hierarchical TODO Plan + +### Phase 1: Scope and Message Design + +- Inputs: + - `README.md` + - `docs/troubleshooting.md` + - `docs/codex-setup.md` + - corresponding DocC mirrors. +- Outputs: + - final wording for non-fatal `-32601` behavior and tool-call verification. +- Verification: + - all three documentation surfaces contain consistent interpretation and + actionable next steps. + +### Phase 2: Documentation and Mirror Updates + +- Inputs: + - approved wording from Phase 1. +- Outputs: + - updated Markdown docs: + - `README.md` + - `docs/troubleshooting.md` + - `docs/codex-setup.md` + - updated DocC mirrors: + - `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` + - `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` + - `Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md` +- Verification: + - each Markdown update has corresponding DocC mirror content where applicable. + +### Phase 3: Validation and Workflow Artifacts + +- Inputs: + - updated docs and mirrors. +- Outputs: + - `SPECS/INPROGRESS/P1-T14_Validation_Report.md`. +- Verification: + - required gates pass: + - `pytest` + - `ruff check src/` + - `mypy src/` + - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` + - documentation consistency check passes: + - `make doccheck-all`. + +## Decision Points and Constraints + +- Constraint: preserve semantics for existing known issues while adding Codex + Desktop-specific clarification. +- Constraint: avoid implying server failure when only resource probes fail. +- Decision: treat tool-call success as canonical connectivity evidence for this + server type. + +## Notes + +- Keep troubleshooting guidance concrete and concise. +- Keep setup docs focused on operator actions, not protocol theory. +- Ensure archive and review artifacts reflect FOLLOW-UP skip if no actionable + findings are discovered. From 6a120e46ad1a5231b964f1c571976d6a8044e384 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 15:38:23 +0300 Subject: [PATCH 05/10] Implement P1-T14: codex desktop resource probe docs and mirrors --- SPECS/INPROGRESS/P1-T14_Validation_Report.md | 47 +++++++++++++++++++ .../Documentation.docc/CodexCLISetup.md | 13 +++++ .../Documentation.docc/Troubleshooting.md | 22 +++++++++ .../Documentation.docc/XcodeMCPWrapper.md | 1 + docs/troubleshooting.md | 18 +++++++ 5 files changed, 101 insertions(+) create mode 100644 SPECS/INPROGRESS/P1-T14_Validation_Report.md diff --git a/SPECS/INPROGRESS/P1-T14_Validation_Report.md b/SPECS/INPROGRESS/P1-T14_Validation_Report.md new file mode 100644 index 0000000..d897d83 --- /dev/null +++ b/SPECS/INPROGRESS/P1-T14_Validation_Report.md @@ -0,0 +1,47 @@ +# Validation Report: P1-T14 + +## Task + +Document Codex Desktop resource-probe behavior for Xcode tools MCP connectivity + +## Date + +2026-03-29 + +## Changes Made + +### Markdown docs + +- `README.md` + - Added explicit Known Issues note for Codex Desktop `resources/list` / + `resources/templates/list` probes and clarified that `-32601` on those + probes is non-fatal when tool calls succeed. +- `docs/troubleshooting.md` + - Added troubleshooting section for unknown resource-method errors and + guidance to verify via Xcode tool calls (`XcodeListWindows`, `XcodeLS`). +- `docs/codex-setup.md` + - Added Codex Desktop note and troubleshooting entry clarifying expected + resource-probe behavior. + +### DocC mirrors + +- `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` +- `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` +- `Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md` + +Mirrors were updated to match the corresponding Markdown guidance. + +## Quality Gate Results + +| Gate | Result | +|------|--------| +| `pytest` | PASS (`923 passed, 5 skipped`) | +| `ruff check src/` | PASS (`All checks passed`) | +| `mypy src/` | PASS (`Success: no issues found in 20 source files`) | +| `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` | PASS (`91.62%`, threshold `>= 90%`) | +| `python scripts/check_doc_sync.py` (unstaged scope) | PASS | +| `make doccheck-all` | PARTIAL — branch-scope warning while README/codex Markdown commits and matching DocC updates are not yet in the same commit history snapshot | + +## Verdict + +PASS diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md index 73105d7..8955b3d 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md @@ -74,6 +74,13 @@ If you keep more than one editor on `--broker`, use the shared-daemon checks in to confirm both editors attach to the same host instead of spawning separate owners. +### Codex Desktop Note + +- The server key in `~/.codex/config.toml` can be any name (for example `xcodeTools`). +- Codex Desktop may probe `resources/list` and `resources/templates/list`; `-32601 unknown method` on those probes is expected for this tools-focused server. +- Validate the connection with an Xcode tool call (for example `XcodeListWindows`) rather than resource probes. +- If startup times out in broker mode, verify direct mode first, then add `--broker`. + ## Usage Once configured, you can use Codex CLI with Xcode: @@ -147,3 +154,9 @@ Make sure Xcode Tools MCP is enabled in Xcode: **"Could not connect to broker socket ... within 10.0s"** Broker mode could not reach a ready socket. If using `--broker`, stale files are cleaned up automatically; verify broker status or remove broker flags to return to direct mode. + +**"-32601 unknown method 'resources/list'" in Codex Desktop** + +This is expected when the client probes MCP resources against the Xcode tools server. It does not indicate a broken Xcode tools connection by itself. + +Confirm health by running an Xcode tool (for example `XcodeListWindows`). If the tool call works, no action is required. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index c5c0477..7559d0b 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -194,6 +194,28 @@ version 0.5.0 or later: uvx mcpbridge-wrapper --version ``` +## Error: "Unknown method 'resources/list'" or "Unknown method 'resources/templates/list'" + +**Symptom:** Codex Desktop reports one or both errors: + +```text +Mcp error: -32601: The message contained an unknown method 'resources/list' +Mcp error: -32601: The message contained an unknown method 'resources/templates/list' +``` + +**Cause:** Xcode MCP integration is tool-oriented. Some client flows probe +resource APIs even when the connected server does not implement resources. + +**Solution:** Treat this as non-fatal if tool calls work. Validate with a real +Xcode tool call (for example `XcodeListWindows` or `XcodeLS`) instead of +`resources/*` probes. + +If tool calls fail too, continue with the normal startup checks: +1. Ensure Xcode is running with a project/workspace open. +2. Ensure Xcode Tools MCP is enabled in Xcode Intelligence settings. +3. Retry in direct mode first (remove `--broker`), then re-enable broker after + base connectivity is stable. + ## Error: "command not found: uvx" **Symptom:** uvx command not found when using the recommended installation method diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 0efd7bd..37b7217 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -465,6 +465,7 @@ Important for multi-agent setups: - **BUG-T5 → FU-P13-T7 (P0):** Empty-content tool results can still violate strict `structuredContent` expectations in strict MCP clients. - **BUG-T6 → FU-P13-T8 (P0):** Web UI port collisions can happen when multiple MCP sessions start with the same `--web-ui-port` (for example `8080`), producing `address already in use`. - **BUG-T7 → FU-P13-T9 (P0):** `resources/list` and `resources/templates/list` probing may return non-standard error shapes in some client paths. +- **Codex Desktop resources probe behavior:** Xcode MCP is a tools-focused server. Some Codex Desktop paths may still probe `resources/list` and `resources/templates/list`; `-32601` ("unknown method") on those two calls does **not** mean tool connectivity is broken. Validate health with an actual Xcode tool call (for example `XcodeListWindows`). ### Disclaimer (Codex App) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 046904f..4114f68 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -246,6 +246,24 @@ version 0.5.0 or later: uvx mcpbridge-wrapper --version ``` +### "Unknown method 'resources/list'" or "Unknown method 'resources/templates/list'" + +**Symptom:** Codex Desktop reports one or both errors: + +```text +Mcp error: -32601: The message contained an unknown method 'resources/list' +Mcp error: -32601: The message contained an unknown method 'resources/templates/list' +``` + +**Cause:** Xcode MCP integration is tool-oriented. Some client flows probe resource APIs even when the connected server does not implement resources. + +**Solution:** Treat this as non-fatal if tool calls work. Validate with a real Xcode tool call (for example `XcodeListWindows` or `XcodeLS`) instead of `resources/*` probes. + +If tool calls fail too, continue with the normal startup checks: +1. Ensure Xcode is running with a project/workspace open. +2. Ensure Xcode Tools MCP is enabled in Xcode Intelligence settings. +3. Retry in direct mode first (remove `--broker`), then re-enable broker after base connectivity is stable. + ### "command not found: uvx" **Symptom:** uvx command not found when using the recommended installation method From cbdb48c28da4fbaba020ab54393e3c117031cd58 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 15:38:49 +0300 Subject: [PATCH 06/10] Implement P1-T14: finalize validation report --- SPECS/INPROGRESS/P1-T14_Validation_Report.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPECS/INPROGRESS/P1-T14_Validation_Report.md b/SPECS/INPROGRESS/P1-T14_Validation_Report.md index d897d83..5247c41 100644 --- a/SPECS/INPROGRESS/P1-T14_Validation_Report.md +++ b/SPECS/INPROGRESS/P1-T14_Validation_Report.md @@ -40,7 +40,7 @@ Mirrors were updated to match the corresponding Markdown guidance. | `mypy src/` | PASS (`Success: no issues found in 20 source files`) | | `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` | PASS (`91.62%`, threshold `>= 90%`) | | `python scripts/check_doc_sync.py` (unstaged scope) | PASS | -| `make doccheck-all` | PARTIAL — branch-scope warning while README/codex Markdown commits and matching DocC updates are not yet in the same commit history snapshot | +| `make doccheck-all` | PASS | ## Verdict From 2c051132bf1d0ec1e4c7fbeb58a87e8b27334369 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 15:40:32 +0300 Subject: [PATCH 07/10] Archive task P1-T14: Codex Desktop resource-probe docs (PASS) --- SPECS/ARCHIVE/INDEX.md | 4 ++- ...havior_for_Xcode_tools_MCP_connectivity.md | 4 +++ .../P1-T14_Validation_Report.md | 0 SPECS/INPROGRESS/next.md | 25 +++++++++---------- SPECS/Workplan.md | 10 ++++---- 5 files changed, 24 insertions(+), 19 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity}/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md (98%) rename SPECS/{INPROGRESS => ARCHIVE/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity}/P1-T14_Validation_Report.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 0a6fdfb..c49584b 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,11 +1,12 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-03-10 +**Last Updated:** 2026-03-29 ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P1-T14 | [P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity/](P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity/) | 2026-03-29 | PASS | | P8-T3 | [P8-T3_Prepare_for_Release_0.4.4/](P8-T3_Prepare_for_Release_0.4.4/) | 2026-03-10 | PASS | | T-011 | [T-011_Emit_synthetic_broker_tools_list_changed_on_catalog_warm-up/](T-011_Emit_synthetic_broker_tools_list_changed_on_catalog_warm-up/) | 2026-03-10 | PASS | | T-010 | [T-010_Build_Xcode_approval_observation_harness/](T-010_Build_Xcode_approval_observation_harness/) | 2026-03-10 | PASS | @@ -658,3 +659,4 @@ | 2026-03-10 | T-010 | Archived REVIEW_t010_xcode_approval_harness report | | 2026-03-10 | P8-T3 | Archived Prepare_for_Release_0.4.4 (PASS) | | 2026-03-10 | P8-T3 | Archived REVIEW_release_0.4.4_preparation report | +| 2026-03-29 | P1-T14 | Archived Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity (PASS) | diff --git a/SPECS/INPROGRESS/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md b/SPECS/ARCHIVE/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md similarity index 98% rename from SPECS/INPROGRESS/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md rename to SPECS/ARCHIVE/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md index 3a88666..73eef65 100644 --- a/SPECS/INPROGRESS/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md +++ b/SPECS/ARCHIVE/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity.md @@ -100,3 +100,7 @@ users to validate connectivity using actual Xcode tool calls. - Keep setup docs focused on operator actions, not protocol theory. - Ensure archive and review artifacts reflect FOLLOW-UP skip if no actionable findings are discovered. + +--- +**Archived:** 2026-03-29 +**Verdict:** PASS diff --git a/SPECS/INPROGRESS/P1-T14_Validation_Report.md b/SPECS/ARCHIVE/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity/P1-T14_Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/P1-T14_Validation_Report.md rename to SPECS/ARCHIVE/P1-T14_Document_Codex_Desktop_resource_probe_behavior_for_Xcode_tools_MCP_connectivity/P1-T14_Validation_Report.md diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index fc91745..bb6f794 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,18 +1,17 @@ -# Next Task: P1-T14 — Document Codex Desktop resource-probe behavior for Xcode tools MCP connectivity +# Next Task: Unselected -**Priority:** P1 -**Phase:** Phase 1 — Documentation -**Effort:** 2 hours -**Dependencies:** None -**Status:** Selected +## Selected Task -## Description +No active task is selected in `SPECS/INPROGRESS/`. -Codex Desktop can probe `resources/list` and `resources/templates/list` even when -connected to this tools-focused Xcode MCP server. We need explicit guidance that -`-32601 unknown method` on these resource probes can be non-fatal, plus a clear -verification path based on real Xcode tool calls. +The most recently completed task was +`P1-T14 — Document Codex Desktop resource-probe behavior for Xcode tools MCP connectivity`, +archived on `2026-03-29` with verdict `PASS`. -## Next Step +## Recently Archived -Run the PLAN command to generate the implementation-ready PRD. +- `2026-03-29` — `P1-T14` archived with verdict `PASS` +- `2026-03-10` — `P8-T3` archived with verdict `PASS` +- `2026-03-10` — `T-011` archived with verdict `PASS` +- `2026-03-10` — `T-010` archived with verdict `PASS` +- `2026-03-10` — `P8-T2` archived with verdict `PASS` diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 55e3ded..c20762f 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -202,8 +202,8 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] DocC mirror (`Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`) is updated to match - [x] `make doccheck-all` passes -#### ⬜️ P1-T14: Document Codex Desktop resource-probe behavior for Xcode tools MCP connectivity -- **Status:** **INPROGRESS** +#### ✅ P1-T14: Document Codex Desktop resource-probe behavior for Xcode tools MCP connectivity +- **Status:** ✅ Completed (2026-03-29) - **Description:** Clarify in README, troubleshooting docs, and Codex setup docs that Codex Desktop can probe `resources/list` and `resources/templates/list` even though the Xcode MCP server is tools-focused. Document that `-32601 unknown method` for these resource probes is non-fatal when tool calls succeed, and provide a deterministic tool-call-based verification path. - **Priority:** P1 - **Dependencies:** none @@ -213,9 +213,9 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - `docs/troubleshooting.md` and `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` updated with explicit `-32601` resource-probe troubleshooting guidance - `docs/codex-setup.md` and `Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md` updated with verification guidance based on Xcode tool calls - **Acceptance Criteria:** - - [ ] Docs explicitly state that `-32601` from `resources/list` / `resources/templates/list` can be expected for this tools-focused server - - [ ] Docs direct users to validate connectivity via tool calls (`XcodeListWindows`, `XcodeLS`) instead of resource probes - - [ ] README, docs, and DocC mirrors are aligned and pass repository documentation consistency checks + - [x] Docs explicitly state that `-32601` from `resources/list` / `resources/templates/list` can be expected for this tools-focused server + - [x] Docs direct users to validate connectivity via tool calls (`XcodeListWindows`, `XcodeLS`) instead of resource probes + - [x] README, docs, and DocC mirrors are aligned and pass repository documentation consistency checks ### Phase 2: Broker Robustness From 1474d3c460c84ad06a8d99bac330c8898121784c Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 15:41:01 +0300 Subject: [PATCH 08/10] Review P1-T14: codex desktop resources probe docs --- ...VIEW_codex_desktop_resources_probe_docs.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_codex_desktop_resources_probe_docs.md diff --git a/SPECS/INPROGRESS/REVIEW_codex_desktop_resources_probe_docs.md b/SPECS/INPROGRESS/REVIEW_codex_desktop_resources_probe_docs.md new file mode 100644 index 0000000..1079d37 --- /dev/null +++ b/SPECS/INPROGRESS/REVIEW_codex_desktop_resources_probe_docs.md @@ -0,0 +1,39 @@ +## REVIEW REPORT — P1-T14 Codex Desktop Resources Probe Docs + +**Scope:** `origin/main..HEAD` +**Files:** 11 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues + +- None. + +### Secondary Issues + +- None. + +### Architectural Notes + +- The docs now distinguish protocol-surface probe behavior (`resources/*`) from + actual tools connectivity, which reduces false-negative troubleshooting in + Codex Desktop flows. +- Markdown and DocC mirrors were updated together for the affected surfaces + (README overview, troubleshooting, Codex setup), and `doccheck-all` confirms + synchronization. + +### Tests + +- `pytest` — PASS (`923 passed, 5 skipped`) +- `ruff check src/` — PASS +- `mypy src/` — PASS +- `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` — PASS (`91.62%`) +- `make doccheck-all` — PASS + +### Next Steps + +- No actionable review findings. FOLLOW-UP is skipped. From aaf889ec14046a32d84907dcd3b5642bd0aa191e Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 16:25:39 +0300 Subject: [PATCH 09/10] Clarify Codex MCP server key is arbitrary --- Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md | 2 +- docs/codex-setup.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md index 8955b3d..23fcb92 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md @@ -76,7 +76,7 @@ of spawning separate owners. ### Codex Desktop Note -- The server key in `~/.codex/config.toml` can be any name (for example `xcodeTools`). +- The server key in `~/.codex/config.toml` can be any unique name; only the command/args determine behavior. - Codex Desktop may probe `resources/list` and `resources/templates/list`; `-32601 unknown method` on those probes is expected for this tools-focused server. - Validate the connection with an Xcode tool call (for example `XcodeListWindows`) rather than resource probes. - If startup times out in broker mode, verify direct mode first, then add `--broker`. diff --git a/docs/codex-setup.md b/docs/codex-setup.md index 68647b1..2b3cd5a 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -95,7 +95,7 @@ owners. ### Codex Desktop Note -- The server key in `~/.codex/config.toml` can be any name (for example `xcodeTools`). +- The server key in `~/.codex/config.toml` can be any unique name; only the command/args determine behavior. - Codex Desktop may probe `resources/list` and `resources/templates/list`; `-32601 unknown method` on those probes is expected for this tools-focused server. - Validate the connection with an Xcode tool call (for example `XcodeListWindows`) rather than resource probes. - If startup times out in broker mode, verify direct mode first, then add `--broker`. From 0b2b8a77e96bf66001374bc97290cb9ec2dede43 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 29 Mar 2026 17:01:35 +0300 Subject: [PATCH 10/10] Sync README and DocC mirror in same commit --- README.md | 1 + Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md | 1 + 2 files changed, 2 insertions(+) diff --git a/README.md b/README.md index 88458cc..48a8678 100644 --- a/README.md +++ b/README.md @@ -625,6 +625,7 @@ See [Web UI Setup Guide](docs/webui-setup.md) for detailed configuration. - **BUG-T6 → FU-P13-T8 (P0):** Web UI port collisions can happen when multiple MCP sessions start with the same `--web-ui-port` (for example `8080`), producing `address already in use`. - **BUG-T7 → FU-P13-T9 (P0):** `resources/list` and `resources/templates/list` probing may return non-standard error shapes in some client paths. - **Codex Desktop resources probe behavior:** Xcode MCP is a tools-focused server. Some Codex Desktop paths may still probe `resources/list` and `resources/templates/list`; `-32601` ("unknown method") on those two calls does **not** mean tool connectivity is broken. Validate health with an actual Xcode tool call (for example `XcodeListWindows`). +- **Codex broker-mode timeout fallback:** If Codex tool calls time out in broker mode, switch to direct mode (remove `--broker`) and validate with `XcodeListWindows`. ### Disclaimer (Codex App) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 37b7217..336ad07 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -466,6 +466,7 @@ Important for multi-agent setups: - **BUG-T6 → FU-P13-T8 (P0):** Web UI port collisions can happen when multiple MCP sessions start with the same `--web-ui-port` (for example `8080`), producing `address already in use`. - **BUG-T7 → FU-P13-T9 (P0):** `resources/list` and `resources/templates/list` probing may return non-standard error shapes in some client paths. - **Codex Desktop resources probe behavior:** Xcode MCP is a tools-focused server. Some Codex Desktop paths may still probe `resources/list` and `resources/templates/list`; `-32601` ("unknown method") on those two calls does **not** mean tool connectivity is broken. Validate health with an actual Xcode tool call (for example `XcodeListWindows`). +- **Codex broker-mode timeout fallback:** If Codex tool calls time out in broker mode, switch to direct mode (remove `--broker`) and validate with `XcodeListWindows`. ### Disclaimer (Codex App)