mcp-stata 1.0.1__py3-none-any.whl → 1.2.2__py3-none-any.whl

mcp_stata/discovery.py

@@ -2,6 +2,7 @@ import os
 import platform
 import glob
 import logging
+import shutil
 
 from typing import Tuple, Optional, List
 
@@ -41,7 +42,7 @@ def find_stata_path() -> Tuple[str, str]:
             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)."
+                "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp or /usr/local/stata18/stata-mp)."
             )
         if not os.access(path, os.X_OK):
             raise PermissionError(
@@ -96,14 +97,51 @@ def find_stata_path() -> Tuple[str, str]:
                         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))
+        linux_binaries = [
+            ("stata-mp", "mp"),
+            ("stata-se", "se"),
+            ("stata-ic", "be"),
+            ("stata", "be"),
+            ("xstata-mp", "mp"),
+            ("xstata-se", "se"),
+            ("xstata-ic", "be"),
+            ("xstata", "be"),
+        ]
+
+        # 2a. Try binaries available on PATH first
+        for binary, edition in linux_binaries:
+            found = shutil.which(binary)
+            if found:
+                candidates.append((found, edition))
+
+        # 2b. Search common install prefixes used by Stata's Linux installer
+        linux_roots = [
+            "/usr/local",
+            "/opt",
+            os.path.expanduser("~/stata"),
+            os.path.expanduser("~/Stata"),
+        ]
+
+        for root in linux_roots:
+            patterns: List[str] = []
+            if root.endswith(("stata", "Stata")):
+                patterns.append(root)
+            else:
+                patterns.extend(
+                    [
+                        os.path.join(root, "stata*"),
+                        os.path.join(root, "Stata*"),
+                    ]
+                )
+
+            for pattern in patterns:
+                for base_dir in glob.glob(pattern):
+                    if not os.path.isdir(base_dir):
+                        continue
+                    for binary, edition in linux_binaries:
+                        full_path = os.path.join(base_dir, binary)
+                        if os.path.exists(full_path):
+                            candidates.append((full_path, edition))
 
     candidates = _dedupe_preserve(candidates)
 
@@ -120,5 +158,5 @@ def find_stata_path() -> Tuple[str, str]:
     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)."
+        "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp, /usr/local/stata18/stata-mp, or C:\\Program Files\\Stata18\\StataMP-64.exe)."
     )

mcp_stata/server.py

@@ -1,5 +1,4 @@
 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 (
@@ -76,28 +75,28 @@ 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`.
+    Use this to see which graphs are available for export via `export_graph`. The
+    response marks the active graph so the agent knows which one will export by
+    default.
     """
     graphs = client.list_graphs_structured()
     return graphs.model_dump_json(indent=2)
 
 @mcp.tool()
-def export_graph(graph_name: str = None) -> Image:
+def export_graph(graph_name: str = None, format: str = "pdf") -> str:
     """
-    Exports a stored Stata graph to an image format (PNG) and returns it.
-
+    Exports a stored Stata graph to a file and returns its path.
+    
     Args:
         graph_name: The name of the graph to export (as seen in `list_graphs`). 
                    If None, exports the currently active graph.
+        format: Output format, defaults to "pdf". Supported: "pdf", "png". Use
+                "png" to view the plot directly so the agent can visually check
+                titles, labels, legends, colors, and other user requirements.
     """
     try:
-        path = client.export_graph(graph_name)
-        with open(path, "rb") as f:
-            data = f.read()
-        return Image(data=data, format="png")
+        return client.export_graph(graph_name, format=format)
     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()
@@ -174,12 +173,17 @@ 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")
+@mcp.tool()
 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://variables/list")
+def get_variable_list_resource() -> str:
+    """Resource wrapper for the variable list."""
+    return get_variable_list()
+
 @mcp.resource("stata://results/stored")
 def get_stored_results_resource() -> str:
     """Returns stored r() and e() results."""
@@ -190,7 +194,9 @@ def get_stored_results_resource() -> str:
 def export_graphs_all() -> str:
     """
     Exports all graphs in memory to base64-encoded PNGs.
-    Returns a JSON envelope listing graph names and images.
+    Returns a JSON envelope listing graph names and images so the agent can open
+    them directly and verify visuals (titles/labels/colors/legends) against the
+    user's requested spec without an extra fetch.
     """
     exports = client.export_graphs_all()
     return exports.model_dump_json(indent=2)

mcp_stata/stata_client.py

@@ -321,6 +321,9 @@ class StataClient:
 
     def list_graphs(self) -> List[str]:
         """Returns list of graphs in memory."""
+        if not self._initialized:
+            self.init()
+        
         # 'graph dir' returns list in r(list)
         # We need to ensure we run it quietly so we don't spam.
         self.stata.run("quietly graph dir, memory")
@@ -341,11 +344,17 @@ class StataClient:
         graphs = [GraphInfo(name=n, active=(n == active_name)) for n in names]
         return GraphListResponse(graphs=graphs)
 
-    def export_graph(self, graph_name: str = None, filename: str = None) -> str:
-        """Exports graph to a temp file and returns path."""
+    def export_graph(self, graph_name: str = None, filename: str = None, format: str = "pdf") -> str:
+        """Exports graph to a temp file (pdf or png) and returns the path."""
         import tempfile
+
+        fmt = (format or "pdf").strip().lower()
+        if fmt not in {"pdf", "png"}:
+            raise ValueError(f"Unsupported graph export format: {format}. Allowed: pdf, png.")
+
         if not filename:
-            with tempfile.NamedTemporaryFile(prefix="mcp_stata_", suffix=".png", delete=False) as tmp:
+            suffix = f".{fmt}"
+            with tempfile.NamedTemporaryFile(prefix="mcp_stata_", suffix=suffix, delete=False) as tmp:
                 filename = tmp.name
         else:
             # Ensure fresh start
@@ -357,9 +366,9 @@ class StataClient:
             
         cmd = "graph export"
         if graph_name:
-            cmd += f' "{filename}", name("{graph_name}") replace'
+            cmd += f' "{filename}", name("{graph_name}") replace as({fmt})'
         else:
-            cmd += f' "{filename}", replace'
+            cmd += f' "{filename}", replace as({fmt})'
             
         output = self.run_command(cmd)
         
@@ -386,6 +395,9 @@ class StataClient:
 
     def get_help(self, topic: str, plain_text: bool = False) -> str:
         """Returns help text as Markdown (default) or plain text."""
+        if not self._initialized:
+            self.init()
+        
         # Try to locate the .sthlp help file
         # We use 'capture' to avoid crashing if not found
         self.stata.run(f"capture findfile {topic}.sthlp")
@@ -477,7 +489,7 @@ class StataClient:
         exports: List[GraphExport] = []
         for name in self.list_graphs():
             try:
-                path = self.export_graph(name)
+                path = self.export_graph(name, format="png")
                 with open(path, "rb") as f:
                     b64 = base64.b64encode(f.read()).decode("ascii")
                 exports.append(GraphExport(name=name, image_base64=b64))

{mcp_stata-1.0.1.dist-info → mcp_stata-1.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-stata
-Version: 1.0.1
+Version: 1.2.2
 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
@@ -33,9 +33,12 @@ Description-Content-Type: text/markdown
 
 # Stata MCP Server
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=mcp-stata&config=eyJjb21tYW5kIjoidXZ4IC0tZnJvbSBtY3Atc3RhdGEgbWNwLXN0YXRhIn0%3D)
+
 A [Model Context Protocol](https://github.com/modelcontextprotocol) (MCP) server that connects AI assistants to a local Stata installation.
 
 Built by <a href="https://tdmonk.com">Thomas Monk</a>, London School of Economics.
+<!-- mcp-name: io.github.tmonk/mcp-stata -->
 
 This server enables LLMs to:
 - **Execute Stata code**: run any Stata command (e.g. `sysuse auto`, `regress price mpg`).
@@ -59,8 +62,6 @@ uvx --from mcp-stata mcp-stata
 
 `uvx` is an alias for `uv tool run` and runs the tool in an isolated, cached environment.
 
-> Tip: You can pin a version (example): `uvx --from mcp-stata==0.1.0 mcp-stata`
-
 ## Configuration
 
 This server attempts to automatically discover your Stata installation (supporting standard paths and StataNow).
@@ -75,6 +76,16 @@ export STATA_PATH="/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
 set STATA_PATH="C:\Program Files\Stata18\StataMP-64.exe"
 ```
 
+If you prefer, add `STATA_PATH` to your MCP config's `env` for any IDE shown below. It's optional and only needed when discovery cannot find Stata.
+
+Optional `env` example (add inside your MCP server entry):
+
+```json
+"env": {
+  "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
+}
+```
+
 ## IDE Setup (MCP)
 
 This MCP server uses the **stdio** transport (the IDE launches the process and communicates over stdin/stdout).
@@ -94,12 +105,9 @@ Config file locations include:
 ```json
 {
   "mcpServers": {
-    "stata": {
+    "mcp-stata": {
       "command": "uvx",
-      "args": ["--from", "mcp-stata", "mcp-stata"],
-      "env": {
-        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
-      }
+        "args": ["--from", "mcp-stata", "mcp-stata"]
     }
   }
 }
@@ -121,12 +129,9 @@ Cursor supports MCP config at:
 ```json
 {
   "mcpServers": {
-    "stata": {
+    "mcp-stata": {
       "command": "uvx",
-      "args": ["--from", "mcp-stata", "mcp-stata"],
-      "env": {
-        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
-      }
+        "args": ["--from", "mcp-stata", "mcp-stata"]
     }
   }
 }
@@ -144,12 +149,9 @@ A common location is `~/.codeium/windsurf/mcp_config.json`.
 ```json
 {
   "mcpServers": {
-    "stata": {
+    "mcp-stata": {
       "command": "uvx",
-      "args": ["--from", "mcp-stata", "mcp-stata"],
-      "env": {
-        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
-      }
+        "args": ["--from", "mcp-stata", "mcp-stata"]
     }
   }
 }
@@ -166,12 +168,9 @@ In Antigravity, MCP servers are managed from the MCP store/menu; you can open **
 ```json
 {
   "mcpServers": {
-    "stata": {
+    "mcp-stata": {
       "command": "uvx",
-      "args": ["--from", "mcp-stata", "mcp-stata"],
-      "env": {
-        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
-      }
+        "args": ["--from", "mcp-stata", "mcp-stata"]
     }
   }
 }
@@ -190,13 +189,10 @@ Create `.vscode/mcp.json`:
 ```json
 {
   "servers": {
-    "stata": {
+    "mcp-stata": {
       "type": "stdio",
       "command": "uvx",
       "args": ["--from", "mcp-stata", "mcp-stata"],
-      "env": {
-        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
-      }
     }
   }
 }
@@ -206,6 +202,10 @@ VS Code documents `.vscode/mcp.json` and the `servers` schema, including `type`
 
 ---
 
+## Skills
+
+- Skill file (for Claude/Codex): [skill/SKILL.md](skill/SKILL.md)
+
 ## Tools Available
 
 * `run_command(code, raw=false)`: Execute Stata syntax. Returns a structured JSON envelope by default; set `raw=true` for plain stdout/stderr. `trace=true` temporarily enables `set trace on`.
@@ -214,7 +214,7 @@ VS Code documents `.vscode/mcp.json` and the `servers` schema, including `type`
 * `describe()`: View dataset structure.
 * `codebook(variable, raw=false)`: Variable-level metadata (JSON envelope by default).
 * `run_do_file(path, trace=false, raw=false)`: Execute a .do file with rich error capture (JSON by default).
-* `export_graph(name)`: Export a graph as an image.
+* `export_graph(name, format="pdf")`: Export a graph to a file path (default PDF; use `format="png"` for PNG).
 * `export_graphs_all()`: Export all in-memory graphs as base64-encoded PNGs (JSON response).
 * `list_graphs()`: See available graphs in memory (JSON list with an `active` flag).
 * `get_stored_results()`: Get `r()` and `e()` scalars/macros.
@@ -237,4 +237,4 @@ See the LICENSE file for the full text.
 
 ## Logging
 
-Set `STATA_MCP_LOGLEVEL` (e.g., `DEBUG`, `INFO`) to control server logging. Logs include discovery details (edition/path) and command-init traces for easier troubleshooting.
+Set `STATA_MCP_LOGLEVEL` (e.g., `DEBUG`, `INFO`) to control server logging. Logs include discovery details (edition/path) and command-init traces for easier troubleshooting.

mcp_stata-1.2.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+mcp_stata/__init__.py,sha256=kJKKRn7lGuVCuS2-GaN5VoVcvnxtNlfuswW_VOlYqwg,98
+mcp_stata/discovery.py,sha256=KVNgLzmsZfkQ41k0UDZjNfwfz8yRwJs7iZR9NMu0qCE,5791
+mcp_stata/models.py,sha256=mVRvZYZMeXf1o5MLcD0bSwd0xO16ldEWaY6qXsJehRc,1078
+mcp_stata/server.py,sha256=KxxuFeVfYbIH5aRmCgYFA_wQwVw-Q1JMD5vC3e7vzAU,7804
+mcp_stata/stata_client.py,sha256=GQi5t3L9jX6xSocaOqIWo0Lp3ORaqRMDYQHfITjNXYM,20474
+mcp_stata/smcl/smcl2html.py,sha256=wi91mOMeV9MCmHtNr0toihNbaiDCNZ_NP6a6xEAzWLM,2624
+mcp_stata-1.2.2.dist-info/METADATA,sha256=DH7y6cqEDJr-blD62LE0p4rudhmzaBkiSuHwtO2uagA,7840
+mcp_stata-1.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcp_stata-1.2.2.dist-info/entry_points.txt,sha256=TcOgrtiTL4LGFEDb1pCrQWA-fUZvIujDOvQ-bWFh5Z8,52
+mcp_stata-1.2.2.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+mcp_stata-1.2.2.dist-info/RECORD,,

mcp_stata-1.0.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-mcp_stata/__init__.py,sha256=kJKKRn7lGuVCuS2-GaN5VoVcvnxtNlfuswW_VOlYqwg,98
-mcp_stata/discovery.py,sha256=_tkZJyvYQujR4sEbbnKCWbs2l-gIfO6TZcdI6Xbdk94,4482
-mcp_stata/models.py,sha256=mVRvZYZMeXf1o5MLcD0bSwd0xO16ldEWaY6qXsJehRc,1078
-mcp_stata/server.py,sha256=uj6n8Uyo5L6_AUnYlKo3PS7bFwMYkQpg7Y0VefRmZuc,7392
-mcp_stata/stata_client.py,sha256=4UmMa74HDKxDC9Y0viFyZrEXsUntBLWqOA3nU4jNvnM,20054
-mcp_stata/smcl/smcl2html.py,sha256=wi91mOMeV9MCmHtNr0toihNbaiDCNZ_NP6a6xEAzWLM,2624
-mcp_stata-1.0.1.dist-info/METADATA,sha256=tEWUYreccqVPe8YW2vfYi3lzr3jfLs3S7AilYFJFqfs,7736
-mcp_stata-1.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mcp_stata-1.0.1.dist-info/entry_points.txt,sha256=TcOgrtiTL4LGFEDb1pCrQWA-fUZvIujDOvQ-bWFh5Z8,52
-mcp_stata-1.0.1.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-mcp_stata-1.0.1.dist-info/RECORD,,