refactor(mcp): flatten to mcp_server package, drop src layout

Rename the import package surfsense_mcp -> mcp_server and remove the
src/ layer so the project mirrors the backend's shape (project folder
!= package name, e.g. surfsense_backend/app). Kills the redundant
surfsense_mcp/src/surfsense_mcp nesting.

Distribution name and console command (surfsense-mcp) are unchanged;
only python -m and internal import paths move to mcp_server. Dockerfile
CMD updated; no PYTHONPATH added since the editable install already
makes the package importable.

surfsense_mcp/Dockerfile

@@ -33,4 +33,4 @@ ENV PYTHONUNBUFFERED=1 \
 
 EXPOSE 8080
 
-CMD ["python", "-m", "surfsense_mcp"]
+CMD ["python", "-m", "mcp_server"]

surfsense_mcp/README.md

@@ -75,7 +75,7 @@ remote support. It uses [uv](https://github.com/astral-sh/uv):
 ```bash
 cd surfsense_mcp
 uv sync
-uv run python -m surfsense_mcp.selfcheck   # verify tools register correctly
+uv run python -m mcp_server.selfcheck   # verify tools register correctly
 ```
 
 Then add it to your client. Cursor (`~/.cursor/mcp.json` or a project
@@ -86,7 +86,7 @@ Then add it to your client. Cursor (`~/.cursor/mcp.json` or a project
   "mcpServers": {
     "surfsense": {
       "command": "uv",
-      "args": ["run", "--directory", "/absolute/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"],
+      "args": ["run", "--directory", "/absolute/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
       "env": {
         "SURFSENSE_BASE_URL": "http://localhost:8000",
         "SURFSENSE_API_KEY": "ss_pat_your_token_here"
@@ -102,7 +102,7 @@ Claude Code:
 claude mcp add surfsense \
   -e SURFSENSE_BASE_URL=http://localhost:8000 \
   -e SURFSENSE_API_KEY=ss_pat_your_token_here \
-  -- uv run --directory /absolute/path/to/SurfSense/surfsense_mcp python -m surfsense_mcp
+  -- uv run --directory /absolute/path/to/SurfSense/surfsense_mcp python -m mcp_server
 ```
 
 Claude Desktop: add the same `mcpServers` block as Cursor to

surfsense_mcp/pyproject.toml

@@ -13,7 +13,7 @@ dependencies = [
 ]
 
 [project.scripts]
-surfsense-mcp = "surfsense_mcp.__main__:main"
+surfsense-mcp = "mcp_server.__main__:main"
 
 [dependency-groups]
 dev = ["pytest>=8.0"]
@@ -23,7 +23,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/surfsense_mcp"]
+packages = ["mcp_server"]
 
 [tool.ruff]
 target-version = "py311"

surfsense_mcp/tests/test_auth_headers.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from starlette.datastructures import Headers
 
-from surfsense_mcp.core.auth.headers import extract_api_key
+from mcp_server.core.auth.headers import extract_api_key
 
 
 def _headers(**pairs: str) -> Headers:

surfsense_mcp/tests/test_client_errors.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import httpx
 
-from surfsense_mcp.core.client import SurfSenseClient
+from mcp_server.core.client import SurfSenseClient
 
 _REQUEST = httpx.Request("GET", "http://localhost:8000/api/v1/documents")
 

surfsense_mcp/tests/test_client_params.py

@@ -6,7 +6,7 @@ import asyncio
 
 import httpx
 
-from surfsense_mcp.core.client import SurfSenseClient
+from mcp_server.core.client import SurfSenseClient
 
 
 def _capture(client: SurfSenseClient) -> dict:

surfsense_mcp/tests/test_note_ingestion.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from surfsense_mcp.features.knowledge_base.note_ingestion import build_note_document
+from mcp_server.features.knowledge_base.note_ingestion import build_note_document
 
 
 def test_builds_extension_document_with_content():

surfsense_mcp/tests/test_rendering.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from surfsense_mcp.core.rendering import clip, compact_items, to_json
+from mcp_server.core.rendering import clip, compact_items, to_json
 
 
 def test_clip_leaves_short_text_untouched():

surfsense_mcp/tests/test_request_auth.py

@@ -12,9 +12,9 @@ import asyncio
 import httpx
 import pytest
 
-from surfsense_mcp.core.auth import identity
-from surfsense_mcp.core.client import SurfSenseClient
-from surfsense_mcp.core.errors import ToolError
+from mcp_server.core.auth import identity
+from mcp_server.core.client import SurfSenseClient
+from mcp_server.core.errors import ToolError
 
 
 def _client_recording_auth(seen: dict, *, fallback: str | None) -> SurfSenseClient:

surfsense_mcp/tests/test_workspace_context.py

@@ -6,9 +6,9 @@ import asyncio
 
 import pytest
 
-from surfsense_mcp.core.auth import identity
-from surfsense_mcp.core.errors import ToolError
-from surfsense_mcp.core.workspace_context import WorkspaceContext
+from mcp_server.core.auth import identity
+from mcp_server.core.errors import ToolError
+from mcp_server.core.workspace_context import WorkspaceContext
 
 
 class FakeClient:

surfsense_web/content/docs/how-to/mcp-server.mdx

@@ -56,7 +56,7 @@ Point the server at your backend with `SURFSENSE_BASE_URL`:
 - **SurfSense Cloud**: `https://api.surfsense.com`
 - **Self-hosted**: wherever your backend runs, e.g. `http://localhost:8000`
 
-Every client below launches the same command — `uv run --directory <path-to>/surfsense_mcp python -m surfsense_mcp` — and passes `SURFSENSE_BASE_URL` and `SURFSENSE_API_KEY` as environment variables. Replace the placeholder paths and key with yours.
+Every client below launches the same command — `uv run --directory <path-to>/surfsense_mcp python -m mcp_server` — and passes `SURFSENSE_BASE_URL` and `SURFSENSE_API_KEY` as environment variables. Replace the placeholder paths and key with yours.
 
 <Tabs items={['Claude Code', 'Codex', 'OpenCode', 'Cursor', 'Claude Desktop', 'VS Code', 'Windsurf', 'Gemini CLI']}>
 <Tab value="Claude Code">
@@ -67,7 +67,7 @@ Run one command in a terminal:
 claude mcp add surfsense \
   -e SURFSENSE_BASE_URL=https://api.surfsense.com \
   -e SURFSENSE_API_KEY=ss_pat_your_key_here \
-  -- uv run --directory /path/to/SurfSense/surfsense_mcp python -m surfsense_mcp
+  -- uv run --directory /path/to/SurfSense/surfsense_mcp python -m mcp_server
 ```
 
 Start Claude Code and run `/mcp` — `surfsense` should be listed as connected. Add `--scope project` to share the server (without the key) via a checked-in `.mcp.json`.
@@ -80,14 +80,14 @@ Add to `~/.codex/config.toml` (or a project's `.codex/config.toml`):
 ```toml
 [mcp_servers.surfsense]
 command = "uv"
-args = ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"]
+args = ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"]
 
 [mcp_servers.surfsense.env]
 SURFSENSE_BASE_URL = "https://api.surfsense.com"
 SURFSENSE_API_KEY = "ss_pat_your_key_here"
 ```
 
-Or use the CLI: `codex mcp add surfsense -e SURFSENSE_API_KEY=... -- uv run --directory ... python -m surfsense_mcp`. Verify with `codex mcp list`.
+Or use the CLI: `codex mcp add surfsense -e SURFSENSE_API_KEY=... -- uv run --directory ... python -m mcp_server`. Verify with `codex mcp list`.
 
 </Tab>
 <Tab value="OpenCode">
@@ -100,7 +100,7 @@ Add to `opencode.json` in your project root (or `~/.config/opencode/opencode.jso
   "mcp": {
     "surfsense": {
       "type": "local",
-      "command": ["uv", "run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"],
+      "command": ["uv", "run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
       "enabled": true,
       "environment": {
         "SURFSENSE_BASE_URL": "https://api.surfsense.com",
@@ -123,7 +123,7 @@ Add to `~/.cursor/mcp.json` (global — keeps the key out of your repo) or a pro
   "mcpServers": {
     "surfsense": {
       "command": "uv",
-      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"],
+      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
       "env": {
         "SURFSENSE_BASE_URL": "https://api.surfsense.com",
         "SURFSENSE_API_KEY": "ss_pat_your_key_here"
@@ -145,7 +145,7 @@ Open **Settings → Developer → Edit Config** to reach `claude_desktop_config.
   "mcpServers": {
     "surfsense": {
       "command": "uv",
-      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"],
+      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
       "env": {
         "SURFSENSE_BASE_URL": "https://api.surfsense.com",
         "SURFSENSE_API_KEY": "ss_pat_your_key_here"
@@ -168,7 +168,7 @@ Add to `.vscode/mcp.json` in your workspace (or run the **MCP: Add Server** comm
     "surfsense": {
       "type": "stdio",
       "command": "uv",
-      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"],
+      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
       "env": {
         "SURFSENSE_BASE_URL": "https://api.surfsense.com",
         "SURFSENSE_API_KEY": "ss_pat_your_key_here"
@@ -190,7 +190,7 @@ Add the standard `mcpServers` block to `~/.codeium/windsurf/mcp_config.json` (or
   "mcpServers": {
     "surfsense": {
       "command": "uv",
-      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"],
+      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
       "env": {
         "SURFSENSE_BASE_URL": "https://api.surfsense.com",
         "SURFSENSE_API_KEY": "ss_pat_your_key_here"
@@ -212,7 +212,7 @@ Add the standard `mcpServers` block to `~/.gemini/settings.json` (or `.gemini/se
   "mcpServers": {
     "surfsense": {
       "command": "uv",
-      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "surfsense_mcp"],
+      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
       "env": {
         "SURFSENSE_BASE_URL": "https://api.surfsense.com",
         "SURFSENSE_API_KEY": "ss_pat_your_key_here"
@@ -257,7 +257,7 @@ For self-host (stdio), all settings are environment variables passed by the clie
 - **401 errors** — the API key is wrong or expired; create a new one.
 - **403 errors** — API access is disabled for the workspace; toggle **API key access** on under **API Playground → API Keys**.
 - **"Could not reach SurfSense"** — the backend isn't running or `SURFSENSE_BASE_URL` is wrong.
-- **Server won't start** — run `uv run python -m surfsense_mcp.selfcheck` inside `surfsense_mcp`; it verifies all 18 tools register without needing a backend.
+- **Server won't start** — run `uv run python -m mcp_server.selfcheck` inside `surfsense_mcp`; it verifies all 18 tools register without needing a backend.
 
 ## Tools reference
 

surfsense_web/lib/mcp/clients.ts

@@ -52,7 +52,7 @@ function bearer(apiKey: string): string {
 }
 
 function serverArgs(serverDir: string): string[] {
-	return ["run", "--directory", serverDir, "python", "-m", "surfsense_mcp"];
+	return ["run", "--directory", serverDir, "python", "-m", "mcp_server"];
 }
 
 /** The `mcpServers` remote shape shared by Cursor, Windsurf, and Gemini CLI. */
@@ -110,7 +110,7 @@ export const MCP_CLIENTS: McpClient[] = [
 					"claude mcp add surfsense \\",
 					`  -e SURFSENSE_BASE_URL=${baseUrl} \\`,
 					`  -e SURFSENSE_API_KEY=${apiKey} \\`,
-					`  -- uv run --directory ${serverDir} python -m surfsense_mcp`,
+					`  -- uv run --directory ${serverDir} python -m mcp_server`,
 				].join("\n"),
 		},
 	},
@@ -139,7 +139,7 @@ export const MCP_CLIENTS: McpClient[] = [
 			configFile: "~/.codex/config.toml",
 			language: "toml",
 			steps: [
-				"Add this to ~/.codex/config.toml (or run `codex mcp add surfsense -- uv run --directory <dir> python -m surfsense_mcp`).",
+				"Add this to ~/.codex/config.toml (or run `codex mcp add surfsense -- uv run --directory <dir> python -m mcp_server`).",
 				"Restart Codex; `codex mcp list` should show surfsense.",
 			],
 			build: ({ baseUrl, apiKey, serverDir }) =>