aigroup-stata-mcp 1.0.3__py3-none-any.whl

aigroup_stata_mcp-1.0.3.dist-info/METADATA

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: aigroup-stata-mcp
+Version: 1.0.3
+Summary: A Stata integration server based on Model Context Protocol (MCP) that allows AI assistants to execute Stata scripts, fetch data information, and run statistical analysis.
+Author-email: jackdark425 <jackdark425@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,data-analysis,mcp,model-context-protocol,stata,statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.21.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.3.0
+Requires-Dist: pathvalidate>=3.3.1
+Requires-Dist: pexpect>=4.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.1.1
+Description-Content-Type: text/markdown
+
+# aigroup-stata-mcp
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blueviolet)](https://spec.modelcontextprotocol.io/)
+[![PyPI version](https://img.shields.io/pypi/v/aigroup-stata-mcp.svg)](https://pypi.org/project/aigroup-stata-mcp/)
+
+一个基于 Model Context Protocol (MCP) 的 Stata 集成服务器，允许 AI 助手执行 Stata 脚本、获取数据信息和运行统计分析。
+
+## 功能特性
+
+### 🚀 核心功能
+- **Stata 脚本执行**: 执行 `.do` 文件并捕获日志输出
+- **数据信息获取**: 支持 `.dta` 和 `.csv` 文件的描述性统计
+- **Stata 命令帮助**: 获取 Stata 内置命令的帮助文档
+- **SSC 包管理**: 从 SSC 仓库安装和管理 Stata 包
+- **文件操作**: 创建、读取和写入 Stata 脚本文件
+
+### 🔧 技术特性
+- **跨平台支持**: Windows、macOS 和 Linux
+- **自动 Stata 检测**: 自动查找系统上的 Stata 安装路径
+- **多传输协议**: 支持 stdio、SSE、HTTP 和 streamable-http
+- **结构化输出**: 使用 Pydantic 模型提供类型安全的响应
+- **多语言支持**: 中英文界面和提示
+
+### 📊 数据处理
+- **数据格式支持**: Stata (.dta)、CSV (.csv) 文件
+- **统计分析**: 描述性统计、变量分析
+- **URL 数据源**: 支持从 URL 直接读取数据文件
+- **智能编码检测**: 自动检测文件编码和分隔符
+
+## 快速开始
+
+### 系统要求
+
+- **Python**: 3.11 或更高版本
+- **Stata**: 已安装并配置好环境变量
+- **MCP 客户端**: Claude Desktop、Cherry Studio 或其他兼容 MCP 的客户端
+
+### 安装
+
+```bash
+# 使用 pip 安装
+pip install aigroup-stata-mcp
+
+# 或使用 uv 安装
+uv add aigroup-stata-mcp
+
+# 或使用 uvx 直接运行（无需安装）
+uvx aigroup-stata-mcp
+```
+
+### 配置
+
+#### Claude Desktop 配置
+
+在 Claude Desktop 配置文件中添加以下内容：
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "stata-mcp": {
+      "command": "uvx",
+      "args": ["aigroup-stata-mcp"],
+      "env": {
+        "STATA_CLI": "/path/to/your/stata/executable"
+      }
+    }
+  }
+}
+```
+
+#### 使用安装器
+
+项目提供了自动安装工具：
+
+```bash
+# 检查系统兼容性
+stata-mcp --usable
+
+# 自动安装到 Claude Desktop
+stata-mcp --install
+```
+
+## 可用工具
+
+### Stata 工具
+
+#### `stata_do`
+执行 Stata do 文件并返回执行结果。
+
+**参数:**
+- `dofile_path`: do 文件路径
+- `log_file_name`: 日志文件名（可选）
+- `is_read_log`: 是否读取日志内容（默认: true）
+
+**示例:**
+```stata
+regress price mpg weight
+outreg2 using "results", replace
+```
+
+#### `get_data_info`
+获取数据文件的描述性统计信息。
+
+**参数:**
+- `data_path`: 数据文件路径
+- `vars_list`: 变量列表（可选）
+- `encoding`: 文件编码（默认: utf-8）
+- `file_extension`: 文件扩展名（可选）
+- `is_save`: 是否保存结果到文件（默认: true）
+
+**支持格式:**
+- Stata 文件 (.dta)
+- CSV 文件 (.csv, .txt, .tsv)
+
+#### `help`
+获取 Stata 命令的帮助文档。
+
+**参数:**
+- `cmd`: Stata 命令名称
+
+**示例:**
+```stata
+help regress
+help summarize
+```
+
+#### `ssc_install`
+从 SSC 仓库安装 Stata 包。
+
+**参数:**
+- `command`: 包名称
+- `is_replace`: 是否替换已安装版本（默认: true）
+
+### 文件工具
+
+#### `write_dofile`
+创建新的 Stata do 文件。
+
+**参数:**
+- `content`: Stata 代码内容
+- `encoding`: 文件编码（默认: utf-8）
+
+#### `append_dofile`
+向现有 do 文件追加内容或创建新文件。
+
+**参数:**
+- `original_dofile_path`: 原始 do 文件路径
+- `content`: 要追加的 Stata 代码
+- `encoding`: 文件编码（默认: utf-8）
+
+#### `read_file`
+读取文件内容。
+
+**参数:**
+- `file_path`: 文件路径
+- `encoding`: 文件编码（默认: utf-8）
+
+#### `load_figure`
+加载图片文件。
+
+**参数:**
+- `figure_path`: 图片文件路径（支持 png、jpg 格式）
+
+### 核心工具
+
+#### `mk_dir`
+安全创建目录。
+
+**参数:**
+- `path`: 目录路径
+
+## 可用提示
+
+### `stata_assistant_role`
+获取 Stata 助手角色定义提示。
+
+**参数:**
+- `lang`: 语言代码（en/cn，可选）
+
+### `stata_analysis_strategy`
+获取 Stata 分析策略指南。
+
+**参数:**
+- `lang`: 语言代码（en/cn，可选）
+
+### `results_doc_path`
+生成结果文档存储路径。
+
+## 项目结构
+
+```
+stata_mcp/
+├── core/                    # 核心功能模块
+│   ├── data_info/          # 数据信息处理
+│   │   ├── _base.py        # 数据信息基类
+│   │   ├── dta.py          # Stata 文件处理
+│   │   └── csv.py          # CSV 文件处理
+│   └── stata/              # Stata 集成
+│       ├── stata_controller/ # Stata 会话控制
+│       ├── stata_do/       # do 文件执行器
+│       └── stata_finder/   # Stata 路径查找器
+├── server/                 # MCP 服务器实现
+│   ├── tools/              # MCP 工具定义
+│   │   ├── core_tools.py   # 核心工具
+│   │   ├── file_tools.py   # 文件工具
+│   │   └── stata_tools.py  # Stata 工具
+│   ├── prompts/            # MCP 提示定义
+│   └── main.py             # 服务器主程序
+├── utils/                  # 工具类
+│   ├── Installer/          # 安装器
+│   ├── Prompt/             # 提示管理
+│   └── usable.py           # 系统兼容性检查
+└── cli/                    # 命令行接口
+```
+
+## 开发指南
+
+### 环境设置
+
+1. 克隆仓库：
+```bash
+git clone https://github.com/jackdark425/aigroup-stata-mcp.git
+cd aigroup-stata-mcp
+```
+
+2. 安装开发依赖：
+```bash
+pip install -e ".[dev]"
+```
+
+3. 运行测试：
+```bash
+python -m pytest
+```
+
+### 添加新工具
+
+在 `src/stata_mcp/server/tools/` 目录下创建新的工具文件：
+
+```python
+from mcp.server.fastmcp import Context, FastMCP
+from pydantic import BaseModel, Field
+
+class MyToolResult(BaseModel):
+    result: str = Field(description="Tool execution result")
+
+def register_my_tools(server: FastMCP) -> None:
+    @server.tool()
+    def my_tool(ctx: Context, param: str) -> MyToolResult:
+        """Tool description."""
+        # Tool implementation
+        return MyToolResult(result="Success")
+```
+
+然后在 `src/stata_mcp/server/main.py` 中注册新工具。
+
+## 故障排除
+
+### 常见问题
+
+1. **Stata 未找到**
+   - 确保 Stata 已正确安装
+   - 手动设置 `STATA_CLI` 环境变量
+   - 使用 `stata-mcp --usable` 检查配置
+
+2. **权限错误**
+   - 确保对工作目录有读写权限
+   - 检查防火墙设置
+
+3. **编码问题**
+   - 指定正确的文件编码
+   - 使用 UTF-8 编码处理中文数据
+
+### 调试模式
+
+启用详细日志输出：
+
+```bash
+stata-mcp --verbose
+```
+
+## 贡献指南
+
+我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。
+
+1. Fork 项目
+2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 打开 Pull Request
+
+## 许可证
+
+本项目基于 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详细信息。
+
+## 致谢
+
+- [Model Context Protocol](https://spec.modelcontextprotocol.io/) - 提供协议规范
+- [Stata](https://www.stata.com/) - 统计分析软件
+- [FastMCP](https://github.com/modelcontextprotocol/python-sdk) - Python MCP SDK
+
+## 支持
+
+如果您遇到问题或有建议，请：
+
+1. 查看 [问题页面](https://github.com/jackdark425/aigroup-stata-mcp/issues)
+2. 创建新的 issue
+3. 联系维护者: jackdark425@gmail.com
+
+---
+
+**注意**: 本项目与 StataCorp LLC 无关，Stata 是 StataCorp LLC 的注册商标。

aigroup_stata_mcp-1.0.3.dist-info/RECORD

@@ -0,0 +1,38 @@
+stata_mcp/__init__.py,sha256=UlHcx94B_pFLtMKtnvWlqI6JMRJ_ETJG_AE4-0dUDAM,457
+stata_mcp/cli/__init__.py,sha256=U4LOJljU47SzkjOSxKUiaDNMGCW3HOgh6ZhxX1CKTnA,123
+stata_mcp/cli/_cli.py,sha256=W5h2eUt-Vt09GSnyvhl7tkvuGhYO6nI9ZZHHeDbsZCQ,2744
+stata_mcp/core/__init__.py,sha256=fTtW3jXgKbh2A9bsZIuzsOvCnKmhms8C9yRG11K6gQg,112
+stata_mcp/core/data_info/__init__.py,sha256=-tmDrCPzlpQYB_3SE4kMpdQJCj92wYCvIqIgEH7aAEc,167
+stata_mcp/core/data_info/_base.py,sha256=728AEtqnzKdb2cmc39i3B4ydvQIqg2lPihk1xNhTSC8,9271
+stata_mcp/core/data_info/csv.py,sha256=ReSiYzw6M52mrjk8TYqsTQGqc3CR64fErOSDuYSUVgo,4680
+stata_mcp/core/data_info/dta.py,sha256=xMw_bW1cZGpL84GBh0fPmtgDLbuLI7PcHVOYpfgS1dQ,2381
+stata_mcp/core/stata/__init__.py,sha256=QCPzqyFc6yxJDZ6b5SEhWyC3ULpBZkjJ3opOlJMfoHE,243
+stata_mcp/core/stata/stata_controller/__init__.py,sha256=t3EQvpziZUkmZAINKU6Zqkd1kfkvWz5qtvpDq-I6lnY,132
+stata_mcp/core/stata/stata_controller/controller.py,sha256=wZZVDerCiWqE16FniFn63XnxanEyH76eW1vW94Xb1pE,6881
+stata_mcp/core/stata/stata_do/__init__.py,sha256=v4ufdO-4nYpAS0qfElq8-Dq9bTUKHM6ZmsdCXKla-8I,107
+stata_mcp/core/stata/stata_do/do.py,sha256=S7XYYXQQhzGweEq1IfK38qZJrpjNy3al9pVoFQE2xDA,6315
+stata_mcp/core/stata/stata_finder/__init__.py,sha256=AUWPgZjiVDoFFmYaS7nVyeyN0lTTGQWBzd3MFD7j5bs,120
+stata_mcp/core/stata/stata_finder/base.py,sha256=ro5KZHrhVi14UqcF1OZ0EJTmgnQb-VhNR8Xi7L1CNKU,9889
+stata_mcp/core/stata/stata_finder/finder.py,sha256=EoPwgO553NCosUTekC6c75ASHsMgabqBMKUEi9S1Uy8,6311
+stata_mcp/core/stata/stata_finder/linux.py,sha256=4-OLymLoxfk1uOuopZstKNNJhxI0IZXqjZ1rFv334F8,1260
+stata_mcp/core/stata/stata_finder/macos.py,sha256=HQJ0EyjOxpUvLFEb6u9V8qh4sCfu_vKNEpn4dTI2h9A,3397
+stata_mcp/core/stata/stata_finder/windows.py,sha256=GZuWS5ZGQuRuzy-lE00ho_vMeZUIOx69P56GQ2PPQKE,6823
+stata_mcp/server/__init__.py,sha256=0eBdEYx1VwIxKWb1vMyXOwPRM24Vdtk7u4-g4RL4YDU,156
+stata_mcp/server/main.py,sha256=RgpZRh6MVkvBNBzKhPyDXLUGpXRi_y4H9HrwumEGeAY,4976
+stata_mcp/server/prompts/__init__.py,sha256=LZ-_iNpYQlAHTWtFJsQjRibiKOEK1_j3SgCn8aoazQA,169
+stata_mcp/server/prompts/core_prompts.py,sha256=9w6-mzFUh-jFGWxqzuRglGnjxlBPpoU7HxBv06Ww_ow,4978
+stata_mcp/server/tools/__init__.py,sha256=pUifpy73eDW3f90JcKjhrrTPTwAQc5AsKw0-bOW0f1Y,300
+stata_mcp/server/tools/core_tools.py,sha256=Q3nRH8jI6TUdQsa1tq9NZR_1NOkx8xuVHnq1e3zMXLc,2071
+stata_mcp/server/tools/file_tools.py,sha256=3xZQ7NkSSrDowRqIHhe3gWK6MYHDM0Bu6G-o-tgE3Bo,6427
+stata_mcp/server/tools/stata_tools.py,sha256=o3yjyMQ7mEWlTQvLAWaPd7xsNBKAhrMZ2bjFV56YEow,8283
+stata_mcp/utils/__init__.py,sha256=bJ6wXXLvVWGILsguhrKWLUq2PxYhcsHG5KQ0EI41gbs,486
+stata_mcp/utils/usable.py,sha256=p90bQ1_sdO4Bq6BY9Ah6Ka2NwRV89FG42UJos-5cKJQ,8025
+stata_mcp/utils/Installer/__init__.py,sha256=yBza9nOoSTR2-Lk9eSCzmiok1DS-duacRcjv0Fgfl_k,110
+stata_mcp/utils/Installer/installer.py,sha256=jRqxEATp9E09BMz1SxFwpNuDH7gNF5HKf3wREkE_Fys,3041
+stata_mcp/utils/Prompt/__init__.py,sha256=7bgikghCBr-rLOjie48We766nRBH4Yuzl9ARZpbd8HY,2047
+stata_mcp/utils/Prompt/string.py,sha256=wSyDZbZkK28TLz7qUunFzOr0OzjCoEPcCTOWYybysLM,4768
+aigroup_stata_mcp-1.0.3.dist-info/METADATA,sha256=jYkCDW1tbxi5G1yRQAXrcpyqLzOU8z2AC-fn-H8BOKA,9287
+aigroup_stata_mcp-1.0.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+aigroup_stata_mcp-1.0.3.dist-info/entry_points.txt,sha256=9Tts_0fSVdmoWZlH_EBPw3vKrvvPKt6Ngjccoo6BxTE,139
+aigroup_stata_mcp-1.0.3.dist-info/licenses/LICENSE,sha256=JFoUmc-vAC0k4-jjI6qyO8x7a7w1ddlitHdaOHVp9Lo,1092
+aigroup_stata_mcp-1.0.3.dist-info/RECORD,,

aigroup_stata_mcp-1.0.3.dist-info/WHEEL

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

aigroup_stata_mcp-1.0.3.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+aigroup-stata-mcp = src.stata_mcp.cli._cli:main
+
+[mcp.server]
+aigroup-stata-mcp = src.stata_mcp.server.main:stata_server

aigroup_stata_mcp-1.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sepine Tam, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stata_mcp/__init__.py

@@ -0,0 +1,18 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("aigroup-stata-mcp")
+except PackageNotFoundError:
+    # Fallback for development mode when package is not installed
+    __version__ = "1.0.3"
+
+__author__ = "jackdark425 <jackdark425@gmail.com>"
+__team__ = "aigroup"
+
+
+if __name__ == "__main__":
+    print(f"Hello aigroup-stata-mcp@version{__version__}")

stata_mcp/cli/__init__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+from ._cli import main as main
+
+if __name__ == "__main__":
+    main()

stata_mcp/cli/_cli.py

@@ -0,0 +1,95 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+import argparse
+import os
+import sys
+from importlib.metadata import version, PackageNotFoundError
+from typing import Optional
+
+
+def get_version() -> str:
+    """Get the package version, handling cases where package is not installed."""
+    try:
+        return version("aigroup-stata-mcp")
+    except PackageNotFoundError:
+        # Fallback for development mode
+        try:
+            # Try to read from pyproject.toml
+            import tomllib
+            with open("pyproject.toml", "rb") as f:
+                data = tomllib.load(f)
+                return data.get("project", {}).get("version", "1.0.0-dev")
+        except (FileNotFoundError, ImportError):
+            return "1.0.0-dev"
+
+
+def main() -> None:
+    """Entry point for the command line interface."""
+    parser = argparse.ArgumentParser(
+        prog="aigroup-stata-mcp",
+        description="Stata-MCP command line interface",
+        add_help=True)
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"Stata-MCP version is {get_version()}",
+        help="show version information",
+    )
+    parser.add_argument(
+        "-c", "--client",
+        nargs="?",
+        const="cc",
+        help="set the client mode (default for Claude Code)"
+    )
+    parser.add_argument(
+        "--usable",
+        action="store_true",
+        help="check whether Stata-MCP could be used on this computer",
+    )
+    parser.add_argument(
+        "--install",
+        action="store_true",
+        help="install Stata-MCP to Claude Desktop")
+
+    # mcp.run
+    parser.add_argument(
+        "-t",
+        "--transport",
+        choices=["stdio", "sse", "http", "streamable-http"],
+        default=None,
+        help="mcp server transport method (default: stdio)",
+    )
+    args = parser.parse_args()
+
+    if args.usable:
+        from stata_mcp.utils.usable import usable
+        sys.exit(usable())
+
+    elif args.install:
+        from stata_mcp.utils.Installer import Installer
+        Installer(sys_os=sys.platform).install()
+
+    elif args.client:
+        os.environ["STATA-MCP-CLIENT"] = "cc"
+        from stata_mcp.server import run_server
+        run_server()
+
+    else:
+        from stata_mcp.server import run_server
+
+        print("Starting Stata-MCP...")
+
+        # Use stdio if there is no transport argument
+        transport = args.transport or "stdio"
+        if transport == "http":
+            transport = (
+                "streamable-http"  # Default to streamable-http for HTTP transport
+            )
+        run_server(transport=transport)
+
+
+if __name__ == "__main__":
+    main()

stata_mcp/core/__init__.py

@@ -0,0 +1,14 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+#
+
+#
+
+
+
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+

stata_mcp/core/data_info/__init__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+from .csv import CsvDataInfo
+from .dta import DtaDataInfo
+
+__all__ = [
+    "CsvDataInfo",
+    "DtaDataInfo",
+]