aigroup-econ-mcp 0.1.1__tar.gz → 0.1.2__tar.gz

{aigroup_econ_mcp-0.1.1 → aigroup_econ_mcp-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aigroup-econ-mcp
-Version: 0.1.1
+Version: 0.1.2
 Summary: 专业计量经济学MCP工具 - 让大模型直接进行数据分析
 Project-URL: Homepage, https://github.com/aigroup/aigroup-econ-mcp
 Project-URL: Repository, https://github.com/aigroup/aigroup-econ-mcp.git

aigroup_econ_mcp-0.1.2/PUBLISHING.md

@@ -0,0 +1,109 @@
+# PyPI 发布指南
+
+## 已完成的准备工作
+
+✅ 版本号已更新到 0.1.1
+✅ 包已成功构建
+✅ 创建了更新日志 (CHANGELOG.md)
+✅ 所有功能测试通过
+
+## 构建产物
+
+```
+dist/
+├── aigroup_econ_mcp-0.1.1.tar.gz          # 源码分发包
+└── aigroup_econ_mcp-0.1.1-py3-none-any.whl # 二进制wheel包
+```
+
+## 发布到PyPI
+
+### 方法1: 使用uv发布（推荐）
+
+```bash
+# 发布到PyPI（需要PyPI账号和Token）
+uv publish
+
+# 或指定token
+uv publish --token YOUR_PYPI_TOKEN
+```
+
+### 方法2: 使用twine发布
+
+```bash
+# 安装twine
+pip install twine
+
+# 检查包
+twine check dist/*
+
+# 上传到TestPyPI（测试）
+twine upload --repository testpypi dist/*
+
+# 上传到PyPI（正式）
+twine upload dist/*
+```
+
+## 配置PyPI凭据
+
+### 选项1: 使用环境变量
+
+```bash
+# Windows PowerShell
+$env:UV_PUBLISH_TOKEN="pypi-..."
+
+# Linux/Mac
+export UV_PUBLISH_TOKEN="pypi-..."
+```
+
+### 选项2: 使用.pypirc文件
+
+创建 `~/.pypirc` 文件：
+
+```ini
+[pypi]
+username = __token__
+password = pypi-YOUR_TOKEN_HERE
+```
+
+## 获取PyPI Token
+
+1. 访问 https://pypi.org/manage/account/token/
+2. 登录你的PyPI账号
+3. 创建新的API Token
+4. 复制token（格式: pypi-...）
+
+## 发布后验证
+
+```bash
+# 安装发布的包
+pip install aigroup-econ-mcp
+
+# 或使用uvx
+uvx aigroup-econ-mcp --version
+```
+
+## 发布检查清单
+
+- [x] 版本号已更新
+- [x] 包已构建成功
+- [x] 所有测试通过
+- [x] README.md完整
+- [x] LICENSE存在
+- [x] CHANGELOG.md已创建
+- [ ] PyPI凭据已配置
+- [ ] 执行发布命令
+- [ ] 验证安装
+
+## 注意事项
+
+⚠️ **重要**: 
+- 发布到PyPI后不能删除或修改
+- 建议先发布到TestPyPI测试
+- 确保版本号遵循语义化版本规范
+- 每次发布必须使用新的版本号
+
+## 快速发布命令
+
+```bash
+# 一键发布（需要已配置token）
+cd d:/aigroup-econ-mcp && uv publish

aigroup_econ_mcp-0.1.2/RELEASE_NOTES_v0.1.1.md

@@ -0,0 +1,121 @@
+# aigroup-econ-mcp v0.1.1 发布说明
+
+## 🎉 发布信息
+
+- **版本**: 0.1.1
+- **发布日期**: 2025-10-25
+- **PyPI链接**: https://pypi.org/project/aigroup-econ-mcp/
+
+## 📦 已发布文件
+
+✅ aigroup_econ_mcp-0.1.0-py3-none-any.whl (16.1 KB)
+✅ aigroup_econ_mcp-0.1.0.tar.gz (26.9 KB)
+✅ aigroup_econ_mcp-0.1.1-py3-none-any.whl (16.3 KB)
+✅ aigroup_econ_mcp-0.1.1.tar.gz (28.5 KB)
+
+## 🐛 重要修复
+
+### 修复MCP连接失败的严重Bug
+
+**问题**: 运行 `uvx aigroup-econ-mcp` 时出现 "MCP error -32000: Connection closed"
+
+**根本原因**: CLI入口点结构混乱
+- 同时使用 `@click.command()` 和 `@click.group()`
+- 默认行为显示帮助而非启动MCP服务器
+- MCP客户端期望stdio通信，但收到帮助文本导致连接关闭
+
+**解决方案**:
+- ✅ 完全重构CLI入口点为单一命令结构
+- ✅ 确保默认行为正确启动stdio模式
+- ✅ 修复Windows UTF-8编码问题
+- ✅ 保留所有功能（版本、调试、多传输协议）
+
+## ✅ 功能验证
+
+所有7项功能测试通过：
+
+| 测试项 | 状态 | 说明 |
+|-------|------|------|
+| 初始化服务器 | ✓ | MCP协议握手成功 |
+| 工具列表 | ✓ | 5个计量经济学工具 |
+| 资源列表 | ✓ | 资源系统正常 |
+| 提示词列表 | ✓ | 1个分析模板 |
+| 描述性统计 | ✓ | 计算成功 |
+| 相关性分析 | ✓ | 分析成功 |
+| 获取资源 | ✓ | 数据获取成功 |
+
+## 📊 测试结果示例
+
+### 描述性统计输出
+```
+均值: 0.0060
+标准差: 0.0131
+相关系数矩阵：
+                stock_returns  market_returns
+stock_returns          1.0000          0.9951
+market_returns         0.9951          1.0000
+```
+
+### 相关性分析输出
+```
+Pearson相关系数矩阵：
+              GDP_Growth  Inflation  Unemployment
+GDP_Growth        1.0000    -0.9492       -0.3322
+Inflation        -0.9492     1.0000        0.3514
+Unemployment     -0.3322     0.3514        1.0000
+```
+
+## 🚀 安装使用
+
+### 从PyPI安装（推荐）
+
+```bash
+# 使用uvx（推荐）
+uvx aigroup-econ-mcp
+
+# 使用pip
+pip install aigroup-econ-mcp
+```
+
+### 与Claude Desktop集成
+
+在配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "aigroup-econ-mcp": {
+      "command": "uvx",
+      "args": ["aigroup-econ-mcp"]
+    }
+  }
+}
+```
+
+## 📝 可用工具
+
+1. **descriptive_statistics** - 描述性统计分析
+2. **ols_regression** - OLS回归分析
+3. **hypothesis_testing** - 假设检验
+4. **time_series_analysis** - 时间序列分析
+5. **correlation_analysis** - 相关性分析
+
+## 🔗 相关链接
+
+- **PyPI**: https://pypi.org/project/aigroup-econ-mcp/
+- **GitHub**: https://github.com/aigroup/aigroup-econ-mcp
+- **文档**: [README.md](README.md)
+- **更新日志**: [CHANGELOG.md](CHANGELOG.md)
+
+## 📧 联系方式
+
+- **Email**: jackdark425@gmail.com
+- **Issues**: https://github.com/aigroup/aigroup-econ-mcp/issues
+
+## 🙏 致谢
+
+感谢所有用户的支持和反馈！
+
+---
+
+**注意**: PyPI索引可能需要几分钟更新。如果遇到安装问题，请稍后重试或使用 `--refresh` 标志。

aigroup_econ_mcp-0.1.2/RELEASE_NOTES_v0.1.2.md

@@ -0,0 +1,83 @@
+# 🎉 aigroup-econ-mcp v0.1.2 发布说明
+
+## 📅 发布日期
+2025-01-25
+
+## ✨ 主要更新
+
+### 📚 文档增强
+本次更新大幅增强了所有MCP工具的说明文档，显著提升大模型的调用准确性和效率。
+
+#### 1. descriptive_statistics（描述性统计）
+- ✅ 新增详细的参数说明和数据格式示例
+- ✅ 补充了数据要求说明（样本量、格式、缺失值处理）
+- ✅ 详细解释输出指标含义（偏度、峰度、相关系数等）
+- ✅ 提供使用场景和注意事项
+
+#### 2. ols_regression（OLS回归分析）
+- ✅ 详细说明因变量和自变量的数据格式
+- ✅ 提供二维列表的具体示例
+- ✅ 解释R²、F统计量、AIC/BIC等指标的经济学含义
+- ✅ 说明多重共线性等常见问题及解决方案
+
+#### 3. hypothesis_testing（假设检验）
+- ✅ 区分单样本t检验和双样本t检验的应用场景
+- ✅ 详细说明ADF检验用于时间序列平稳性检验
+- ✅ 解释p值的统计学含义和显著性判断标准
+- ✅ 提供实际应用场景示例（新药测试、教学方法对比等）
+
+#### 4. time_series_analysis（时间序列分析）
+- ✅ 说明时间序列数据的格式要求和排序规则
+- ✅ 详细解释ADF检验、ACF、PACF的含义
+- ✅ 提供结果解读指南和模型选择建议
+- ✅ 说明如何根据ACF/PACF识别AR、MA、ARMA模型
+
+#### 5. correlation_analysis（相关性分析）
+- ✅ 详细对比pearson、spearman、kendall三种方法的适用场景
+- ✅ 提供相关系数的标准解读方法
+- ✅ 强调"相关性≠因果关系"的重要概念
+- ✅ 提供多重共线性检测等实际应用场景
+
+## 🎯 改进效果
+
+大模型在使用本工具时将能够：
+1. **准确理解参数**：每个参数都有详细说明和示例格式
+2. **正确选择工具**：根据分析任务选择合适的工具
+3. **提供正确输入**：遵循规定的数据格式和要求
+4. **解释输出结果**：理解每个统计指标的含义
+5. **避免常见错误**：注意事项说明帮助避免误用
+
+## 📋 文档结构
+
+每个工具的说明现在都包含：
+- 📊 **功能说明**：清晰描述工具的作用和原理
+- 📈 **输出指标**：详细解释每个返回值的统计学含义
+- 💡 **使用场景**：提供经济学/统计学实际应用示例
+- ⚠️ **注意事项**：说明常见问题、限制和最佳实践
+- 📖 **结果解读**：帮助理解和应用输出结果
+
+## 🔧 技术改进
+
+- 使用 `Annotated` 和 `Field` 为每个参数添加详细的描述信息
+- 提供多种数据格式示例，覆盖常见使用场景
+- 添加参数验证说明，帮助用户提供正确的输入
+- 统一文档风格，使用emoji和结构化格式提高可读性
+
+## 📦 安装升级
+
+```bash
+# 使用pip安装或升级
+pip install --upgrade aigroup-econ-mcp
+
+# 使用uv安装或升级
+uv pip install --upgrade aigroup-econ-mcp
+```
+
+## 🙏 致谢
+
+感谢社区用户的反馈和建议，帮助我们持续改进工具的易用性。
+
+## 📞 支持
+
+- GitHub Issues: https://github.com/aigroup/aigroup-econ-mcp/issues
+- 邮箱: jackdark425@gmail.com

{aigroup_econ_mcp-0.1.1 → aigroup_econ_mcp-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "aigroup-econ-mcp"
-version = "0.1.1"
+version = "0.1.2"
 description = "专业计量经济学MCP工具 - 让大模型直接进行数据分析"
 readme = "README.md"
 requires-python = ">=3.10"

{aigroup_econ_mcp-0.1.1 → aigroup_econ_mcp-0.1.2}/src/aigroup_econ_mcp/__init__.py

@@ -10,7 +10,7 @@ AIGroup 计量经济学 MCP 服务
 - 模型诊断
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 __author__ = "AIGroup"
 __description__ = "专业计量经济学MCP工具 - 让大模型直接进行数据分析"
 

{aigroup_econ_mcp-0.1.1 → aigroup_econ_mcp-0.1.2}/src/aigroup_econ_mcp/server.py

@@ -152,12 +152,54 @@ def economic_analysis_prompt(data_description: str, analysis_type: str = "descri
 @mcp.tool()
 async def descriptive_statistics(
     ctx: Context[ServerSession, AppContext],
-    data: Dict[str, List[float]]
+    data: Annotated[
+        Dict[str, List[float]],
+        Field(
+            description="""数据字典，格式为 {变量名: [数值列表]}
+            
+示例格式：
+{
+    "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]
+}
+
+要求：
+- 至少包含一个变量
+- 每个变量的数据点数量应相同
+- 数值必须为浮点数或整数
+- 建议样本量 >= 30 以获得可靠的统计推断"""
+        )
+    ]
 ) -> Annotated[CallToolResult, DescriptiveStatsResult]:
     """计算描述性统计量
+    
+    📊 功能说明：
+    对输入数据进行全面的描述性统计分析，包括集中趋势、离散程度、分布形状等指标。
+    
+    📈 输出指标：
+    - 样本数量 (count)
+    - 均值 (mean)：数据的平均水平
+    - 标准差 (std)：数据的离散程度
+    - 最小值/最大值 (min/max)：数据的取值范围
+    - 中位数 (median)：数据的中间值，对异常值不敏感
+    - 偏度 (skewness)：分布的对称性，0表示对称，>0右偏，<0左偏
+    - 峰度 (kurtosis)：分布的尖峭程度，0表示正态分布
+    - 相关系数矩阵：变量间的线性相关关系
+    
+    💡 使用场景：
+    - 初步了解数据的分布特征
+    - 检查数据质量和异常值
+    - 为后续建模提供基础信息
+    - 比较不同变量的统计特征
+    
+    ⚠️ 注意事项：
+    - 偏度绝对值 > 1 表示数据明显偏斜，可能需要转换
+    - 峰度绝对值 > 3 表示尖峭或扁平分布
+    - 相关系数 > 0.8 表示强相关，可能存在多重共线性
 
     Args:
-        data: 字典格式的数据，键为变量名，值为数值列表
+        data: 数据字典，键为变量名，值为数值列表
         ctx: MCP上下文对象
     """
     await ctx.info(f"开始计算描述性统计，处理 {len(data)} 个变量")
@@ -211,16 +253,85 @@ async def descriptive_statistics(
 @mcp.tool()
 async def ols_regression(
     ctx: Context[ServerSession, AppContext],
-    y_data: List[float],
-    x_data: List[List[float]],
-    feature_names: Optional[List[str]] = None
+    y_data: Annotated[
+        List[float],
+        Field(
+            description="""因变量数据（被解释变量/响应变量）
+            
+示例：[12000, 13500, 11800, 14200, 15100]
+
+要求：
+- 必须为数值列表
+- 长度必须与自变量观测数量一致
+- 不能包含缺失值（NaN）
+- 建议样本量 >= 30"""
+        )
+    ],
+    x_data: Annotated[
+        List[List[float]],
+        Field(
+            description="""自变量数据（解释变量/预测变量），二维列表格式
+            
+示例格式（3个观测，2个自变量）：
+[
+    [800, 5.2],    # 第1个观测的自变量值
+    [900, 5.8],    # 第2个观测的自变量值
+    [750, 4.9]     # 第3个观测的自变量值
+]
+
+要求：
+- 外层列表：每个元素代表一个观测
+- 内层列表：该观测的所有自变量值
+- 所有观测的自变量数量必须相同
+- 观测数量必须与y_data长度一致
+- 自变量数量建议 < 观测数量/10（避免过拟合）"""
+        )
+    ],
+    feature_names: Annotated[
+        Optional[List[str]],
+        Field(
+            default=None,
+            description="""自变量名称列表（可选）
+            
+示例：["广告支出", "价格指数"]
+
+说明：
+- 如果不提供，将自动命名为 x1, x2, x3...
+- 名称数量必须与自变量数量一致
+- 建议使用有意义的名称以便解释结果"""
+        )
+    ] = None
 ) -> Annotated[CallToolResult, OLSRegressionResult]:
-    """执行OLS回归分析
+    """执行普通最小二乘法(OLS)回归分析
+    
+    📊 功能说明：
+    使用最小二乘法估计线性回归模型，分析因变量与自变量之间的线性关系。
+    模型形式：Y = β₀ + β₁X₁ + β₂X₂ + ... + βₖXₖ + ε
+    
+    📈 输出指标：
+    - R²：决定系数，取值0-1，衡量模型拟合优度
+    - 调整R²：考虑自变量数量的修正R²
+    - F统计量及p值：检验模型整体显著性
+    - AIC/BIC：信息准则，用于模型比较，越小越好
+    - 回归系数：每个自变量的估计值、标准误、t统计量、p值、置信区间
+    
+    💡 使用场景：
+    - 因果关系分析（如广告支出对销售额的影响）
+    - 预测建模（如根据经济指标预测GDP）
+    - 控制变量分析（如研究教育回报率时控制工作经验）
+    - 假设检验（如检验某变量是否对结果有显著影响）
+    
+    ⚠️ 注意事项：
+    - R² > 0.7 表示拟合良好，但需警惕过拟合
+    - p值 < 0.05 表示该系数在5%水平显著
+    - 需检查残差的正态性、同方差性和独立性假设
+    - 自变量间高度相关（相关系数>0.8）可能导致多重共线性问题
+    - 样本量过小可能导致不可靠的估计结果
 
     Args:
         y_data: 因变量数据
         x_data: 自变量数据，每行一个观测
-        feature_names: 自变量名称
+        feature_names: 自变量名称（可选）
         ctx: MCP上下文对象
     """
     await ctx.info(f"开始OLS回归分析，样本大小: {len(y_data)}，自变量数量: {len(x_data[0]) if x_data else 0}")
@@ -286,16 +397,97 @@ async def ols_regression(
 @mcp.tool()
 async def hypothesis_testing(
     ctx: Context[ServerSession, AppContext],
-    data1: List[float],
-    data2: Optional[List[float]] = None,
-    test_type: str = "t_test"
+    data1: Annotated[
+        List[float],
+        Field(
+            description="""第一组数据或单一样本数据
+            
+示例：[3.2, 2.8, 3.5, 2.9, 3.1, 2.7, 3.3]
+
+要求：
+- 必须为数值列表
+- 不能包含缺失值
+- 建议样本量 >= 30（大样本）
+- t检验要求数据近似正态分布"""
+        )
+    ],
+    data2: Annotated[
+        Optional[List[float]],
+        Field(
+            default=None,
+            description="""第二组数据（可选，用于双样本检验）
+            
+示例：[2.5, 2.9, 2.3, 2.6, 2.8]
+
+说明：
+- 仅在双样本t检验时需要提供
+- 单样本t检验时保持为None
+- 两组数据可以有不同的样本量
+- ADF检验不需要第二组数据"""
+        )
+    ] = None,
+    test_type: Annotated[
+        str,
+        Field(
+            default="t_test",
+            description="""假设检验类型
+
+可选值：
+- "t_test": t检验（默认）
+  * 单样本t检验：检验样本均值是否等于0（data2=None）
+  * 双样本t检验：检验两组样本均值是否相等（提供data2）
+  
+- "adf": 增强迪基-富勒检验（Augmented Dickey-Fuller Test）
+  * 用于检验时间序列的平稳性
+  * 原假设：存在单位根（非平稳）
+  * p<0.05 拒绝原假设，序列平稳
+
+使用建议：
+- 比较均值差异 → 使用 t_test
+- 检验时间序列平稳性 → 使用 adf"""
+        )
+    ] = "t_test"
 ) -> Annotated[CallToolResult, HypothesisTestResult]:
-    """执行假设检验
+    """执行统计假设检验
+    
+    📊 功能说明：
+    对数据进行统计假设检验，判断样本是否支持某个统计假设。
+    
+    📈 检验类型详解：
+    
+    1️⃣ t检验 (t_test)：
+       - 单样本：H₀: μ = 0 vs H₁: μ ≠ 0
+       - 双样本：H₀: μ₁ = μ₂ vs H₁: μ₁ ≠ μ₂
+       - 适用于小样本（n<30）且数据近似正态分布
+    
+    2️⃣ ADF检验 (adf)：
+       - H₀: 序列存在单位根（非平稳）
+       - H₁: 序列不存在单位根（平稳）
+       - 用于时间序列分析前的平稳性检验
+    
+    📊 输出指标：
+    - 检验统计量：用于判断是否拒绝原假设
+    - p值：显著性水平，<0.05表示在5%水平显著
+    - 是否显著：基于5%显著性水平的判断
+    - 置信区间：参数的可能取值范围（仅t检验）
+    
+    💡 使用场景：
+    - 检验新药是否有效（单样本t检验）
+    - 比较两种教学方法的效果差异（双样本t检验）
+    - 检验股价序列是否平稳（ADF检验）
+    - 验证经济理论假说（如购买力平价理论）
+    
+    ⚠️ 注意事项：
+    - p值 < 0.05：拒绝原假设（结果显著）
+    - p值 >= 0.05：不能拒绝原假设（结果不显著）
+    - t检验要求数据近似正态分布
+    - 小样本(<30)时t检验结果可能不可靠
+    - ADF检验中p<0.05表示序列平稳（拒绝非平稳假设）
 
     Args:
         data1: 第一组数据
-        data2: 第二组数据（可选）
-        test_type: 检验类型
+        data2: 第二组数据（可选，用于双样本检验）
+        test_type: 检验类型（t_test或adf）
         ctx: MCP上下文对象
     """
     await ctx.info(f"开始假设检验: {test_type}")
@@ -359,12 +551,82 @@ async def hypothesis_testing(
 @mcp.tool()
 async def time_series_analysis(
     ctx: Context[ServerSession, AppContext],
-    data: List[float]
+    data: Annotated[
+        List[float],
+        Field(
+            description="""时间序列数据（按时间顺序排列）
+            
+示例格式：
+[12000, 13500, 11800, 14200, 15100, 14800, 16200, 15900]
+# 表示连续8期的观测值，如月度销售额
+
+要求：
+- 必须按时间顺序排列（从早到晚）
+- 建议至少30个观测点以获得可靠结果
+- 数据应等间隔采样（如日度、月度、季度）
+- 不能包含缺失值
+- 数据量越大，ACF/PACF分析越准确
+
+应用示例：
+- 股票价格序列
+- GDP季度数据
+- 月度销售额
+- 日均气温数据"""
+        )
+    ]
 ) -> Annotated[CallToolResult, TimeSeriesStatsResult]:
-    """时间序列分析
+    """时间序列统计分析
+    
+    📊 功能说明：
+    对时间序列数据进行全面的统计分析，包括平稳性检验和自相关分析。
+    
+    📈 分析内容：
+    
+    1️⃣ ADF单位根检验（Augmented Dickey-Fuller Test）：
+       - 检验序列是否平稳
+       - H₀: 存在单位根（序列非平稳）
+       - p < 0.05：拒绝原假设，序列平稳
+       - 平稳性是时间序列建模的基础
+    
+    2️⃣ 自相关函数（ACF）：
+       - 衡量序列与其滞后值之间的相关性
+       - 用于识别MA模型的阶数
+       - 指数衰减→AR过程；q阶截尾→MA(q)过程
+    
+    3️⃣ 偏自相关函数（PACF）：
+       - 剔除中间滞后项影响后的相关性
+       - 用于识别AR模型的阶数
+       - p阶截尾→AR(p)过程
+    
+    📊 输出指标：
+    - ADF统计量：越负越可能平稳
+    - ADF p值：<0.05表示序列平稳
+    - 平稳性判断：基于5%显著性水平
+    - ACF值：前20阶（或更少）的自相关系数
+    - PACF值：前20阶（或更少）的偏自相关系数
+    
+    💡 使用场景：
+    - ARIMA建模前的平稳性检验
+    - 识别合适的时间序列模型（AR、MA、ARMA）
+    - 检测季节性和趋势
+    - 评估序列的记忆性和持续性
+    
+    ⚠️ 注意事项：
+    - 非平稳序列需要差分或变换后才能建模
+    - ACF和PACF应结合使用以识别模型类型
+    - 数据点太少（<30）可能导致不可靠的结果
+    - 强烈的季节性可能影响ACF/PACF的解读
+    - 建议同时观察ACF/PACF图形以获得更好的直观理解
+    
+    📖 结果解读：
+    - ADF p值 < 0.05 + ACF快速衰减 → 平稳序列，可直接建模
+    - ADF p值 >= 0.05 → 非平稳序列，需要差分处理
+    - PACF在p阶截尾 → 考虑AR(p)模型
+    - ACF在q阶截尾 → 考虑MA(q)模型
+    - ACF和PACF都衰减 → 考虑ARMA模型
 
     Args:
-        data: 时间序列数据
+        data: 时间序列数据（按时间顺序）
         ctx: MCP上下文对象
     """
     await ctx.info(f"开始时间序列分析，数据点数量: {len(data)}")
@@ -413,14 +675,99 @@ async def time_series_analysis(
 @mcp.tool()
 async def correlation_analysis(
     ctx: Context[ServerSession, AppContext],
-    data: Dict[str, List[float]],
-    method: str = "pearson"
+    data: Annotated[
+        Dict[str, List[float]],
+        Field(
+            description="""多变量数据字典
+            
+示例格式：
+{
+    "销售额": [12000, 13500, 11800, 14200],
+    "广告支出": [800, 900, 750, 1000],
+    "价格": [99, 95, 102, 98],
+    "竞争对手数量": [3, 3, 4, 3]
+}
+
+要求：
+- 至少包含2个变量
+- 所有变量的数据点数量必须相同
+- 建议样本量 >= 30
+- 数值不能包含缺失值
+
+应用：
+- 探索变量间的关联关系
+- 识别潜在的多重共线性
+- 为回归分析筛选变量"""
+        )
+    ],
+    method: Annotated[
+        str,
+        Field(
+            default="pearson",
+            description="""相关系数计算方法
+
+可选值：
+- "pearson": 皮尔逊相关系数（默认）
+  * 衡量线性相关关系
+  * 取值范围：-1到1
+  * 要求：数据近似正态分布
+  * 对异常值敏感
+  
+- "spearman": 斯皮尔曼秩相关系数
+  * 衡量单调相关关系（不要求线性）
+  * 基于数据的秩次
+  * 对异常值不敏感
+  * 适用于非正态分布
+  
+- "kendall": 肯德尔τ相关系数
+  * 衡量一致性程度
+  * 更稳健但计算较慢
+  * 适用于小样本和有序数据
+
+选择建议：
+- 数据正态分布 + 关注线性关系 → pearson
+- 数据有异常值或非正态 → spearman
+- 有序分类数据 → kendall"""
+        )
+    ] = "pearson"
 ) -> str:
-    """相关性分析
+    """变量间相关性分析
+    
+    📊 功能说明：
+    计算多个变量之间的相关系数矩阵，揭示变量间的关联关系强度和方向。
+    
+    📈 相关系数解读：
+    - 相关系数范围：-1 到 +1
+    - |r| = 0.0-0.3：弱相关或无相关
+    - |r| = 0.3-0.7：中等程度相关
+    - |r| = 0.7-1.0：强相关
+    - r > 0：正相关（同向变化）
+    - r < 0：负相关（反向变化）
+    - r = 0：无线性相关
+    
+    💡 使用场景：
+    - 探索性数据分析（EDA）
+    - 回归分析前的变量筛选
+    - 识别多重共线性问题
+    - 构建投资组合（寻找低相关资产）
+    - 因子分析和主成分分析的前置步骤
+    
+    ⚠️ 注意事项：
+    - 相关≠因果：高相关不代表因果关系
+    - 皮尔逊相关仅衡量线性关系，可能错过非线性关系
+    - 异常值会显著影响皮尔逊相关系数
+    - 回归分析中，自变量间相关系数>0.8可能导致多重共线性
+    - 小样本(<30)的相关系数可能不稳定
+    
+    📖 实际应用示例：
+    - 营销分析：广告支出与销售额的相关性
+    - 金融分析：不同股票收益率之间的相关性
+    - 经济研究：GDP增长与失业率的关系
+    - 多重共线性检测：回归模型中自变量间的相关性
 
     Args:
-        data: 变量数据
-        method: 相关系数类型
+        data: 变量数据字典
+        method: 相关系数类型（pearson/spearman/kendall）
         ctx: MCP上下文对象
     """
     await ctx.info(f"开始相关性分析: {method}")