aigroup-econ-mcp 0.3.8__py3-none-any.whl → 0.4.0__py3-none-any.whl

aigroup_econ_mcp/server_with_file_support.py

@@ -0,0 +1,259 @@
+"""
+AIGroup 计量经济学 MCP 服务器 - 支持CSV文件路径输入
+使用最新的MCP特性提供专业计量经济学分析工具
+"""
+
+from typing import List, Dict, Any, Optional, Annotated, Union
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+import json
+from pathlib import Path
+
+import pandas as pd
+import numpy as np
+import statsmodels.api as sm
+from statsmodels.tsa import stattools
+from scipy import stats
+from pydantic import BaseModel, Field
+
+from mcp.server.fastmcp import FastMCP, Context
+from mcp.server.session import ServerSession
+from mcp.types import CallToolResult, TextContent
+
+
+# 数据模型定义
+class DescriptiveStatsResult(BaseModel):
+    """描述性统计结果"""
+    count: int = Field(description="样本数量")
+    mean: float = Field(description="均值")
+    std: float = Field(description="标准差")
+    min: float = Field(description="最小值")
+    max: float = Field(description="最大值")
+    median: float = Field(description="中位数")
+    skewness: float = Field(description="偏度")
+    kurtosis: float = Field(description="峰度")
+
+
+# 应用上下文
+@dataclass
+class AppContext:
+    """应用上下文，包含共享资源"""
+    config: Dict[str, Any]
+    version: str = "0.2.0"
+
+
+@asynccontextmanager
+async def lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+    """服务器生命周期管理"""
+    config = {
+        "max_sample_size": 10000,
+        "default_significance_level": 0.05,
+        "supported_tests": ["t_test", "f_test", "chi_square", "adf"],
+        "data_types": ["cross_section", "time_series", "panel"]
+    }
+    try:
+        yield AppContext(config=config, version="0.2.0")
+    finally:
+        pass
+
+
+# 创建MCP服务器实例
+mcp = FastMCP(
+    name="aigroup-econ-mcp",
+    instructions="Econometrics MCP Server with CSV file path support",
+    lifespan=lifespan
+)
+
+
+# 辅助函数：加载CSV文件
+async def load_data_from_path(file_path: str, ctx: Context) -> Dict[str, List[float]]:
+    """从CSV文件路径加载数据"""
+    await ctx.info(f"正在从文件加载数据: {file_path}")
+    
+    try:
+        # 读取CSV文件
+        df = pd.read_csv(file_path)
+        
+        # 转换为字典格式
+        data = {col: df[col].tolist() for col in df.columns}
+        
+        await ctx.info(f"✅ 文件加载成功：{len(df.columns)}个变量，{len(df)}个观测")
+        return data
+        
+    except FileNotFoundError:
+        raise ValueError(f"文件不存在: {file_path}")
+    except Exception as e:
+        raise ValueError(f"文件读取失败: {str(e)}")
+
+
+@mcp.tool()
+async def descriptive_statistics(
+    ctx: Context[ServerSession, AppContext],
+    data: Annotated[
+        Union[Dict[str, List[float]], str],
+        Field(
+            description="""数据输入，支持两种格式：
+
+📊 格式1：数据字典
+{
+    "GDP增长率": [3.2, 2.8, 3.5, 2.9],
+    "通货膨胀率": [2.1, 2.3, 1.9, 2.4],
+    "失业率": [4.5, 4.2, 4.0, 4.3]
+}
+
+📁 格式2：CSV文件路径（推荐）
+"d:/data/economic_data.csv"
+或
+"./test_data.csv"
+
+CSV文件要求：
+- 第一行为变量名（表头）
+- 后续行为数值数据
+- 所有列必须为数值类型"""
+        )
+    ]
+) -> CallToolResult:
+    """计算描述性统计量
+    
+    📊 功能说明：
+    对输入数据进行全面的描述性统计分析，包括集中趋势、离散程度、分布形状等指标。
+    
+    💡 使用场景：
+    - 初步了解数据的分布特征
+    - 检查数据质量和异常值
+    - 为后续建模提供基础信息
+    """
+    try:
+        # 检测输入类型并加载数据
+        if isinstance(data, str):
+            # 文件路径输入
+            data_dict = await load_data_from_path(data, ctx)
+        else:
+            # 字典输入
+            data_dict = data
+        
+        await ctx.info(f"开始计算描述性统计，处理 {len(data_dict)} 个变量")
+        
+        # 数据验证
+        if not data_dict:
+            raise ValueError("数据不能为空")
+        
+        df = pd.DataFrame(data_dict)
+        
+        # 基础统计量
+        result = DescriptiveStatsResult(
+            count=len(df),
+            mean=df.mean().mean(),
+            std=df.std().mean(),
+            min=df.min().min(),
+            max=df.max().max(),
+            median=df.median().mean(),
+            skewness=df.skew().mean(),
+            kurtosis=df.kurtosis().mean()
+        )
+        
+        # 计算相关系数矩阵
+        correlation_matrix = df.corr().round(4)
+        
+        await ctx.info(f"描述性统计计算完成，样本大小: {len(df)}")
+        
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"描述性统计结果：\n"
+                         f"样本数: {result.count}\n"
+                         f"均值: {result.mean:.4f}\n"
+                         f"标准差: {result.std:.4f}\n"
+                         f"最小值: {result.min:.4f}\n"
+                         f"最大值: {result.max:.4f}\n"
+                         f"中位数: {result.median:.4f}\n"
+                         f"偏度: {result.skewness:.4f}\n"
+                         f"峰度: {result.kurtosis:.4f}\n\n"
+                         f"相关系数矩阵：\n{correlation_matrix.to_string()}"
+                )
+            ],
+            structuredContent=result.model_dump()
+        )
+        
+    except Exception as e:
+        await ctx.error(f"计算描述性统计时出错: {str(e)}")
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"错误: {str(e)}")],
+            isError=True
+        )
+
+
+@mcp.tool()
+async def correlation_analysis(
+    ctx: Context[ServerSession, AppContext],
+    data: Annotated[
+        Union[Dict[str, List[float]], str],
+        Field(
+            description="""数据输入，支持两种格式：
+
+📊 格式1：数据字典
+{
+    "销售额": [12000, 13500, 11800, 14200],
+    "广告支出": [800, 900, 750, 1000],
+    "价格": [99, 95, 102, 98]
+}
+
+📁 格式2：CSV文件路径
+"d:/data/marketing_data.csv"
+
+要求：
+- 至少包含2个变量
+- 所有变量的数据点数量必须相同"""
+        )
+    ],
+    method: Annotated[
+        str,
+        Field(
+            default="pearson",
+            description="相关系数类型：pearson/spearman/kendall"
+        )
+    ] = "pearson"
+) -> CallToolResult:
+    """变量间相关性分析"""
+    try:
+        # 检测输入类型并加载数据
+        if isinstance(data, str):
+            data_dict = await load_data_from_path(data, ctx)
+        else:
+            data_dict = data
+        
+        await ctx.info(f"开始相关性分析: {method}")
+        
+        # 数据验证
+        if not data_dict:
+            raise ValueError("数据不能为空")
+        if len(data_dict) < 2:
+            raise ValueError("至少需要2个变量进行相关性分析")
+        
+        df = pd.DataFrame(data_dict)
+        correlation_matrix = df.corr(method=method)
+        
+        await ctx.info("相关性分析完成")
+        
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"{method.title()}相关系数矩阵：\n{correlation_matrix.round(4).to_string()}"
+                )
+            ]
+        )
+        
+    except Exception as e:
+        await ctx.error(f"相关性分析出错: {str(e)}")
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"错误: {str(e)}")],
+            isError=True
+        )
+
+
+def create_mcp_server() -> FastMCP:
+    """创建并返回MCP服务器实例"""
+    return mcp

aigroup_econ_mcp/tools/__init__.py

@@ -3,7 +3,7 @@
 """
 
 from . import regression, statistics, time_series, machine_learning, panel_data
-from . import validation, cache, monitoring
+from . import validation, cache, monitoring, file_parser
 
 __all__ = [
     "regression", 
@@ -13,5 +13,6 @@ __all__ = [
     "panel_data",
     "validation",
     "cache", 
-    "monitoring"
+    "monitoring",
+    "file_parser"
 ]

aigroup_econ_mcp/tools/data_loader.py

@@ -0,0 +1,171 @@
+"""
+数据加载辅助模块
+提供通用的CSV文件加载功能
+"""
+
+from typing import Dict, List, Union
+from pathlib import Path
+import pandas as pd
+
+
+async def load_data_if_path(
+    data: Union[Dict[str, List[float]], str],
+    ctx = None
+) -> Dict[str, List[float]]:
+    """
+    智能加载数据：如果是字符串则作为文件路径加载，否则直接返回
+    
+    Args:
+        data: 数据字典或CSV文件路径
+        ctx: MCP上下文对象（可选，用于日志）
+        
+    Returns:
+        数据字典
+        
+    Raises:
+        ValueError: 文件不存在或读取失败
+    """
+    # 如果已经是字典，直接返回
+    if isinstance(data, dict):
+        return data
+    
+    # 如果是字符串，作为文件路径处理
+    if isinstance(data, str):
+        if ctx:
+            await ctx.info(f"📁 检测到文件路径，正在加载: {data}")
+        
+        try:
+            # 检查文件是否存在
+            path = Path(data)
+            if not path.exists():
+                raise ValueError(f"文件不存在: {data}")
+            
+            # 读取CSV文件
+            df = pd.read_csv(path)
+            
+            # 转换为字典格式
+            result = {col: df[col].tolist() for col in df.columns}
+            
+            if ctx:
+                await ctx.info(f"✅ CSV文件加载成功：{len(df.columns)}个变量，{len(df)}个观测")
+            
+            return result
+            
+        except FileNotFoundError:
+            raise ValueError(f"文件不存在: {data}")
+        except Exception as e:
+            raise ValueError(f"CSV文件读取失败: {str(e)}")
+    
+    # 其他类型报错
+
+async def load_single_var_if_path(
+    data: Union[List[float], str],
+    ctx = None,
+    column_name: str = None
+) -> List[float]:
+    """
+    智能加载单变量数据：如果是字符串则作为文件路径加载，否则直接返回
+    
+    Args:
+        data: 数据列表或CSV文件路径
+        ctx: MCP上下文对象（可选，用于日志）
+        column_name: CSV文件中要读取的列名（可选，默认读取第一列）
+        
+    Returns:
+        数据列表
+        
+    Raises:
+        ValueError: 文件不存在或读取失败
+    """
+    # 如果已经是列表，直接返回
+    if isinstance(data, list):
+        return data
+    
+    # 如果是字符串，作为文件路径处理
+    if isinstance(data, str):
+        if ctx:
+            await ctx.info(f"📁 检测到文件路径，正在加载: {data}")
+        
+        try:
+            # 检查文件是否存在
+            path = Path(data)
+            if not path.exists():
+                raise ValueError(f"文件不存在: {data}")
+            
+            # 读取CSV文件
+            df = pd.read_csv(path)
+            
+            # 确定要读取的列
+            if column_name:
+                if column_name not in df.columns:
+                    raise ValueError(f"列'{column_name}'不存在于CSV文件中。可用列: {list(df.columns)}")
+                result = df[column_name].tolist()
+            else:
+                # 默认读取第一列
+                result = df.iloc[:, 0].tolist()
+                if ctx:
+                    await ctx.info(f"未指定列名，使用第一列: {df.columns[0]}")
+            
+            if ctx:
+                await ctx.info(f"✅ CSV文件加载成功：{len(result)}个观测")
+            
+            return result
+            
+        except FileNotFoundError:
+            raise ValueError(f"文件不存在: {data}")
+        except Exception as e:
+            raise ValueError(f"CSV文件读取失败: {str(e)}")
+    
+    # 其他类型报错
+    raise TypeError(f"不支持的数据类型: {type(data)}，期望List或str")
+async def load_x_data_if_path(
+    data: Union[List[List[float]], str],
+    ctx = None
+) -> List[List[float]]:
+    """
+    智能加载自变量数据：如果是字符串则作为文件路径加载，否则直接返回
+    
+    Args:
+        data: 自变量数据（二维列表）或CSV文件路径
+        ctx: MCP上下文对象（可选，用于日志）
+        
+    Returns:
+        自变量数据（二维列表）
+        
+    Raises:
+        ValueError: 文件不存在或读取失败
+    """
+    # 如果已经是二维列表，直接返回
+    if isinstance(data, list) and all(isinstance(item, list) for item in data):
+        return data
+    
+    # 如果是字符串，作为文件路径处理
+    if isinstance(data, str):
+        if ctx:
+            await ctx.info(f"📁 检测到自变量文件路径，正在加载: {data}")
+        
+        try:
+            # 检查文件是否存在
+            path = Path(data)
+            if not path.exists():
+                raise ValueError(f"文件不存在: {data}")
+            
+            # 读取CSV文件
+            df = pd.read_csv(path)
+            
+            # 转换为二维列表格式
+            result = df.values.tolist()
+            
+            if ctx:
+                await ctx.info(f"✅ 自变量CSV文件加载成功：{len(result)}个观测，{len(result[0]) if result else 0}个自变量")
+            
+            return result
+            
+        except FileNotFoundError:
+            raise ValueError(f"文件不存在: {data}")
+        except Exception as e:
+            raise ValueError(f"自变量CSV文件读取失败: {str(e)}")
+    
+    # 其他类型报错
+    raise TypeError(f"不支持的数据类型: {type(data)}，期望List[List[float]]或str")
+    raise TypeError(f"不支持的数据类型: {type(data)}，期望Dict或str")

aigroup_econ_mcp/tools/decorators.py

@@ -0,0 +1,178 @@
+"""
+工具装饰器模块
+提供自动文件输入处理、错误处理等功能
+"""
+
+from typing import Callable, Optional, Dict, Any, List
+from functools import wraps
+from mcp.server.session import ServerSession
+from mcp.server.fastmcp import Context
+from mcp.types import CallToolResult, TextContent
+
+from .file_parser import FileParser
+
+
+def with_file_input(tool_type: str):
+    """
+    为工具函数添加文件输入支持的装饰器
+    
+    支持两种输入方式：
+    1. file_path: CSV/JSON文件路径
+    2. file_content: 文件内容字符串
+    
+    Args:
+        tool_type: 工具类型 ('single_var', 'multi_var_dict', 'regression', 'panel', 'time_series')
+    
+    使用示例:
+        @with_file_input('regression')
+        async def my_tool(ctx, y_data=None, x_data=None, file_path=None, file_content=None, file_format='auto', **kwargs):
+            # 如果提供了file_path或file_content，数据会被自动填充
+            pass
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # 提取上下文和文件参数
+            ctx = args[0] if args else kwargs.get('ctx')
+            file_path = kwargs.get('file_path')
+            file_content = kwargs.get('file_content')
+            file_format = kwargs.get('file_format', 'auto')
+            
+            # 优先处理file_path
+            if file_path:
+                try:
+                    await ctx.info(f"检测到文件路径输入: {file_path}")
+                    
+                    # 从文件路径解析
+                    parsed = FileParser.parse_file_path(file_path, file_format)
+                    
+                    await ctx.info(
+                        f"文件解析成功：{parsed['n_variables']}个变量，"
+                        f"{parsed['n_observations']}个观测"
+                    )
+                    
+                    # 转换为工具格式
+                    converted = FileParser.convert_to_tool_format(parsed, tool_type)
+                    
+                    # 更新kwargs
+                    kwargs.update(converted)
+                    
+                    await ctx.info(f"数据已转换为{tool_type}格式")
+                    
+                except Exception as e:
+                    await ctx.error(f"文件解析失败: {str(e)}")
+                    return CallToolResult(
+                        content=[TextContent(type="text", text=f"文件解析错误: {str(e)}")],
+                        isError=True
+                    )
+            
+            # 如果没有file_path但有file_content，处理文件内容
+            elif file_content:
+                try:
+                    await ctx.info("检测到文件内容输入，开始解析...")
+                    
+                    # 解析文件内容
+                    parsed = FileParser.parse_file_content(file_content, file_format)
+                    
+                    await ctx.info(
+                        f"文件解析成功：{parsed['n_variables']}个变量，"
+                        f"{parsed['n_observations']}个观测"
+                    )
+                    
+                    # 转换为工具格式
+                    converted = FileParser.convert_to_tool_format(parsed, tool_type)
+                    
+                    # 更新kwargs
+                    kwargs.update(converted)
+                    
+                    await ctx.info(f"数据已转换为{tool_type}格式")
+                    
+                except Exception as e:
+                    await ctx.error(f"文件解析失败: {str(e)}")
+                    return CallToolResult(
+                        content=[TextContent(type="text", text=f"文件解析错误: {str(e)}")],
+                        isError=True
+                    )
+            
+            # 调用原函数
+            return await func(*args, **kwargs)
+        
+        return wrapper
+    return decorator
+
+
+def with_error_handling(func: Callable) -> Callable:
+    """
+    为工具函数添加统一错误处理的装饰器
+    """
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        ctx = args[0] if args else kwargs.get('ctx')
+        tool_name = func.__name__
+        
+        try:
+            return await func(*args, **kwargs)
+        except Exception as e:
+            await ctx.error(f"{tool_name}执行出错: {str(e)}")
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"错误: {str(e)}")],
+                isError=True
+            )
+    
+    return wrapper
+
+
+def with_logging(func: Callable) -> Callable:
+    """
+    为工具函数添加日志记录的装饰器
+    """
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        ctx = args[0] if args else kwargs.get('ctx')
+        tool_name = func.__name__
+        
+        await ctx.info(f"开始执行 {tool_name}")
+        result = await func(*args, **kwargs)
+        await ctx.info(f"{tool_name} 执行完成")
+        
+        return result
+    
+    return wrapper
+
+
+def econometric_tool(
+    tool_type: str,
+    with_file_support: bool = True,
+    with_error_handling: bool = True,
+    with_logging: bool = True
+):
+    """
+    组合装饰器：为计量经济学工具添加所有标准功能
+    
+    Args:
+        tool_type: 工具类型
+        with_file_support: 是否启用文件输入支持
+        with_error_handling: 是否启用错误处理
+        with_logging: 是否启用日志记录
+    
+    使用示例:
+        @econometric_tool('regression')
+        async def ols_regression(ctx, y_data=None, x_data=None, **kwargs):
+            # 只需要编写核心业务逻辑
+            pass
+    """
+    def decorator(func: Callable) -> Callable:
+        wrapped = func
+        
+        if with_error_handling:
+            wrapped = globals()['with_error_handling'](wrapped)
+        
+        if with_file_support:
+            wrapped = with_file_input(tool_type)(wrapped)
+        
+        if with_logging:
+            wrapped = globals()['with_logging'](wrapped)
+        
+        return wrapped
+    
+    return decorator