Interactive Brokers MCP Server

# 快照状态工具实现总结

## 概述

已成功实现了三个 MCP 工具，用于从数据库中检查期权链快照状态。这些工具替代了之前的 `NOT_IMPLEMENTED` 状态，现在可以从数据库中读取和分析快照数据。

## 实现的工具

### 1. `list_option_snapshots`

**功能**：从数据库列出最近的期权链快照

**参数**：
- `symbol`: 可选的符号过滤器（如果未提供，显示所有符号）
- `limit`: 返回的最大快照数量（默认：10）

**返回值**：
- 快照列表，包含以下信息：
  - `symbol`: 股票符号
  - `timestamp`: 快照时间戳
  - `underlying_price`: 标的资产价格
  - `option_count`: 期权合约数量
  - `age_minutes`: 快照年龄（分钟）
  - `total_calls`: 看涨期权数量
  - `total_puts`: 看跌期权数量
  - `avg_call_iv`: 看涨期权平均隐含波动率
  - `avg_put_iv`: 看跌期权平均隐含波动率
  - `iv_skew`: 波动率偏斜
  - `total_volume`: 总成交量
  - `total_open_interest`: 总未平仓量
  - `market_data_type`: 市场数据类型

**数据源**：
- 使用 `option_chain_repo.get_by_symbol()` 获取特定符号的快照
- 使用 SQLAlchemy `select()` 查询获取所有快照

### 2. `get_snapshot_status`

**功能**：获取特定符号的最新快照详细状态

**参数**：
- `symbol`: 要检查的股票符号

**返回值**：
- 详细快照信息：
  - `exists`: 快照是否存在
  - `timestamp`: 快照创建时间
  - `age_minutes`: 快照年龄（分钟）
  - `underlying_price`: 标的资产价格
  - `option_count`: 期权合约数量
  - `total_calls`: 看涨期权数量
  - `total_puts`: 看跌期权数量
  - `avg_call_iv`: 看涨期权平均隐含波动率
  - `avg_put_iv`: 看跌期权平均隐含波动率
  - `iv_skew`: 波动率偏斜
  - `total_volume`: 总成交量
  - `total_open_interest`: 总未平仓量
  - `market_data_type`: 市场数据类型
  - `data_quality`: 数据质量评估
    - `score`: 质量评分（0-100）
    - `rating`: 质量等级（excellent/good/fair/poor）
    - `issues`: 数据质量问题列表
  - `next_scheduled`: 下次调度时间

**数据质量评估**：
- 数据新鲜度（40分）：≤60分钟得满分，≤240分钟得20分
- 期权数量（30分）：≥20个得满分，≥10个得15分
- Greeks数据（20分）：有数据得满分
- 价格数据（10分）：有bid/ask得满分

**数据源**：
- 使用 `option_chain_repo.get_latest()` 获取最新快照
- 结合 `schedule_status` 获取下次调度信息

### 3. `check_snapshot_freshness`

**功能**：检查所有可用快照的新鲜度

**参数**：
- `max_age_minutes`: 认为是新鲜的最大年龄（分钟，默认：60）

**返回值**：
- 新鲜度摘要：
  - `total_symbols`: 有快照的符号总数
  - `fresh_count`: 新鲜快照数量
  - `stale_count`: 过期快照数量
  - `max_age_minutes`: 使用的最大年龄阈值
  - `details`: 每个符号的详细信息列表
  - `summary`: 汇总统计
    - `fresh_percentage`: 新鲜快照百分比
    - `stale_percentage`: 过期快照百分比

**详细信息包括**：
- `symbol`: 股票符号
- `timestamp`: 快照时间戳
- `age_minutes`: 快照年龄
- `is_fresh`: 是否新鲜
- `underlying_price`: 标的资产价格
- `option_count`: 期权合约数量
- `total_calls`: 看涨期权数量
- `total_puts`: 看跌期权数量
- `market_data_type`: 市场数据类型

**数据源**：
- 使用 SQLAlchemy 查询获取所有快照
- 按符号分组，每符号取最新快照
- 按新鲜度排序（新鲜的在前面）

## 数据库集成

### 使用的库和模块

```python
from ibkr_mcp.infrastructure.repositories import get_db_session, option_chain_repo
from datetime import datetime, timezone
from sqlalchemy import select
```

### 错误处理

所有工具都包含完整的错误处理：

1. **导入错误** (`ImportError`)：
   - 当数据库仓库不可用时返回错误
   - 提示检查数据库配置

2. **一般异常** (`Exception`)：
   - 捕获所有其他数据库错误
   - 返回详细的错误信息

### 数据库兼容性

- 支持 SQLite（默认）
- 支持 PostgreSQL
- 支持 MySQL
- 通过 `DatabaseManager` 自动处理不同数据库

## 使用示例

### 列出快照
```python
# 列出所有符号的最新快照
list_option_snapshots()

# 列出特定符号的快照
list_option_snapshots(symbol="AAPL", limit=5)
```

### 获取快照状态
```python
# 获取 AAPL 的最新快照状态
get_snapshot_status(symbol="AAPL")
```

### 检查快照新鲜度
```python
# 检查所有快照，60分钟为新鲜阈值
check_snapshot_freshness()

# 使用自定义新鲜阈值（120分钟）
check_snapshot_freshness(max_age_minutes=120)
```

## 依赖关系

这些工具依赖于：

1. **数据库模型**：
   - `OptionChainSnapshot` 模型
   - `option_chain_repo` 仓库实例

2. **数据库连接**：
   - `get_db_session()` 上下文管理器
   - `db_manager` 数据库管理器

3. **调度器状态**：
   - `option_data_service.get_schedule_status()`
   - 用于获取下次调度时间

## 迁移状态

- ✅ `list_option_snapshots`: 从 TODO 状态迁移到完整实现
- ✅ `get_snapshot_status`: 从 TODO 状态迁移到完整实现
- ✅ `check_snapshot_freshness`: 从 TODO 状态迁移到完整实现

所有三个工具现在都是完全功能的 MCP 工具，可以从数据库中读取和显示期权链快照数据。