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

mcp_stata/discovery.py

@@ -1,3 +1,12 @@
+"""
+Improved discovery.py with better error handling for intermittent failures.
+Key improvements:
+1. Retry logic for file existence checks
+2. Better diagnostic logging
+3. Fuzzy path matching for common typos
+4. Case-insensitive path resolution on Windows
+"""
+
 import os
 import sys
 import platform
@@ -5,12 +14,106 @@ import glob
 import logging
 import shutil
 import ntpath
-
+import time
 from typing import Tuple, List, Optional
 
 logger = logging.getLogger("mcp_stata.discovery")
 
 
+def _exists_with_retry(path: str, max_attempts: int = 3, delay: float = 0.1) -> bool:
+    """
+    Check if file exists with retry logic to handle transient failures.
+    This helps with antivirus scans, file locks, and other temporary issues.
+    """
+    for attempt in range(max_attempts):
+        if os.path.exists(path):
+            return True
+        if attempt < max_attempts - 1:
+            logger.debug(
+                f"File existence check attempt {attempt + 1} failed for: {path}"
+            )
+            time.sleep(delay)
+    return False
+
+
+def _find_similar_stata_dirs(target_path: str) -> List[str]:
+    """
+    Find similar Stata directories to help diagnose path typos.
+    Useful when user has 'Stata19Now' instead of 'StataNow19'.
+    """
+    parent = os.path.dirname(target_path)
+    
+    # If parent doesn't exist, try grandparent (for directory name typos)
+    search_dir = parent
+    if not os.path.exists(parent):
+        search_dir = os.path.dirname(parent)
+    
+    if not os.path.exists(search_dir):
+        return []
+    
+    try:
+        subdirs = [
+            d for d in os.listdir(search_dir)
+            if os.path.isdir(os.path.join(search_dir, d))
+        ]
+        # Filter to Stata-related directories (case-insensitive)
+        stata_dirs = [
+            os.path.join(search_dir, d)
+            for d in subdirs
+            if 'stata' in d.lower()
+        ]
+        return stata_dirs
+    except (OSError, PermissionError) as e:
+        logger.debug(f"Could not list directory {search_dir}: {e}")
+        return []
+
+
+def _validate_path_with_diagnostics(path: str, system: str) -> Tuple[bool, str]:
+    """
+    Validate path exists and provide detailed diagnostics if not.
+    Returns (exists, diagnostic_message)
+    """
+    if _exists_with_retry(path):
+        return True, ""
+    
+    # Build diagnostic message
+    diagnostics = []
+    diagnostics.append(f"File not found: '{path}'")
+    
+    parent_dir = os.path.dirname(path)
+    filename = os.path.basename(path)
+    
+    if _exists_with_retry(parent_dir):
+        diagnostics.append(f"✓ Parent directory exists: '{parent_dir}'")
+        try:
+            files_in_parent = os.listdir(parent_dir)
+            # Look for similar filenames
+            similar_files = [
+                f for f in files_in_parent
+                if 'stata' in f.lower() and f.lower().endswith('.exe' if system == 'Windows' else '')
+            ]
+            if similar_files:
+                diagnostics.append(f"Found {len(similar_files)} Stata file(s) in parent:")
+                for f in similar_files[:5]:  # Show max 5
+                    diagnostics.append(f"  - {f}")
+            else:
+                diagnostics.append(f"No Stata executables found in parent directory")
+                diagnostics.append(f"Files present: {', '.join(files_in_parent[:10])}")
+        except (OSError, PermissionError) as e:
+            diagnostics.append(f"✗ Could not list parent directory: {e}")
+    else:
+        diagnostics.append(f"✗ Parent directory does not exist: '{parent_dir}'")
+        
+        # Check for similar directories (typo detection)
+        similar_dirs = _find_similar_stata_dirs(path)
+        if similar_dirs:
+            diagnostics.append("\nDid you mean one of these directories?")
+            for dir_path in similar_dirs[:5]:
+                diagnostics.append(f"  - {dir_path}")
+    
+    return False, "\n".join(diagnostics)
+
+
 def _normalize_env_path(raw: str, system: str) -> str:
     """Strip quotes/whitespace, expand variables, and normalize slashes for STATA_PATH."""
     cleaned = raw.strip()
@@ -30,7 +133,7 @@ def _normalize_env_path(raw: str, system: str) -> str:
 
 
 def _is_executable(path: str, system: str) -> bool:
-    if not os.path.exists(path):
+    if not _exists_with_retry(path):  # Use retry logic
         return False
     if system == "Windows":
         # On Windows, check if it's a file and has .exe extension
@@ -71,11 +174,11 @@ def _resolve_windows_host_path(path: str, system: str) -> str:
     """
     if system != "Windows":
         return path
-    if os.path.exists(path):
+    if _exists_with_retry(path):  # Use retry logic
         return path
     if os.sep != "\\" and "\\" in path:
         alt_path = path.replace("\\", os.sep)
-        if os.path.exists(alt_path):
+        if _exists_with_retry(alt_path):  # Use retry logic
             return alt_path
     return path
 
@@ -97,11 +200,12 @@ def find_stata_path() -> Tuple[str, str]:
 
     Behavior:
     - If STATA_PATH is set and valid, use it.
-    - If STATA_PATH is set but invalid, fall back to auto-discovery.
-    - If auto-discovery fails, raise an error (including STATA_PATH failure context, if any).
+    - If STATA_PATH is set but invalid, provide detailed diagnostics and fall back.
+    - If auto-discovery fails, raise an error with helpful suggestions.
     """
     system = _detect_system()
     stata_path_error: Optional[Exception] = None
+    stata_path_diagnostics: Optional[str] = None
 
     windows_binaries = [
         ("StataMP-64.exe", "mp"),
@@ -158,11 +262,15 @@ def find_stata_path() -> Tuple[str, str]:
                         )
                         return candidate, edition
 
-                raise FileNotFoundError(
-                    f"STATA_PATH points to directory '{path}', but no Stata executable was found within. "
+                # Enhanced error with diagnostics
+                exists, diagnostics = _validate_path_with_diagnostics(path, system)
+                error_msg = (
+                    f"STATA_PATH points to directory '{path}', but no Stata executable was found within.\n"
+                    f"{diagnostics}\n\n"
                     "Point STATA_PATH directly to the Stata binary "
-                    "(e.g., C:\\Program Files\\Stata19\\StataMP-64.exe)."
+                    "(e.g., C:\\Program Files\\StataNow19\\StataMP-64.exe)."
                 )
+                raise FileNotFoundError(error_msg)
 
             edition = "be"
             lower_path = path.lower()
@@ -173,13 +281,18 @@ def find_stata_path() -> Tuple[str, str]:
             elif "be" in lower_path:
                 edition = "be"
 
-            if not os.path.exists(path):
-                raise FileNotFoundError(
-                    f"STATA_PATH points to '{path}', but that file does not exist. "
+            # Use enhanced validation with diagnostics
+            exists, diagnostics = _validate_path_with_diagnostics(path, system)
+            if not exists:
+                error_msg = (
+                    f"STATA_PATH points to '{path}', but that file does not exist.\n"
+                    f"{diagnostics}\n\n"
                     "Update STATA_PATH to your Stata binary (e.g., "
                     "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp, "
-                    "/usr/local/stata19/stata-mp or C:\\Program Files\\Stata19Now\\StataSE-64.exe)."
+                    "/usr/local/stata19/stata-mp or C:\\Program Files\\StataNow19\\StataMP-64.exe)."
                 )
+                raise FileNotFoundError(error_msg)
+                
             if not _is_executable(path, system):
                 raise PermissionError(
                     f"STATA_PATH points to '{path}', but it is not executable. "
@@ -191,6 +304,7 @@ def find_stata_path() -> Tuple[str, str]:
 
         except Exception as exc:
             stata_path_error = exc
+            stata_path_diagnostics = str(exc)
             logger.warning(
                 "STATA_PATH override failed (%s). Falling back to auto-discovery.",
                 exc,
@@ -213,11 +327,11 @@ def find_stata_path() -> Tuple[str, str]:
         for pattern in app_globs:
             for app_dir in glob.glob(pattern):
                 binary_dir = os.path.join(app_dir, "Contents", "MacOS")
-                if not os.path.exists(binary_dir):
+                if not _exists_with_retry(binary_dir):  # Use retry logic
                     continue
                 for binary, edition in [("stata-mp", "mp"), ("stata-se", "se"), ("stata", "be")]:
                     full_path = os.path.join(binary_dir, binary)
-                    if os.path.exists(full_path):
+                    if _exists_with_retry(full_path):  # Use retry logic
                         candidates.append((full_path, edition))
 
     elif system == "Windows":
@@ -265,7 +379,7 @@ def find_stata_path() -> Tuple[str, str]:
                 continue
             for exe, edition in windows_binaries:
                 full_path = os.path.join(stata_dir, exe)
-                if os.path.exists(full_path):
+                if _exists_with_retry(full_path):  # Use retry logic
                     candidates.append((full_path, edition))
 
     elif system == "Linux":
@@ -303,13 +417,13 @@ def find_stata_path() -> Tuple[str, str]:
                         continue
                     for binary, edition in linux_binaries:
                         full_path = os.path.join(base_dir, binary)
-                        if os.path.exists(full_path):
+                        if _exists_with_retry(full_path):  # Use retry logic
                             candidates.append((full_path, edition))
 
     candidates = _dedupe_preserve(candidates)
 
     for path, edition in candidates:
-        if not os.path.exists(path):
+        if not _exists_with_retry(path):  # Use retry logic
             logger.warning("Discovered candidate missing on disk: %s", path)
             continue
         if not _is_executable(path, system):
@@ -318,21 +432,27 @@ def find_stata_path() -> Tuple[str, str]:
         logger.info("Auto-discovered Stata at %s (%s)", path, edition)
         return path, edition
 
+    # Build comprehensive error message
+    error_parts = ["Could not automatically locate Stata."]
+    
     if stata_path_error is not None:
-        raise FileNotFoundError(
-            "Could not automatically locate Stata after STATA_PATH failed. "
-            f"STATA_PATH error was: {stata_path_error}. "
-            "Fix STATA_PATH to point to the Stata executable, or install Stata in a standard location "
-            "(e.g., /Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp, /usr/local/stata18/stata-mp, "
-            "or C:\\Program Files\\Stata18\\StataMP-64.exe)."
-        ) from stata_path_error
-
-    raise FileNotFoundError(
-        "Could not automatically locate Stata. "
-        "Set STATA_PATH to your Stata executable (e.g., "
-        "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp, /usr/local/stata18/stata-mp, "
-        "or C:\\Program Files\\Stata18\\StataMP-64.exe)."
+        error_parts.append(
+            f"\nSTATA_PATH was set but failed:\n{stata_path_diagnostics}"
+        )
+    
+    error_parts.append(
+        "\nTo fix this issue:\n"
+        "1. Set STATA_PATH to point to your Stata executable, for example:\n"
+        "   - Windows: C:\\Program Files\\StataNow19\\StataMP-64.exe\n"
+        "   - macOS: /Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp\n"
+        "   - Linux: /usr/local/stata19/stata-mp\n"
+        "\n2. Or install Stata in a standard location where it can be auto-discovered."
     )
+    
+    if stata_path_error is not None:
+        raise FileNotFoundError("\n".join(error_parts)) from stata_path_error
+    else:
+        raise FileNotFoundError("\n".join(error_parts))
 
 
 def main() -> int:

mcp_stata/stata_client.py

@@ -408,6 +408,73 @@ class StataClient:
                 return None
         return None
 
+    def _read_log_tail(self, path: str, max_chars: int) -> str:
+        try:
+            with open(path, "rb") as f:
+                f.seek(0, os.SEEK_END)
+                size = f.tell()
+                if size <= 0:
+                    return ""
+                read_size = min(size, max_chars)
+                f.seek(-read_size, os.SEEK_END)
+                data = f.read(read_size)
+            return data.decode("utf-8", errors="replace")
+        except Exception:
+            return ""
+
+    def _select_stata_error_message(self, text: str, fallback: str) -> str:
+        if not text:
+            return fallback
+        ignore_patterns = (
+            r"^r\(\d+\);?$",
+            r"^end of do-file$",
+            r"^execution terminated$",
+            r"^[-=*]{3,}.*$",
+        )
+        rc_pattern = r"^r\(\d+\);?$"
+        error_patterns = (
+            r"\btype mismatch\b",
+            r"\bnot found\b",
+            r"\bnot allowed\b",
+            r"\bno observations\b",
+            r"\bconformability error\b",
+            r"\binvalid\b",
+            r"\bsyntax error\b",
+            r"\berror\b",
+        )
+        lines = text.splitlines()
+        for raw in reversed(lines):
+            line = raw.strip()
+            if not line:
+                continue
+            if any(re.search(pat, line, re.IGNORECASE) for pat in error_patterns):
+                return line
+        for i in range(len(lines) - 1, -1, -1):
+            line = lines[i].strip()
+            if not line:
+                continue
+            if re.match(rc_pattern, line, re.IGNORECASE):
+                for j in range(i - 1, -1, -1):
+                    prev_line = lines[j].strip()
+                    if not prev_line:
+                        continue
+                    if prev_line.startswith((".", ">", "-", "=")):
+                        continue
+                    if any(re.match(pat, prev_line, re.IGNORECASE) for pat in ignore_patterns):
+                        continue
+                    return prev_line
+                return line
+        for raw in reversed(lines):
+            line = raw.strip()
+            if not line:
+                continue
+            if line.startswith((".", ">", "-", "=")):
+                continue
+            if any(re.match(pat, line, re.IGNORECASE) for pat in ignore_patterns):
+                continue
+            return line
+        return fallback
+
     def _smcl_to_text(self, smcl: str) -> str:
         """Convert simple SMCL markup into plain text for LLM-friendly help."""
         # First, keep inline directive content if present (e.g., {bf:word} -> word)
@@ -433,7 +500,10 @@ class StataClient:
         rc_final = rc_hint if (rc_hint is not None and rc_hint != 0) else (rc if rc not in (-1, None) else rc_hint)
         line_no = self._parse_line_from_text(combined) if combined else None
         snippet = combined[-800:] if combined else None
-        message = (stderr or (str(exc) if exc else "") or stdout or "Stata error").strip()
+        fallback = (stderr or (str(exc) if exc else "") or stdout or "Stata error").strip()
+        if fallback == "Stata error" and rc_final is not None:
+            fallback = f"Stata error r({rc_final})"
+        message = self._select_stata_error_message(combined, fallback)
         return ErrorEnvelope(
             message=message,
             rc=rc_final,
@@ -640,7 +710,7 @@ class StataClient:
             buffering=1,
         )
         log_path = log_file.name
-        tail = TailBuffer(max_chars=8000)
+        tail = TailBuffer(max_chars=200000 if trace else 20000)
         tee = FileTeeIO(log_file, tail)
 
         # Inform the MCP client immediately where to read/tail the output.
@@ -705,6 +775,9 @@ class StataClient:
                 logger.warning(f"Failed to cache detected graphs: {e}")
 
         tail_text = tail.get_value()
+        log_tail = self._read_log_tail(log_path, 200000 if trace else 20000)
+        if log_tail and len(log_tail) > len(tail_text):
+            tail_text = log_tail
         combined = (tail_text or "") + (f"\n{exc}" if exc else "")
         rc_hint = self._parse_rc_from_text(combined) if combined else None
         if exc is None and rc_hint is not None and rc_hint != 0:
@@ -718,14 +791,10 @@ class StataClient:
             rc_hint = self._parse_rc_from_text(combined) if combined else None
             rc_final = rc_hint if (rc_hint is not None and rc_hint != 0) else (rc if rc not in (-1, None) else rc_hint)
             line_no = self._parse_line_from_text(combined) if combined else None
-            message = "Stata error"
-            if tail_text and tail_text.strip():
-                for line in reversed(tail_text.splitlines()):
-                    if line.strip():
-                        message = line.strip()
-                        break
-            elif exc is not None:
-                message = str(exc).strip() or message
+            fallback = (str(exc).strip() if exc is not None else "") or "Stata error"
+            if fallback == "Stata error" and rc_final is not None:
+                fallback = f"Stata error r({rc_final})"
+            message = self._select_stata_error_message(combined, fallback)
 
             error = ErrorEnvelope(
                 message=message,
@@ -876,7 +945,7 @@ class StataClient:
             buffering=1,
         )
         log_path = log_file.name
-        tail = TailBuffer(max_chars=8000)
+        tail = TailBuffer(max_chars=200000 if trace else 20000)
         tee = FileTeeIO(log_file, tail)
 
         # Inform the MCP client immediately where to read/tail the output.
@@ -1042,6 +1111,9 @@ class StataClient:
                 logger.error(f"Post-execution graph detection failed: {e}")
 
         tail_text = tail.get_value()
+        log_tail = self._read_log_tail(log_path, 200000 if trace else 20000)
+        if log_tail and len(log_tail) > len(tail_text):
+            tail_text = log_tail
         combined = (tail_text or "") + (f"\n{exc}" if exc else "")
         rc_hint = self._parse_rc_from_text(combined) if combined else None
         if exc is None and rc_hint is not None and rc_hint != 0:
@@ -1055,14 +1127,10 @@ class StataClient:
             rc_hint = self._parse_rc_from_text(combined) if combined else None
             rc_final = rc_hint if (rc_hint is not None and rc_hint != 0) else (rc if rc not in (-1, None) else rc_hint)
             line_no = self._parse_line_from_text(combined) if combined else None
-            message = "Stata error"
-            if tail_text and tail_text.strip():
-                for line in reversed(tail_text.splitlines()):
-                    if line.strip():
-                        message = line.strip()
-                        break
-            elif exc is not None:
-                message = str(exc).strip() or message
+            fallback = (str(exc).strip() if exc is not None else "") or "Stata error"
+            if fallback == "Stata error" and rc_final is not None:
+                fallback = f"Stata error r({rc_final})"
+            message = self._select_stata_error_message(combined, fallback)
 
             error = ErrorEnvelope(
                 message=message,
@@ -1425,6 +1493,65 @@ class StataClient:
 
         return indices
 
+    def apply_sort(self, sort_spec: List[str]) -> None:
+        """
+        Apply sorting to the dataset using gsort.
+
+        Args:
+            sort_spec: List of variables to sort by, with optional +/- prefix.
+                      e.g., ["-price", "+mpg"] sorts by price descending, then mpg ascending.
+                      No prefix is treated as ascending (+).
+
+        Raises:
+            ValueError: If sort_spec is invalid or contains invalid variables
+            RuntimeError: If no data in memory or sort command fails
+        """
+        if not self._initialized:
+            self.init()
+
+        state = self.get_dataset_state()
+        if int(state.get("k", 0) or 0) == 0 and int(state.get("n", 0) or 0) == 0:
+            raise RuntimeError("No data in memory")
+
+        if not sort_spec or not isinstance(sort_spec, list):
+            raise ValueError("sort_spec must be a non-empty list")
+
+        # Validate all variables exist
+        var_map = self._get_var_index_map()
+        for spec in sort_spec:
+            if not isinstance(spec, str) or not spec:
+                raise ValueError(f"Invalid sort specification: {spec!r}")
+
+            # Extract variable name (remove +/- prefix if present)
+            varname = spec.lstrip("+-")
+            if not varname:
+                raise ValueError(f"Invalid sort specification: {spec!r}")
+
+            if varname not in var_map:
+                raise ValueError(f"Variable not found: {varname}")
+
+        # Build gsort command
+        # gsort uses - for descending, + or nothing for ascending
+        gsort_args = []
+        for spec in sort_spec:
+            if spec.startswith("-") or spec.startswith("+"):
+                gsort_args.append(spec)
+            else:
+                # No prefix means ascending, add + explicitly for clarity
+                gsort_args.append(f"+{spec}")
+
+        cmd = f"gsort {' '.join(gsort_args)}"
+
+        try:
+            result = self.run_command_structured(cmd, echo=False)
+            if not result.success:
+                error_msg = result.error.message if result.error else "Sort failed"
+                raise RuntimeError(f"Failed to sort dataset: {error_msg}")
+        except Exception as e:
+            if isinstance(e, RuntimeError):
+                raise
+            raise RuntimeError(f"Failed to sort dataset: {e}")
+
     def get_variable_details(self, varname: str) -> str:
         """Returns codebook/summary for a specific variable."""
         resp = self.run_command_structured(f"codebook {varname}", echo=True)
@@ -2247,7 +2374,7 @@ class StataClient:
             buffering=1,
         )
         log_path = log_file.name
-        tail = TailBuffer(max_chars=8000)
+        tail = TailBuffer(max_chars=200000 if trace else 20000)
         tee = FileTeeIO(log_file, tail)
 
         rc = -1
@@ -2278,6 +2405,9 @@ class StataClient:
         tee.close()
 
         tail_text = tail.get_value()
+        log_tail = self._read_log_tail(log_path, 200000 if trace else 20000)
+        if log_tail and len(log_tail) > len(tail_text):
+            tail_text = log_tail
         combined = (tail_text or "") + (f"\n{exc}" if exc else "")
         rc_hint = self._parse_rc_from_text(combined) if combined else None
         if exc is None and rc_hint is not None and rc_hint != 0:
@@ -2292,14 +2422,10 @@ class StataClient:
             rc_hint = self._parse_rc_from_text(combined) if combined else None
             rc_final = rc_hint if (rc_hint is not None and rc_hint != 0) else (rc if rc not in (-1, None) else rc_hint)
             line_no = self._parse_line_from_text(combined) if combined else None
-            message = "Stata error"
-            if tail_text and tail_text.strip():
-                for line in reversed(tail_text.splitlines()):
-                    if line.strip():
-                        message = line.strip()
-                        break
-            elif exc is not None:
-                message = str(exc).strip() or message
+            fallback = (str(exc).strip() if exc is not None else "") or "Stata error"
+            if fallback == "Stata error" and rc_final is not None:
+                fallback = f"Stata error r({rc_final})"
+            message = self._select_stata_error_message(combined, fallback)
 
             error = ErrorEnvelope(
                 message=message,
@@ -2384,4 +2510,3 @@ class StataClient:
                 )
 
         return result
-

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:
@@ -473,6 +485,13 @@ def handle_page_request(manager: UIChannelManager, body: dict[str, Any], *, view
     vars_req = body.get("vars", [])
     include_obs_no = bool(body.get("includeObsNo", False))
 
+    # 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:
@@ -509,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,
@@ -518,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.8.dist-info → mcp_stata-1.7.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-stata
-Version: 1.6.8
+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
@@ -300,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
   }
 }
 ```
@@ -341,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.6.8.dist-info → mcp_stata-1.7.3.dist-info}/RECORD

@@ -1,14 +1,14 @@
 mcp_stata/__init__.py,sha256=kJKKRn7lGuVCuS2-GaN5VoVcvnxtNlfuswW_VOlYqwg,98
-mcp_stata/discovery.py,sha256=J_XU1_AXRpqWg_ULV8xf4lT6RRN8MxOdpr1ioTi5TjQ,12951
+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=TNJnlkZ0IoNoVXhKUw0_IYLiRNOwyL2wVmb1gWdiRUY,95981
+mcp_stata/stata_client.py,sha256=06cA5K4vwXc_kNCwIifUL8eSSYsIYtM5zArhJcLcUlo,101267
 mcp_stata/streaming_io.py,sha256=GVaXgTtxx8YLY6RWqdTcO2M3QSqxLsefqkmnlNO1nTI,6974
-mcp_stata/ui_http.py,sha256=kkPYpqp-lQDXs_9qcs7hb16FtvNcag3rKSH7wvQX7Qo,22013
+mcp_stata/ui_http.py,sha256=w1tYxNuwuhkjyfWHxUnpd1DcVBaakjPkEnWr-Fo1lWo,24193
 mcp_stata/smcl/smcl2html.py,sha256=wi91mOMeV9MCmHtNr0toihNbaiDCNZ_NP6a6xEAzWLM,2624
-mcp_stata-1.6.8.dist-info/METADATA,sha256=V5mN_9vRL5f1aja0zrhMatBKb-_ZC6Ok3uOXfRBfYw4,13794
-mcp_stata-1.6.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mcp_stata-1.6.8.dist-info/entry_points.txt,sha256=TcOgrtiTL4LGFEDb1pCrQWA-fUZvIujDOvQ-bWFh5Z8,52
-mcp_stata-1.6.8.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-mcp_stata-1.6.8.dist-info/RECORD,,
+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,,