mcp-stata 1.0.1__py3-none-any.whl

mcp_stata/__init__.py

@@ -0,0 +1,4 @@
+from .server import main
+from .stata_client import StataClient
+
+__all__ = ["main", "StataClient"]

mcp_stata/discovery.py

@@ -0,0 +1,124 @@
+import os
+import platform
+import glob
+import logging
+
+from typing import Tuple, Optional, List
+
+logger = logging.getLogger("mcp_stata.discovery")
+
+
+def _dedupe_preserve(items: List[tuple]) -> List[tuple]:
+    seen = set()
+    unique = []
+    for path, edition in items:
+        if path in seen:
+            continue
+        seen.add(path)
+        unique.append((path, edition))
+    return unique
+
+
+def find_stata_path() -> Tuple[str, str]:
+    """
+    Attempts to automatically locate the Stata installation path.
+    Returns (path_to_executable, edition_string).
+    """
+    system = platform.system()
+
+    # 1. Check Environment Variable
+    if os.environ.get("STATA_PATH"):
+        path = os.environ["STATA_PATH"]
+        edition = "be"
+        lower_path = path.lower()
+        if "mp" in lower_path:
+            edition = "mp"
+        elif "se" in lower_path:
+            edition = "se"
+        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. "
+                "Update STATA_PATH to your Stata binary (e.g., "
+                "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp)."
+            )
+        if not os.access(path, os.X_OK):
+            raise PermissionError(
+                f"STATA_PATH points to '{path}', but it is not executable. "
+                "Ensure this is the Stata binary, not the .app directory."
+            )
+        logger.info("Using STATA_PATH override: %s (%s)", path, edition)
+        return path, edition
+
+    # 2. Platform-specific search
+    candidates = []  # List of (path, edition)
+
+    if system == "Darwin":  # macOS
+        app_globs = [
+            "/Applications/StataNow/StataMP.app",
+            "/Applications/StataNow/StataSE.app",
+            "/Applications/StataNow/Stata.app",
+            "/Applications/Stata/StataMP.app",
+            "/Applications/Stata/StataSE.app",
+            "/Applications/Stata/Stata.app",
+            "/Applications/Stata*/Stata*.app",
+        ]
+
+        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):
+                    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):
+                        candidates.append((full_path, edition))
+
+    elif system == "Windows":
+        base_dirs = [
+            os.environ.get("ProgramFiles", "C:\\Program Files"),
+            os.environ.get("ProgramFiles(x86)", "C:\\Program Files (x86)"),
+        ]
+
+        for base_dir in base_dirs:
+            for stata_dir in glob.glob(os.path.join(base_dir, "Stata*")):
+                for exe, edition in [
+                    ("StataMP-64.exe", "mp"),
+                    ("StataMP.exe", "mp"),
+                    ("StataSE-64.exe", "se"),
+                    ("StataSE.exe", "se"),
+                    ("Stata-64.exe", "be"),
+                    ("Stata.exe", "be"),
+                ]:
+                    full_path = os.path.join(stata_dir, exe)
+                    if os.path.exists(full_path):
+                        candidates.append((full_path, edition))
+
+    elif system == "Linux":
+        for binary, edition in [
+            ("/usr/local/stata/stata-mp", "mp"),
+            ("/usr/local/stata/stata-se", "se"),
+            ("/usr/local/stata/stata", "be"),
+            ("/usr/bin/stata", "be"),
+        ]:
+            if os.path.exists(binary):
+                candidates.append((binary, edition))
+
+    candidates = _dedupe_preserve(candidates)
+
+    for path, edition in candidates:
+        if not os.path.exists(path):
+            logger.warning("Discovered candidate missing on disk: %s", path)
+            continue
+        if not os.access(path, os.X_OK):
+            logger.warning("Discovered candidate is not executable: %s", path)
+            continue
+        logger.info("Auto-discovered Stata at %s (%s)", path, edition)
+        return path, edition
+
+    raise FileNotFoundError(
+        "Could not automatically locate Stata. "
+        "Set STATA_PATH to your Stata executable (e.g., "
+        "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp or C:\\Program Files\\Stata18\\StataMP-64.exe)."
+    )

mcp_stata/models.py

@@ -0,0 +1,57 @@
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel
+
+
+class ErrorEnvelope(BaseModel):
+    message: str
+    rc: Optional[int] = None
+    line: Optional[int] = None
+    command: Optional[str] = None
+    stdout: Optional[str] = None
+    stderr: Optional[str] = None
+    snippet: Optional[str] = None
+    trace: Optional[bool] = None
+
+
+class CommandResponse(BaseModel):
+    command: str
+    rc: int
+    stdout: str
+    stderr: Optional[str] = None
+    success: bool
+    error: Optional[ErrorEnvelope] = None
+
+
+class DataResponse(BaseModel):
+    start: int
+    count: int
+    data: List[Dict[str, Any]]
+
+
+class VariableInfo(BaseModel):
+    name: str
+    label: Optional[str] = None
+    type: Optional[str] = None
+
+
+class VariablesResponse(BaseModel):
+    variables: List[VariableInfo]
+
+
+class GraphInfo(BaseModel):
+    name: str
+    active: bool = False
+
+
+class GraphListResponse(BaseModel):
+    graphs: List[GraphInfo]
+
+
+class GraphExport(BaseModel):
+    name: str
+    image_base64: str
+
+
+class GraphExportResponse(BaseModel):
+    graphs: List[GraphExport]
+

mcp_stata/server.py

@@ -0,0 +1,202 @@
+from mcp.server.fastmcp import FastMCP
+from mcp.server.fastmcp import Image
+import mcp.types as types
+from .stata_client import StataClient
+from .models import (
+    DataResponse,
+    GraphListResponse,
+    VariablesResponse,
+    GraphExportResponse,
+)
+import logging
+import json
+import os
+
+LOG_LEVEL = os.getenv("STATA_MCP_LOGLEVEL", "INFO").upper()
+logging.basicConfig(level=LOG_LEVEL, format="%(asctime)s %(levelname)s %(name)s - %(message)s")
+
+# Initialize FastMCP
+mcp = FastMCP("stata")
+client = StataClient()
+
+@mcp.tool()
+def run_command(code: str, echo: bool = True, as_json: bool = True, trace: bool = False, raw: bool = False) -> str:
+    """
+    Executes a specific Stata command.
+
+    This is the primary tool for interacting with Stata. You can run any valid Stata syntax.
+    
+    Args:
+        code: The detailed Stata command(s) to execute (e.g., "sysuse auto", "regress price mpg", "summarize").
+        echo: If True, the command itself is included in the output. Default is True.
+        as_json: If True, returns a JSON envelope with rc/stdout/stderr/error.
+        trace: If True, enables `set trace on` for deeper error diagnostics (automatically disabled after).
+    """
+    result = client.run_command_structured(code, echo=echo, trace=trace)
+    if raw:
+        if result.success:
+            return result.stdout
+        if result.error:
+            msg = result.error.message
+            if result.error.rc is not None:
+                msg = f"{msg}\nrc={result.error.rc}"
+            return msg
+        return result.stdout
+    if as_json:
+        return result.model_dump_json(indent=2)
+    # Default structured string for compatibility when as_json is False but raw is also False
+    return result.model_dump_json(indent=2)
+
+@mcp.tool()
+def get_data(start: int = 0, count: int = 50) -> str:
+    """
+    Returns a slice of the active dataset as a JSON-formatted list of dictionaries.
+
+    Use this to inspect the actual data values in memory. Useful for checking data quality or content.
+    
+    Args:
+        start: The zero-based index of the first observation to retrieve.
+        count: The number of observations to retrieve. Defaults to 50.
+    """
+    data = client.get_data(start, count)
+    resp = DataResponse(start=start, count=count, data=data)
+    return resp.model_dump_json(indent=2)
+
+@mcp.tool()
+def describe() -> str:
+    """
+    Returns variable descriptions, storage types, and labels (equivalent to Stata's `describe` command).
+
+    Use this to understand the structure of the dataset, variable names, and their formats before running analysis.
+    """
+    return client.run_command("describe")
+
+@mcp.tool()
+def list_graphs() -> str:
+    """
+    Lists the names of all graphs currently stored in Stata's memory.
+
+    Use this to see which graphs are available for export via `export_graph`.
+    """
+    graphs = client.list_graphs_structured()
+    return graphs.model_dump_json(indent=2)
+
+@mcp.tool()
+def export_graph(graph_name: str = None) -> Image:
+    """
+    Exports a stored Stata graph to an image format (PNG) and returns it.
+
+    Args:
+        graph_name: The name of the graph to export (as seen in `list_graphs`). 
+                   If None, exports the currently active graph.
+    """
+    try:
+        path = client.export_graph(graph_name)
+        with open(path, "rb") as f:
+            data = f.read()
+        return Image(data=data, format="png")
+    except Exception as e:
+        # Return error as text if image fails? 
+        # FastMCP expects Image or error.
+        raise RuntimeError(f"Failed to export graph: {e}")
+
+@mcp.tool()
+def get_help(topic: str, plain_text: bool = False) -> str:
+    """
+    Returns the official Stata help text for a given command or topic.
+
+    Args:
+        topic: The command name or help topic (e.g., "regress", "graph", "options").
+               Returns Markdown by default, or plain text when plain_text=True.
+    """
+    return client.get_help(topic, plain_text=plain_text)
+
+@mcp.tool()
+def get_stored_results() -> str:
+    """
+    Returns the current stored results (r-class and e-class scalars/macros) as a JSON-formatted string.
+
+    Use this after running a command (like `summarize` or `regress`) to programmatically retrieve 
+    specific values (e.g., means, coefficients, sample sizes) for validation or further calculation.
+    """
+    import json
+    return json.dumps(client.get_stored_results(), indent=2)
+
+@mcp.tool()
+def load_data(source: str, clear: bool = True, as_json: bool = True, raw: bool = False) -> str:
+    """
+    Loads data using sysuse/webuse/use heuristics based on the source string.
+    Automatically appends , clear unless clear=False.
+    """
+    result = client.load_data(source, clear=clear)
+    if raw:
+        return result.stdout if result.success else (result.error.message if result.error else result.stdout)
+    return result.model_dump_json(indent=2) if as_json else result.model_dump_json(indent=2)
+
+@mcp.tool()
+def codebook(variable: str, as_json: bool = True, trace: bool = False, raw: bool = False) -> str:
+    """
+    Returns codebook/summary for a specific variable.
+    """
+    result = client.codebook(variable, trace=trace)
+    if raw:
+        return result.stdout if result.success else (result.error.message if result.error else result.stdout)
+    return result.model_dump_json(indent=2) if as_json else result.model_dump_json(indent=2)
+
+@mcp.tool()
+def run_do_file(path: str, echo: bool = True, as_json: bool = True, trace: bool = False, raw: bool = False) -> str:
+    """
+    Executes a .do file with optional trace output and JSON envelope.
+    """
+    result = client.run_do_file(path, echo=echo, trace=trace)
+    if raw:
+        return result.stdout if result.success else (result.error.message if result.error else result.stdout)
+    return result.model_dump_json(indent=2) if as_json else result.model_dump_json(indent=2)
+
+@mcp.resource("stata://data/summary")
+def get_summary() -> str:
+    """
+    Returns the output of the `summarize` command for the dataset in memory.
+    Provides descriptive statistics (obs, mean, std. dev, min, max) for all variables.
+    """
+    return client.run_command("summarize")
+
+@mcp.resource("stata://data/metadata")
+def get_metadata() -> str:
+    """
+    Returns the output of the `describe` command.
+    Provides metadata about the dataset, including variable names, storage types, display formats, and labels.
+    """
+    return client.run_command("describe")
+
+@mcp.resource("stata://graphs/list")
+def get_graph_list() -> str:
+    """Returns list of active graphs."""
+    return client.list_graphs_structured().model_dump_json(indent=2)
+
+@mcp.resource("stata://variables/list")
+def get_variable_list() -> str:
+    """Returns JSON list of all variables."""
+    variables = client.list_variables_structured()
+    return variables.model_dump_json(indent=2)
+
+@mcp.resource("stata://results/stored")
+def get_stored_results_resource() -> str:
+    """Returns stored r() and e() results."""
+    import json
+    return json.dumps(client.get_stored_results(), indent=2)
+
+@mcp.tool()
+def export_graphs_all() -> str:
+    """
+    Exports all graphs in memory to base64-encoded PNGs.
+    Returns a JSON envelope listing graph names and images.
+    """
+    exports = client.export_graphs_all()
+    return exports.model_dump_json(indent=2)
+
+def main():
+    mcp.run()
+
+if __name__ == "__main__":
+    main()

mcp_stata/smcl/smcl2html.py

@@ -0,0 +1,80 @@
+"""Convert a SMCL file into Markdown.
+
+Adapted from https://github.com/sergiocorreia/parse-smcl (MIT). Simplified into
+a single module geared toward MCP, emitting Markdown by default.
+"""
+
+import os
+import re
+
+
+def expand_includes(lines, adopath):
+    """Expand INCLUDE directives if ado path is available."""
+    if not adopath:
+        return lines
+    includes = [(i, line[13:].strip()) for (i, line) in enumerate(lines) if line.startswith("INCLUDE help ")]
+    if os.path.exists(adopath):
+        for i, cmd in reversed(includes):
+            fn = os.path.join(adopath, cmd[0], cmd if cmd.endswith(".ihlp") else cmd + ".ihlp")
+            try:
+                with open(fn, "r", encoding="utf-8") as f:
+                    content = f.readlines()
+            except FileNotFoundError:
+                continue
+            if content and content[0].startswith("{* *! version"):
+                content.pop(0)
+            lines[i:i+1] = content
+    return lines
+
+
+def _inline_to_markdown(text: str) -> str:
+    """Convert common inline SMCL directives to Markdown."""
+
+    def repl(match: re.Match) -> str:
+        tag = match.group(1).lower()
+        content = match.group(2) or ""
+        if tag in ("bf", "strong"):
+            return f"**{content}**"
+        if tag in ("it", "em"):
+            return f"*{content}*"
+        if tag in ("cmd", "cmdab", "code", "inp", "input", "res", "err", "txt"):
+            return f"`{content}`"
+        return content
+
+    text = re.sub(r"\{([a-zA-Z0-9_]+):([^}]*)\}", repl, text)
+    text = re.sub(r"\{[^}]*\}", "", text)
+    return text
+
+
+def smcl_to_markdown(smcl_text: str, adopath: str = None, current_file: str = "help") -> str:
+    """Convert SMCL text to lightweight Markdown suitable for LLM consumption."""
+    if not smcl_text:
+        return ""
+
+    lines = smcl_text.splitlines()
+    if lines and lines[0].strip() == "{smcl}":
+        lines = lines[1:]
+
+    lines = expand_includes(lines, adopath)
+
+    title = None
+    body_parts = []
+
+    for raw in lines:
+        line = raw.strip()
+        if not line:
+            continue
+        if line.startswith("{title:"):
+            title = line[len("{title:") :].rstrip("}")
+            continue
+        # Paragraph markers
+        line = line.replace("{p_end}", "")
+        line = re.sub(r"\{p[^}]*\}", "", line)
+        body_parts.append(_inline_to_markdown(line))
+
+    md_parts = [f"# Help for {current_file}"]
+    if title:
+        md_parts.append(f"\n## {title}\n")
+    md_parts.append("\n".join(part for part in body_parts if part).strip())
+
+    return "\n\n".join(part for part in md_parts if part).strip() + "\n"