Repository navigation
[chore] Align local app ports #11
Description
Motivation
Local app ports are currently temporary and inconsistent across packages: server-context commonly uses 8787, server-brain uses 8788, and the MCP setup documentation/example points at 8789. These ports are scattered across defaults, environment examples, tests, and setup docs, which makes local startup and proxy configuration easy to confuse. We should reserve a dedicated, less commonly proxied local port block for the apps (candidate: 18787–18789).
Scope
- Define one local port policy and a single source of truth for the HTTP apps.
- Move the Context Server and Brain Server defaults to the selected dedicated port block (candidate: Context
18787, Brain18788; reserve18789for a future HTTP app if useful). - Update Wrangler/dev commands, environment examples, Chrome defaults/placeholders/tests, and all README/setup documentation consistently.
- Keep
server-mcpdocumented as stdio-only; it must not claim or require its own HTTP port. ItsCONTEXT_SERVER_URLshould point to the Context Server port. - Do not change Cloudflare deployment URLs or ephemeral test ports.
Acceptance criteria
- A documented port table identifies each HTTP app, host, port, and ownership.
- No stale
8787/8788/8789references remain in local defaults, examples, or setup instructions unless explicitly documented as historical/intentional. - A fresh local setup can start Context Server and Brain Server without port ambiguity, and Chrome connects to the selected defaults.
- MCP setup connects to the selected Context Server URL while remaining stdio-only.
- Relevant package tests and
pnpm verifypass.
Verification plan
- Search the repository for all old and new port references.
- Start the local Context Server and Brain Server with the documented commands and verify their health/action endpoints.
- Build/test the Chrome client and MCP server against the updated local URLs.
- Run
pnpm verifyfrom the repository root.
Metadata
Metadata
Assignees
Labels
No labels
Activity
ThreeLight2000 commentedon Aug 18, 2026
Discussion starter
Based on the current repository layout, I suggest starting with this local port policy:
127.0.0.1:18787(the only HTTP dependency for MCP)127.0.0.1:18788CONTEXT_SERVER_URLpoints to Context Server on1878718789: keep reserved for a future HTTP app, but do not bind it nowThe
18787–18789block keeps the service order (context → brain) while avoiding the more common local preview/proxy ports. The change should update defaults, environment examples, startup commands, README/setup docs, Chrome placeholders/tests, and MCP examples together.Before implementation, I would like to confirm:
18787–18789an acceptable project-local range?18789remain reserved, or should we only document ports that are currently used?Once these are settled, the implementation can proceed with a repository-wide stale-reference check and
pnpm verify.ThreeLight2000 commentedon Aug 18, 2026
Port range proposal update
17XXXlooks simpler and easier to remember than18787–18789. It also follows the existing pattern of reserving a project-local block such as12001–12XXX, without looking like a transformed version of the current8787/8788/8789values.Suggested allocation:
127.0.0.1:17001127.0.0.1:170021700117XXXas neededThis gives us a compact project convention:
17XXX = Context OS local development services, with the low suffixes assigned in dependency order. I recommend replacing the previous18787–18789candidate with this range.ThreeLight2000 commentedon Aug 18, 2026
Implementation has started on branch
chore/11-align-local-app-ports. The working proposal is Context Server17001, Brain Server17002, and MCP stdio-only.ThreeLight2000 commentedon Aug 18, 2026
Implementation is complete on
chore/11-align-local-app-portsin the dedicated worktree.Updated tracked apps and documentation:
1700117002docs/local-ports.mdas the17XXXlocal service policypnpm verifypasses, and the repository contains no stale8787,8788, or8789references in this worktree. A direct Wrangler startup check was blocked by the sandbox because Wrangler tried to write its log under~/Library/Preferences/.wrangler; this is an environment permission issue, not a test/build failure.The existing uncommitted
server-mcpimplementation remains isolated in the originalfeat/9-context-mcp-serverworktree and was intentionally not copied or modified. ItsCONTEXT_SERVER_URLexample should be updated to17001when that feature work is committed or rebased.ThreeLight2000 commentedon Aug 18, 2026
PR #13 is open: #13. It contains the 17001/17002 local port alignment and passes
pnpm verify.chore(dev): align local service ports
chore(dev): align integrated service ports
ThreeLight2000 commentedon Aug 18, 2026
After the three-server endpoint integration landed on
main, PR #13 has been rebased ontoorigin/main(b7d09a1) and updated for the complete local service set:170011700217003(/mcp); stdio remains supportedIntegrated MCP, Raycast Voice Capture, root README, and external-entrypoint documentation are now included. PR #13 is conflict-free and all CI checks pass.
Merge pull request #13 from ThreeLightStudio/chore/11-align-local-app…