From 116291a3b62a248d4ca2a0c274e3dff6267410e3 Mon Sep 17 00:00:00 2001 From: CREDO23 Date: Tue, 7 Jul 2026 20:24:53 +0200 Subject: [PATCH] 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 | 2 +- surfsense_mcp/README.md | 6 ++--- .../surfsense_mcp => mcp_server}/__init__.py | 0 .../surfsense_mcp => mcp_server}/__main__.py | 0 .../surfsense_mcp => mcp_server}/config.py | 0 .../core/__init__.py | 0 .../core/auth/__init__.py | 0 .../core/auth/headers.py | 0 .../core/auth/identity.py | 0 .../core/auth/middleware.py | 0 .../core/client.py | 0 .../core/errors.py | 0 .../core/rendering.py | 0 .../core/transport/__init__.py | 0 .../core/transport/http.py | 0 .../core/workspace_context.py | 0 .../core/workspace_matching.py | 0 .../features/__init__.py | 0 .../features/knowledge_base/__init__.py | 0 .../features/knowledge_base/annotations.py | 0 .../features/knowledge_base/document_tools.py | 0 .../features/knowledge_base/note_ingestion.py | 0 .../features/knowledge_base/search_tools.py | 0 .../features/scrapers/__init__.py | 0 .../features/scrapers/annotations.py | 0 .../features/scrapers/capability.py | 0 .../features/scrapers/platforms/__init__.py | 0 .../scrapers/platforms/google_maps.py | 0 .../scrapers/platforms/google_search.py | 0 .../features/scrapers/platforms/reddit.py | 0 .../features/scrapers/platforms/web.py | 0 .../features/scrapers/platforms/youtube.py | 0 .../features/scrapers/run_history.py | 0 .../features/workspaces/__init__.py | 0 .../surfsense_mcp => mcp_server}/selfcheck.py | 0 .../surfsense_mcp => mcp_server}/server.py | 0 surfsense_mcp/pyproject.toml | 4 ++-- surfsense_mcp/tests/test_auth_headers.py | 2 +- surfsense_mcp/tests/test_client_errors.py | 2 +- surfsense_mcp/tests/test_client_params.py | 2 +- surfsense_mcp/tests/test_note_ingestion.py | 2 +- surfsense_mcp/tests/test_rendering.py | 2 +- surfsense_mcp/tests/test_request_auth.py | 6 ++--- surfsense_mcp/tests/test_workspace_context.py | 6 ++--- .../content/docs/how-to/mcp-server.mdx | 22 +++++++++---------- surfsense_web/lib/mcp/clients.ts | 6 ++--- 46 files changed, 31 insertions(+), 31 deletions(-) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/__main__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/config.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/auth/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/auth/headers.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/auth/identity.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/auth/middleware.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/client.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/errors.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/rendering.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/transport/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/transport/http.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/workspace_context.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/core/workspace_matching.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/knowledge_base/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/knowledge_base/annotations.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/knowledge_base/document_tools.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/knowledge_base/note_ingestion.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/knowledge_base/search_tools.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/annotations.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/capability.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/platforms/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/platforms/google_maps.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/platforms/google_search.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/platforms/reddit.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/platforms/web.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/platforms/youtube.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/scrapers/run_history.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/features/workspaces/__init__.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/selfcheck.py (100%) rename surfsense_mcp/{src/surfsense_mcp => mcp_server}/server.py (100%) diff --git a/surfsense_mcp/Dockerfile b/surfsense_mcp/Dockerfile index e6c215932..673fb2c63 100644 --- a/surfsense_mcp/Dockerfile +++ b/surfsense_mcp/Dockerfile @@ -33,4 +33,4 @@ ENV PYTHONUNBUFFERED=1 \ EXPOSE 8080 -CMD ["python", "-m", "surfsense_mcp"] +CMD ["python", "-m", "mcp_server"] diff --git a/surfsense_mcp/README.md b/surfsense_mcp/README.md index cc5ef19c5..c18a857e1 100644 --- a/surfsense_mcp/README.md +++ b/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 diff --git a/surfsense_mcp/src/surfsense_mcp/__init__.py b/surfsense_mcp/mcp_server/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/__init__.py rename to surfsense_mcp/mcp_server/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/__main__.py b/surfsense_mcp/mcp_server/__main__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/__main__.py rename to surfsense_mcp/mcp_server/__main__.py diff --git a/surfsense_mcp/src/surfsense_mcp/config.py b/surfsense_mcp/mcp_server/config.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/config.py rename to surfsense_mcp/mcp_server/config.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/__init__.py b/surfsense_mcp/mcp_server/core/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/__init__.py rename to surfsense_mcp/mcp_server/core/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/auth/__init__.py b/surfsense_mcp/mcp_server/core/auth/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/auth/__init__.py rename to surfsense_mcp/mcp_server/core/auth/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/auth/headers.py b/surfsense_mcp/mcp_server/core/auth/headers.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/auth/headers.py rename to surfsense_mcp/mcp_server/core/auth/headers.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/auth/identity.py b/surfsense_mcp/mcp_server/core/auth/identity.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/auth/identity.py rename to surfsense_mcp/mcp_server/core/auth/identity.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/auth/middleware.py b/surfsense_mcp/mcp_server/core/auth/middleware.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/auth/middleware.py rename to surfsense_mcp/mcp_server/core/auth/middleware.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/client.py b/surfsense_mcp/mcp_server/core/client.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/client.py rename to surfsense_mcp/mcp_server/core/client.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/errors.py b/surfsense_mcp/mcp_server/core/errors.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/errors.py rename to surfsense_mcp/mcp_server/core/errors.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/rendering.py b/surfsense_mcp/mcp_server/core/rendering.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/rendering.py rename to surfsense_mcp/mcp_server/core/rendering.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/transport/__init__.py b/surfsense_mcp/mcp_server/core/transport/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/transport/__init__.py rename to surfsense_mcp/mcp_server/core/transport/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/transport/http.py b/surfsense_mcp/mcp_server/core/transport/http.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/transport/http.py rename to surfsense_mcp/mcp_server/core/transport/http.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/workspace_context.py b/surfsense_mcp/mcp_server/core/workspace_context.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/workspace_context.py rename to surfsense_mcp/mcp_server/core/workspace_context.py diff --git a/surfsense_mcp/src/surfsense_mcp/core/workspace_matching.py b/surfsense_mcp/mcp_server/core/workspace_matching.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/core/workspace_matching.py rename to surfsense_mcp/mcp_server/core/workspace_matching.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/__init__.py b/surfsense_mcp/mcp_server/features/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/__init__.py rename to surfsense_mcp/mcp_server/features/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/knowledge_base/__init__.py b/surfsense_mcp/mcp_server/features/knowledge_base/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/knowledge_base/__init__.py rename to surfsense_mcp/mcp_server/features/knowledge_base/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/knowledge_base/annotations.py b/surfsense_mcp/mcp_server/features/knowledge_base/annotations.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/knowledge_base/annotations.py rename to surfsense_mcp/mcp_server/features/knowledge_base/annotations.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/knowledge_base/document_tools.py b/surfsense_mcp/mcp_server/features/knowledge_base/document_tools.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/knowledge_base/document_tools.py rename to surfsense_mcp/mcp_server/features/knowledge_base/document_tools.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/knowledge_base/note_ingestion.py b/surfsense_mcp/mcp_server/features/knowledge_base/note_ingestion.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/knowledge_base/note_ingestion.py rename to surfsense_mcp/mcp_server/features/knowledge_base/note_ingestion.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/knowledge_base/search_tools.py b/surfsense_mcp/mcp_server/features/knowledge_base/search_tools.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/knowledge_base/search_tools.py rename to surfsense_mcp/mcp_server/features/knowledge_base/search_tools.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/__init__.py b/surfsense_mcp/mcp_server/features/scrapers/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/__init__.py rename to surfsense_mcp/mcp_server/features/scrapers/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/annotations.py b/surfsense_mcp/mcp_server/features/scrapers/annotations.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/annotations.py rename to surfsense_mcp/mcp_server/features/scrapers/annotations.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/capability.py b/surfsense_mcp/mcp_server/features/scrapers/capability.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/capability.py rename to surfsense_mcp/mcp_server/features/scrapers/capability.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/__init__.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/__init__.py rename to surfsense_mcp/mcp_server/features/scrapers/platforms/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/google_maps.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/google_maps.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/google_maps.py rename to surfsense_mcp/mcp_server/features/scrapers/platforms/google_maps.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/google_search.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/google_search.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/google_search.py rename to surfsense_mcp/mcp_server/features/scrapers/platforms/google_search.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/reddit.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/reddit.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/reddit.py rename to surfsense_mcp/mcp_server/features/scrapers/platforms/reddit.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/web.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/web.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/web.py rename to surfsense_mcp/mcp_server/features/scrapers/platforms/web.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/youtube.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/youtube.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/platforms/youtube.py rename to surfsense_mcp/mcp_server/features/scrapers/platforms/youtube.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/scrapers/run_history.py b/surfsense_mcp/mcp_server/features/scrapers/run_history.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/scrapers/run_history.py rename to surfsense_mcp/mcp_server/features/scrapers/run_history.py diff --git a/surfsense_mcp/src/surfsense_mcp/features/workspaces/__init__.py b/surfsense_mcp/mcp_server/features/workspaces/__init__.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/features/workspaces/__init__.py rename to surfsense_mcp/mcp_server/features/workspaces/__init__.py diff --git a/surfsense_mcp/src/surfsense_mcp/selfcheck.py b/surfsense_mcp/mcp_server/selfcheck.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/selfcheck.py rename to surfsense_mcp/mcp_server/selfcheck.py diff --git a/surfsense_mcp/src/surfsense_mcp/server.py b/surfsense_mcp/mcp_server/server.py similarity index 100% rename from surfsense_mcp/src/surfsense_mcp/server.py rename to surfsense_mcp/mcp_server/server.py diff --git a/surfsense_mcp/pyproject.toml b/surfsense_mcp/pyproject.toml index 489bbf455..5d8362a41 100644 --- a/surfsense_mcp/pyproject.toml +++ b/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" diff --git a/surfsense_mcp/tests/test_auth_headers.py b/surfsense_mcp/tests/test_auth_headers.py index efb2d85a9..feb21a9e1 100644 --- a/surfsense_mcp/tests/test_auth_headers.py +++ b/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: diff --git a/surfsense_mcp/tests/test_client_errors.py b/surfsense_mcp/tests/test_client_errors.py index 0525fb523..3245f39b1 100644 --- a/surfsense_mcp/tests/test_client_errors.py +++ b/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") diff --git a/surfsense_mcp/tests/test_client_params.py b/surfsense_mcp/tests/test_client_params.py index e9cd33a0c..c6b013d88 100644 --- a/surfsense_mcp/tests/test_client_params.py +++ b/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: diff --git a/surfsense_mcp/tests/test_note_ingestion.py b/surfsense_mcp/tests/test_note_ingestion.py index 6ab16acfc..da980e5db 100644 --- a/surfsense_mcp/tests/test_note_ingestion.py +++ b/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(): diff --git a/surfsense_mcp/tests/test_rendering.py b/surfsense_mcp/tests/test_rendering.py index 5b254e39a..fd5024f86 100644 --- a/surfsense_mcp/tests/test_rendering.py +++ b/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(): diff --git a/surfsense_mcp/tests/test_request_auth.py b/surfsense_mcp/tests/test_request_auth.py index c548dff7a..088946196 100644 --- a/surfsense_mcp/tests/test_request_auth.py +++ b/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: diff --git a/surfsense_mcp/tests/test_workspace_context.py b/surfsense_mcp/tests/test_workspace_context.py index d2024e5d5..6d5eace8f 100644 --- a/surfsense_mcp/tests/test_workspace_context.py +++ b/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: diff --git a/surfsense_web/content/docs/how-to/mcp-server.mdx b/surfsense_web/content/docs/how-to/mcp-server.mdx index 62628a659..f5f419219 100644 --- a/surfsense_web/content/docs/how-to/mcp-server.mdx +++ b/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 /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 /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. @@ -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`. @@ -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 diff --git a/surfsense_web/lib/mcp/clients.ts b/surfsense_web/lib/mcp/clients.ts index 795832ad1..258357ca5 100644 --- a/surfsense_web/lib/mcp/clients.ts +++ b/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 python -m surfsense_mcp`).", + "Add this to ~/.codex/config.toml (or run `codex mcp add surfsense -- uv run --directory python -m mcp_server`).", "Restart Codex; `codex mcp list` should show surfsense.", ], build: ({ baseUrl, apiKey, serverDir }) =>