Skip to content

fix(tray): preserve host in normalizeListen + sane port-conflict and core-URL semantics for pinned --listen - #1036

Merged
github-actions[bot] merged 4 commits into
mainfrom
fix/tray-listen-followups
Aug 25, 2026
Merged

github-actions[bot] merged 4 commits into
mainfrom
fix/tray-listen-followups

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 24, 2026

Copy link
Copy Markdown
Member

Three follow-ups to #1015 (tray --listen forwarding).

1. normalizeListen no longer widens a bind (security-adjacent).
normalizeListen("127.0.0.1:8181") returned ":8181" — an all-interfaces bind for an address the user had pinned to loopback. That value is handed to the core as --listen from both the MCPPROXY_TRAY_LISTEN path and the CLI path added in #1015. New rules: a pinned host is preserved verbatim (IPv6 included), a bare port (8181) defaults to loopback — mirroring listenArgFromURL's "never bind to all interfaces" rule for derived addresses — an explicit all-interfaces request (:8181, 0.0.0.0:8181) is honored as written, and anything that isn't a host:port pair passes through for the core to reject.

2. A pinned --listen fails loudly on port conflict.
handlePortConflictError bumped the port and relaunched, expecting buildCoreArgs to derive the new port from coreURL. Since an explicit CLI --listen now always wins, that retry would re-hit the same busy port forever. Decision (documented at the call site): an explicitly pinned listen is a user contract — the core comes up on that address or not at all. On conflict the tray logs an error, records it on the state machine, and shows a notification, staying in the port-conflict state. Silently moving off the pinned address would be worse: clients configured for it would talk to nothing. Unpinned setups keep the old auto-bump (the env listen still flows through coreURL, so bumping still reaches the core there).

3. resolveCoreURL honors the CLI listen on the TCP fallback.
Without a socket, the core bound the pinned port while the tray probed 127.0.0.1:8080. The parsed CLI listen is now fed in and takes priority over MCPPROXY_TRAY_LISTEN / MCPPROXY_TRAY_PORT; wildcard binds are dialed on loopback.

Table tests cover loopback / explicit host / bare port / all-interfaces / IPv6 / garbage inputs, plus the URL and port-conflict semantics. New tray notification helper added to both the real and the linux/headless stub file.

…core-URL semantics for pinned --listen

Three follow-ups to PR #1015 (tray --listen forwarding):

1. normalizeListen("127.0.0.1:8181") returned ":8181", silently rebinding a
   loopback-pinned address to every interface — and that value is forwarded
   verbatim as the core's --listen from both the MCPPROXY_TRAY_LISTEN path and
   the new CLI path. It now never widens a bind: a pinned host is preserved
   (IPv6 included), a bare port defaults to loopback (matching
   listenArgFromURL's rule for derived addresses), an explicit all-interfaces
   request is honored, and unparseable input passes through for the core to
   reject.

2. handlePortConflictError bumped the port and relaunched, expecting
   buildCoreArgs to derive the new one from coreURL — but an explicit CLI
   --listen always wins, so the retry would re-hit the same busy port forever.
   An explicitly pinned listen is now treated as a user contract: fail loudly
   (error log + state-machine error + tray notification) instead of silently
   retrying or silently moving off the pinned address. Unpinned setups keep the
   auto-bump. The choice is documented at the call site.

3. resolveCoreURL ignored the CLI listen on the TCP-fallback path, so the core
   bound the pinned port while the tray probed the default. It now takes the
   parsed CLI listen (highest priority, above MCPPROXY_TRAY_LISTEN and
   MCPPROXY_TRAY_PORT); wildcard binds are dialed on loopback.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 24, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: f089602
Status: ✅  Deploy successful!
Preview URL: https://a233a7ff.mcpproxy-docs.pages.dev
Branch Preview URL: https://fix-tray-listen-followups.mcpproxy-docs.pages.dev

View logs

@codecov-commenter

codecov-commenter commented Aug 24, 2026 •

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/tray/notifications_stub.go 0.00% 2 Missing ⚠️

📢 Thoughts on this report? Let us know!

Cross-model review finding on the new coreURLFromListen(): it built the
URL by string concatenation, so a zoned IPv6 listen such as
"[fe80::1%en0]:8181" produced "http://[fe80::1%en0]:8181" — which
url.Parse rejects outright with `invalid URL escape "%en"`. Every later
parse of the core URL (readiness checks, listenArgFromURL, the
port-conflict handler) would then fail on an address the function was
specifically meant to support, since it already claimed IPv6 handling.

Build the URL through url.URL instead, which escapes the zone
("fe80::1%en0" -> "fe80::1%25en0") and round-trips through url.Parse.

Adds the zoned case to the coreURLFromListen table plus a
TestCoreURLFromListen_AlwaysParseable invariant asserting that every
derived core URL survives url.Parse with the expected port.

Also tightens docs/tray-debug.md: an all-interfaces value supplied via
MCPPROXY_TRAY_LISTEN / MCPPROXY_TRAY_PORT is narrowed to loopback
(the core's --listen is derived from the URL the tray dials), so the
tray's own --listen flag is the way to ask for a LAN-exposed bind. The
previous wording implied the variables forwarded any host as written.
@github-actions

github-actions Bot commented Aug 24, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: fix/tray-listen-followups

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (25 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (20 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 32765422339 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

Second cross-model review round. Before the resolveCoreURL rework, an
unparseable MCPPROXY_TRAY_LISTEN / --listen produced an unparseable core
URL, so listenArgFromURL returned "" and buildCoreArgs fell through to
the raw env value — handing the core a bad --listen that it rejected
loudly. Now coreURLFromListen returns "" for such a value and
resolveCoreTCPURL falls through to the valid default endpoint, so
listenArgFromURL succeeds and the explicitly configured address is
dropped without a trace. Worse, when a core is already listening on that
default the tray attaches to it and looks like it honoured an address it
actually ignored.

Add unparseableListenSources(), which reports every explicitly set
listen value that cannot be turned into a dialable endpoint, and log each
one at Warn from main() next to the resolved core URL. This keeps
normalizeListen's stated contract — unparseable input is surfaced rather
than silently rewritten — on the path that no longer reaches the core.

Behaviour is otherwise unchanged: valid values (bare port, pinned host,
wildcard, IPv6) report nothing, and blank/whitespace values count as unset.
…ppened

Third cross-model review round. The warning added in the previous commit
claimed the value was "ignored" and that the tray fell back to "the
default core endpoint". Both can be wrong: with an invalid --listen and a
valid MCPPROXY_TRAY_LISTEN, resolution falls through to the env endpoint
rather than the default, and the invalid CLI value is still forwarded to
the launched core by buildCoreArgs, so it is not ignored either.

Reword to the accurate, neutral claim — the value cannot form an endpoint
the tray can dial and therefore did not determine the core URL — and keep
the resolved core_url field so the log still shows which endpoint won.
No behaviour change.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved (Model B): Paperclip review verdicts = ACCEPT and qa-gate green at this head SHA. Arming auto-merge; GitHub merges when all required checks pass.

@github-actions
github-actions Bot merged commit 1282f04 into main Aug 25, 2026
38 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants