Release 0.4.4

XcodeMCPWrapper 0.4.4

This patch release improves reliability around the Xcode approval flow and adds better tooling for diagnosing startup readiness issues.

Added

• Added a deterministic Xcode approval observation harness for capturing timestamped MCP startup traces, timeout windows, EOF boundaries, and tool-catalog readiness behavior during the Xcode permission flow.
• Added a repeatable way to investigate approval-race scenarios without changing user configuration or package metadata.

Fixed

• The broker now emits a synthetic notifications/tools/list_changed when its warmed tool catalog first becomes available.
• The synthetic notification is only re-emitted when a later reconnect produces a materially different non-empty tool catalog, avoiding duplicate refresh signals.

Why This Matters

• Strict MCP clients now get an explicit catalog refresh hint even when Xcode’s upstream bridge does not send tools/list_changed after approval.
• Approval-flow problems are easier to observe, reproduce, and diagnose with structured protocol traces.

Notes

• No configuration changes are required for existing users.
• This release is focused on startup visibility and broker refresh behavior after Xcode approval.

Release 0.4.3

XcodeMCPWrapper 0.4.3

0.4.3 is a patch release focused on broker startup reliability and one development-environment troubleshooting improvement.

Fixed

• Broker no longer exposes a premature empty tools/list result while its internal tool catalog is still warming up.
• External tools/list requests are now held behind a dedicated warmed-catalog readiness gate.
• If the internal warm-up probe returns an empty or invalid catalog, the broker retries the probe instead of caching a broken success.
• When the tool catalog never becomes safely ready, the broker now returns a deterministic -32001 timeout instead of allowing a misleading empty success state.

Changed

• Added troubleshooting guidance for local editable installs where .venv still reports an older package version after a version bump.
• The docs now clarify that uvx fetches the latest published release independently of a local editable install.
• Contributors working from a local checkout can refresh stale version metadata with pip install -e ..

Notes

• No user configuration changes are required for this release.
• This is a patch release on top of 0.4.2; existing broker and Web UI workflows continue to work as before.

0.4.2

Release Notes

Phase 7: Broker UX and Diagnostics

This release focuses on making the broker easier to start, monitor, and recover from failures — replacing multi-step manual sequences with single commands and actionable diagnostics.

---

🚀 One-command broker console (--broker-console)

Start the dedicated broker host and immediately land in the terminal monitoring frontend with a single command. No more manually sequencing --broker-daemon, --web-ui, and --tui separately. If the port is already owned by a healthy broker-backed dashboard, the command attaches to it instead of spawning a duplicate.

---

🩺 Broker doctor diagnostics (--doctor)

A new diagnostic command inspects the full chain visible to the user — Python runtime, broker PID/socket/version files, dashboard endpoint ownership, upstream Xcode bridge state, and common failure modes (stale ports, missing dashboard, version mismatch). Output is user-facing and actionable without requiring manual lsof, curl, or log inspection.

---

⚡ Dashboard port-conflict recovery

Startup no longer silently leaves a broker running without its requested dashboard. Port conflicts now fail fast with one explicit remediation path. The conflict classifier distinguishes:

• Foreign process on the dashboard port
• Broker-owned listener with a degraded probe
• Mixed state (live broker PID + foreign listener)

Each case surfaces the real blocker and the exact recovery command.

---

🖥️ TUI local-status fallback

The terminal frontend now remains useful even when the Web UI dashboard API is unavailable. It falls back to local broker state from PID/socket/version files and clearly distinguishes live dashboard-backed data from local fallback data, so you can tell at a glance whether you need to restart the broker, free a port, or just attach a client.

---

📖 Simplified broker UX docs and quickstart

New docs/quickstart.md presents the recommended end-to-end broker workflow in 5 steps. docs/broker-mode.md is restructured quickstart-first with a dedicated failure recovery section. docs/troubleshooting.md now references --doctor and the quickstart directly, replacing raw shell debugging instructions.

---

Bug Fixes / Follow-ups

• --broker-console interrupt normalization — Ctrl-C now exits cleanly with code 0 whether the console spawned a new host or reattached to an existing one.
• Mixed-state conflict prioritization — foreign port-owner guidance is surfaced first when both a live broker PID and a foreign dashboard listener coexist, preventing users from being sent into a broker-reset loop for the wrong blocker.
• Broker-owned listener exclusion — the conflict classifier no longer treats the broker's own dashboard listener as a foreign port owner during degraded-probe scenarios.

v0.4.1

Fixed

• Broker daemon now sends notifications/initialized to the upstream before the tools/list probe, completing the MCP handshake and unblocking client requests that previously stalled and timed out.

Published Artifacts

• PyPI package: mcpbridge-wrapper==0.4.1
• MCP Registry server: io.github.SoundBlaster/xcode-mcpbridge-wrapper

Release v0.3.3

• Fixed the BUG-T0 Uptime widget on Web UI always shows 1h 0m 0s #32

Version 0.3.2

Fix publishing to https://registry.modelcontextprotocol.io/?q=Xcode

Version 0.3.1

Version 0.3.1

Fixed issues

• FU-REBUILD-P10-T1-7: packaged Web UI static assets so --web-ui serves full dashboard instead of
  fallback HTML.
• FU-P9-T2-1: updated uvx Web UI examples/configs to use mcpbridge-wrapper[webui] to avoid missing
  dependency errors.

v0.3.0

Changelog

All notable changes to the mcpbridge-wrapper project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

0.3.0 - 2026-02-13

Added

• Optional Web UI dashboard for real-time wrapper monitoring (--web-ui)
• Runtime metrics panel with request counts, latency, and error visibility
• Audit logging and activity inspection surfaces for wrapper operations

Changed

• Documentation and setup guidance aligned for Web UI-enabled workflows
• Release metadata bumped to 0.3.0 for PyPI and MCP Registry publication

0.2.0 - 2026-02-08

Added

• MCP Registry publishing support with automated CI/CD workflow
• server.json manifest for MCP Registry compatibility
• GitHub Actions workflow for publishing to PyPI and MCP Registry

Changed

• Version bump for initial PyPI and MCP Registry release

0.1.0 - 2026-02-08

Added

• Phase 1: Foundation - Project structure, Python packaging, development tooling
• Phase 2: Core Bridge - Subprocess wrapper around xcrun mcpbridge with bidirectional I/O
• Phase 3: Response Transformation - JSON parsing, MCP compliance detection, structuredContent injection
• Phase 4: Edge Cases - Empty content, non-text content, already compliant responses, error handling
• Phase 5: Testing - Comprehensive unit tests (98%+ coverage), integration tests, performance benchmarks
• Phase 6: Packaging - Installation script, configuration templates for Cursor/Claude/Codex
• Phase 7: Documentation - Installation guide, configuration guides, troubleshooting, API reference

Features

• ✅ MCP protocol compatibility fix for Cursor
• ✅ Line-buffered I/O for minimal latency (<0.01ms overhead)
• ✅ Memory-efficient processing (<10MB footprint)
• ✅ Graceful error handling and process lifecycle management
• ✅ Support for all 20 Xcode MCP tools
• ✅ Configuration examples for Cursor, Claude Code, and Codex CLI

0.2.0

Release Notes - v0.2.0

Release Date: 2026-02-08

MCP Registry & PyPI Publishing

This release focuses on making the package available through the MCP Registry and PyPI with automated CI/CD workflows:

• https://registry.modelcontextprotocol.io/?q=xcode-mcpbridge-wrapper
• https://pypi.org/project/mcpbridge-wrapper/

Added

1. MIT License - Added open-source licensing for distribution
2. MCP Distribution Support - Initial setup for MCP Registry publishing
3. PyPI Classifier Fix - Changed from invalid 'Tools' to valid 'Build Tools' classifier
4. CI Workflow Fix - Removed mcp-publisher validate step (command not available in CI)
5. GitHub Authentication Fix - Fixed server name casing to "SoundBlaster" (capital S) for GitHub auth
6. Documentation Updates - Updated docs for MCP Registry publication
7. Package Discoverability Improvements:

• Improved title: "Xcode: MCP Bridge Wrapper for Cursor"
• Renamed server: xcode-mcpbridge-wrapper for better discoverability

Documentation & Website

8. Apple DocC Documentation Support (P8-T1):

• Added DocC documentation publishing workflow
• Created documentation catalog for soundblaster.github.io GitHub Pages
• Added swift-docc-plugin for documentation generation
• Fixed DocC hosting base path to match repository name

9. DocC Canonical Structure (P8-T2):

• Restructured DocC to canonical Swift Package format
• Renamed SPM and DocC from mcpbridge-wrapper to XcodeMCPWrapper
• Fixed script and config references after SPM/DocC rename

10. Deployment Path Change (P8-T3):

• Changed deployment path from mcpbridge-wrapper to xcodemcpwrapper
• Updated all references in scripts and configurations

CI/CD & Automation

11. GitHub CI Workflow (P6-T10):

• Added GitHub Actions workflow for automated testing
• Integrated PyPI publishing via OIDC
• Added linting and formatting checks (ruff)
• Added dev dependencies to pyproject.toml
• Fixed Python 3.11/3.12 test failures
• Added CONTRIBUTING.md with PR-only workflow rule
• Added DocC documentation sync check

Files Added/Updated

• server.json - MCP server manifest for registry compatibility
• .github/workflows/publish-mcp.yml - Automated publishing workflow
• .github/workflows/ci.yml - Continuous integration workflow
• .github/workflows/docs.yml - Documentation publishing workflow
• CONTRIBUTING.md - Contribution guidelines
• PUBLISHING.md - Publishing documentation
• LICENSE - MIT License
• Package.swift - Swift Package Manager manifest for DocC documentation build
• Sources/XcodeMCPWrapper/Documentation.docc/ - DocC documentation catalog

Version History

Version   Changes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
0.1.0     Initial release with core functionality
0.1.1     MCP Distribution setup
0.1.2     PyPI classifier fix
0.1.3     CI workflow fix
0.1.4     Version bump for GitHub auth fix
0.1.5     Documentation updates for MCP Registry
0.1.6     Title improvement for discoverability
0.1.7     Server rename for better discoverability
0.2.0     DocC documentation, CI/CD, deployment path changes

0.1.0

XcodeMCPWrapper - mcpbridge-wrapper - v0.1.0

MCP protocol compatibility fix for Xcode's xcrun mcpbridge.

What it does

Xcode 26.3+ includes an MCP bridge that exposes Xcode's internal tools to AI agents. However, it has a protocol compatibility issue: it returns tool responses in the content field but omits the required structuredContent field when a tool declares an outputSchema.

This wrapper intercepts responses from xcrun mcpbridge and copies the data from content into structuredContent, making Xcode's MCP tools fully compatible with Cursor, Claude Code, and Codex CLI.

What's included

• ✅ MCP protocol compatibility fix (adds structuredContent to responses)
• ✅ Subprocess wrapper with bidirectional I/O
• ✅ Graceful error handling and process lifecycle management
• ✅ Support for all 20 Xcode MCP tools (BuildProject, RunTests, XcodeRead, XcodeWrite, etc.)
• ✅ Configuration templates for Cursor, Claude Code, and Codex CLI
• ✅ 98%+ test coverage

Quick start

# Install
./scripts/install.sh

# Configure for Cursor (edit ~/.cursor/mcp.json)
{
  "mcpServers": {
    "xcode-tools": {
      "command": "/Users/YOUR_USERNAME/bin/mcpbridge-wrapper"
    }
  }
}

Requirements

• Xcode 26.3+
• Python 3.7+
• Xcode Tools MCP Server enabled in Xcode Settings → Intelligence

Related Links

• https://rudrank.com/exploring-xcode-using-mcp-tools-cursor-external-clients
• https://bleepingswift.com/blog/xcode-mcp-server-ai-workflow