# 中国股票市场行情 MCP 服务

这是一个基于 MCP (Model Context Protocol) 的中国股票市场行情服务，提供实时股票价格、历史数据、市场指数、技术分析等全面功能。

## 🚀 功能特性

### 📊 **基础数据**
- 🔄 **实时行情**: 获取A股实时价格、涨跌幅、成交量等数据
- 📈 **历史数据**: 查询股票历史K线数据（日线、周线、月线）
- 📊 **市场指数**: 获取上证指数、深证成指、创业板指、科创50、沪深300、中证500等主要指数
- 🔍 **股票搜索**: 根据股票名称或代码搜索相关股票
- ⏰ **时间服务**: 获取当前时间、交易状态、交易日判断等时间相关信息

### 📅 **智能交易日历**
- 🗓️ **真实交易日历**: 使用akshare获取中国股市真实交易日历
- 🎯 **节假日识别**: 自动识别春节、国庆等法定节假日和调休安排
- 📊 **交易日计算**: 基于实际交易日数量计算历史数据范围
- 🔄 **智能回退**: 当交易日历不可用时，自动回退到简化判断逻辑
- ⚡ **缓存优化**: 交易日历数据本地缓存，提高查询效率

### 📈 **技术分析**
- 📊 **移动平均线**: MA5、MA10、MA20、MA60
- 📈 **MACD指标**: DIF、DEA、MACD柱状图
- 📉 **RSI指标**: 相对强弱指数
- 🎯 **KDJ指标**: 随机指标K、D、J值
- 📊 **布林带**: 上轨、中轨、下轨
- 🎨 **技术状态**: 自动分析多头/空头排列、金叉死叉、超买超卖等

### 🔧 **增强功能**
- 📋 **综合分析**: 一键获取完整的股票分析报告
- ⚡ **数据缓存**: 内置缓存机制，提高数据获取效率
- 🛡️ **错误处理**: 完善的异常处理和NaN值处理
- 🎨 **智能分析**: 自动判断技术指标状态和趋势
- 📊 **综合评价**: 基于多个指标的综合信号分析
- 🔄 **混合数据源**: 智能切换数据源，确保数据完整性

### 🛡️ **安全与限制**
- 🚦 **请求频率限制**: 每分钟最多100次请求，防止过度使用
- 📏 **数据量限制**: 历史数据最大365天，技术指标最大120天
- 🔒 **输入验证**: 严格验证股票代码格式和参数范围
- 🛡️ **错误信息清理**: 自动清理敏感信息，避免内部细节泄露
- ⚡ **智能缓存**: 5分钟数据缓存，减少重复请求

## 📦 安装依赖

```bash
# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装项目依赖
uv sync --no-install-project
```

## 🔧 使用方法

### MCP客户端配置

在您的MCP客户端配置文件中添加以下配置：

```json
{
  "mcpServers": {
    "stock-market": {
      "command": "uv",
      "args": ["--directory", "PATH_TO_YOUR_STOCK_MCP_SERVICE/stock_mcp_service", "run", "stock_mcp_server.py"],
      "transportType": "stdio"
    }
  }
}
```

**注意**: 请将路径 `PATH_TO_YOUR_STOCK_MCP_SERVICE/stock_mcp_service` 替换为您的实际项目路径。

### 手动启动服务器（调试用）

```bash
# 使用uv运行
uv run python stock_mcp_server.py
```

## 🛠️ 可用工具

### 1. 获取当前时间
```json
{
  "name": "get_current_time",
  "arguments": {
    "timezone": "Asia/Shanghai"
  }
}
```

### 2. 获取股票实时行情
```json
{
  "name": "get_stock_realtime",
  "arguments": {
    "symbol": "600519"
  }
}
```

### 3. 获取股票历史数据（支持交易日计算）
```json
{
  "name": "get_stock_history", 
  "arguments": {
    "symbol": "600519",
    "period": "daily",
    "days": 30
  }
}
```

或使用具体日期：
```json
{
  "name": "get_stock_history", 
  "arguments": {
    "symbol": "600519",
    "period": "daily",
    "start_date": "20240101",
    "end_date": "20240131"
  }
}
```

### 4. 获取市场指数
```json
{
  "name": "get_market_index",
  "arguments": {
    "random_string": "dummy"
  }
}
```

### 5. 搜索股票
```json
{
  "name": "search_stock",
  "arguments": {
    "keyword": "茅台"
  }
}
```

### 6. 获取技术指标（限制最大120天）
```json
{
  "name": "get_technical_indicators",
  "arguments": {
    "symbol": "600519",
    "period": "daily",
    "days": 30
  }
}
```

### 7. 获取综合分析
```json
{
  "name": "get_comprehensive_analysis",
  "arguments": {
    "symbol": "600519"
  }
}
```

## 📊 技术指标说明

### 移动平均线 (MA)
- **MA5**: 5日移动平均线
- **MA10**: 10日移动平均线  
- **MA20**: 20日移动平均线
- **MA60**: 60日移动平均线

### MACD指标
- **DIF**: 快线，12日EMA - 26日EMA
- **DEA**: 慢线，DIF的9日EMA
- **MACD**: 柱状图，(DIF - DEA) × 2

### RSI指标
- 相对强弱指数，范围0-100
- >80: 超买区域
- <20: 超卖区域

### KDJ指标
- **K值**: 快速随机指标
- **D值**: 慢速随机指标
- **J值**: 3K - 2D

### 布林带
- **上轨**: 中轨 + 2倍标准差
- **中轨**: 20日移动平均线
- **下轨**: 中轨 - 2倍标准差

## ⏰ 时间服务功能

### 智能交易日历
- **真实交易日历**: 使用akshare的`tool_trade_date_hist_sina()`获取官方交易日历
- **节假日处理**: 自动处理春节、国庆、清明、端午、中秋等法定节假日
- **调休识别**: 识别因节假日调休导致的工作日非交易日情况
- **缓存机制**: 交易日历按年缓存，每日自动更新

### 时间信息
- **当前时间**: 北京时间（Asia/Shanghai时区）
- **时间戳**: Unix时间戳
- **交易日判断**: 基于真实交易日历判断是否为交易日
- **交易时间判断**: 自动判断是否在交易时间内
  - 上午：9:30-11:30
  - 下午：13:00-15:00
- **下一个交易日**: 自动计算下一个交易日期

### 智能日期范围
- **基于交易日的范围计算**: `get_date_range_for_trading_days()`方法
- **自然日范围计算**: `get_date_range_for_days()`方法
- **智能回退**: 当交易日历不可用时，自动使用自然日计算
- **防止无限循环**: 内置最大查找天数限制

## 🎯 技术状态分析

系统会自动分析以下技术状态：

- **MA趋势**: 多头排列/空头排列/震荡整理
- **MACD**: 金叉向上/死叉向下/震荡调整
- **RSI**: 超买区域/超卖区域/强势区域/弱势区域
- **KDJ**: 超买区域/超卖区域/金叉向上/死叉向下
- **布林带**: 突破上轨/跌破下轨/中轨上方/中轨下方
- **综合评价**: 偏多信号/偏空信号/信号中性

## 🔄 数据源优化

### 混合数据源策略
为确保数据完整性，系统采用智能数据源切换：

- **实时行情**: 优先使用`stock_zh_a_spot_em()`
- **历史数据**: 使用`stock_zh_a_hist()`
- **市场指数**: 混合使用现货数据和历史数据接口
- **交易日历**: 使用`tool_trade_date_hist_sina()`

### 数据处理优化
- **NaN值处理**: 自动处理pandas中的NaN值，转换为合适的默认值
- **类型转换**: 安全的数据类型转换，避免转换错误
- **数据验证**: 验证数据完整性和有效性

## 🛡️ 安全注意事项

### 部署安全
⚠️ **重要**: 在生产环境部署此MCP服务时，请注意以下安全事项：

#### 网络安全
- 🔒 **不要直接暴露到公网**: 此服务设计为本地或内网使用
- 🛡️ **使用防火墙**: 如需网络访问，请配置适当的防火墙规则
- 🔐 **VPN访问**: 建议通过VPN或专用网络访问
- 📡 **代理服务**: 如需公网访问，请使用反向代理并配置SSL

#### 访问控制
- 👥 **用户认证**: 在生产环境中实施用户认证机制
- 🎫 **访问令牌**: 考虑使用API密钥或访问令牌
- 📊 **审计日志**: 记录所有API调用和用户活动
- ⏱️ **会话管理**: 实施适当的会话超时机制

#### 资源保护
- 🚦 **请求限制**: 已内置每分钟100次请求限制
- 💾 **内存监控**: 监控服务内存使用情况
- 📈 **性能监控**: 监控API响应时间和错误率
- 🔄 **自动重启**: 配置服务异常时的自动重启机制

#### 数据安全
- 🔒 **敏感信息**: 错误消息已自动清理敏感信息
- 📝 **日志安全**: 确保日志文件不包含敏感数据
- 🗄️ **数据存储**: 缓存数据仅存储在内存中，不持久化
- 🔐 **传输加密**: 在网络传输中使用HTTPS

#### 监控建议
- 📊 **实时监控**: 监控服务状态和性能指标
- 🚨 **异常告警**: 配置异常情况的告警机制
- 📈 **使用统计**: 跟踪API使用情况和趋势
- 🔍 **安全扫描**: 定期进行安全漏洞扫描

### 使用限制
- 📏 **历史数据**: 最大365天限制
- 🔧 **技术指标**: 最大120天限制
- 🚦 **请求频率**: 每分钟最多100次请求
- 💾 **缓存时间**: 数据缓存5分钟自动过期

## 🔧 参数说明

### 历史数据参数
- `symbol`: 6位数字股票代码（必需）
- `period`: 数据周期，支持 "daily"、"weekly"、"monthly"
- `days`: 获取天数，基于交易日计算，优先级高于start_date
- `start_date`: 开始日期，格式YYYYMMDD
- `end_date`: 结束日期，格式YYYYMMDD

### 技术指标参数
- `symbol`: 6位数字股票代码（必需）
- `period`: 数据周期，支持 "daily"、"weekly"、"monthly"
- `days`: 获取天数，默认30天，最大120天

### 搜索参数
- `keyword`: 搜索关键词，支持股票名称或代码片段
- 返回最多20条匹配结果

## 📝 更新日志

### v2.0.0 - 安全与功能增强版
- ✅ 集成akshare真实交易日历
- ✅ 添加基于交易日的日期范围计算
- ✅ 实施请求频率限制（每分钟100次）
- ✅ 添加数据量上限保护（历史365天，技术指标120天）
- ✅ 优化错误消息，清理敏感信息
- ✅ 增强输入验证和参数限制
- ✅ 改进缓存机制和数据处理
- ✅ 添加安全部署指南

### v1.0.0 - 基础功能版
- ✅ 实时股票行情查询
- ✅ 历史数据获取
- ✅ 市场指数监控
- ✅ 股票搜索功能
- ✅ 技术指标计算
- ✅ 综合分析报告

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## ⚠️ 免责声明

本服务提供的股票数据仅供参考，不构成投资建议。投资有风险，入市需谨慎。使用者应当根据自己的判断做出投资决策，并承担相应的投资风险。