deepresearch-flow 0.7.2__tar.gz → 0.7.3__tar.gz

{deepresearch_flow-0.7.2/python/deepresearch_flow.egg-info → deepresearch_flow-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepresearch-flow
-Version: 0.7.2
+Version: 0.7.3
 Summary: Workflow tools for paper extraction, review, and research automation.
 Author-email: DengQi <dengqi935@gmail.com>
 License: MIT License
@@ -532,6 +532,22 @@ server {
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   }
+
+  # SSE transport for MCP clients that require Server-Sent Events
+  location ^~ /mcp-sse {
+    proxy_pass http://127.0.0.1:8001;
+    proxy_http_version 1.1;
+    proxy_set_header Connection "";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    chunked_transfer_encoding off;
+    add_header X-Accel-Buffering no;
+  }
 }
 
 # Static assets (separate domain)
@@ -562,12 +578,15 @@ uv run deepresearch-flow paper db api serve \
   --host 0.0.0.0 --port 8001
 ```
 
-### 3.1) MCP (FastMCP Streamable HTTP)
+### 3.1) MCP (FastMCP Streamable HTTP + SSE)
 
-This project exposes an MCP server mounted at `/mcp` on the snapshot API:
+This project exposes MCP servers mounted on the snapshot API:
 
-- Endpoint: `http://<host>:8001/mcp` (same host/port as `paper db api serve`)
-- Transport: Streamable HTTP via `POST` only (no SSE; `GET` returns 405)
+- Streamable HTTP endpoint: `http://<host>:8001/mcp`
+- SSE endpoint: `http://<host>:8001/mcp-sse`
+- Transport behavior:
+  - `/mcp`: Streamable HTTP via `POST` only (`GET` returns 405)
+  - `/mcp-sse`: SSE-enabled transport (supports `GET` handshake)
 - Protocol header: optional `mcp-protocol-version` (`2025-03-26` or `2025-06-18`)
 - Static reads: summary/source/translation are served as **text content** by reading snapshot static assets (local-first via `PAPER_DB_STATIC_EXPORT_DIR`, HTTP fallback via `PAPER_DB_STATIC_BASE` / `PAPER_DB_STATIC_BASE_URL`)
 
@@ -959,7 +978,7 @@ docker run --rm -p 8899:8899 \
 ```
 
 Notes:
-- nginx listens on 8899 and proxies `/api` and `/mcp` to the internal API at `127.0.0.1:8000`.
+- nginx listens on 8899 and proxies `/api`, `/mcp`, and `/mcp-sse` to the internal API at `127.0.0.1:8000`.
 - Mount your snapshot DB to `/db/papers.db` inside the container.
 - Mount snapshot static assets to `/static` when serving assets from this container (default `PAPER_DB_STATIC_BASE` is `/static`).
 - If `PAPER_DB_STATIC_BASE` is a full URL (e.g. `https://static.example.com`), nginx still serves the frontend locally, while API responses use that external static base for asset links.

{deepresearch_flow-0.7.2 → deepresearch_flow-0.7.3}/README.md

@@ -469,6 +469,22 @@ server {
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   }
+
+  # SSE transport for MCP clients that require Server-Sent Events
+  location ^~ /mcp-sse {
+    proxy_pass http://127.0.0.1:8001;
+    proxy_http_version 1.1;
+    proxy_set_header Connection "";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    chunked_transfer_encoding off;
+    add_header X-Accel-Buffering no;
+  }
 }
 
 # Static assets (separate domain)
@@ -499,12 +515,15 @@ uv run deepresearch-flow paper db api serve \
   --host 0.0.0.0 --port 8001
 ```
 
-### 3.1) MCP (FastMCP Streamable HTTP)
+### 3.1) MCP (FastMCP Streamable HTTP + SSE)
 
-This project exposes an MCP server mounted at `/mcp` on the snapshot API:
+This project exposes MCP servers mounted on the snapshot API:
 
-- Endpoint: `http://<host>:8001/mcp` (same host/port as `paper db api serve`)
-- Transport: Streamable HTTP via `POST` only (no SSE; `GET` returns 405)
+- Streamable HTTP endpoint: `http://<host>:8001/mcp`
+- SSE endpoint: `http://<host>:8001/mcp-sse`
+- Transport behavior:
+  - `/mcp`: Streamable HTTP via `POST` only (`GET` returns 405)
+  - `/mcp-sse`: SSE-enabled transport (supports `GET` handshake)
 - Protocol header: optional `mcp-protocol-version` (`2025-03-26` or `2025-06-18`)
 - Static reads: summary/source/translation are served as **text content** by reading snapshot static assets (local-first via `PAPER_DB_STATIC_EXPORT_DIR`, HTTP fallback via `PAPER_DB_STATIC_BASE` / `PAPER_DB_STATIC_BASE_URL`)
 
@@ -896,7 +915,7 @@ docker run --rm -p 8899:8899 \
 ```
 
 Notes:
-- nginx listens on 8899 and proxies `/api` and `/mcp` to the internal API at `127.0.0.1:8000`.
+- nginx listens on 8899 and proxies `/api`, `/mcp`, and `/mcp-sse` to the internal API at `127.0.0.1:8000`.
 - Mount your snapshot DB to `/db/papers.db` inside the container.
 - Mount snapshot static assets to `/static` when serving assets from this container (default `PAPER_DB_STATIC_BASE` is `/static`).
 - If `PAPER_DB_STATIC_BASE` is a full URL (e.g. `https://static.example.com`), nginx still serves the frontend locally, while API responses use that external static base for asset links.

{deepresearch_flow-0.7.2 → deepresearch_flow-0.7.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepresearch-flow"
-version = "0.7.2"
+version = "0.7.3"
 description = "Workflow tools for paper extraction, review, and research automation."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }

{deepresearch_flow-0.7.2 → deepresearch_flow-0.7.3}/python/deepresearch_flow/paper/snapshot/api.py

@@ -908,7 +908,7 @@ def create_app(
     # Lazy import to avoid circular dependency
     from deepresearch_flow.paper.snapshot.mcp_server import (
         McpSnapshotConfig,
-        create_mcp_app,
+        create_mcp_apps,
         resolve_static_export_dir,
     )
 
@@ -919,7 +919,7 @@ def create_app(
         limits=limits or ApiLimits(),
         origin_allowlist=cors_allowed_origins or ["*"],
     )
-    mcp_app, mcp_lifespan = create_mcp_app(mcp_config)
+    mcp_apps, mcp_lifespan = create_mcp_apps(mcp_config)
 
     routes = [
         Route("/api/v1/config", _api_config, methods=["GET"]),
@@ -931,7 +931,8 @@ def create_app(
         Route("/api/v1/facets/{facet:str}/{facet_id:str}/stats", _api_facet_stats, methods=["GET"]),
         Route("/api/v1/facets/{facet:str}/by-value/{value:str}/papers", _api_facet_by_value_papers, methods=["GET"]),
         Route("/api/v1/facets/{facet:str}/by-value/{value:str}/stats", _api_facet_by_value_stats, methods=["GET"]),
-        Mount("/mcp", app=mcp_app),
+        Mount("/mcp", app=mcp_apps["streamable-http"]),
+        Mount("/mcp-sse", app=mcp_apps["sse"]),
     ]
 
     # Pass MCP lifespan to ensure session manager initializes properly

{deepresearch_flow-0.7.2 → deepresearch_flow-0.7.3}/python/deepresearch_flow/paper/snapshot/mcp_server.py

@@ -5,7 +5,7 @@ import json
 import os
 from pathlib import Path
 import re
-from typing import Any
+from typing import Any, Literal
 
 import httpx
 from starlette.applications import Starlette
@@ -76,14 +76,13 @@ class McpSnapshotConfig:
 
 
 class McpRequestGuardMiddleware(BaseHTTPMiddleware):
-    def __init__(self, app, *, origin_allowlist: list[str]) -> None:
+    def __init__(self, app, *, origin_allowlist: list[str], allowed_methods: set[str] | None = None) -> None:
         super().__init__(app)
         self._allowlist = [origin.lower() for origin in origin_allowlist]
+        self._allowed_methods = {method.upper() for method in (allowed_methods or {"POST", "OPTIONS"})}
 
     async def dispatch(self, request: Request, call_next):  # type: ignore[override]
-        if request.method == "GET":
-            return Response("Method Not Allowed", status_code=405)
-        if request.method not in {"POST", "OPTIONS"}:
+        if request.method.upper() not in self._allowed_methods:
             return Response("Method Not Allowed", status_code=405)
         origin = request.headers.get("origin")
         if origin and not self._is_allowed_origin(origin):
@@ -108,23 +107,49 @@ def configure(config: McpSnapshotConfig) -> None:
     _CONFIG = config
 
 
-def create_mcp_app(config: McpSnapshotConfig) -> tuple[Starlette, Any]:
-    """Create MCP app with middleware and return it along with lifespan.
-    
-    Returns:
-        Tuple of (wrapped_app, lifespan_context) for use by parent Starlette.
-    """
+def _allowed_methods_for_transport(transport: Literal["streamable-http", "sse"]) -> set[str]:
+    if transport == "sse":
+        return {"GET", "POST", "OPTIONS"}
+    return {"POST", "OPTIONS"}
+
+
+def create_mcp_transport_app(
+    config: McpSnapshotConfig,
+    *,
+    transport: Literal["streamable-http", "sse"] = "streamable-http",
+) -> tuple[Starlette, Any]:
+    """Create MCP app for a specific transport with transport-aware method guard."""
     configure(config)
-    mcp_app = mcp.http_app(path="/", stateless_http=True)
+    mcp_app = mcp.http_app(path="/", transport=transport, stateless_http=(transport == "streamable-http"))
     wrapped = Starlette(
         routes=[Mount("/", app=mcp_app)],
         middleware=[
-            Middleware(McpRequestGuardMiddleware, origin_allowlist=config.origin_allowlist),
+            Middleware(
+                McpRequestGuardMiddleware,
+                origin_allowlist=config.origin_allowlist,
+                allowed_methods=_allowed_methods_for_transport(transport),
+            ),
         ],
     )
     return wrapped, mcp_app.lifespan
 
 
+def create_mcp_apps(config: McpSnapshotConfig) -> tuple[dict[str, Starlette], Any]:
+    """Create streamable-http and sse MCP apps.
+
+    Returns:
+        A tuple of (apps_by_transport, lifespan_context).
+    """
+    streamable_app, lifespan = create_mcp_transport_app(config, transport="streamable-http")
+    sse_app, _ = create_mcp_transport_app(config, transport="sse")
+    return {"streamable-http": streamable_app, "sse": sse_app}, lifespan
+
+
+def create_mcp_app(config: McpSnapshotConfig) -> tuple[Starlette, Any]:
+    """Backward-compatible helper returning streamable-http MCP app."""
+    return create_mcp_transport_app(config, transport="streamable-http")
+
+
 def _get_config() -> McpSnapshotConfig:
     if _CONFIG is None:
         raise RuntimeError("MCP server not configured")

deepresearch_flow-0.7.3/python/deepresearch_flow/paper/snapshot/tests/test_mcp_transport.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+import unittest
+
+from deepresearch_flow.paper.snapshot.api import create_app
+from deepresearch_flow.paper.snapshot.common import ApiLimits
+from deepresearch_flow.paper.snapshot.mcp_server import (
+    McpSnapshotConfig,
+    _allowed_methods_for_transport,
+)
+
+
+class TestMcpTransport(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.tmpdir = tempfile.TemporaryDirectory()
+        cls.snapshot_db = Path(cls.tmpdir.name) / "snapshot.db"
+        cls.snapshot_db.touch()
+        cls.cfg = McpSnapshotConfig(
+            snapshot_db=cls.snapshot_db,
+            static_base_url="",
+            static_export_dir=None,
+            limits=ApiLimits(),
+            origin_allowlist=["*"],
+        )
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.tmpdir.cleanup()
+
+    def test_streamable_transport_rejects_get(self) -> None:
+        self.assertNotIn("GET", _allowed_methods_for_transport("streamable-http"))
+
+    def test_sse_transport_allows_get(self) -> None:
+        self.assertIn("GET", _allowed_methods_for_transport("sse"))
+
+    def test_api_mounts_streamable_and_sse_endpoints(self) -> None:
+        app = create_app(
+            snapshot_db=self.snapshot_db,
+            static_base_url="",
+            cors_allowed_origins=["*"],
+            limits=ApiLimits(),
+        )
+        mount_paths = sorted(getattr(route, "path", "") for route in app.routes)
+        self.assertIn("/mcp", mount_paths)
+        self.assertIn("/mcp-sse", mount_paths)
+
+
+if __name__ == "__main__":
+    unittest.main()

{deepresearch_flow-0.7.2 → deepresearch_flow-0.7.3/python/deepresearch_flow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepresearch-flow
-Version: 0.7.2
+Version: 0.7.3
 Summary: Workflow tools for paper extraction, review, and research automation.
 Author-email: DengQi <dengqi935@gmail.com>
 License: MIT License
@@ -532,6 +532,22 @@ server {
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   }
+
+  # SSE transport for MCP clients that require Server-Sent Events
+  location ^~ /mcp-sse {
+    proxy_pass http://127.0.0.1:8001;
+    proxy_http_version 1.1;
+    proxy_set_header Connection "";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    chunked_transfer_encoding off;
+    add_header X-Accel-Buffering no;
+  }
 }
 
 # Static assets (separate domain)
@@ -562,12 +578,15 @@ uv run deepresearch-flow paper db api serve \
   --host 0.0.0.0 --port 8001
 ```
 
-### 3.1) MCP (FastMCP Streamable HTTP)
+### 3.1) MCP (FastMCP Streamable HTTP + SSE)
 
-This project exposes an MCP server mounted at `/mcp` on the snapshot API:
+This project exposes MCP servers mounted on the snapshot API:
 
-- Endpoint: `http://<host>:8001/mcp` (same host/port as `paper db api serve`)
-- Transport: Streamable HTTP via `POST` only (no SSE; `GET` returns 405)
+- Streamable HTTP endpoint: `http://<host>:8001/mcp`
+- SSE endpoint: `http://<host>:8001/mcp-sse`
+- Transport behavior:
+  - `/mcp`: Streamable HTTP via `POST` only (`GET` returns 405)
+  - `/mcp-sse`: SSE-enabled transport (supports `GET` handshake)
 - Protocol header: optional `mcp-protocol-version` (`2025-03-26` or `2025-06-18`)
 - Static reads: summary/source/translation are served as **text content** by reading snapshot static assets (local-first via `PAPER_DB_STATIC_EXPORT_DIR`, HTTP fallback via `PAPER_DB_STATIC_BASE` / `PAPER_DB_STATIC_BASE_URL`)
 
@@ -959,7 +978,7 @@ docker run --rm -p 8899:8899 \
 ```
 
 Notes:
-- nginx listens on 8899 and proxies `/api` and `/mcp` to the internal API at `127.0.0.1:8000`.
+- nginx listens on 8899 and proxies `/api`, `/mcp`, and `/mcp-sse` to the internal API at `127.0.0.1:8000`.
 - Mount your snapshot DB to `/db/papers.db` inside the container.
 - Mount snapshot static assets to `/static` when serving assets from this container (default `PAPER_DB_STATIC_BASE` is `/static`).
 - If `PAPER_DB_STATIC_BASE` is a full URL (e.g. `https://static.example.com`), nginx still serves the frontend locally, while API responses use that external static base for asset links.

{deepresearch_flow-0.7.2 → deepresearch_flow-0.7.3}/python/deepresearch_flow.egg-info/SOURCES.txt

@@ -64,6 +64,7 @@ python/deepresearch_flow/paper/snapshot/unpacker.py
 python/deepresearch_flow/paper/snapshot/tests/__init__.py
 python/deepresearch_flow/paper/snapshot/tests/test_identity.py
 python/deepresearch_flow/paper/snapshot/tests/test_mcp_server_schema_compat.py
+python/deepresearch_flow/paper/snapshot/tests/test_mcp_transport.py
 python/deepresearch_flow/paper/templates/__init__.py
 python/deepresearch_flow/paper/templates/deep_read.md.j2
 python/deepresearch_flow/paper/templates/deep_read_phi.md.j2