deepresearch-flow 0.7.2__py3-none-any.whl → 0.7.3__py3-none-any.whl

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/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/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.dist-info → deepresearch_flow-0.7.3.dist-info}/METADATA

@@ -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.dist-info → deepresearch_flow-0.7.3.dist-info}/RECORD

@@ -43,17 +43,18 @@ deepresearch_flow/paper/schemas/default_paper_schema.json,sha256=6h_2ayHolJj8JMn
 deepresearch_flow/paper/schemas/eight_questions_schema.json,sha256=VFKKpdZkgPdQkYIW5jyrZQ7c2TlQZwB4svVWfoiwxdg,1005
 deepresearch_flow/paper/schemas/three_pass_schema.json,sha256=8aNr4EdRiilxszIRBCC4hRNXrfIOcdnVW4Qhe6Fnh0o,689
 deepresearch_flow/paper/snapshot/__init__.py,sha256=1VLO36xxDB3J5Yoo-HH9vyI-4ev2HcivXN0sNLg8O5k,102
-deepresearch_flow/paper/snapshot/api.py,sha256=F_qehvCjxTBTGj9FmqP4NnJQayUPJm0N5e_8mm5JlDQ,37405
+deepresearch_flow/paper/snapshot/api.py,sha256=z1TJmFeMKr5ZiNbZT1xTueVqUqQJD0WhBplDHKlFXRo,37476
 deepresearch_flow/paper/snapshot/builder.py,sha256=HbRcfNteMoP4RnQ4y2onZCm9XfnIvzXLn_EwsLZsDzY,38692
 deepresearch_flow/paper/snapshot/common.py,sha256=KAhlGlPgabOCe9Faps8BoDqin71qpkCfaL_ADCr_9vg,917
 deepresearch_flow/paper/snapshot/identity.py,sha256=k9x1EZPFBU1qgxzkTGvwVtDjLgcosmM_udPuvRLl0uI,7748
-deepresearch_flow/paper/snapshot/mcp_server.py,sha256=KGNCtOWiJ82wHQmrLNVhLwDugGtosqVvKWeLq4ZlBlg,23395
+deepresearch_flow/paper/snapshot/mcp_server.py,sha256=c_WrM7PIMGRmvLg_3759NXc8wH5iwLCa6REBAnngwRg,24491
 deepresearch_flow/paper/snapshot/schema.py,sha256=DcVmAklLYyEeDoVV9jYw7hoMHnHd9Eziivl-LP2busY,8991
 deepresearch_flow/paper/snapshot/text.py,sha256=0RnxLowa6AdirdLsUYym6BhWbjwiP2Qj2oZeA-pjmdE,4368
 deepresearch_flow/paper/snapshot/unpacker.py,sha256=ScKSFdrQLJHrITHe9KAxgAEH-vAAnXLolvW9zeJ3wsc,8575
 deepresearch_flow/paper/snapshot/tests/__init__.py,sha256=G0IowrxHjGUIaqxcw6SvlcLFAtE5ZsleG6ECgd-sIdk,52
 deepresearch_flow/paper/snapshot/tests/test_identity.py,sha256=KDFixAUU9l68KOum7gf1IrD0Oy18dBCSXG7RbJTqflA,4520
 deepresearch_flow/paper/snapshot/tests/test_mcp_server_schema_compat.py,sha256=T7FtkKkGpZx5M7Z278F4iaQFfwS0_XXce_tRdTArt5k,7076
+deepresearch_flow/paper/snapshot/tests/test_mcp_transport.py,sha256=Qh91te1XgzssTUfgCJUpq6Xjnw4tzhhr78bcI3Z4DpA,1622
 deepresearch_flow/paper/templates/__init__.py,sha256=p8W6kINvrf-T2X6Ow4GMr28syVOorFuMn0pbmieVzAw,35
 deepresearch_flow/paper/templates/deep_read.md.j2,sha256=vwVSPOzMBFIS72ez5XFBaKrDZGz0z32L3VGP6mNk434,4780
 deepresearch_flow/paper/templates/deep_read_phi.md.j2,sha256=6Yz2Kxk0czGDPkZiWX3b87glLYHwDU1afr6CkjS-dh8,1666
@@ -467,9 +468,9 @@ deepresearch_flow/translator/placeholder.py,sha256=mEgqA-dPdOsIhno0h_hzfpXpY2asb
 deepresearch_flow/translator/prompts.py,sha256=EvfBvBIpQXARDj4m87GAyFXJGL8EJeahj_rOmp9mv68,5556
 deepresearch_flow/translator/protector.py,sha256=yUMuS2FgVofK_MRXrcauLRiwNvdCCjNAnh6CcNd686o,11777
 deepresearch_flow/translator/segment.py,sha256=rBFMCLTrvm2GrPc_hNFymi-8Ih2DAtUQlZHCRE9nLaM,5146
-deepresearch_flow-0.7.2.dist-info/licenses/LICENSE,sha256=hT8F2Py1pe6flxq3Ufdm2UKFk0B8CBm0aAQfsLXfvjw,1063
-deepresearch_flow-0.7.2.dist-info/METADATA,sha256=2QzhwiS1G6q-XZyRXv7SGgzzsNueZ3PH5-q3g0jlP-Y,31331
-deepresearch_flow-0.7.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-deepresearch_flow-0.7.2.dist-info/entry_points.txt,sha256=1uIKscs0YRMg_mFsg9NjsaTt4CvQqQ_-zGERUKhhL_Y,65
-deepresearch_flow-0.7.2.dist-info/top_level.txt,sha256=qBl4RvPJNJUbL8CFfMNWxY0HpQLx5RlF_ko-z_aKpm0,18
-deepresearch_flow-0.7.2.dist-info/RECORD,,
+deepresearch_flow-0.7.3.dist-info/licenses/LICENSE,sha256=hT8F2Py1pe6flxq3Ufdm2UKFk0B8CBm0aAQfsLXfvjw,1063
+deepresearch_flow-0.7.3.dist-info/METADATA,sha256=I8ERjmgnZ-IZ9WQvm6sPT_yKgozcL5g11sWgqh36Ti8,31955
+deepresearch_flow-0.7.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+deepresearch_flow-0.7.3.dist-info/entry_points.txt,sha256=1uIKscs0YRMg_mFsg9NjsaTt4CvQqQ_-zGERUKhhL_Y,65
+deepresearch_flow-0.7.3.dist-info/top_level.txt,sha256=qBl4RvPJNJUbL8CFfMNWxY0HpQLx5RlF_ko-z_aKpm0,18
+deepresearch_flow-0.7.3.dist-info/RECORD,,