内容
# @romaco/mcp
MCP 服务器，用于 [romaco-charts](https://www.npmjs.com/package/romaco-charts)。通过 Claude、Cursor 或任何与 MCP 兼容的 AI 代理控制您的交易图表。
```bash
npx @romaco/mcp
```
---
## 理念
Romaco MCP 是**以压缩为优先**的。工具返回功能和决策，而不是原始的 OHLCV 数据。每个工具的典型输出都小于 **2 KB**。原始有效载荷（完整的图表状态、快照、所有柱状图指标系列）存在，但**需要授权** `acknowledgeHighTokenCost: true` —— 代理必须有意识地选择加入，用户必须明确请求原始数据。
规则：*代理永远不会计算，它总是查询*。推理特征的代理不能臆造价格；给定 70 KB 的原始 OHLCV 转储的代理将在完成思考之前烧毁其上下文窗口。
### 成本表
| 工具 | 默认 | 授权原始数据（启用 `acknowledgeHighTokenCost:true`） |
|---|---|---|
| `romaco_analyze_market` | ~3–5 KB 压缩 MarketSummary | — |
| `romaco_thesis` | <2 KB 计算的牛/熊辩论 + 裁决 + 设置 | 增强的服务器端论文（专业版） |
| `romaco_find_levels` | <500 B | — |
| `romaco_detect_patterns` | <2 KB（修剪后的匹配） | 完整的匹配结果和锚点 `points[]` |
| `romaco_setup_chart` | <5 KB（设置日志 + 摘要） | — |
| `romaco_load_candles` | <200 B 确认 | — |
| `romaco_calculate_position_size` | <1 KB | — |
| `romaco_list_templates` | ~4.5 KB 静态目录 | — |
| `romaco_list_panes` | <1 KB | — |
| `romaco_get_chart_context` | ~1 KB 快照 | ~80 KB 完整有效载荷 |
| `romaco_get_visible_candles` | <1 KB 范围摘要 | ~70 KB 原始 OHLCV |
| `romaco_get_indicator_values` | <500 B 最后/前/增量/状态 | ~10 KB 每柱状图系列 |
| `romaco_capture_snapshot` | 错误（必须确认） | 300–800 KB base64 图像 |
| `romaco_add_*`, `romaco_set_*`, `romaco_clear_*`, `romaco_go_to_*`, `romaco_open_paper_position` | <100 B 确认消息 | — |
## 30 秒启动
```bash
# 1. 安装
npm install -g @romaco/mcp
# 2. 连接到 Claude Code（从项目根目录运行）
cat > .mcp.json <<'EOF'
{ "mcpServers": { "romaco": { "command": "romaco-mcp" } } }
EOF
```
然后启动 Claude Code 并提示：
> 使用 `romaco_setup_chart` 分析 AAPL 日线图，并使用 `trend_analysis` 预设。
就这样。MCP 服务器获取 yfinance 数据（带有磁盘缓存 + cookie/crumb 握手），运行完整的技术分析，并返回压缩的 MarketSummary（约 500 个令牌）给 Claude。无需 429 错误，无需手动身份验证。
### 实时图表控制（可选）
要让 Claude 控制实时图表 —— 绘图、指标、警报在您的浏览器中可见 —— 在 `TradingTerminal` 旁边安装 `<McpBridge />`：
```tsx
import { TradingTerminal, McpBridge, type TradingTerminalRef } from 'romaco-charts/react';
import { useRef } from 'react';
function App() {
const ref = useRef<TradingTerminalRef | null>(null);
return (
<>
<TradingTerminal ref={ref} data={candles} symbol="AAPL" />
<McpBridge chartRef={ref} />
</>
);
}
```
参见 [examples/pro-volatility-scanner](./examples/pro-volatility-scanner) 以获取完整的设置。安装 `<McpBridge />` 后，图表桥接工具（`add_indicator`、`add_drawing`、`add_alert`、`capture_snapshot` 等）可用。
### 数据缓存
每次成功的 `yfinance` 获取都会缓存到 `~/.romaco/cache/`，每个时间范围的 TTL（1m→1min，1h→1h，1d→24h，...）。N 个小部件请求相同的符号会触发**一次**上游获取。随时使用 `rm -rf ~/.romaco/cache` 清除缓存，或使用 `ROMACO_CACHE_DIR=/tmp/cache` 覆盖位置。
## 功能
公开 20+ MCP 工具，分为两类：
**无头工具** —— 无需浏览器，加载数据并在服务器端运行分析：
- `romaco_setup_chart` —— 一键设置：加载 + 预设 + 分析（推荐首选调用）
- `romaco_load_candles` —— 从 Yahoo Finance 获取 OHLCV 数据（免费）或传递您自己的数组
- `romaco_analyze_market` —— 完整的技术分析：趋势、支撑/阻力水平、RSI/MACD/背离、波动性、模式
- `romaco_thesis` —— 计算的牛/熊辩论 → 裁决（做多/做空/观望）+ 置信度 + 进场/止损/目标设置；当风险回报率较差时保持观望（不会伪造信号）
- `romaco_find_levels` —— 通过 K-means + 交易量配置文件（POC/VAH/VAL）寻找支撑/阻力
- `romaco_detect_patterns` —— H&S、双顶/底、三角形、旗帜
- `romaco_calculate_position_size` —— 纯数学风险基于风险回报率 + 保本胜率的仓位测算
- `romaco_list_templates` —— 绘图模板目录（趋势线、斐波那契、通道等）
**图表桥接工具** —— 控制实时 Romaco 图表：
- `romaco_add_indicator` —— EMA、RSI、MACD、Bollinger、ATR、29+ 指标
- `romaco_add_drawing` —— 趋势线、斐波那契、水平线、通道、矩形
- `romaco_add_alert` —— 价格警报，带方向（上方/下方/交叉）
- `romaco_capture_snapshot` —— PNG/JPEG base64 用于视觉 LLM
- `romaco_open_paper_position` —— 模拟做多/做空，带止损/止盈
- `romaco_get_chart_context` —— 完整的图表状态，JSON 格式
- `romaco_get_visible_candles` —— 当前视口的 OHLCV
- `romaco_set_zoom` / `romaco_reset_view` —— 缩放控制
- `romaco_clear_drawings` —— 删除所有绘图
- `romaco_list_panes` —— 枚举主 + 子面板（例如 RSI 子面板 ID）
- `romaco_get_indicator_values` —— 读取计算的指标系列（按 ID 或名称）
- `romaco_go_to_timestamp` —— 跳转到给定时间戳
---
## 安装
### Claude 桌面版
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"romaco": {
"command": "npx",
"args": ["-y", "@romaco/mcp"]
}
}
}
```
重启 Claude 桌面版。
### Claude Code
```bash
claude mcp add romaco -- npx -y @romaco/mcp
```
或添加到项目的 `.mcp.json`:
```json
{
"mcpServers": {
"romaco": {
"command": "npx",
"args": ["-y", "@romaco/mcp"]
}
}
}
```
### Cursor / 其他 MCP 客户端
任何支持 stdio MCP 服务器的客户端都可以使用。指向 `npx @romaco/mcp`。
---
## 用例
### 无头分析（无需浏览器）
```
加载 500 根 AAPL 1h 蜡烛线，从 yfinance 获取，然后分析市场。
```
Claude 将调用：
1. `romaco_load_candles` → 从 Yahoo Finance 获取数据
2. `romaco_analyze_market` → 返回压缩的 MarketSummary（约 500 个令牌）
3. `romaco_find_levels` → 支撑/阻力区域，POC，VAH，VAL
4. 根据特征推理 → 告诉你它看到了什么
### 实时图表控制（带浏览器）
在图表应用中添加 `<McpBridge />`：
```tsx
import { TradingTerminal, McpBridge } from 'romaco-charts/react';
function App() {
const ref = useRef(null);
return (
<>
<TradingTerminal ref={ref} symbol="AAPL" timeframe="1h" datafeed={myDatafeed} />
<McpBridge chartRef={ref} />
</>
);
}
```
然后从 Claude：
```
添加 EMA 20 和 RSI 14 到图表，绘制从最后一个波动低点到高点的斐波那契，
并捕获快照以便我查看。
```
---
## 数据源
| 源 | 认证 | 覆盖范围 |
|--------|------|----------|
| `yfinance` | 无（默认） | 股票、ETF、加密货币、外汇、指数 —— 延迟数据 |
| `raw` | 无 | 传递您自己的 OHLCV 数组 |
**自带密钥（BYOK）** - 即将来临的 v1.1：Alpaca、Polygon.io、FMP。
---
## 配置
| 选项 | 默认值 | 如何设置 |
|--------|---------|-----------|
| WebSocket 端口 | `7399` | `--port 3200` 或 `ROMACO_MCP_PORT=3200` |
| `ROMACO_TOKEN` | _(无 → 免费)_ | 来自 [romaco.io](https://romaco.io) 的 API 密钥 —— 解锁专业版 |
| `ROMACO_API_URL` | `http://localhost:8000` | ROA-I 后端；生产环境：`https://api.romaco.tech` |
```bash
# 自定义端口
npx @romaco/mcp --port 3200
# 或通过环境变量
ROMACO_MCP_PORT=3200 npx @romaco/mcp
```
在 `<McpBridge port={3200} />` 中设置相同的端口。
---
## 免费 vs 专业版（ROA-I）
此 MCP 是**免费钩子**。它完全独立运行 —— 分析在本地计算，并受限于您的代理使用的任何模型。
| | 免费 | 专业版（`ROMACO_TOKEN`） |
|---|------|----------------------|
| 数据 | `yfinance` / `raw` | 相同 |
| 分析 | 本地计算 (`src/compression`) | 委托给 **ROA-I** 在后端 |
| 工具 | 这里列出的工具 | + ROA-I 的专属后端工具（深度数学，推理代理） |
设置 `ROMACO_TOKEN` 后，分析工具（以 `romaco_analyze_market` 开头）会将繁重计算转发给 ROA-I，地址为 `ROMACO_API_URL`。无令牌或后端无法访问 → 回退到本地计算，因此免费路径永远不会中断。
在 [romaco.io](https://romaco.io) 获取密钥。参见 `.env.example`。
---
## 示例提示
**机构分析：**
> "加载 TSLA 4h 蜡烛线，从 yfinance 获取，分析市场，查找关键水平，检测任何图表模式，然后在图表上绘制斐波那契回撤线，并在 0.618 水平添加警报。"
**条件自动化：**
> "加载 AAPL 15m 蜡烛线，运行完整分析。如果 RSI 显示看涨背离且价格接近支撑水平，则开仓 100 股纸质多头，止损设在 Volume Profile 的 VAL 处。"
**模式扫描器：**
> "加载 SPY 1d 蜡烛线并检测模式。对于发现的任何头肩形态，告诉我目标价格和失效水平。"
---
## 要求
- Node.js >= 18
- 对于图表桥接工具：romaco-charts >= 1.0.0-beta.6，您的应用中包含 `<McpBridge />`
---
## 链接
- [romaco-charts npm](https://www.npmjs.com/package/romaco-charts)
- [文档](https://romaco.io)
- [GitHub](https://github.com/romaco-labs/romaco-mcp)
