Title: `devframe connect --port` can't reach a hub mounted under a base path (Vite DevTools `/__devtools/`) and reports it as "no MCP endpoint" · Issue #403 · devframes/devframe · GitHub
Open Graph Title: `devframe connect --port` can't reach a hub mounted under a base path (Vite DevTools `/__devtools/`) and reports it as "no MCP endpoint" · Issue #403 · devframes/devframe
X Title: `devframe connect --port` can't reach a hub mounted under a base path (Vite DevTools `/__devtools/`) and reports it as "no MCP endpoint" · Issue #403 · devframes/devframe
Description: Summary devframe connect --port
Open Graph Description: Summary devframe connect --port
X Description: Summary devframe connect --port <n> always probes http://localhost:<n>/__connection.json. Vite DevTools mounts its hub at /__devtools/, so the probe misses the real connection meta at /...
Opengraph URL: https://github.com/devframes/devframe/issues/403
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"`devframe connect --port` can't reach a hub mounted under a base path (Vite DevTools `/__devtools/`) and reports it as \"no MCP endpoint\"","articleBody":"### Summary\n\n`devframe connect --port \u003cn>` always probes `http://localhost:\u003cn>/__connection.json`. Vite DevTools mounts its hub at `/__devtools/`, so the probe misses the real connection meta at `/__devtools/__connection.json`. Vite's SPA fallback answers the root probe with `200 text/html`, and the probe accepts that as a live devframe. The connector then lists a phantom `port-\u003cn>` instance with `mcp: null` and fails `call-tool` with [DF0051](https://devfra.me/errors/df0051), telling the user to \"restart the instance with the --mcp flag\". That flag doesn't exist for a Vite server, and the MCP route is in fact up at `/__devtools/__mcp`.\n\nThere's no flag or documented way to give the connector a base path, so this isn't a usage problem: `--port` is the documented fallback for instances missing from the registry (`docs/content/2.adapters/7.mcp.md`, \"Discovery: `devframe connect`\"), and it only works for root-mounted devframes.\n\n**Scope:** registry-based discovery of Vite DevTools is already handled by vitejs/devtools#579 (merged, not yet released), which registers the hub with its `/__devtools/` base. This issue is only about the `--port` fallback and the `__connection.json` origin probe.\n\n### Versions\n\n- `devframe` 1.0.0, `@devframes/agentic` 1.0.0, `@devframes/hub` 1.0.0, `@devframes/vite` 1.0.0\n- `@vitejs/devtools` 0.7.5, `vite` 8.3.0\n- Node 24.21.0, Windows 11. Nothing here is platform-specific.\n- `main` at `18fa60e` has no changes to `packages/agentic/src/connect/` or `packages/devframe/src/node/instance-registry.ts` since `v1.0.0`, so the behavior is the same there.\n\n### Reproduction\n\n1. Run any Vite 8.3 app with `@vitejs/devtools` 0.7.5 enabled (dev server on `127.0.0.1:5174` here, `mcp` left at its default).\n2. The hub is alive under its base:\n ```sh\n curl -s http://127.0.0.1:5174/__devtools/__connection.json\n # {\"backend\":\"websocket\",\"websocket\":{\"path\":\"/__devtools/__ws\"},...,\"mcp\":{\"path\":\"__mcp\"},...}\n curl -s -o /dev/null -w '%{http_code} %{content_type}\\n' http://127.0.0.1:5174/__connection.json\n # 200 text/html \u003c- Vite SPA fallback (index.html)\n ```\n3. Start the connector with an empty registry and call both gateway tools over stdio:\n ```sh\n DEVFRAME_INSTANCES_DIR=$(mktemp -d) npx devframe connect --port 5174\n ```\n `devframe_connect_list-instances` returns:\n ```json\n { \"id\": \"port-5174\", \"port\": 5174, \"basePath\": \"/\", \"mcp\": null,\n \"hint\": \"This instance runs without an MCP route. Restart it with the --mcp flag to expose its tools, then list instances again.\" }\n ```\n `devframe_connect_call-tool` `{ \"port\": 5174, \"tool\": \"devframes_plugin_inspect_list-state-keys\" }` returns:\n ```json\n { \"error\": { \"code\": \"DF0051\", \"message\": \"The devframe instance on port 5174 has no MCP endpoint.\",\n \"fix\": \"Restart the instance with the --mcp flag to expose its tools, then list instances again.\" } }\n ```\n\nFor comparison, a registry record with the right base works end to end with the same 1.0.0 connector against the same server: 11 tools listed, and `call-tool` returns the state keys. The record is `{\"port\":5174,\"origin\":\"http://127.0.0.1:5174\",\"basePath\":\"/__devtools/\",\"mcp\":{\"path\":\"/__devtools/__mcp\"},...}`, the shape vitejs/devtools#579 now writes. So the MCP route and the connector's proxy are fine; only the `--port` probe is wrong.\n\n### Root cause\n\nAt `18fa60e`:\n\n1. **The base is hardcoded to `/`.** [`packages/agentic/src/connect/index.ts#L202-L217`](https://github.com/devframes/devframe/blob/18fa60effeb928eb445add2a536cd44906a59981/packages/agentic/src/connect/index.ts#L202-L217) (`probePort`) calls `probeDevframeOrigin(\\`http://localhost:${port}\\`, '/', timeoutMs)`, records `basePath: '/'`, and resolves the MCP path with `joinURL('/', probed.meta.mcp.path)`. For a hub at `/__devtools/`, whose meta advertises the relative `\"__mcp\"`, that would give `/__mcp` even if the meta were found. The in-process registration in `instance-shell.ts#L596` correctly uses `joinURL(base, …)`.\n2. **Any `200` counts as a devframe.** [`packages/devframe/src/node/instance-registry.ts#L195-L216`](https://github.com/devframes/devframe/blob/18fa60effeb928eb445add2a536cd44906a59981/packages/devframe/src/node/instance-registry.ts#L195-L216) (`probeDevframeOrigin`) checks only `response.ok`, then falls back to `{}` when `response.json()` fails. An HTML SPA fallback therefore \"proves\" a devframe with no MCP route. That produces the misleading DF0051 instead of DF0050. The same probe is the registry's liveness check, so a stale record whose port is now held by some SPA dev server also stays \"live\" instead of being pruned.\n\n### Related\n\n- vitejs/devtools#579 (merged 2026-09-17, after the 0.7.5 release, not yet published) registers Vite DevTools in the instance registry with its base. That fixes discovery through the registry for the next `@vitejs/devtools` release. `--port` is still the documented fallback for anything unregistered: older `@vitejs/devtools`, `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1`, a registry directory the connector can't see (container, WSL, a different `HOME`), or the window before the hub's first request, since registration waits for the origin.\n- #394 (per-tab MCP routing) touches the same connector but is a different problem.\n- No existing issue found for \"connect\" + base path, `__connection.json` probing, or DF0051 (searched issues and PRs).\n\n### Suggested fix\n\nHappy to send a PR:\n\n- In `probeDevframeOrigin`, accept only a JSON object as connection meta (skip `text/html` or unparseable bodies). A non-devframe `200` then yields \"no instance\" (DF0050) instead of a phantom instance, and stale registry records on a port now held by an unrelated server get pruned.\n- Add a `--base \u003cpath>` option to `devframe connect` (default `/`, with a matching `base` field in `ConnectServerOptions`) that applies to the `--port` probes, and resolve the advertised MCP path against that base the same way `instance-shell` does. `devframe connect --port 5174 --base /__devtools/` would then reach Vite DevTools, and the connector stays free of hardcoded mount paths.\n- Document `--base` in the CLI help and in the \"Discovery\" section of the MCP adapter docs.\n","author":{"url":"https://github.com/zahidzorbaz","@type":"Person","name":"zahidzorbaz"},"datePublished":"2026-09-24T09:27:18Z","url":"https://github.com/devframes/devframe/issues/403"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react-reconciler,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@d5750093facf |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:ef55f541-8b78-ca2a-7384-78e75fa980bc |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | CEDC:2C50EC:101C8A:16A3C9:6AFB6ADE |
| html-safe-nonce | 7af89eb497e3bfcda470e65188458627ac6f72763a1413e560f4a3ff47aa320f |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJDRURDOjJDNTBFQzoxMDFDOEE6MTZBM0M5OjZBRkI2QURFIiwidmlzaXRvcl9pZCI6Ijg1ODI5MDczOTU5Mzg0MTMyNzgiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 92890b9bffebac88a0e418dd7cfb9bdf2a79526fde9010914609f34d6fe8e34b |
| hovercard-subject-tag | issue:5566214695 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/devframes/devframe/403/issue_layout |
| twitter:image | https://opengraph.githubassets.com/33e7bd2fb66f4e47539450f8cc1feeb9e41048721cb39d8d647cf0187401dd44/devframes/devframe/issues/403 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/33e7bd2fb66f4e47539450f8cc1feeb9e41048721cb39d8d647cf0187401dd44/devframes/devframe/issues/403 |
| og:image:alt | Summary devframe connect --port |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | zahidzorbaz |
| hostname | github.com |
| expected-hostname | github.com |
| None | cca289ecd54650fcf3c0b037a58b97186dee2cc4406819d87fab93728fd83700 |
| turbo-cache-control | no-preview |
| go-import | github.com/devframes/devframe git https://github.com/devframes/devframe.git |
| octolytics-dimension-user_id | 279879373 |
| octolytics-dimension-user_login | devframes |
| octolytics-dimension-repository_id | 1231722386 |
| octolytics-dimension-repository_nwo | devframes/devframe |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1231722386 |
| octolytics-dimension-repository_network_root_nwo | devframes/devframe |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 88808b1fae5ab8a526a73e7ce5542a10eb9d6971 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width