aigroup-econ-mcp 0.4.2__py3-none-any.whl → 1.4.3__py3-none-any.whl

resources/MCP_TOOLS_DATA_FORMAT_GUIDE.md

@@ -0,0 +1,185 @@
+# MCP工具数据格式指南
+
+## 概述
+本文档详细说明各个MCP工具的数据输入格式要求，帮助大模型正确调用工具。
+
+## 1. VAR/SVAR模型工具
+
+### 数据格式
+```python
+# 多元时间序列数据格式
+data = [
+    [var1_t1, var2_t1, var3_t1],  # 时间点1的所有变量值
+    [var1_t2, var2_t2, var3_t2],  # 时间点2的所有变量值
+    [var1_t3, var2_t3, var3_t3],  # 时间点3的所有变量值
+    # ...
+]
+
+# 变量名称（可选）
+variables = ["GDP", "Inflation", "Interest"]
+```
+
+### 示例调用
+```python
+{
+  "data": [[1.0, 2.5, 1.8], [1.2, 2.7, 2.0], [1.4, 2.9, 2.2]],
+  "model_type": "var",
+  "lags": 1,
+  "variables": ["GDP", "Inflation", "Interest"],
+  "output_format": "json"
+}
+```
+
+## 2. 联立方程模型工具
+
+### 数据格式说明
+联立方程模型需要三个主要数据组件：
+
+#### 因变量数据 (y_data)
+- **格式**: 二维列表，每个子列表代表一个方程的因变量时间序列
+- **要求**: 所有方程的观测数量必须相同
+
+```python
+# 两个方程的示例
+y_data = [
+    [1.0, 1.2, 1.4, 1.6],  # 方程1的因变量
+    [2.0, 2.2, 2.4, 2.6]   # 方程2的因变量
+]
+```
+
+#### 自变量数据 (x_data)
+- **格式**: 二维列表，每个子列表代表一个观测的所有自变量值
+- **要求**: 观测数量必须与因变量相同
+
+```python
+# 4个观测，每个观测有2个自变量
+x_data = [
+    [1.5, 2.5],  # 观测1的自变量
+    [1.7, 2.7],  # 观测2的自变量
+    [1.9, 2.9],  # 观测3的自变量
+    [2.1, 3.1]   # 观测4的自变量
+]
+```
+
+#### 工具变量数据 (instruments)
+- **格式**: 二维列表，每个子列表代表一个观测的所有工具变量值
+- **要求**: 观测数量必须与其他变量相同
+
+```python
+# 4个观测，每个观测有2个工具变量
+instruments = [
+    [1.8, 2.8],  # 观测1的工具变量
+    [2.0, 3.0],  # 观测2的工具变量
+    [2.2, 3.2],  # 观测3的工具变量
+    [2.4, 3.4]   # 观测4的工具变量
+]
+```
+
+### 示例调用
+```python
+{
+  "y_data": [[1.0, 1.2, 1.4, 1.6], [2.0, 2.2, 2.4, 2.6]],
+  "x_data": [[1.5, 2.5], [1.7, 2.7], [1.9, 2.9], [2.1, 3.1]],
+  "instruments": [[1.8, 2.8], [2.0, 3.0], [2.2, 3.2], [2.4, 3.4]],
+  "equation_names": ["Demand", "Supply"],
+  "instrument_names": ["Income", "Price"],
+  "constant": true,
+  "output_format": "json"
+}
+```
+
+## 3. 动态面板数据模型工具
+
+### 数据格式说明
+动态面板数据需要四个主要数据组件：
+
+#### 因变量数据 (y_data)
+- **格式**: 一维列表，所有个体的因变量时间序列
+
+```python
+y_data = [1.0, 1.2, 1.4, 1.6, 1.8, 2.0, 2.2, 2.4, 2.6, 2.8]
+```
+
+#### 自变量数据 (x_data)
+- **格式**: 二维列表，每个子列表代表一个自变量的时间序列
+- **重要**: 每个自变量的观测数量必须与因变量相同
+
+```python
+# 1个自变量，10个观测
+x_data = [[1.5, 1.7, 1.9, 2.1, 2.3, 2.5, 2.7, 2.9, 3.1, 3.3]]
+
+# 2个自变量，10个观测
+x_data = [
+    [1.5, 1.7, 1.9, 2.1, 2.3, 2.5, 2.7, 2.9, 3.1, 3.3],  # 自变量1
+    [2.5, 2.7, 2.9, 3.1, 3.3, 3.5, 3.7, 3.9, 4.1, 4.3]   # 自变量2
+]
+```
+
+#### 个体标识符 (entity_ids)
+- **格式**: 一维列表，标识每个观测属于哪个个体
+
+```python
+# 2个个体，每个个体5个时间点
+entity_ids = [1, 1, 1, 1, 1, 2, 2, 2, 2, 2]
+```
+
+#### 时间标识符 (time_periods)
+- **格式**: 一维列表，标识每个观测的时间点
+
+```python
+# 10个观测，时间从1到5重复两次
+time_periods = [1, 2, 3, 4, 5, 1, 2, 3, 4, 5]
+```
+
+### 示例调用
+```python
+{
+  "y_data": [1.0, 1.2, 1.4, 1.6, 1.8, 2.0, 2.2, 2.4, 2.6, 2.8],
+  "x_data": [[1.5, 1.7, 1.9, 2.1, 2.3, 2.5, 2.7, 2.9, 3.1, 3.3]],
+  "entity_ids": [1, 1, 1, 1, 1, 2, 2, 2, 2, 2],
+  "time_periods": [1, 2, 3, 4, 5, 1, 2, 3, 4, 5],
+  "model_type": "diff_gmm",
+  "lags": 1,
+  "output_format": "json"
+}
+```
+
+## 4. 数据格式验证要点
+
+### 通用规则
+1. **数据维度一致性**: 所有相关数据的观测数量必须相同
+2. **数据类型**: 必须为数值类型
+3. **数据完整性**: 不能有空值或缺失值
+
+### 联立方程模型特殊要求
+- 因变量数据是二维列表，每个子列表代表一个方程
+- 自变量和工具变量是二维列表，每个子列表代表一个观测
+- 所有数据的观测数量必须严格一致
+
+### 动态面板数据特殊要求
+- 自变量数据是二维列表，每个子列表代表一个自变量的完整时间序列
+- 个体和时间标识符必须与因变量观测数量一致
+- 面板数据必须平衡（每个个体有相同数量的时间点）
+
+## 5. 常见错误及解决方案
+
+### 错误: "自变量的观测数量必须与因变量相同"
+**原因**: 数据维度不匹配
+**解决方案**: 检查所有数据的观测数量是否一致
+
+### 错误: "所有数据序列的长度必须一致"
+**原因**: 动态面板数据中某个自变量的观测数量与因变量不同
+**解决方案**: 确保每个自变量的时间序列长度与因变量相同
+
+### 错误: "输入数据不能为空"
+**原因**: 数据为空或格式错误
+**解决方案**: 提供有效的数据或检查文件路径
+
+## 6. 最佳实践
+
+1. **使用文件输入**: 对于复杂数据，建议使用CSV文件格式
+2. **数据预处理**: 在调用工具前确保数据格式正确
+3. **逐步测试**: 先用小样本数据测试，确认格式正确后再使用完整数据
+4. **检查维度**: 始终验证所有相关数据的观测数量是否一致
+
+通过遵循这些指南，可以确保MCP工具的正确调用和稳定运行。

server.py

@@ -0,0 +1,83 @@
+"""
+AIGroup 计量经济学 MCP 服务器 - 简化修复版
+直接注册工具，避免复杂的包装器
+"""
+
+import sys
+import os
+from typing import List, Optional, Union
+from mcp.server.fastmcp import FastMCP, Context
+from mcp.server.session import ServerSession
+
+# 设置Windows控制台编码
+if sys.platform == "win32":
+    try:
+        # 尝试设置UTF-8编码
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except:
+        # 如果失败，使用ASCII字符
+        pass
+
+# 导入工具注册中心
+from tools.mcp_tools_registry import registry
+
+# 创建 FastMCP 服务器实例
+mcp = FastMCP("aigroup-econ-mcp")
+
+# 自动发现并注册所有工具组
+print("正在自动发现工具组...")
+registry.auto_discover_groups()
+
+# 直接注册所有工具
+print("正在注册工具...")
+for tool_name, tool_info in registry.get_all_tools().items():
+    # 获取原始工具处理器
+    original_handler = tool_info["handler"]
+    
+    # 直接注册工具
+    mcp.tool(name=tool_name, description=tool_info["description"])(original_handler)
+    
+    print(f"  - 已注册: {tool_name}")
+
+@mcp.resource("guide://econometrics")
+def get_econometrics_guide() -> str:
+    """Get complete econometrics tools guide"""
+    try:
+        with open("resources/MCP_MASTER_GUIDE.md", "r", encoding="utf-8") as f:
+            return f.read()
+    except FileNotFoundError:
+        return "完整使用指南文件未找到，请检查 resources/MCP_MASTER_GUIDE.md 文件是否存在。"
+
+
+def main():
+    """Start FastMCP server"""
+    print("=" * 60)
+    print("AIGroup Econometrics MCP Server - SIMPLE FIXED")
+    print("=" * 60)
+    print("\n架构: 简化修复版")
+    print("\n已注册工具组:")
+    
+    # 显示工具组信息
+    for group in registry.tool_groups:
+        tools_in_group = [name for name, info in registry.tools.items() if info["group"] == group.name]
+        print(f"  - {group.name} ({len(tools_in_group)} tools)")
+    
+    print(f"\n总工具数: {len(registry.tools)}")
+    print("\n支持格式:")
+    print("  输入: txt/json/csv/excel (.xlsx, .xls)")
+    print("  输出: json/markdown/txt")
+    
+    print("\n优势:")
+    print("  * 简化工具注册")
+    print("  * 避免包装器问题")
+    print("  * 直接使用原始处理器")
+    
+    print("\n启动服务器...")
+    print("=" * 60)
+    
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

tools/README.md

@@ -0,0 +1,88 @@
+# Tools Directory
+
+## 当前架构 (v2.0 - Adapter Pattern)
+
+### 活跃文件
+
+1. **econometrics_adapter.py** - 核心适配器
+   - 将 econometrics/ 核心算法适配为 MCP 工具
+   - 支持文件输入和多种输出格式
+   - 减少 84% 代码重复
+
+2. **data_loader.py** - 数据加载组件
+   - 支持 txt/json/csv/excel 格式
+   - DataLoader: OLS/GMM 数据
+   - MLEDataLoader: MLE 数据
+
+3. **output_formatter.py** - 输出格式化组件
+   - MarkdownFormatter: Markdown 格式
+   - TextFormatter: 纯文本格式
+   - 结果保存功能
+
+### 架构优势
+
+```
+MCP Server (fastmcp_server.py)
+    ↓
+Adapter Layer (econometrics_adapter.py) - 90 lines
+    ↓
+Core Algorithms (econometrics/basic_parametric_estimation/)
+    ├── ols/ols_model.py - OLS 核心算法
+    ├── mle/mle_model.py - MLE 核心算法
+    └── gmm/gmm_model.py - GMM 核心算法 (已修复 j_p_value bug)
+```
+
+**优点**：
+- ✅ 代码复用：单一真相源
+- ✅ DRY 原则：不重复自己
+- ✅ 易于维护：Bug 只需修复一次
+- ✅ 清晰分层：职责明确
+- ✅ 易于扩展：新算法只需写适配器
+
+### 备份文件
+
+`bak_old_implementation/` - 旧的独立实现（已废弃）
+- ols_tool.py (155 lines)
+- mle_tool.py (219 lines) 
+- gmm_tool.py (190 lines)
+
+这些文件已被 econometrics_adapter.py (164 lines) 替代
+节省代码：474 lines (84%)
+
+## 使用示例
+
+```python
+from tools.econometrics_adapter import (
+    ols_adapter,
+    mle_adapter,
+    gmm_adapter
+)
+
+# 直接数据输入
+result = ols_adapter(
+    y_data=[1,2,3,4,5],
+    x_data=[[1],[2],[3],[4],[5]],
+    output_format="json"
+)
+
+# 文件输入
+result = mle_adapter(
+    file_path="data/sample.csv",
+    distribution="normal",
+    output_format="markdown",
+    save_path="results/mle.md"
+)
+```
+
+## 迁移记录
+
+- 2025-11-04: 切换到适配器模式
+- 修复核心 GMM bug (j_p_value)
+- 移动旧实现到 bak_old_implementation/
+- 减少 84% 重复代码
+
+## 相关文档
+
+- [架构分析](../ARCHITECTURE_ANALYSIS.md)
+- [服务器代码](../fastmcp_server.py)
+- [核心算法](../econometrics/basic_parametric_estimation/)

tools/__init__.py

@@ -0,0 +1,45 @@
+"""
+工具模块初始化文件
+"""
+
+from .data_loader import DataLoader
+from .output_formatter import OutputFormatter
+from .econometrics_adapter import EconometricsAdapter
+
+# 时间序列和面板数据工具
+from .time_series_panel_data_adapter import TimeSeriesPanelDataAdapter
+from .time_series_panel_data_tools import (
+    arima_model,
+    exponential_smoothing_model,
+    garch_model,
+    unit_root_tests,
+    var_svar_model,
+    cointegration_analysis,
+    dynamic_panel_model
+)
+
+# 保持向后兼容性
+ols_adapter = EconometricsAdapter.ols_regression
+mle_adapter = EconometricsAdapter.mle_estimation
+gmm_adapter = EconometricsAdapter.gmm_estimation
+
+__all__ = [
+    "DataLoader",
+    "OutputFormatter",
+    "EconometricsAdapter",
+    "TimeSeriesPanelDataAdapter",
+    
+    # 基础工具
+    "ols_adapter",
+    "mle_adapter",
+    "gmm_adapter",
+    
+    # 时间序列和面板数据工具
+    "arima_model",
+    "exponential_smoothing_model",
+    "garch_model",
+    "unit_root_tests",
+    "var_svar_model",
+    "cointegration_analysis",
+    "dynamic_panel_model"
+]

tools/data_loader.py

@@ -0,0 +1,213 @@
+"""
+数据加载组件 - 支持多种文件格式
+支持txt、json、csv、excel文件的读取和解析
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Union
+import pandas as pd
+
+
+class DataLoader:
+    """数据加载器，支持多种文件格式"""
+    
+    @staticmethod
+    def load_from_file(file_path: str) -> Dict[str, Any]:
+        """
+        从文件加载数据
+        
+        Args:
+            file_path: 文件路径
+            
+        Returns:
+            包含y_data和x_data的字典
+            
+        Raises:
+            FileNotFoundError: 文件不存在
+            ValueError: 不支持的文件格式或数据格式错误
+        """
+        path = Path(file_path)
+        
+        if not path.exists():
+            raise FileNotFoundError(f"文件不存在: {file_path}")
+        
+        suffix = path.suffix.lower()
+        
+        if suffix == '.txt':
+            return DataLoader._load_txt(path)
+        elif suffix == '.json':
+            return DataLoader._load_json(path)
+        elif suffix == '.csv':
+            return DataLoader._load_csv(path)
+        elif suffix in ['.xlsx', '.xls']:
+            return DataLoader._load_excel(path)
+        else:
+            raise ValueError(f"不支持的文件格式: {suffix}")
+    
+    @staticmethod
+    def _load_txt(path: Path) -> Dict[str, Any]:
+        """加载txt文件（空格或制表符分隔）"""
+        with open(path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+        
+        # 跳过空行和注释行
+        data_lines = [line.strip() for line in lines if line.strip() and not line.strip().startswith('#')]
+        
+        if not data_lines:
+            raise ValueError("txt文件为空或没有有效数据")
+        
+        # 解析数据
+        data = []
+        for line in data_lines:
+            # 支持空格和制表符分隔
+            row = [float(x) for x in line.split()]
+            data.append(row)
+        
+        return DataLoader._parse_data_matrix(data)
+    
+    @staticmethod
+    def _load_json(path: Path) -> Dict[str, Any]:
+        """加载json文件"""
+        with open(path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        
+        # 支持两种格式：
+        # 1. {"y_data": [...], "x_data": [[...], ...]}
+        # 2. {"data": [[y, x1, x2, ...], ...]}
+        
+        if "y_data" in data and "x_data" in data:
+            return {
+                "y_data": data["y_data"],
+                "x_data": data["x_data"],
+                "feature_names": data.get("feature_names"),
+            }
+        elif "data" in data:
+            return DataLoader._parse_data_matrix(data["data"])
+        else:
+            raise ValueError("JSON格式错误：需要包含'y_data'和'x_data'或'data'字段")
+    
+    @staticmethod
+    def _load_csv(path: Path) -> Dict[str, Any]:
+        """加载csv文件"""
+        df = pd.read_csv(path)
+        return DataLoader._parse_dataframe(df)
+    
+    @staticmethod
+    def _load_excel(path: Path) -> Dict[str, Any]:
+        """加载excel文件"""
+        df = pd.read_excel(path)
+        return DataLoader._parse_dataframe(df)
+    
+    @staticmethod
+    def _parse_dataframe(df: pd.DataFrame) -> Dict[str, Any]:
+        """解析DataFrame"""
+        if df.empty:
+            raise ValueError("数据框为空")
+        
+        # 第一列为y，其余列为x
+        y_data = df.iloc[:, 0].tolist()
+        
+        if df.shape[1] > 1:
+            x_data = df.iloc[:, 1:].values.tolist()
+            feature_names = df.columns[1:].tolist()
+        else:
+            raise ValueError("数据至少需要包含因变量和一个自变量")
+        
+        return {
+            "y_data": y_data,
+            "x_data": x_data,
+            "feature_names": feature_names,
+        }
+    
+    @staticmethod
+    def _parse_data_matrix(data: List[List[float]]) -> Dict[str, Any]:
+        """解析数据矩阵（第一列为y，其余列为x）"""
+        if not data:
+            raise ValueError("数据矩阵为空")
+        
+        y_data = [row[0] for row in data]
+        
+        if len(data[0]) > 1:
+            x_data = [row[1:] for row in data]
+            feature_names = [f"X{i+1}" for i in range(len(data[0]) - 1)]
+        else:
+            raise ValueError("数据至少需要包含因变量和一个自变量")
+        
+        return {
+            "y_data": y_data,
+            "x_data": x_data,
+            "feature_names": feature_names,
+        }
+
+
+class MLEDataLoader:
+    """MLE专用数据加载器"""
+    
+    @staticmethod
+    def load_from_file(file_path: str) -> Dict[str, Any]:
+        """
+        从文件加载MLE数据（单列数据）
+        
+        Args:
+            file_path: 文件路径
+            
+        Returns:
+            包含data的字典
+        """
+        path = Path(file_path)
+        
+        if not path.exists():
+            raise FileNotFoundError(f"文件不存在: {file_path}")
+        
+        suffix = path.suffix.lower()
+        
+        if suffix == '.txt':
+            return MLEDataLoader._load_txt(path)
+        elif suffix == '.json':
+            return MLEDataLoader._load_json(path)
+        elif suffix == '.csv':
+            return MLEDataLoader._load_csv(path)
+        elif suffix in ['.xlsx', '.xls']:
+            return MLEDataLoader._load_excel(path)
+        else:
+            raise ValueError(f"不支持的文件格式: {suffix}")
+    
+    @staticmethod
+    def _load_txt(path: Path) -> Dict[str, Any]:
+        """加载txt文件"""
+        with open(path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+        
+        data = []
+        for line in lines:
+            line = line.strip()
+            if line and not line.startswith('#'):
+                data.append(float(line.split()[0]))
+        
+        return {"data": data}
+    
+    @staticmethod
+    def _load_json(path: Path) -> Dict[str, Any]:
+        """加载json文件"""
+        with open(path, 'r', encoding='utf-8') as f:
+            loaded = json.load(f)
+        
+        if isinstance(loaded, dict) and "data" in loaded:
+            return {"data": loaded["data"]}
+        elif isinstance(loaded, list):
+            return {"data": loaded}
+        else:
+            raise ValueError("JSON格式错误")
+    
+    @staticmethod
+    def _load_csv(path: Path) -> Dict[str, Any]:
+        """加载csv文件"""
+        df = pd.read_csv(path)
+        return {"data": df.iloc[:, 0].tolist()}
+    
+    @staticmethod
+    def _load_excel(path: Path) -> Dict[str, Any]:
+        """加载excel文件"""
+        df = pd.read_excel(path)
+        return {"data": df.iloc[:, 0].tolist()}

tools/decorators.py

@@ -0,0 +1,38 @@
+"""
+工具装饰器模块
+"""
+
+from functools import wraps
+from typing import Callable, Any
+
+
+def with_file_support_decorator(tool_name: str):
+    """
+    支持文件输入的装饰器
+    
+    Args:
+        tool_name: 工具名称
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # 简化实现 - 直接调用原函数
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def validate_input(data_type: str = "econometric"):
+    """
+    输入验证装饰器
+    
+    Args:
+        data_type: 数据类型
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # 简化实现 - 直接调用原函数
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator