sumscope-data

---
name: sumscope-data
description: 通过 Sumscope qeubee MCP 服务器查询金融数据（行情、债券、资金等）。当用户需要查询 qeubee 相关数据、了解可用的数据 API、或要求获取某类金融数据时使用。必须按"先获取 API 清单和参数定义，再调用"的流程执行。
version: 1.0.1
author: Sumscope MCP
---

# Sumscope qeubee 数据查询

通过 MCP 工具查询 qeubee 金融数据。本 Skill 定义了标准调用流程，**必须严格遵守**，禁止跳过清单/详情获取步骤直接调用查询工具。

## 可用工具

| 工具 | 作用 |
|---|---|
| `listAvailableApis` | 列出当前用户已授权的所有 API（API 清单），返回 `apiName` + `apiDesc` |
| `getApiDetail` | 获取指定 API 的入参/出参详细定义（参数名、类型、是否必填、默认值、样例值，以及返回字段、字段描述、样例值） |
| `queryData` | 按实际参数查询指定 API 的数据 |

## 标准调用流程（三步，不可跳步）

### Step 1：获取 API 清单

调用 `listAvailableApis`，得到当前用户**已授权**的全部 API 列表（`apiName` / `apiDesc`）。

- **不要**凭记忆或猜测 API 名称，一切以清单返回值为准
- 清单为空时，说明当前用户无授权 API，应明确告知用户，不要强行调用
- 若用户所需数据在清单中**完全找不到**对应接口（该数据类别无任何相关 API）：
  - 不要强行选择无关接口凑合，也不要凭空猜测或虚构接口调用
  - 明确告知用户"当前账号暂未开通该数据接口"，并提示用户**联系 qeubee 客服或销售咨询采购**，可附上清单中已有的相近接口供参考，引导用户确认采购后再查询
- 若存在描述最接近但非完全匹配的 API，选择最接近的 API 查询，并向用户说明你的选择（如数据口径可能与本意有差异，可提示用户采购专有接口）

### Step 2：获取目标 API 的参数定义与样例

针对选定的 `apiName`，调用 `getApiDetail(apiName)`，得到：

- `params`：入参定义，每项包含
  - `paramName`：参数名（**调用时必须与之一致**）
  - `paramDesc`：参数说明
  - `paramType`：参数类型
  - `isNullAble`：是否可空（`false` 表示必填）
  - `defaultValue`：默认值（可选参数的缺省值）
  - `paramSample`：样例值（**推荐按此格式构造参数**）
  - `paramGroup`：参数分组（如时间区间、标的等）
- `resultFields`：出参定义，每项包含 `fieldName` / `fieldDesc` / `sampleValue`，用于理解返回结果的字段含义

### Step 3：按实际参数调用查询

调用 `queryData(apiName, params)`，其中 `params` 为 `key=value` 形式：

- `key` 必须与 Step 2 返回的 `paramName` **完全一致**
- `value` 根据用户实际诉求填写；拿不准格式时，参考该参数的 `paramSample`
- **必填参数**（`isNullAble=false`）必须提供；可空参数未提供时用 `defaultValue`
- 不要为了凑参数而传入清单外的 key

### 调用后的处理

- 向用户展示查询结果时，用 `resultFields` 的 `fieldDesc` 解释字段含义，避免直接抛原始 JSON 字段名
- 调用失败（如 API 不存在 / 未授权 / 参数错误）时，先按下方"缓存刷新"规则刷新后再重试一次；仍失败则如实反馈错误信息

## API 清单与参数定义：本地缓存 + 定期刷新

为减少重复调用、提升效率，采用**本地缓存 + 定期刷新**策略：

1. **缓存内容**：API 清单（`listAvailableApis` 结果）、各 API 的入参/出参详情（`getApiDetail` 结果）
2. **首次获取**：本次会话第一次查询数据前，先完整获取清单，再按需获取目标 API 详情
3. **缓存复用**：同一会话内，已获取过的 API 详情直接复用，不要对同一 `apiName` 重复调用 `getApiDetail`
4. **定期刷新**：会话持续较长（超过 30 分钟）或用户明确要求更新时，重新获取清单和详情，以反映授权变更或 API 定义更新
5. **异常触发刷新**：当调用 `queryData` 返回"API 不存在"、"未授权"等错误时，优先怀疑缓存过期，刷新对应缓存后重试
6. 如需跨会话持久化，可将清单与详情整理为结构化笔记保存在本地，作为下次会话的初始缓存，但**每次会话首次使用时必须校验并刷新**

## 注意事项

- `apiName` 大小写敏感，必须与清单完全一致
- 数据访问受当前用户授权约束：只能查询清单中列出的 API，不能越权
- 参数值为空字符串与不传参数含义可能不同，严格按 `isNullAble` 与 `defaultValue` 判断
- 查询结果可能较大，向用户呈现时先概括（条数、范围），再展示明细