feat: add SSE transport support and refactor CLI arg parsing

README.md

@@ -129,7 +129,18 @@ uv run ruff check .
 uv run ruff format .
 
 # Build package
-uv build
+uv build# Clone the repo
+git clone https://github.com/kapillamba4/code-memory.git
+cd code-memory
+
+# Install dependencies
+uv sync
+
+# Run the MCP server (stdio transport)
+uv run mcp run server.py
+
+# Run the MCP server (SSE transport for shared usage)
+uv run python server.py --transport sse
 
 # Build standalone binary (requires pyinstaller)
 pip install pyinstaller
@@ -228,8 +239,77 @@ For Windows:
 }
 ```
 
+## Shared SSE Server (Reduce Memory Usage)
+
+By default, each MCP host project launches its own `code-memory` process, which loads the embedding model (~1–2 GB) once per project. To avoid this, you can run a **single shared instance** over SSE (Server-Sent Events) and point all your MCP hosts at it.
+
+### Start the shared server
+
+```bash
+# Using uvx (recommended)
+uvx code-memory --transport sse
+
+# Custom port and host
+uvx code-memory --transport sse --port 8765 --host 127.0.0.1
+
+# Using standalone binary
+./code-memory-linux-x86_64 --transport sse
+```
+
+The server listens on `http://127.0.0.1:8765/sse` by default.
+
+### Configure MCP hosts to use the shared server
+
+Instead of launching a new process, point your MCP host at the running SSE endpoint.
+
+#### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "code-memory": {
+      "url": "http://127.0.0.1:8765/sse"
+    }
+  }
+}
+```
+
+#### VS Code (Copilot / Continue)
+
+```json
+{
+  "servers": {
+    "code-memory": {
+      "url": "http://127.0.0.1:8765/sse"
+    }
+  }
+}
+```
+
+#### Claude Code (CLI) — `.mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "code-memory": {
+      "url": "http://127.0.0.1:8765/sse"
+    }
+  }
+}
+```
+
+> **Tip:** Configure `uvx code-memory --transport sse` to start via a single-instance service manager (e.g. systemd user service, launchd agent, or another one-time login/startup mechanism) so the shared server starts automatically.
+
 ## Configuration
 
+### CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--transport` | Transport protocol: `stdio` or `sse` | `stdio` |
+| `--port` | Port for SSE transport (only when `--transport sse` is used) | `8765` |
+| `--host` | Host/bind address for SSE transport (only when `--transport sse` is used) | `127.0.0.1` |
+
 ### Environment Variables
 
 | Variable | Description | Default |

server.py

@@ -772,10 +772,44 @@ def search_history(
 
 
 # ── Entrypoint ────────────────────────────────────────────────────────────
+def build_arg_parser() -> "argparse.ArgumentParser":
+    """Build and return the CLI argument parser for code-memory."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="code-memory",
+        description="code-memory MCP server",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse"],
+        default="stdio",
+        help="Transport protocol to use (default: stdio). Use 'sse' to run a shared HTTP server.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8765,
+        help="Port for SSE transport (default: 8765). Only used when --transport=sse.",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host for SSE transport (default: 127.0.0.1). Only used when --transport=sse.",
+    )
+    return parser
+
+
 def main():
     """Entry point for the MCP server when installed as a package."""
+    args = build_arg_parser().parse_args()
+
+    if args.transport == "sse":
+        mcp.settings.host = args.host
+        mcp.settings.port = args.port
+
     # Warmup is now done lazily on first index_codebase call
-    mcp.run()
+    mcp.run(transport=args.transport)
 
 
 if __name__ == "__main__":

tests/test_main.py

@@ -0,0 +1,107 @@
+"""Tests for the main() entrypoint CLI argument parsing."""
+
+from __future__ import annotations
+
+import argparse
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from server import build_arg_parser
+
+
+class TestMainArgParsing:
+    """Tests for CLI argument parsing in main()."""
+
+    def _parse_args(self, argv: list[str]) -> argparse.Namespace:
+        """Parse args using the real CLI parser from server.py."""
+        return build_arg_parser().parse_args(argv)
+
+    def test_default_transport_is_stdio(self):
+        """Default transport should be stdio."""
+        args = self._parse_args([])
+        assert args.transport == "stdio"
+
+    def test_default_port_is_8765(self):
+        """Default SSE port should be 8765."""
+        args = self._parse_args([])
+        assert args.port == 8765
+
+    def test_default_host_is_localhost(self):
+        """Default SSE host should be 127.0.0.1."""
+        args = self._parse_args([])
+        assert args.host == "127.0.0.1"
+
+    def test_sse_transport_flag(self):
+        """--transport sse should set transport to sse."""
+        args = self._parse_args(["--transport", "sse"])
+        assert args.transport == "sse"
+
+    def test_custom_port(self):
+        """--port should accept a custom port number."""
+        args = self._parse_args(["--transport", "sse", "--port", "9000"])
+        assert args.port == 9000
+
+    def test_custom_host(self):
+        """--host should accept a custom host."""
+        args = self._parse_args(["--transport", "sse", "--host", "0.0.0.0"])
+        assert args.host == "0.0.0.0"
+
+    def test_invalid_transport_raises_error(self):
+        """Invalid transport should raise SystemExit."""
+        with pytest.raises(SystemExit):
+            self._parse_args(["--transport", "invalid"])
+
+
+class TestMainRunsBehavior:
+    """Tests that main() calls mcp.run() with the correct arguments."""
+
+    @pytest.fixture(autouse=True)
+    def require_server(self):
+        """Skip tests when server module dependencies are unavailable."""
+        pytest.importorskip("sqlite_vec", reason="sqlite_vec not installed")
+
+    @pytest.fixture
+    def server_main(self):
+        """Import and return the server.main function."""
+        import importlib
+
+        import server as server_mod
+        importlib.reload(server_mod)
+        return server_mod.main
+
+    def test_stdio_calls_run_with_stdio(self, server_main):
+        """main() with no args should call mcp.run(transport='stdio')."""
+        import server as server_mod
+        with patch("sys.argv", ["code-memory"]):
+            with patch.object(server_mod, "mcp") as mock_mcp:
+                mock_mcp.settings = MagicMock()
+                server_main()
+                mock_mcp.run.assert_called_once_with(transport="stdio")
+
+    def test_sse_calls_run_with_sse(self, server_main):
+        """main() with --transport sse should call mcp.run(transport='sse')."""
+        import server as server_mod
+        with patch("sys.argv", ["code-memory", "--transport", "sse"]):
+            with patch.object(server_mod, "mcp") as mock_mcp:
+                mock_mcp.settings = MagicMock()
+                server_main()
+                mock_mcp.run.assert_called_once_with(transport="sse")
+
+    def test_sse_sets_port_on_settings(self, server_main):
+        """main() with --transport sse --port 9000 should set mcp.settings.port."""
+        import server as server_mod
+        with patch("sys.argv", ["code-memory", "--transport", "sse", "--port", "9000"]):
+            with patch.object(server_mod, "mcp") as mock_mcp:
+                mock_mcp.settings = MagicMock()
+                server_main()
+                assert mock_mcp.settings.port == 9000
+
+    def test_sse_sets_host_on_settings(self, server_main):
+        """main() with --transport sse --host 0.0.0.0 should set mcp.settings.host."""
+        import server as server_mod
+        with patch("sys.argv", ["code-memory", "--transport", "sse", "--host", "0.0.0.0"]):
+            with patch.object(server_mod, "mcp") as mock_mcp:
+                mock_mcp.settings = MagicMock()
+                server_main()
+                assert mock_mcp.settings.host == "0.0.0.0"