mcp-stata 1.6.2__py3-none-any.whl → 1.7.3__py3-none-any.whl

mcp_stata/ui_http.py

@@ -27,6 +27,7 @@ class ViewHandle:
     view_id: str
     dataset_id: str
     frame: str
+    filter_expr: str
     obs_indices: list[int]
     filtered_n: int
     created_at: float
@@ -86,7 +87,7 @@ class UIChannelManager:
             return UIChannelInfo(base_url=base_url, token=self._token or "", expires_at=self._expires_at)
 
     def capabilities(self) -> dict[str, bool]:
-        return {"dataBrowser": True, "filtering": True}
+        return {"dataBrowser": True, "filtering": True, "sorting": True}
 
     def current_dataset_id(self) -> str:
         with self._lock:
@@ -138,6 +139,7 @@ class UIChannelManager:
             view_id=view_id,
             dataset_id=current_id,
             frame=frame,
+            filter_expr=filter_expr,
             obs_indices=obs_indices,
             filtered_n=len(obs_indices),
             created_at=now,
@@ -290,11 +292,16 @@ class UIChannelManager:
                         body = self._read_json()
                         if body is None:
                             return
+                        # Debug logging to diagnose limit parameter issues
+                        import sys
+                        print(f"[DEBUG] /v1/page request body: {body}", file=sys.stderr, flush=True)
+                        print(f"[DEBUG] limit value: {body.get('limit')!r} (type: {type(body.get('limit')).__name__})", file=sys.stderr, flush=True)
                         try:
                             resp = handle_page_request(manager, body, view_id=None)
                             self._send_json(200, resp)
                             return
                         except HTTPError as e:
+                            print(f"[DEBUG] HTTPError: {e.code} - {e.message}", file=sys.stderr, flush=True)
                             self._error(e.status, e.code, e.message, stata_rc=e.stata_rc)
                             return
                         except Exception as e:
@@ -347,11 +354,16 @@ class UIChannelManager:
                         body = self._read_json()
                         if body is None:
                             return
+                        # Debug logging to diagnose limit parameter issues
+                        import sys
+                        print(f"[DEBUG] /v1/views/{view_id}/page request body: {body}", file=sys.stderr, flush=True)
+                        print(f"[DEBUG] limit value: {body.get('limit')!r} (type: {type(body.get('limit')).__name__})", file=sys.stderr, flush=True)
                         try:
                             resp = handle_page_request(manager, body, view_id=view_id)
                             self._send_json(200, resp)
                             return
                         except HTTPError as e:
+                            print(f"[DEBUG] HTTPError: {e.code} - {e.message}", file=sys.stderr, flush=True)
                             self._error(e.status, e.code, e.message, stata_rc=e.stata_rc)
                             return
                         except Exception as e:
@@ -455,16 +467,42 @@ def handle_page_request(manager: UIChannelManager, body: dict[str, Any], *, view
         dataset_id = view.dataset_id
         frame = view.frame
 
-    offset = int(body.get("offset", 0) or 0)
-    limit = int(body.get("limit", 0) or 0)
+    # Parse offset (default 0 is valid since offset >= 0)
+    try:
+        offset = int(body.get("offset") or 0)
+    except (ValueError, TypeError) as e:
+        raise HTTPError(400, "invalid_request", f"offset must be a valid integer, got: {body.get('offset')!r}")
+
+    # Parse limit (no default - must be explicitly provided)
+    limit_raw = body.get("limit")
+    if limit_raw is None:
+        raise HTTPError(400, "invalid_request", "limit is required")
+    try:
+        limit = int(limit_raw)
+    except (ValueError, TypeError) as e:
+        raise HTTPError(400, "invalid_request", f"limit must be a valid integer, got: {limit_raw!r}")
+
     vars_req = body.get("vars", [])
     include_obs_no = bool(body.get("includeObsNo", False))
-    max_chars_req = int(body.get("maxChars", max_chars) or max_chars)
+
+    # Parse sortBy parameter
+    sort_by = body.get("sortBy", [])
+    if sort_by is not None and not isinstance(sort_by, list):
+        raise HTTPError(400, "invalid_request", f"sortBy must be an array, got: {type(sort_by).__name__}")
+    if sort_by and not all(isinstance(s, str) for s in sort_by):
+        raise HTTPError(400, "invalid_request", "sortBy must be an array of strings")
+
+    # Parse maxChars
+    max_chars_raw = body.get("maxChars", max_chars)
+    try:
+        max_chars_req = int(max_chars_raw or max_chars)
+    except (ValueError, TypeError) as e:
+        raise HTTPError(400, "invalid_request", f"maxChars must be a valid integer, got: {max_chars_raw!r}")
 
     if offset < 0:
-        raise HTTPError(400, "invalid_request", "offset must be >= 0")
+        raise HTTPError(400, "invalid_request", f"offset must be >= 0, got: {offset}")
     if limit <= 0:
-        raise HTTPError(400, "invalid_request", "limit must be > 0")
+        raise HTTPError(400, "invalid_request", f"limit must be > 0, got: {limit}")
     if limit > max_limit:
         raise HTTPError(400, "request_too_large", f"limit must be <= {max_limit}")
     if max_chars_req <= 0:
@@ -490,6 +528,20 @@ def handle_page_request(manager: UIChannelManager, body: dict[str, Any], *, view
         filtered_n = view.filtered_n
 
     try:
+        # Apply sorting if requested
+        if sort_by:
+            try:
+                manager._client.apply_sort(sort_by)
+                # If sorting with a filtered view, re-compute indices after sort
+                if view_id is not None:
+                    assert view is not None
+                    obs_indices = manager._client.compute_view_indices(view.filter_expr)
+                    filtered_n = len(obs_indices)
+            except ValueError as e:
+                raise HTTPError(400, "invalid_request", f"Invalid sort specification: {e}")
+            except RuntimeError as e:
+                raise HTTPError(500, "internal_error", f"Failed to apply sort: {e}")
+
         dataset_state = manager._client.get_dataset_state()
         page = manager._client.get_page(
             offset=offset,
@@ -499,6 +551,9 @@ def handle_page_request(manager: UIChannelManager, body: dict[str, Any], *, view
             max_chars=max_chars_req,
             obs_indices=obs_indices,
         )
+    except HTTPError:
+        # Re-raise HTTPError exceptions as-is
+        raise
     except RuntimeError as e:
         # StataClient uses RuntimeError("No data in memory") for empty dataset.
         msg = str(e) or "No data in memory"

{mcp_stata-1.6.2.dist-info → mcp_stata-1.7.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-stata
-Version: 1.6.2
+Version: 1.7.3
 Summary:  A lightweight Model Context Protocol (MCP) server for Stata. Execute commands, inspect data, retrieve stored results (`r()`/`e()`), and view graphs in your chat interface. Built for economists who want to integrate LLM assistance into their Stata workflow. 
 Project-URL: Homepage, https://github.com/tmonk/mcp-stata
 Project-URL: Repository, https://github.com/tmonk/mcp-stata
@@ -259,6 +259,14 @@ VS Code documents `.vscode/mcp.json` and the `servers` schema, including `type`
 * `get_stored_results()`: Get `r()` and `e()` scalars/macros as JSON.
 * `get_variable_list()`: JSON list of variables and labels.
 
+### Cancellation
+
+- Clients may cancel an in-flight request by sending the MCP notification `notifications/cancelled` with `params.requestId` set to the original tool call ID.
+- Client guidance:
+  1. Pass a `_meta.progressToken` when invoking the tool if you want progress updates (optional).
+  2. If you need to cancel, send `notifications/cancelled` with the same requestId. You may also stop tailing the log file path once you receive cancellation confirmation (the tool call will return an error indicating cancellation).
+  3. Be prepared for partial output in the log file; cancellation is best-effort and depends on Stata surfacing `BreakError`.
+
 Resources exposed for MCP clients:
 
 * `stata://data/summary` → `summarize`
@@ -292,7 +300,8 @@ Call the MCP tool `get_ui_channel()` and parse the JSON:
   "expiresAt": 1730000000,
   "capabilities": {
     "dataBrowser": true,
-    "filtering": true
+    "filtering": true,
+    "sorting": true
   }
 }
 ```
@@ -333,10 +342,67 @@ curl -sS \
   "$BASE_URL/v1/page"
 ```
 
+#### Sorting
+
+The `/v1/page` and `/v1/views/:viewId/page` endpoints support sorting via the optional `sortBy` parameter:
+
+```bash
+# Sort by price ascending
+curl -sS \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"datasetId":"...","offset":0,"limit":50,"vars":["price","mpg"],"sortBy":["price"]}' \
+  "$BASE_URL/v1/page"
+
+# Sort by price descending
+curl -sS \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"datasetId":"...","offset":0,"limit":50,"vars":["price","mpg"],"sortBy":["-price"]}' \
+  "$BASE_URL/v1/page"
+
+# Multi-variable sort: foreign ascending, then price descending
+curl -sS \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"datasetId":"...","offset":0,"limit":50,"vars":["foreign","price","mpg"],"sortBy":["foreign","-price"]}' \
+  "$BASE_URL/v1/page"
+```
+
+**Sort specification format:**
+- `sortBy` is an array of strings (variable names with optional prefix)
+- No prefix or `+` prefix = ascending order (e.g., `"price"` or `"+price"`)
+- `-` prefix = descending order (e.g., `"-price"`)
+- Multiple variables are supported for multi-level sorting
+- Uses Stata's `gsort` command internally
+
+**Sorting with filtered views:**
+- Sorting is fully supported with filtered views
+- The sort is applied to the entire dataset, then filtered indices are re-computed
+- Example: Filter for `price < 5000`, then sort descending by price
+
+```bash
+# Create a filtered view
+curl -sS \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"datasetId":"...","frame":"default","filterExpr":"price < 5000"}' \
+  "$BASE_URL/v1/views"
+# Returns: {"view": {"id": "view_abc123", "filteredN": 37}}
+
+# Get sorted page from filtered view
+curl -sS \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"offset":0,"limit":50,"vars":["price","mpg"],"sortBy":["-price"]}' \
+  "$BASE_URL/v1/views/view_abc123/page"
+```
+
 Notes:
 
 - `datasetId` is used for cache invalidation. If the dataset changes due to running Stata commands, the server will report a new dataset id and view handles become invalid.
 - Filter expressions are evaluated in Python using values read from Stata via `sfi.Data.get`. Use boolean operators like `==`, `!=`, `<`, `>`, and `and`/`or` (Stata-style `&`/`|` are also accepted).
+- Sorting modifies the dataset order in memory using `gsort`. When combined with views, the filtered indices are automatically re-computed after sorting.
 
 ## License
 

mcp_stata-1.7.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+mcp_stata/__init__.py,sha256=kJKKRn7lGuVCuS2-GaN5VoVcvnxtNlfuswW_VOlYqwg,98
+mcp_stata/discovery.py,sha256=jQN9uvBNHF_hCCU9k6BDtSdDxiUVpvXcOJwpWYwo55c,17430
+mcp_stata/graph_detector.py,sha256=-dJIU1Dq_c1eQSk4eegUi0gU2N-tFqjFGM0tE1E32KM,16066
+mcp_stata/models.py,sha256=QETpYKO3yILy_L6mhouVEanvUIvu4ww_CAAFuiP2YdM,1201
+mcp_stata/server.py,sha256=PV8ragGMeHT72zgVx5DJp3vt8CPqT8iwdvJ8GXSctds,15989
+mcp_stata/stata_client.py,sha256=06cA5K4vwXc_kNCwIifUL8eSSYsIYtM5zArhJcLcUlo,101267
+mcp_stata/streaming_io.py,sha256=GVaXgTtxx8YLY6RWqdTcO2M3QSqxLsefqkmnlNO1nTI,6974
+mcp_stata/ui_http.py,sha256=w1tYxNuwuhkjyfWHxUnpd1DcVBaakjPkEnWr-Fo1lWo,24193
+mcp_stata/smcl/smcl2html.py,sha256=wi91mOMeV9MCmHtNr0toihNbaiDCNZ_NP6a6xEAzWLM,2624
+mcp_stata-1.7.3.dist-info/METADATA,sha256=cOSWlFgl296f5UhvozBLCPpe7tWS7kcVWGBNlnqO2Hs,15951
+mcp_stata-1.7.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcp_stata-1.7.3.dist-info/entry_points.txt,sha256=TcOgrtiTL4LGFEDb1pCrQWA-fUZvIujDOvQ-bWFh5Z8,52
+mcp_stata-1.7.3.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+mcp_stata-1.7.3.dist-info/RECORD,,

mcp_stata-1.6.2.dist-info/RECORD

@@ -1,14 +0,0 @@
-mcp_stata/__init__.py,sha256=kJKKRn7lGuVCuS2-GaN5VoVcvnxtNlfuswW_VOlYqwg,98
-mcp_stata/discovery.py,sha256=K8SK4oEnLESxnJWcBsLK76s85yNVdbLlfOql_Rf94B4,8390
-mcp_stata/graph_detector.py,sha256=-dJIU1Dq_c1eQSk4eegUi0gU2N-tFqjFGM0tE1E32KM,16066
-mcp_stata/models.py,sha256=QETpYKO3yILy_L6mhouVEanvUIvu4ww_CAAFuiP2YdM,1201
-mcp_stata/server.py,sha256=9_0i8xux11NpZ6yJwOniqQo-Cs3ph2mrkr0gwZ9GZ1I,15671
-mcp_stata/stata_client.py,sha256=floQMie0j7xI1PUeVu3mbmv4_eztw2CLjviZ7fdmClo,90673
-mcp_stata/streaming_io.py,sha256=GVaXgTtxx8YLY6RWqdTcO2M3QSqxLsefqkmnlNO1nTI,6974
-mcp_stata/ui_http.py,sha256=UhIPzCpBelVpZWUgwBnGpOCAEpG2vFVvX-TxRuyhkR0,21210
-mcp_stata/smcl/smcl2html.py,sha256=wi91mOMeV9MCmHtNr0toihNbaiDCNZ_NP6a6xEAzWLM,2624
-mcp_stata-1.6.2.dist-info/METADATA,sha256=buX6iqLIsnmtBlVueebezon9o3OYxL6I0DYmmwHOV0I,13141
-mcp_stata-1.6.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mcp_stata-1.6.2.dist-info/entry_points.txt,sha256=TcOgrtiTL4LGFEDb1pCrQWA-fUZvIujDOvQ-bWFh5Z8,52
-mcp_stata-1.6.2.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-mcp_stata-1.6.2.dist-info/RECORD,,