aigroup-stata-mcp 1.0.6__tar.gz

aigroup_stata_mcp-1.0.6/.gitignore

@@ -0,0 +1,60 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+dev/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables
+.env
+
+# IDEs
+.idea/
+.vscode/
+
+# OS X
+*.DS_Store
+
+# Config
+config.py
+
+# test
+test/
+tests/
+*.test.*
+
+# Logs
+logs/
+log/
+
+# private
+src_private/
+private/
+privates/
+source/paper
+
+# local file
+*.local.*
+local/
+
+# temp files
+tmp/
+*.tmp
+*.tmp.*
+
+# releases
+releases/
+
+# backup
+backup/
+backup.*
+*.backup
+*.backup.*
+
+# PyPI configuration
+.pypirc

aigroup_stata_mcp-1.0.6/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.

aigroup_stata_mcp-1.0.6/PKG-INFO

@@ -0,0 +1,347 @@
+Metadata-Version: 2.4
+Name: aigroup-stata-mcp
+Version: 1.0.6
+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: numpy>=1.24.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
+Requires-Dist: requests>=2.31.0
+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 的注册商标。