mcp-stata 1.0.1__py3-none-any.whl

mcp_stata-1.0.1.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: mcp-stata
+Version: 1.0.1
+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
+Project-URL: Issues, https://github.com/tmonk/mcp-stata/issues
+Author-email: Thomas Monk <t.d.monk@lse.ac.uk>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Keywords: ai,econometrics,llm,mcp,stata,statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pystata>=0.0.1
+Requires-Dist: stata-setup>=0.1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.3.0; extra == 'dev'
+Requires-Dist: hatch>=1.16.2; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Stata MCP Server
+
+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.
+
+This server enables LLMs to:
+- **Execute Stata code**: run any Stata command (e.g. `sysuse auto`, `regress price mpg`).
+- **Inspect data**: retrieve dataset summaries and variable codebooks.
+- **Export graphics**: generate and view Stata graphs (histograms, scatterplots).
+- **Verify results**: programmatically check stored results (`r()`, `e()`) for accurate validation.
+
+## Prerequisites
+
+- **Stata 17+** (required for `pystata` integration)
+- **Python 3.11+** (recommended)
+- **uv** (recommended for install/run)
+
+## Installation
+
+### Run as a published tool with `uvx`
+
+```bash
+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).
+
+If auto-discovery fails, set the `STATA_PATH` environment variable to your Stata executable:
+
+```bash
+# macOS example
+export STATA_PATH="/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
+
+# Windows example (cmd.exe)
+set STATA_PATH="C:\Program Files\Stata18\StataMP-64.exe"
+```
+
+## IDE Setup (MCP)
+
+This MCP server uses the **stdio** transport (the IDE launches the process and communicates over stdin/stdout).
+
+---
+
+### Claude Desktop
+
+Open Claude Desktop → **Settings** → **Developer** → **Edit Config**.
+Config file locations include:
+
+* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+#### Published tool (uvx)
+
+```json
+{
+  "mcpServers": {
+    "stata": {
+      "command": "uvx",
+      "args": ["--from", "mcp-stata", "mcp-stata"],
+      "env": {
+        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
+      }
+    }
+  }
+}
+```
+
+After editing, fully quit and restart Claude Desktop to reload MCP servers.
+
+---
+
+### Cursor
+
+Cursor supports MCP config at:
+
+* Global: `~/.cursor/mcp.json`
+* Project: `.cursor/mcp.json`
+
+#### Published tool (uvx)
+
+```json
+{
+  "mcpServers": {
+    "stata": {
+      "command": "uvx",
+      "args": ["--from", "mcp-stata", "mcp-stata"],
+      "env": {
+        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Windsurf
+
+Windsurf supports MCP plugins and also allows manual editing of `mcp_config.json`. After adding/editing a server, use the UI’s refresh so it re-reads the config.
+
+A common location is `~/.codeium/windsurf/mcp_config.json`.
+#### Published tool (uvx)
+
+```json
+{
+  "mcpServers": {
+    "stata": {
+      "command": "uvx",
+      "args": ["--from", "mcp-stata", "mcp-stata"],
+      "env": {
+        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Google Antigravity
+
+In Antigravity, MCP servers are managed from the MCP store/menu; you can open **Manage MCP Servers** and then **View raw config** to edit `mcp_config.json`.
+
+#### Published tool (uvx)
+
+```json
+{
+  "mcpServers": {
+    "stata": {
+      "command": "uvx",
+      "args": ["--from", "mcp-stata", "mcp-stata"],
+      "env": {
+        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Visual Studio Code
+
+VS Code supports MCP servers via a `.vscode/mcp.json` file. The top-level key is **`servers`** (not `mcpServers`).
+
+Create `.vscode/mcp.json`:
+
+#### Published tool (uvx)
+
+```json
+{
+  "servers": {
+    "stata": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--from", "mcp-stata", "mcp-stata"],
+      "env": {
+        "STATA_PATH": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
+      }
+    }
+  }
+}
+```
+
+VS Code documents `.vscode/mcp.json` and the `servers` schema, including `type` and `command`/`args`.
+
+---
+
+## 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`.
+* `load_data(source, clear=True, raw=false)`: Heuristic loader (sysuse/webuse/use/path/URL) with JSON envelope.
+* `get_data(start, count)`: View dataset rows (JSON response, capped to 500 rows).
+* `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_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.
+* `get_help(topic, plain_text=false)`: Returns Markdown-rendered Stata help (default). Use `plain_text=true` for stripped text. Falls back to the Stata online help URL if missing.
+* `get_variable_list()`: JSON list of variables and labels.
+
+## License
+
+This project is licensed under the GNU Affero General Public License v3.0 or later.
+See the LICENSE file for the full text.
+
+## Error reporting
+
+- All tools that execute Stata commands support JSON envelopes (`as_json=true`) carrying:
+  - `rc` (from r()/c(rc)), `stdout`, `stderr`, `message`, optional `line` (when Stata reports it), `command`, and a `snippet` excerpt of error output.
+- Stata-specific cues are preserved:
+  - `r(XXX)` codes are parsed when present in output.
+  - “Red text” is captured via stderr where available.
+  - `trace=true` adds `set trace on` around the command/do-file to surface program-defined errors; the trace is turned off afterward.
+
+## 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.

mcp_stata-1.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+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,,

mcp_stata-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_stata-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-stata = mcp_stata.server:main