Metadata-Version: 2.4
Name: mcp-cb-arbitrage
Version: 2.2.0
Summary: 可转债套利决策引擎 MCP Server — 机会扫描 + 深度分析 + 强赎应对
Author: cb-trader
License: MIT
Project-URL: Homepage, https://github.com/cb-trader/mcp-cb-arbitrage
Project-URL: Repository, https://github.com/cb-trader/mcp-cb-arbitrage
Keywords: mcp,convertible-bond,arbitrage,china-stock,akshare
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: akshare>=1.14.0
Requires-Dist: pandas>=2.0.0

# mcp-cb-arbitrage — 可转债套利决策 MCP Server（v2）

> 基于 AKShare（完全免费，无需 API Key），为中国 A 股可转债投资者提供**决策级**套利信号。
> 从"数据查询"升级到"行动建议"——不只是告诉你数据，还告诉你该怎么做。

## 功能特性（v2）

| 工具 | 功能 | 回答的问题 |
|------|------|-----------|
| `cb_opportunity_scan` | 套利机会扫描 | "现在什么值得买？" — 多维度打分排名，综合溢价率、价格、规模、评级 |
| `cb_deep_analysis` | 个债深度分析 | "XX 转债该不该买/卖？" — 72 列基本面数据 + 转股价值 + 纯债价值 + 正股联动 |
| `cb_redemption_action` | 强赎行动助手 | "强赎了我怎么办？" — 转股 vs 卖出的盈亏计算 + 最后交易日倒计时 |

### 工具详情

#### `cb_opportunity_scan` — 套利机会扫描
- **输入**：`strategy`（双低/三低/高YTM/低溢价）、`top_n`（返回数量）、`min_price`/`max_price`（价格区间）
- **输出**：按策略公式排序的转债列表，含综合评分、各维度分项得分
- **数据源**：`bond_zh_hs_cov_spot()`（337 只实时行情）+ `bond_cb_redeem_jsl()`（324 条强赎数据）

#### `cb_deep_analysis` — 个债深度分析
- **输入**：`keyword`（转债名称或代码）
- **输出**：72 列深度数据，包括：转股价值、纯债价值估算、正股价趋势、强赎进度、下修概率、到期收益率
- **数据源**：多接口聚合（行情 + 强赎 + 集思录补充数据）

#### `cb_redemption_action` — 强赎行动助手
- **输入**：`keyword`（转债名称或代码，可选，不填则显示所有已公告强赎）
- **输出**：转股 vs 卖出的盈亏对比计算、最后交易日倒计时、行动建议
- **数据源**：`bond_cb_redeem_jsl()`（集思录原生强赎数据，含天计数和条款文本）

## 安装方式

### 方式一：Claude Code / Cursor 配置（推荐）

在 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "cb-arbitrage": {
      "command": "python",
      "args": ["D:/LLM/mcp-cb-arbitrage/server.py"],
      "env": {}
    }
  }
}
```

### 方式二：手动运行

```bash
# 克隆仓库
git clone https://github.com/YOUR_USERNAME/mcp-cb-arbitrage.git
cd mcp-cb-arbitrage

# 安装依赖
pip install -r requirements.txt

# 运行服务器
python server.py
```

### 方式三：Smithery 一键安装

```bash
npx smithery add mcp-cb-arbitrage --client claude
```

## 依赖要求

- Python >= 3.10
- mcp >= 1.0.0
- akshare >= 1.14.0
- pandas >= 2.0.0

## 使用示例

### 1. 扫描套利机会

```
用户：帮我看看今天有哪些可转债值得买？
AI：调用 cb_opportunity_scan(strategy="双低", top_n=10)
返回：按双低值排序的转债列表，含综合评分和分项得分
```

### 2. 深度分析个债

```
用户：兴瑞转债现在能买吗？
AI：调用 cb_deep_analysis(keyword="兴瑞转债")
返回：72 列深度分析，含转股价值、纯债价值、强赎进度、到期收益率
```

### 3. 强赎行动建议

```
用户：科利转债要强赎了，我该怎么办？
AI：调用 cb_redemption_action(keyword="科利转债")
返回：转股 vs 卖出的盈亏对比 + 最后交易日倒计时 + 行动建议
```

### 4. 批量强赎预警

```
用户：最近有哪些转债要强赎？
AI：调用 cb_redemption_action()
返回：所有已公告强赎的转债列表 + 行动建议
```

## 数据来源

| 数据 | 接口 | 规模 | 成本 |
|------|------|------|------|
| 实时行情 | `akshare.bond_zh_hs_cov_spot()` | 337 只活跃转债 | 免费 |
| 强赎信息 | `akshare.bond_cb_redeem_jsl()` | 324 条强赎数据 | 免费 |
| 集思录补充 | `akshare.bond_cb_jsl()` | 30 条精选数据 | 免费（无需 Cookie） |

- **数据更新频率**：实时（AKShare 直连交易所数据）
- **成本**：完全免费，无需 API Key，无需注册

## 与竞品对比

| 对比项 | mcp-cb-arbitrage (v2) | cb-strategy-mcp |
|--------|----------------------|-----------------|
| **产品定位** | 决策支撑（告诉你该怎么做） | 策略排名（告诉你排序） |
| **数据源** | AKShare 直连（已验证无代理问题） | 东方财富（可能被 Clash 等代理拦截） |
| **强赎数据** | 集思录**原生**数据（含天计数、条款文本） | **估算**触发价（转股价×1.3） |
| **强赎判断** | 原生状态（已公告/要公告/不公告） | 自行计算 ratio 阈值（80%/100%/130%） |
| **Windows 兼容** | ✅ 已测试通过 | ❌ emoji 编码 bug（GBK 环境报错） |
| **行动建议** | ✅ 转股 vs 卖出盈亏计算 | ❌ 无 |
| **深度分析** | ✅ 72 列个债分析 | ❌ 无（仅排名） |
| **缓存机制** | 60 秒内存缓存 | 120 秒内存缓存 |

### 竞品实测发现（任务 #8）

- **cb-strategy-mcp** 的 `early_redemption_monitor()` 有 Unicode bug：Windows GBK 环境下 emoji（🔥⚠️）编码报错
- 竞品的强赎触发价是估算值（转股价×1.3），我们使用集思录原生数据更准确
- 竞品依赖 `ak.bond_zh_cov()`（东方财富），在有代理的环境下可能连接失败

## 定价策略

- **免费版**：每天 5 次调用
- **Pro 版**：$19.9/月，无限次调用（规划中）

## v2 Roadmap

| 阶段 | 功能 | 预计时间 |
|------|------|----------|
| **v2.0** ✅ | 三个核心工具（机会扫描、深度分析、强赎行动） | 已完成设计 |
| **v2.1** | 历史回测：双低策略过去 1 年收益率 | 2 周 |
| **v2.2** | 定时扫描 + 推送：每日自动扫描并推送套利信号 | 1 个月 |
| **v2.3** | LOF 套利扩展：复用架构，增加 LOF 折溢价监控 | 2 个月 |
| **v3.0** | 智能问答：自然语言对话式投资分析 | 3 个月 |

## 许可证

MIT License

## 相关链接

- [AKShare 官方文档](https://akshare.akfamily.xyz/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [GitHub 仓库](https://github.com/YOUR_USERNAME/mcp-cb-arbitrage)
- [Smithery 页面](https://smithery.ai/)（发布后更新链接）
