diff --git a/CHANGELOG.md b/CHANGELOG.md index d2610e5..a131ed8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,30 @@ All notable changes to the mcpbridge-wrapper project will be documented in this The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.4.3] - 2026-03-10 + +### Fixed + +- Broker now keeps external `tools/list` requests behind a warmed tool-catalog gate, retries empty internal warm-up probes, and returns a deterministic `-32001` timeout if the catalog never becomes safely ready instead of exposing a premature empty success. + +### Changed + +- Added troubleshooting guidance for stale editable installs after a version bump so local development environments can distinguish outdated `.venv` package metadata from the latest `uvx`-fetched release and refresh the editable install with `pip install -e .`. + +## [0.4.2] - 2026-03-07 + +### Added + +- Introduced the broker terminal frontend, one-command broker host startup flow, and broker doctor diagnostics for faster local diagnosis of broker state and Xcode connectivity issues. + +### Changed + +- Reworked the broker quickstart and recovery guidance around the simplest supported broker UX, including dedicated-host workflow documentation and local-status fallback when the dashboard API is unavailable. + +### Fixed + +- Improved broker startup recovery around dashboard port ownership conflicts so guidance distinguishes foreign listeners from broker-owned listeners and keeps users on the correct remediation path. + ## [0.4.1] - 2026-03-06 ### Fixed @@ -89,6 +113,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - ✅ Support for all 20 Xcode MCP tools - ✅ Configuration examples for Cursor, Claude Code, and Codex CLI +[0.4.3]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.3 +[0.4.2]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.2 +[0.4.1]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.1 [0.4.0]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.0 [0.3.2]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.3.2 [0.3.1]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.3.1 diff --git a/README.md b/README.md index db1738d..830aeb8 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ -[![Version](https://img.shields.io/badge/version-0.4.2-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.2) +[![Version](https://img.shields.io/badge/version-0.4.3-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.3) [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index a5f7945..f9d0e30 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -6,6 +6,7 @@ | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P8-T2 | [P8-T2_Prepare_for_Release_0.4.3/](P8-T2_Prepare_for_Release_0.4.3/) | 2026-03-10 | PASS | | P1-T13 | [P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/](P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/) | 2026-03-10 | PASS | | P2-T8 | [P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/](P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/) | 2026-03-10 | PASS | | P8-T1 | [P8-T1_Release_version_0.4.2_to_PyPI_and_MCP_Registry/](P8-T1_Release_version_0.4.2_to_PyPI_and_MCP_Registry/) | 2026-03-07 | PASS | @@ -207,6 +208,7 @@ | File | Description | |------|-------------| +| [REVIEW_release_0.4.3_preparation.md](P8-T2_Prepare_for_Release_0.4.3/REVIEW_release_0.4.3_preparation.md) | Review report for P8-T2 | | [REVIEW_p1_t13_editable_install_troubleshooting.md](_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md) | Review report for P1-T13 | | [REVIEW_p2_t8_tools_catalog_gate.md](_Historical/REVIEW_p2_t8_tools_catalog_gate.md) | Review report for P2-T8 | | [REVIEW_broker_ux_docs.md](_Historical/REVIEW_broker_ux_docs.md) | Review report for P7-T5 | @@ -640,6 +642,8 @@ | 2026-03-07 | P7-T2 | Archived REVIEW_broker_doctor_diagnostics report | | 2026-03-07 | P7-T3 | Archived Auto-recover_or_guide_on_dashboard_port_ownership_conflicts (PASS) | | 2026-03-07 | P7-T3 | Archived REVIEW_dashboard_port_ownership_conflicts report | +| 2026-03-10 | P8-T2 | Archived Prepare_for_Release_0.4.3 (PASS) | +| 2026-03-10 | P8-T2 | Archived REVIEW_release_0.4.3_preparation report | | 2026-03-10 | P2-T8 | Archived Gate_broker_tools_list_on_warmed_tool_catalog (PASS) | | 2026-03-10 | P2-T8 | Archived REVIEW_p2_t8_tools_catalog_gate report | | 2026-03-10 | P1-T13 | Archived Document_stale_editable_install_version_mismatch_in_troubleshooting_guide (PASS) | diff --git a/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/P8-T2_Prepare_for_Release_0.4.3.md b/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/P8-T2_Prepare_for_Release_0.4.3.md new file mode 100644 index 0000000..8c26b2f --- /dev/null +++ b/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/P8-T2_Prepare_for_Release_0.4.3.md @@ -0,0 +1,131 @@ +# P8-T2: Prepare for Release 0.4.3 + +**Status:** In Progress +**Date:** 2026-03-10 +**Priority:** P0 +**Dependencies:** P1-T13, P2-T8 (completed) + +--- + +## Objective + +Prepare patch release `0.4.3` for the work merged after `v0.4.2`: +- `P2-T8` hardened broker startup by gating `tools/list` on a warmed tool catalog and retrying the probe instead of exposing a transient empty catalog to clients. +- `P1-T13` documented the editable-install version mismatch trap so local development setups can self-diagnose stale `.venv` metadata after a version bump. + +The deliverable is a merge-ready branch that updates release metadata, records release notes in `CHANGELOG.md`, passes the full pre-release quality gate suite, and leaves exact post-merge tag/publish commands for the human operator. + +**Scope boundary:** Creating and pushing the `v0.4.3` tag, publishing to PyPI, and publishing to the MCP Registry remain post-merge human actions on `main`. This task prepares the branch and validates the repository state before those actions. + +--- + +## Current State + +| Artifact | Current value | +|----------|---------------| +| `pyproject.toml` version | `0.4.2` | +| `server.json` root version | `0.4.2` | +| `server.json` package version | `0.4.2` | +| `README.md` version badge | `v0.4.2` | +| Latest git tag on current baseline | `v0.4.2` | +| Unreleased merged work since `v0.4.2` | `P2-T8`, `P1-T13` | + +--- + +## Deliverables + +1. **`pyproject.toml`** — `[project].version` updated to `0.4.3`. +2. **`server.json`** — root `version` and `packages[0].version` updated to `0.4.3`. +3. **`README.md`** — version badge updated to `v0.4.3`. +4. **`CHANGELOG.md`** — new `[0.4.3] - 2026-03-10` entry summarizing the shipped fixes/docs. +5. **`SPECS/INPROGRESS/P8-T2_Validation_Report.md`** — records release metadata checks, quality gates, and post-merge publish instructions. + +--- + +## Implementation Steps + +### 1. Update release metadata + +Use the existing release helpers so version fields stay in sync: + +```bash +make bump-version VERSION=0.4.3 +make badge-version TAG=v0.4.3 +``` + +This updates: +- `pyproject.toml` +- `server.json` +- `README.md` version badge block + +### 2. Add release notes + +Update `CHANGELOG.md` with a new `0.4.3` entry that covers: +- broker `tools/list` warm-catalog gating / retry behavior (`P2-T8`) +- the editable-install troubleshooting addition (`P1-T13`) + +### 3. Run pre-release quality gates + +Run the full local validation suite required by FLOW, `CONTRIBUTING.md`, and this release workflow: + +```bash +pytest tests/ -v --cov=src --cov-report=term +python -m ruff check src/ tests/ +python -m ruff format --check src/ tests/ +mypy src/ +make doccheck-all +python -m build +twine check dist/* +``` + +### 4. Record release validation + +Write `SPECS/INPROGRESS/P8-T2_Validation_Report.md` with: +- the exact versions now present in release metadata +- changelog verification +- quality gate outcomes +- explicit post-merge steps for tagging and publish verification + +### 5. Post-merge operator steps + +These commands must be executed only after the PR merges into `main`: + +```bash +git checkout main +git pull origin main +git tag v0.4.3 +git push origin v0.4.3 +``` + +Then verify: +- GitHub Actions `publish-mcp.yml` succeeds for `v0.4.3` +- PyPI serves `mcpbridge-wrapper==0.4.3` +- the MCP Registry reflects `0.4.3` + +--- + +## Acceptance Criteria + +- [ ] `pyproject.toml` contains `version = "0.4.3"`. +- [ ] `server.json` root `version` and `packages[0].version` both equal `0.4.3`. +- [ ] `README.md` version badge reflects `v0.4.3`. +- [ ] `CHANGELOG.md` contains `[0.4.3] - 2026-03-10` and summarizes `P2-T8` and `P1-T13`. +- [ ] `pytest tests/ -v --cov=src --cov-report=term` passes with coverage ≥90%. +- [ ] `python -m ruff check src/ tests/` passes. +- [ ] `python -m ruff format --check src/ tests/` passes. +- [ ] `mypy src/` passes. +- [ ] `make doccheck-all` passes. +- [ ] `python -m build` and `twine check dist/*` pass. +- [ ] Validation report captures the exact post-merge commands and verification steps for `v0.4.3`. + +--- + +## Risk Notes + +- `main` is protected. Do not tag or publish from this feature branch; tag only after merge. +- `make badge-version` must be called with explicit `TAG=v0.4.3` so it does not reuse `v0.4.2`. +- If the local editable install was not refreshed after the version bump, local `mcpbridge-wrapper --version` output may lag until `pip install -e .` is rerun. This is documented by `P1-T13`. + +--- +**Archived:** 2026-03-10 +**Verdict:** PASS diff --git a/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/P8-T2_Validation_Report.md b/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/P8-T2_Validation_Report.md new file mode 100644 index 0000000..e528c2a --- /dev/null +++ b/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/P8-T2_Validation_Report.md @@ -0,0 +1,65 @@ +# P8-T2 Validation Report — Prepare for Release 0.4.3 + +**Date:** 2026-03-10 +**Branch:** `codex/feature/P8-T2-prepare-release-0.4.3` +**Python:** `3.10.19` +**Verdict:** PASS + +--- + +## Deliverables Checklist + +| Deliverable | Status | Detail | +|-------------|--------|--------| +| `pyproject.toml` version = `0.4.3` | ✅ PASS | Updated via `make bump-version VERSION=0.4.3` | +| `server.json` root `version` = `0.4.3` | ✅ PASS | Updated by `scripts/publish_helper.py` | +| `server.json` `packages[0].version` = `0.4.3` | ✅ PASS | Updated by `scripts/publish_helper.py` | +| `README.md` badge updated to `v0.4.3` | ✅ PASS | Updated via `make badge-version TAG=v0.4.3` | +| `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` badge updated to `v0.4.3` | ✅ PASS | Synced via `python scripts/update_version_badge.py --readme ... --tag v0.4.3` | +| `CHANGELOG.md` contains `[0.4.3] - 2026-03-10` | ✅ PASS | Added release notes for `P2-T8` and `P1-T13` | + +--- + +## Quality Gates + +| Gate | Result | Detail | +|------|--------|--------| +| `pytest tests/ -v --cov=src --cov-report=term` | ✅ PASS | `902 passed, 5 skipped, 2 warnings in 8.93s` | +| Coverage ≥ 90% | ✅ PASS | Total coverage: **91.55%** | +| `python -m ruff check src/ tests/` | ✅ PASS | All checks passed | +| `python -m ruff format --check src/ tests/` | ✅ PASS | `55 files already formatted` | +| `mypy src/` | ✅ PASS | `Success: no issues found in 20 source files` | +| `make doccheck-all` | ✅ PASS | README and DocC overview stayed in sync across unstaged/staged/branch scopes | +| `python -m build` | ✅ PASS | Built `dist/mcpbridge_wrapper-0.4.3.tar.gz` and `dist/mcpbridge_wrapper-0.4.3-py3-none-any.whl` | +| `twine check dist/*` | ✅ PASS | Wheel and sdist metadata both passed | + +--- + +## Release Notes Scope + +`0.4.3` is prepared as a patch release for the work merged after `v0.4.2`: + +- `P2-T8` prevents clients from seeing a premature empty `tools/list` success by gating on a warmed, valid tool catalog and retrying empty warm-up probes. +- `P1-T13` documents how stale editable-install metadata can make a local `.venv` report an older package version than the current `uvx` release after version bumps. + +--- + +## Remaining Steps (post-merge) + +The following steps are intentionally deferred until the PR merges into `main`: + +1. `git checkout main` +2. `git pull origin main` +3. `git tag v0.4.3` +4. `git push origin v0.4.3` +5. Verify GitHub Actions `publish-mcp.yml` for `v0.4.3` completes successfully +6. Verify `https://pypi.org/project/mcpbridge-wrapper/0.4.3/` is live +7. Verify the MCP Registry reflects `0.4.3` + +These checks are acceptance criteria that cannot be completed on the feature branch without publishing from the wrong ref. + +--- + +## Summary + +All pre-merge release-preparation deliverables are complete. Version metadata is consistent across package, registry manifest, README, and DocC overview; the changelog captures the shipped work; and the full local validation suite required by FLOW, `CONTRIBUTING.md`, and `PUBLISHING.md` passed. diff --git a/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/REVIEW_release_0.4.3_preparation.md b/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/REVIEW_release_0.4.3_preparation.md new file mode 100644 index 0000000..783f472 --- /dev/null +++ b/SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/REVIEW_release_0.4.3_preparation.md @@ -0,0 +1,34 @@ +## REVIEW REPORT — release_0.4.3_preparation + +**Scope:** `origin/main..HEAD` +**Files:** 10 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues + +- None. + +### Secondary Issues + +- None. + +### Architectural Notes + +- The release-preparation branch keeps publication side effects out of scope for the PR itself, which matches the protected-`main` workflow documented in `CONTRIBUTING.md` and `PUBLISHING.md`. +- README and DocC overview version badges were updated together, so the branch remains compatible with `make doccheck-all`. +- `CHANGELOG.md` now documents only the work merged after `v0.4.2`, keeping the patch-release scope narrow and reviewable. + +### Tests + +- `pytest tests/ -v --cov=src --cov-report=term` passed with `902 passed, 5 skipped, 2 warnings` and `91.55%` total coverage. +- `python -m ruff check src/ tests/`, `python -m ruff format --check src/ tests/`, `mypy src/`, `make doccheck-all`, `python -m build`, and `twine check dist/*` all passed. + +### Next Steps + +- No actionable review findings. FOLLOW-UP is skipped. +- After merge, run the documented `git tag v0.4.3` / `git push origin v0.4.3` sequence on `main` and verify the `publish-mcp.yml` workflow, PyPI package page, and MCP Registry entry. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 3a112cf..323b4c9 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -15,6 +15,7 @@ task only after a follow-up or new workplan entry is created. ## Recently Archived +- `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` @@ -22,3 +23,15 @@ task only after a follow-up or new workplan entry is created. - `2026-03-07` — `P7-T4` archived with verdict `PASS` - `2026-03-07` — `FU-P7-T3-2` archived with verdict `PASS` - `2026-03-07` — `FU-P7-T3-1` archived with verdict `PASS` + +## Post-Merge Action Required + +After the `P8-T2` PR merges to `main`, push the release tag to trigger publishing: + +```bash +git checkout main && git pull origin main +git tag v0.4.3 +git push origin v0.4.3 +``` + +Then verify GitHub Actions `publish-mcp.yml` completes successfully. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 6daa9fc..8d56120 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -640,3 +640,25 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [ ] Git tag `v0.4.2` exists on `origin/main` (post-merge) - [ ] `https://pypi.org/project/mcpbridge-wrapper/0.4.2/` is accessible (post-merge) - [ ] GitHub Actions `publish-mcp.yml` run for tag `v0.4.2` shows all steps green (post-merge) + +#### ✅ P8-T2: Prepare for Release 0.4.3 +- **Status:** ✅ Completed (2026-03-10) +- **Description:** Prepared patch release `0.4.3` for the work merged after `v0.4.2`, covering the broker warmed-tool-catalog readiness fix (`P2-T8`) and the editable-install troubleshooting guidance (`P1-T13`). Bumped release metadata to `0.4.3`, synced the README and DocC overview badges, added changelog release notes, and validated the full local pre-release gate suite. Tagging and publication remain post-merge actions on `main`. +- **Priority:** P0 +- **Dependencies:** P1-T13, P2-T8 +- **Parallelizable:** no +- **Outputs/Artifacts:** + - `pyproject.toml` — version set to `0.4.3` + - `server.json` — root and package versions set to `0.4.3` + - `README.md` and `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` — version badges updated to `v0.4.3` + - `CHANGELOG.md` — `[0.4.3]` entry added for `P2-T8` and `P1-T13` + - `SPECS/ARCHIVE/P8-T2_Prepare_for_Release_0.4.3/` — archived PRD + validation report + - (Post-merge, human action) `git tag v0.4.3` push triggers PyPI + MCP Registry publish +- **Acceptance Criteria:** + - [x] `pyproject.toml` and `server.json` both contain version `0.4.3` + - [x] `README.md` version badge reflects `v0.4.3` + - [x] `CHANGELOG.md` contains a `[0.4.3]` entry dated `2026-03-10` covering the release contents + - [x] `pytest tests/ -v --cov=src --cov-report=term`, `ruff check src/ tests/`, `ruff format --check src/ tests/`, `mypy src/`, `make doccheck-all`, `python -m build`, and `twine check dist/*` all pass + - [ ] Git tag `v0.4.3` exists on `origin/main` (post-merge) + - [ ] `https://pypi.org/project/mcpbridge-wrapper/0.4.3/` is accessible (post-merge) + - [ ] GitHub Actions `publish-mcp.yml` run for tag `v0.4.3` shows all steps green (post-merge) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 13b56f3..a46f022 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -8,7 +8,7 @@ Model Context Protocol (MCP). [https://github.com/SoundBlaster/XcodeMCPWrapper](https://github.com/SoundBlaster/XcodeMCPWrapper) -[![Version](https://img.shields.io/badge/version-0.4.2-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.2) +[![Version](https://img.shields.io/badge/version-0.4.3-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.3) ## Overview diff --git a/pyproject.toml b/pyproject.toml index e1ca32b..0ad1615 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "mcpbridge-wrapper" -version = "0.4.2" +version = "0.4.3" description = "Python wrapper for xcrun mcpbridge that adds structuredContent to MCP responses" readme = "README.md" requires-python = ">=3.9" diff --git a/server.json b/server.json index 6682d49..be1099a 100644 --- a/server.json +++ b/server.json @@ -3,7 +3,7 @@ "name": "io.github.SoundBlaster/xcode-mcpbridge-wrapper", "title": "Xcode: MCP Bridge Wrapper for Cursor", "description": "Python wrapper that makes Xcode's MCP bridge compatible with strict MCP clients like Cursor", - "version": "0.4.2", + "version": "0.4.3", "repository": { "url": "https://github.com/SoundBlaster/XcodeMCPWrapper", "source": "github" @@ -13,7 +13,7 @@ { "registryType": "pypi", "identifier": "mcpbridge-wrapper", - "version": "0.4.2", + "version": "0.4.3", "transport": { "type": "stdio" },