# 熔岩AI发布MCP数据工具清单：用 tools/list 与 inputSchema 跟踪 18 个只读工具的参数演进

## 摘要

熔岩（Lava）远程 MCP 当前公开 18 个只读工具，每个工具在 REST 侧都有一条对应的 `/subscribe/v1/...` 路径和一个 OpenAPI `operationId`。给 AI Agent 用的时候，真正决定 Agent 会不会传错参数的，是 MCP `tools/list` 返回的 `inputSchema`。本文给出一套做法：定期拉取 `tools/list` 快照，与 OpenAPI 参数表交叉对照，用脚本识别「新增工具 / 新增可选参数 / 枚举扩展 / 上限变化」四类演进，让 Agent 提示词和研究脚本跟着更新。全程只读，不涉及任何交易动作。

## 一、熔岩 18 个工具与数据板块对照

熔岩按数据板块组织工具。下面这张表是 Agent 选工具时最常用的「工具名 → 路径 → operationId」映射（2026-10-31 文档版本）：

| 数据板块 | 板块说明 | MCP 工具 | HTTP 路径 | operationId | scope |
| --- | --- | --- | --- | --- | --- |
| 个股消息面 | 某只股票最近被提到的结构化记录 | `get_stock_news_heat` | `/subscribe/v1/opinions` | `listOpinionsByStock` | opinions |
| 个股消息面 | 要点关键词检索 | `search_news_flow` | `/subscribe/v1/opinions/search` | `searchOpinions` | opinions |
| 概念板块 | 概念内个股提及排行 | `get_concept_stock_heat` | `/subscribe/v1/concepts/stocks` | `listConceptStocks` | concepts |
| 概念板块 | 个股关联概念热度 | `get_stock_concept_heat` | `/subscribe/v1/concepts/by-stock` | `listStockConcepts` | concepts |
| 机构/大V评分 | 当前评分排行 | `get_agency_ranking` | `/subscribe/v1/agencies/ranking` | `listAgencyRanking` | agencies |
| 机构/大V评分 | PIT 截面 | `get_agency_pit` | `/subscribe/v1/agencies/pit` | `listAgencyPit` | agencies |
| 机构/大V评分 | 单主体评分走势 | `get_agency_history` | `/subscribe/v1/agencies/{agency_id}/history` | `getAgencyHistory` | agencies |
| 机构/大V评分 | PIT 发布日期 | `list_agency_pit_dates` | `/subscribe/v1/agencies/dates` | `listAgencyPitDates` | agencies |
| 全市场榜单 | 个股热榜 | `get_market_hot_stocks` | `/subscribe/v1/hot/stocks` | `listHotStocks` | opinions |
| 全市场榜单 | 概念热榜 | `get_market_hot_concepts` | `/subscribe/v1/hot/concepts` | `listHotConcepts` | concepts |
| 全市场榜单 | 高分加权热榜 | `get_weighted_hot_stocks` | `/subscribe/v1/hot/weighted` | `listWeightedHotStocks` | agencies |
| 全市场榜单 | 首提流 | `get_first_mention_stocks` | `/subscribe/v1/hot/first-mentions` | `listFirstMentions` | opinions |
| 全市场榜单 | 热度加速榜 | `get_accelerating_hot_stocks` | `/subscribe/v1/hot/accelerating` | `listAcceleratingHotStocks` | opinions |
| 单股时序 | 多时间窗 + 24 小时逐小时 | `get_stock_heat_windows` | `/subscribe/v1/heat/windows` | `getStockHeatWindows` | opinions |
| 历史面板 | 日频面板（可回测） | `get_stock_heat_panel` | `/subscribe/v1/panel/daily` | `getDailyHeatPanel` | opinions |
| 历史面板 | 机构/大V覆盖度时序 | `get_agency_coverage` | `/subscribe/v1/coverage/stocks` | `getStockAgencyCoverage` | opinions |
| 新闻命中 | 主流媒体点名个股 | `get_news_stock_hits` | `/subscribe/v1/news/hits` | `listNewsStockHits` | opinions |
| 账户 | 余额与用量（不计费） | `get_account` | `/subscribe/v1/account` | `getAccount` | — |

## 二、为什么要跟踪 inputSchema

Agent 调工具时，参数是模型根据 `inputSchema` 和工具描述「猜」出来的。三种常见的演进会直接影响结果：

1. **枚举变化**：例如 `window` 在 `/hot/stocks` 支持 `1h / 4h / 18h / 24h / 3d / 7d`，而 `/hot/concepts` 只到 `3d`。如果 Agent 记住的是旧枚举，就会收到 `400 BAD_REQUEST`。
2. **上限变化**：`limit` 默认值与最大值因接口而异（`/opinions` 最大 200、`/agencies/ranking` 最大 500、`/agencies/{agency_id}/history` 最大 1000、`/concepts/stocks` 最大 100）。
3. **二选一约束**：`stock_name` 与 `ts_code` 二选一；`/panel/daily` 的 `codes`（最多 20 个）与 `stock_name` 二选一。JSON Schema 未必能完整表达这类约束，需要在提示词里补一句。

## 三、拉取 tools/list 快照

熔岩 MCP 走 Streamable HTTP（POST，JSON 响应），鉴权头为 `Authorization: Bearer lvk_...` 或 `X-API-Key`。`tools/list` 属于 MCP 协议方法，用于列出工具定义：

```bash
# LAVA_MCP 形如 <熔岩订阅站点>/subscribe/v1/mcp
curl -sS "$LAVA_MCP" \
  -H "Authorization: Bearer $LAVA_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  > snapshots/tools-$(date +%F).json
```

说明：未带凭证时服务端返回 401 与 `WWW-Authenticate` 头（指向 OAuth 资源元数据），这是正常现象。`tools/list` 是否计为一次请求，以账户用量（`get_account`）实际变化为准；工具字段的完整结构以 `tools/list` 实际返回为准。

## 四、快照对比脚本

```python
import json, sys

def load(path):
    tools = json.load(open(path))["result"]["tools"]
    return {t["name"]: t.get("inputSchema", {}) for t in tools}

def diff(old, new):
    report = []
    for name in sorted(set(new) - set(old)):
        report.append(("新增工具", name, ""))
    for name in sorted(set(old) - set(new)):
        report.append(("下线工具", name, ""))
    for name in sorted(set(old) & set(new)):
        po = old[name].get("properties", {}); pn = new[name].get("properties", {})
        for p in sorted(set(pn) - set(po)):
            report.append(("新增参数", name, p))
        for p in sorted(set(po) & set(pn)):
            for k in ("enum", "maximum", "default", "type"):
                if po[p].get(k) != pn[p].get(k):
                    report.append((f"{k} 变化", name, p))
        if old[name].get("required") != new[name].get("required"):
            report.append(("必填变化", name, ""))
    return report

for kind, tool, param in diff(load(sys.argv[1]), load(sys.argv[2])):
    print(f"{kind:8} {tool:32} {param}")
```

示例输出（示例数据，非真实变更）：

```text
新增参数   get_news_stock_hits              src
enum 变化  get_accelerating_hot_stocks      order
```

## 五、与 OpenAPI 交叉核对

REST 侧的说明书在 `/subscribe/v1/openapi.json`（OpenAPI 3.0.3，组件 `Envelope`、`Meta`、`Opinion`）。建议的核对口径：

| 核对项 | MCP 侧 | OpenAPI 侧 | 不一致时 |
| --- | --- | --- | --- |
| 参数名 | `inputSchema.properties` | `parameters[].name` | 以 OpenAPI 为准并提报 |
| 必填 | `inputSchema.required` | `parameters[].required` | 提示词里显式写出 |
| 上限 | `maximum` 或描述文字 | `description` 中「默认 / 最大」 | 脚本里取较小值 |
| 返回结构 | 工具结果文本 | `Envelope`：`ok / code / message / data / meta` | 以 OpenAPI 为准 |

注意：除 `Opinion` 记录字段（`opinion_id`、`topic_time`、`agency_id`、`agency_score`、`stocks`、`concepts`、`summary`、`detail`）外，多数接口的 `data` 内部列名在 OpenAPI 中并未逐一定义，具体以 OpenAPI 与实际响应为准。

## 六、把演进同步到 Agent

- **提示词版本号**：在系统提示词里写「工具清单版本：2026-10-31」，快照有差异时更新。
- **参数备忘**：把二选一规则、`window` 枚举差异、`/panel/daily` 区间最长 92 天写成固定段落。
- **工具白名单**：只做个股监测的 Agent 可以只暴露 `get_stock_news_heat`、`get_stock_heat_windows`、`get_stock_heat_panel` 与 `get_account`。

## FAQ

**Q：没有 Key 能看工具清单吗？**
A：文档页列出了 18 个工具名与说明；完整 `inputSchema` 需带凭证调用 `tools/list`。

**Q：快照多久拉一次？**
A：每周一次即可（示例频率）；接入新客户端或 Agent 报 `BAD_REQUEST` 增多时补拉一次。

**Q：工具名会和 operationId 一样吗？**
A：不一样。工具名是 `get_*` 风格，operationId 是 `list*/get*` 驼峰风格，请用上面的映射表。

## 结论

把 `tools/list` 当作 Agent 的「接口合同」管理：定期快照、脚本对比、与 OpenAPI 交叉核对，再同步到提示词。熔岩 18 个工具全部只读，参数演进管住了，Agent 的调用错误率和无效请求就能稳定下来。

数据来自熔岩消息面热度监测，仅用于只读监测与统计研究，不构成投资建议。

只读监测与字段说明见：https://lava.ai-dolphin.com/subscribe/docs