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

stata_mcp/utils/Prompt/__init__.py

@@ -0,0 +1,74 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+from .string import frame
+
+
+class Prompt:
+   
+   
+   
+    def __init__(self):
+        """简要描述函数功能"""
+        self.prompts = {}
+        self.lang = "en"
+
+    def set_lang(self, lang):
+        """简要描述函数功能"""
+        self.lang = lang
+
+    def add_prompt(self, prompt_id: str, lang: str, prompt: str):
+        """简要描述函数功能"""
+        if prompt_id not in self.prompts:
+            self.prompts[prompt_id] = {}
+        self.prompts[prompt_id][lang] = prompt
+
+    def get_prompt(self, prompt_id: str, lang: str = None):
+        """简要描述函数功能"""
+        if lang is None:
+            lang = self.lang
+
+        if prompt_id not in self.prompts:
+            return ""
+
+        if lang not in self.prompts[prompt_id]:
+            lang = "en"
+            if lang not in self.prompts[prompt_id]:
+                return ""
+        return self.prompts[prompt_id][lang]
+
+    @staticmethod
+    def extract(var_name: str):
+        """简要描述函数功能"""
+        name_list = var_name.split("_")
+        lang = name_list[-1]
+        prompt_id = "_".join(name_list[:-1])
+        return prompt_id, lang
+
+    def auto_extract(self, prompts_dict: dict):
+        """简要描述函数功能"""
+        for key, prompt in prompts_dict.items():
+            prompt_id, lang = Prompt.extract(key)
+            self.add_prompt(prompt_id=prompt_id, lang=lang, prompt=prompt)
+
+
+def filter_system_vars(dictionary):
+    """简要描述函数功能"""
+    exclude_prefixes = ["__"]
+    exclude_vars = ["inspect", "frame"]
+
+    filtered_dict = {}
+    for key, value in dictionary.items():
+        if (
+            not any(key.startswith(prefix) for prefix in exclude_prefixes)
+            and key not in exclude_vars
+        ):
+            filtered_dict[key] = value
+    return filtered_dict
+
+
+prompts_dict: dict = filter_system_vars(frame.f_locals)
+
+pmp = Prompt()
+pmp.auto_extract(prompts_dict)

stata_mcp/utils/Prompt/string.py

@@ -0,0 +1,91 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+import inspect
+
+frame = inspect.currentframe()
+
+stata_assistant_role_en: str = """
+You will play the role of an economics research assistant with strong programming abilities. Stata is a very simple and familiar tool for you.
+
+You should view the user as an economist with strong economic intuition but unfamiliar with Stata operations, making your collaboration the strongest economics research team.
+
+Your task is to generate Stata code based on the user's instructions, adding comments before each line of code, and then run this dofile.
+The user will provide you with a data path and their research story or regression model.
+What you need to do is understand the data structure based on the data path, and then write Stata regression code according to the user's model.
+
+Your output should tell the user how the results look, whether they meet the user's expectations, and inform them of the locations of the dofile and log file.
+"""
+
+stata_assistant_role_cn: str = """
+你将扮演一个经济学的研究助理，你有很强的编程能力，Stata在你这里是一个非常简单非常家常的工具。
+
+你应该把用户视为一个经济直觉很强但是不熟悉Stata操作的经济学家，因此你们合作就是最强的经济学研究组合。
+
+你的任务是根据用户的指令去生成Stata代码，并在每行代码前加上注释，然后运行这个dofile。
+用户会给你一个数据的路径和他的研究故事或者回归模型，
+而你需要做的是根据数据路径去了解数据结构，然后根据用户的模型去写Stata的回归代码。
+
+你的输出应该是告诉用户这个结果如何，是否是符合用户预期的，并把dofile和log文件的位置都告诉用户。
+"""
+
+stata_analysis_strategy_en: str = """
+When conducting data analysis using Stata, please follow these strategies:
+
+1. Data preparation and exploration:
+   - First use get_data_info() to understand the basic characteristics of the dataset, including variable types, missing values, and distributions
+   - Ensure you understand the meaning of each variable and possible encoding methods
+   - Assess whether data cleaning, variable transformation, or missing value handling is needed
+
+2. Code generation and execution workflow:
+   - Break down the analysis into multiple logical steps, each with a clear objective
+   - Use write_dofile() to create the initial do file
+   - For complex analyses, first run the basic steps, then use append_dofile() to add more analyses
+   - Execute with stata_do() and check results after each modification
+
+3. Results management:
+   - Use results_doc_path() to get a unified storage path for results before generating tables or outputs
+   - Save this path in the do file using the local output_path command
+   - Use commands like outreg2 or esttab to output results to the specified path
+
+4. Reporting results:
+   - After executing the do file, use read_log() to view execution results and possible errors
+   - Analyze and interpret important statistical results
+   - Provide context and explanation of the meaning of results
+
+5. Handling common issues:
+   - If syntax errors occur, first check if variable names are correct
+   - Check if the dataset has been properly loaded
+   - For large datasets, consider using a subsample for preliminary analysis
+"""
+
+stata_analysis_strategy_cn: str = """
+使用Stata进行数据分析时，请遵循以下策略：
+
+1. 数据准备和探索：
+   - 首先使用get_data_info()了解数据集的基本情况，包括变量类型、缺失值和分布
+   - 确保理解每个变量的意义和可能的编码方式
+   - 评估是否需要数据清洗、变量转换或缺失值处理
+
+2. 代码生成和执行流程：
+   - 将分析分解为多个逻辑步骤，每个步骤都有明确的目标
+   - 使用write_dofile()创建初始do文件
+   - 对于复杂分析，先运行基础步骤，然后使用append_dofile()添加更多分析
+   - 每次修改后使用stata_do()执行并检查结果
+
+3. 结果管理：
+   - 在生成表格或输出结果前使用results_doc_path()获取统一的结果存储路径
+   - 在do文件中使用local output_path命令保存此路径
+   - 使用outreg2或esttab等命令将结果输出到指定路径
+
+4. 报告结果：
+   - 执行do文件后使用read_log()查看执行结果和可能的错误
+   - 分析并解释重要的统计结果
+   - 提供结果的上下文和含义解释
+
+5. 常见问题处理：
+   - 如果出现语法错误，先检查变量名称是否正确
+   - 检查数据集是否已正确加载
+   - 针对大型数据集，考虑使用子样本进行初步分析
+"""

stata_mcp/utils/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+import platform
+from datetime import datetime
+
+
+def set_config(key, value):
+    """简要描述函数功能"""
+    with open(".env", "w+", encoding="utf-8") as f:
+        f.write(f"{key}={value}")
+    return {key: value}
+
+
+def get_nowtime():
+    """简要描述函数功能"""
+    return datetime.strftime(datetime.now(), "%Y%m%d%H%M%S")
+
+
+def get_os():
+    """简要描述函数功能"""
+    return platform.system()

stata_mcp/utils/usable.py

@@ -0,0 +1,244 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+"""
+Stata MCP Configuration Check Script
+This script automatically checks if your Stata MCP configuration is correct
+"""
+
+import os
+import platform
+import subprocess
+import sys
+import time
+from typing import Dict, Tuple
+
+from ..core.stata import StataFinder
+
+
+def print_status(message: str, status: bool) -> None:
+    """Print a message with status indicator"""
+    status_str = "✅ PASSED" if status else "❌ FAILED"
+    print(f"{message}: {status_str}")
+
+
+def check_os() -> Tuple[str, bool]:
+    """Check current operating system"""
+    os_name = platform.system()
+    os_mapping = {"Darwin": "macOS", "Windows": "Windows", "Linux": "Linux"}
+    detected_os = os_mapping.get(os_name, "unknown")
+    is_supported = detected_os in [
+        "macOS",
+        "Windows",
+        "Linux",
+    ]  # All three are now supported
+
+    return detected_os, is_supported
+
+
+def check_python_version() -> Tuple[str, bool]:
+    """Check if the Python version is compatible"""
+    current_version = (
+        f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    )
+    is_compatible = sys.version_info.major == 3 and sys.version_info.minor >= 11
+
+    return current_version, is_compatible
+
+
+def test_stata_execution(stata_cli_path: str) -> bool:
+    """Test if Stata can be executed"""
+    if not stata_cli_path or not os.path.exists(stata_cli_path):
+        return False
+
+    sys_os = platform.system()
+
+    try:
+        if sys_os == "Darwin" or sys_os == "Linux":  # macOS or Linux
+            proc = subprocess.Popen(
+                [stata_cli_path],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                shell=True,
+            )
+            # Send a simple command and exit
+            commands = """
+            display "Stata-MCP test successful"
+            exit, STATA
+            """
+            proc.communicate(input=commands, timeout=10)
+            return proc.returncode == 0
+
+        elif sys_os == "Windows":  # Windows
+            # Create a temporary do-file for testing
+            temp_dir = os.path.dirname(os.path.abspath(__file__))
+            temp_do_file = os.path.join(temp_dir, "temp_test.do")
+
+            with open(temp_do_file, "w") as f:
+                f.write('display "Stata-MCP test successful"\nexit, STATA\n')
+
+            # Run Stata with the temp do-file
+            cmd = f'"{stata_cli_path}" /e do "{temp_do_file}"'
+            result = subprocess.run(cmd, shell=True, timeout=10)
+
+            # Clean up
+            if os.path.exists(temp_do_file):
+                os.remove(temp_do_file)
+
+            return result.returncode == 0
+
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError, OSError) as e:
+        print(f"  Error testing Stata: {e}")
+        return False
+
+    return False
+
+
+def check_directories() -> Dict[str, Tuple[str, bool]]:
+    """Check if required directories exist and create them if needed"""
+    home_dir = os.path.expanduser("~")
+    documents_path = os.path.join(home_dir, "Documents")
+
+    # Define directories that should exist
+    base_path = os.path.join(documents_path, "stata-mcp-folder")
+    dirs = {
+        "base_dir": (base_path, False),
+        "log_dir": (os.path.join(base_path, "stata-mcp-log"), False),
+        "dofile_dir": (os.path.join(base_path, "stata-mcp-dofile"), False),
+        "result_dir": (os.path.join(base_path, "stata-mcp-result"), False),
+    }
+
+    # Check and create directories if they don't exist
+    for name, (path, _) in dirs.items():
+        exists = os.path.exists(path)
+        if not exists:
+            try:
+                os.makedirs(path, exist_ok=True)
+                exists = True
+                print(f"  Created directory: {path}")
+            except Exception as e:
+                print(f"  Error creating directory {path}: {e}")
+
+        is_writable = os.access(path, os.W_OK) if exists else False
+        dirs[name] = (path, exists and is_writable)
+
+    return dirs
+
+
+def check_mcp_installation() -> bool:
+    """Check if MCP library is installed"""
+    try:
+        pass
+
+        return True
+    except ImportError:
+        return False
+
+
+def animate_loading(seconds: int) -> None:
+    """Display an animated loading spinner"""
+    chars = "|/-\\"
+    for _ in range(seconds * 5):
+        for char in chars:
+            sys.stdout.write(f"\r  Finding Stata CLI {char} ")
+            sys.stdout.flush()
+            time.sleep(0.05)
+    sys.stdout.write("\r" + " " * 20 + "\r")
+    sys.stdout.flush()
+
+
+def usable():
+    """Main function to check Stata MCP configuration"""
+    print("\n===== Stata MCP Configuration Check =====\n")
+
+    # Check operating system
+    detected_os, os_supported = check_os()
+    print_status(f"Operating system (Current: {detected_os})", os_supported)
+    if not os_supported:
+        print(
+            "  Warning: Your operating system may not be fully supported by Stata-MCP."
+        )
+
+    # Check Python version
+    python_version, python_compatible = check_python_version()
+    print_status(
+        f"Python version (Current: {python_version})",
+        python_compatible)
+    if not python_compatible:
+        print("  Warning: Python 3.11+ is recommended for Stata-MCP.")
+
+    # Check MCP library
+    mcp_installed = check_mcp_installation()
+    print_status("MCP library installation", mcp_installed)
+    if not mcp_installed:
+        print("  Please install MCP library: pip install mcp[cli]")
+
+    # Find Stata CLI
+    print("Locating Stata CLI...")
+    animate_loading(2)  # Show loading animation for 2 seconds
+    stata_cli_path = StataFinder().STATA_CLI
+
+    stata_found = bool(stata_cli_path and os.path.exists(stata_cli_path))
+    print_status(
+        f"Stata CLI (Path: {stata_cli_path or 'Not found'})",
+        stata_found)
+
+    # Test Stata execution if found
+    stata_works = False
+    if stata_found:
+        print("Testing Stata execution...")
+        stata_works = test_stata_execution(stata_cli_path)
+        print_status("Stata execution test", stata_works)
+        if not stata_works:
+            print("  Warning: Stata was found but could not be executed properly.")
+            print(
+                "  You may need to specify the path manually in config.py or as an environment variable."
+            )
+
+    # Check and create necessary directories
+    print("\nChecking required directories...")
+    directories = check_directories()
+    all_dirs_ok = True
+    for name, (path, exists) in directories.items():
+        dir_name = name.replace("_", " ").title()
+        print_status(f"{dir_name} (Path: {path})", exists)
+        if not exists:
+            all_dirs_ok = False
+            print(f"  Warning: Could not create or access {path}")
+
+    # Overall summary
+    print("\n===== Summary =====")
+    all_passed = (
+        os_supported
+        and python_compatible
+        and mcp_installed
+        and stata_found
+        and stata_works
+        and all_dirs_ok
+    )
+
+    if all_passed:
+        print("\n✅ Success! Your Stata-MCP setup is ready to use.")
+        print(
+            "You can now use Stata-MCP with your preferred MCP client (Claude, Cherry Studio, etc.)"
+        )
+    else:
+        print(
+            "\n⚠️ Some checks failed. Please address the issues above to use Stata-MCP."
+        )
+        if not stata_found or not stata_works:
+            print(
+                "\nTo manually specify your Stata path, add this to your MCP configuration:"
+            )
+            print('  "env": {')
+            print('    "stata_cli": "/path/to/your/stata/executable"')
+            print("  }")
+
+    return 0 if all_passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(usable())