feat: Let stdio MCP honor per-project cloud routing (#590)

Signed-off-by: phernandez <paul@basicmachines.co>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: phernandez

README.md

@@ -396,7 +396,8 @@ basic-memory project ls --name main --cloud
 
 No-flag behavior defaults to local when no project context is present.
 
-The local MCP server (`basic-memory mcp`) always uses local routing (including `--transport stdio`).
+The local MCP server routes per transport: `--transport stdio` honors per-project routing
+(local or cloud), while `--transport streamable-http` and `--transport sse` always route locally.
 
 **CLI Note Editing (`tool edit-note`):**
 

docs/SPEC-PER-PROJECT-ROUTING.md

@@ -10,7 +10,7 @@ This document is the canonical contract for local/cloud routing behavior in CLI,
 ## Goals
 
 1. Remove global `cloud_mode` from runtime/routing semantics.
-2. Keep MCP stdio local-only and predictable.
+2. Keep MCP HTTP/SSE local-only; let stdio honor per-project routing.
 3. Make CLI routing explicit and easy to reason about.
 4. Support projects that exist in both local and cloud without ambiguity.
 
@@ -79,13 +79,25 @@ When explicit routing is active, project mode does not override the selected rou
   - reports auth state (API key, OAuth token validity)
   - runs health checks only when credentials are available
 
-## MCP Stdio Local Guarantee
+## MCP Transport Routing
 
-`bm mcp --transport stdio` always routes locally.
+### Stdio (default)
 
-The command sets explicit local routing (`BASIC_MEMORY_FORCE_LOCAL=true` and
-`BASIC_MEMORY_EXPLICIT_ROUTING=true`) before starting the server. This prevents cloud routing for stdio MCP,
-even if the selected project has `mode: cloud`.
+`bm mcp --transport stdio` uses natural per-project routing.
+
+- Local-mode projects route through the in-process ASGI transport.
+- Cloud-mode projects route to the cloud proxy with Bearer auth (API key).
+- No explicit routing env vars are injected by the CLI command.
+- Externally-set env vars are honored (e.g. `BASIC_MEMORY_FORCE_CLOUD=true` for cloud deployments).
+- Users who need all projects forced local can set `BASIC_MEMORY_FORCE_LOCAL=true` externally.
+
+### HTTP and SSE Transports
+
+`bm mcp --transport streamable-http` and `bm mcp --transport sse` always route locally.
+
+These transports set explicit local routing (`BASIC_MEMORY_FORCE_LOCAL=true` and
+`BASIC_MEMORY_EXPLICIT_ROUTING=true`) before starting the server. This prevents cloud
+routing regardless of project mode, since HTTP/SSE serve as local API endpoints.
 
 ## Project List UX for Dual Presence
 
@@ -130,6 +142,6 @@ Runtime mode is no longer a cloud/local routing switch for local app flows.
 3. `--local/--cloud` always override per-project mode for that command.
 4. No-project + no-flags commands route local by default.
 5. `bm cloud login/logout` do not toggle routing behavior.
-6. `bm mcp` remains local-only in stdio mode.
+6. `bm mcp` stdio routes per-project mode; HTTP/SSE remain local-forced.
 7. `bm project list` communicates dual local/cloud presence without ambiguity.
 8. `bm project ls` output identifies route target explicitly.

src/basic_memory/cli/analytics.py

@@ -25,6 +25,7 @@
 # Configuration — read from environment so nothing is hard-coded in source
 # ---------------------------------------------------------------------------
 
+
 def _umami_host() -> Optional[str]:
     return os.getenv("BASIC_MEMORY_UMAMI_HOST", "").strip() or None
 

src/basic_memory/cli/commands/mcp.py

@@ -45,14 +45,20 @@ def mcp(
     Users who have cloud mode enabled can still use local MCP for Claude Code
     and Claude Desktop while using cloud MCP for web and mobile access.
     """
-    # Force local routing for local MCP server.
-    # Trigger: MCP server command invocation (all transports).
-    # Why: local MCP must never route through cloud; stdio in particular must
-    #      remain local-only to avoid cross-environment ambiguity.
-    # Outcome: explicit local override disables per-project cloud routing.
-    os.environ["BASIC_MEMORY_FORCE_LOCAL"] = "true"
-    os.environ.pop("BASIC_MEMORY_FORCE_CLOUD", None)
-    os.environ["BASIC_MEMORY_EXPLICIT_ROUTING"] = "true"
+    # --- Routing setup ---
+    # Trigger: MCP server command invocation.
+    # Why: HTTP/SSE transports serve as local API endpoints and must never
+    #      route through cloud. Stdio is a client-facing protocol that
+    #      should honor per-project routing (local or cloud).
+    # Outcome: HTTP/SSE get explicit local override; stdio passes through
+    #          whatever env vars are already set (honoring external overrides)
+    #          and defaults to per-project routing resolution.
+    if transport in ("streamable-http", "sse"):
+        os.environ["BASIC_MEMORY_FORCE_LOCAL"] = "true"
+        os.environ.pop("BASIC_MEMORY_FORCE_CLOUD", None)
+        os.environ["BASIC_MEMORY_EXPLICIT_ROUTING"] = "true"
+    # stdio: no env var manipulation — per-project routing applies by default,
+    # and externally-set env vars (e.g. BASIC_MEMORY_FORCE_CLOUD) are honored.
 
     # Import mcp tools/prompts to register them with the server
     import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover

src/basic_memory/cli/promo.py

@@ -7,13 +7,12 @@
 from rich.panel import Panel
 
 import basic_memory
-from basic_memory.cli.analytics import track, EVENT_PROMO_SHOWN, EVENT_PROMO_OPTED_OUT
+from basic_memory.cli.analytics import track, EVENT_PROMO_SHOWN
 from basic_memory.config import ConfigManager
 
 OSS_DISCOUNT_CODE = "BMFOSS"
 CLOUD_LEARN_MORE_URL = (
-    "https://basicmemory.com"
-    "?utm_source=bm-cli&utm_medium=promo&utm_campaign=cloud-upsell"
+    "https://basicmemory.com?utm_source=bm-cli&utm_medium=promo&utm_campaign=cloud-upsell"
 )
 
 

src/basic_memory/config.py

@@ -42,7 +42,9 @@ class DatabaseBackend(str, Enum):
 def _default_semantic_search_enabled() -> bool:
     """Enable semantic search by default when required local semantic dependencies exist."""
     required_modules = ("fastembed", "sqlite_vec")
-    return all(importlib.util.find_spec(module_name) is not None for module_name in required_modules)
+    return all(
+        importlib.util.find_spec(module_name) is not None for module_name in required_modules
+    )
 
 
 @dataclass

test-int/cli/test_routing_integration.py

@@ -1,7 +1,7 @@
 """Integration tests for CLI routing flags (--local/--cloud).
 
 These tests verify that the --local and --cloud flags work correctly
-across CLI commands, and that the MCP command forces local routing.
+across CLI commands, and that MCP routing varies by transport.
 
 Note: Environment variable behavior during command execution is tested
 in unit tests (tests/cli/test_routing.py) which can properly monkeypatch
@@ -89,33 +89,93 @@ def test_tool_edit_note_both_flags_error(self):
         assert "Cannot specify both --local and --cloud" in result.output
 
 
-class TestMcpCommandForcesLocal:
-    """Tests that the MCP command forces local routing."""
+class TestMcpCommandRouting:
+    """Tests that MCP routing varies by transport."""
 
-    def test_mcp_sets_force_local_env(self, monkeypatch):
-        """MCP command should set BASIC_MEMORY_FORCE_LOCAL before server starts."""
-        # Track what environment variable was set
-        env_set_value = []
+    def test_mcp_stdio_does_not_force_local(self, monkeypatch):
+        """Stdio transport should not inject explicit local routing env vars."""
+        # Ensure env is clean before test
+        monkeypatch.delenv("BASIC_MEMORY_FORCE_LOCAL", raising=False)
+        monkeypatch.delenv("BASIC_MEMORY_EXPLICIT_ROUTING", raising=False)
+
+        env_at_run = {}
 
-        # Mock the MCP server run to capture env state without actually starting server
         import basic_memory.cli.commands.mcp as mcp_mod
 
         def mock_run(*args, **kwargs):
-            env_set_value.append(os.environ.get("BASIC_MEMORY_FORCE_LOCAL"))
-            # Don't actually start the server
+            env_at_run["FORCE_LOCAL"] = os.environ.get("BASIC_MEMORY_FORCE_LOCAL")
+            env_at_run["EXPLICIT"] = os.environ.get("BASIC_MEMORY_EXPLICIT_ROUTING")
             raise SystemExit(0)
 
-        # Get the actual mcp_server from the module
         monkeypatch.setattr(mcp_mod.mcp_server, "run", mock_run)
+        monkeypatch.setattr(mcp_mod, "init_mcp_logging", lambda: None)
+
+        runner.invoke(cli_app, ["mcp"])  # default transport is stdio
+
+        # Command should not have set these vars
+        assert env_at_run["FORCE_LOCAL"] is None
+        assert env_at_run["EXPLICIT"] is None
+
+    def test_mcp_stdio_honors_external_env_override(self, monkeypatch):
+        """Stdio transport should pass through externally-set routing env vars."""
+        monkeypatch.setenv("BASIC_MEMORY_FORCE_CLOUD", "true")
+        monkeypatch.setenv("BASIC_MEMORY_EXPLICIT_ROUTING", "true")
 
-        # Also mock init_mcp_logging to avoid file operations
+        env_at_run = {}
+
+        import basic_memory.cli.commands.mcp as mcp_mod
+
+        def mock_run(*args, **kwargs):
+            env_at_run["FORCE_CLOUD"] = os.environ.get("BASIC_MEMORY_FORCE_CLOUD")
+            env_at_run["EXPLICIT"] = os.environ.get("BASIC_MEMORY_EXPLICIT_ROUTING")
+            raise SystemExit(0)
+
+        monkeypatch.setattr(mcp_mod.mcp_server, "run", mock_run)
         monkeypatch.setattr(mcp_mod, "init_mcp_logging", lambda: None)
 
         runner.invoke(cli_app, ["mcp"])
 
-        # Environment variable should have been set to "true"
-        assert len(env_set_value) == 1
-        assert env_set_value[0] == "true"
+        # Externally-set vars should be preserved
+        assert env_at_run["FORCE_CLOUD"] == "true"
+        assert env_at_run["EXPLICIT"] == "true"
+
+    def test_mcp_streamable_http_forces_local(self, monkeypatch):
+        """Streamable-HTTP transport should force local routing."""
+        env_at_run = {}
+
+        import basic_memory.cli.commands.mcp as mcp_mod
+
+        def mock_run(*args, **kwargs):
+            env_at_run["FORCE_LOCAL"] = os.environ.get("BASIC_MEMORY_FORCE_LOCAL")
+            env_at_run["EXPLICIT"] = os.environ.get("BASIC_MEMORY_EXPLICIT_ROUTING")
+            raise SystemExit(0)
+
+        monkeypatch.setattr(mcp_mod.mcp_server, "run", mock_run)
+        monkeypatch.setattr(mcp_mod, "init_mcp_logging", lambda: None)
+
+        runner.invoke(cli_app, ["mcp", "--transport", "streamable-http"])
+
+        assert env_at_run["FORCE_LOCAL"] == "true"
+        assert env_at_run["EXPLICIT"] == "true"
+
+    def test_mcp_sse_forces_local(self, monkeypatch):
+        """SSE transport should force local routing."""
+        env_at_run = {}
+
+        import basic_memory.cli.commands.mcp as mcp_mod
+
+        def mock_run(*args, **kwargs):
+            env_at_run["FORCE_LOCAL"] = os.environ.get("BASIC_MEMORY_FORCE_LOCAL")
+            env_at_run["EXPLICIT"] = os.environ.get("BASIC_MEMORY_EXPLICIT_ROUTING")
+            raise SystemExit(0)
+
+        monkeypatch.setattr(mcp_mod.mcp_server, "run", mock_run)
+        monkeypatch.setattr(mcp_mod, "init_mcp_logging", lambda: None)
+
+        runner.invoke(cli_app, ["mcp", "--transport", "sse"])
+
+        assert env_at_run["FORCE_LOCAL"] == "true"
+        assert env_at_run["EXPLICIT"] == "true"
 
 
 class TestToolCommandsAcceptFlags:

tests/cli/test_analytics.py

@@ -1,7 +1,6 @@
 """Tests for CLI analytics module."""
 
 import json
-import threading
 from unittest.mock import patch, MagicMock
 
 import pytest
@@ -128,6 +127,7 @@ def fake_urlopen(req, timeout=None):
 
         with patch("basic_memory.cli.analytics.urllib.request.urlopen", fake_urlopen):
             with patch("basic_memory.cli.analytics.threading.Thread") as mock_thread:
+
                 def run_target(target, daemon):
                     target()  # Should not raise
                     return MagicMock()