数据分析

对通过 MCP 服务器获取的数据进行分页、筛选、聚合、合并和导出，无需发起新的 API 调用。

目标：用 execute 获取一次数据，然后在服务器端处理完整结果，而不是重新获取或把全部数据加载进对话。

通常你只需要用自然语言告诉客户端（比如“只保留柏林的，导出一个 CSV”）；这些工具由客户端自行选用。 本页说明它们各自的作用，方便你知道该怎么提要求。

缓存是如何工作的

1. execute 会把完整结果存在服务器上，并返回前 10 条结果、total 和一个 cache_key。如果还有 更多条目，响应中还会带 next_offset。
2. 下面的每个工具都使用这个 cache_key。它们都不会重新调用数据源，也都不消耗用量。
3. 缓存结果和你的 execute 调用历史会保留 7 天。之后，cache_key 会返回 No data found for this cache_key. It may have expired — re-run execute().

分页浏览结果

get_page(cache_key, offset, limit) 返回从 offset 开始的条目，并带有 next_offset 和 has_more。 一页最多包含 50 条；如果 limit 更大，会返回 50 条以及提示从 next_offset 继续获取。

筛选与排序

query_cache(cache_key, conditions, sort_by, sort_order, limit, offset) 返回匹配的条目及其 total。

{
  "cache_key": "<cache_key>",
  "conditions": [
    {"field": "location", "op": "contains", "value": "Berlin"},
    {"field": "follower_count", "op": ">", "value": 1000}
  ],
  "sort_by": "follower_count",
  "sort_order": "desc",
  "limit": 10
}

• 所有条件都必须满足（AND）。
• 运算符：=、!=、>、<、>=、<=、contains、not_contains。contains 和 not_contains 不 区分大小写；>、<、>=、<= 用于数值比较。
• 嵌套字段用点号表示，例如 "field": "company.name"。
• sort_order 为 asc（默认）或 desc。
• 字段名就是 execute 返回的条目中的字段名。如果没有任何匹配但缓存中确实有数据，工具会给出提示 —— 检查字段名和取值是否正确。

聚合

加上 aggregate 可以得到一个数字，而不是一批条目：

{"cache_key": "<cache_key>", "aggregate": {"field": "follower_count", "op": "avg"}}

• 函数：count、sum、avg、min、max、uniq（不同值的数量）。count 不需要指定字段。
• 加上 group_by 可以按组返回每组一个值，按从大到小排序，最多 limit 个组（默认 10 个）： {"aggregate": {"op": "count"}, "group_by": "industry"} 会返回 {"groups": {"Software": 42, ...}}。
• conditions 会在聚合之前应用。

合并多个结果

merge_data(cache_keys, dedupe_by) 把 2 到 20 个缓存结果（总共最多 10 万行）合并成一个新的 cache_key，本页的每个工具都可以直接使用它。

• 完全相同的行始终会被合并去重。
• dedupe_by（最多 10 个字段名，例如 ["url"]）还会合并这些字段取值相同的行。如果其中任何字段缺失 或为空，该行会被保留，并计入 rows_without_key。
• 已过期的 key 会被跳过并在提示中列出；其余的会被正常合并。

导出文件

export_data(cache_key, output_format, list_unpack) 返回一个 file_url、行数 total、文件大小和一份 预览。

• 格式：json（默认）、csv、jsonl、xlsx。
• 导出始终包含该 cache_key 下的全部条目。query_cache 的筛选条件不会缩小导出范围。如果要把多次 获取的结果导出为一个文件，先用 merge_data 合并，再导出合并后的 key。
• list_unpack（仅 CSV 和 XLSX，取值 0–255，默认 1）设置每个嵌套列表中有多少个条目会被展开成单独的 列。
• 下载链接不需要密钥 —— 任何拿到链接的人都能下载文件，所以数据敏感时不要分享该链接。只要缓存结果还 在，链接就会一直有效。

查找之前的结果

search_requests(source, category, endpoint, query, since, until, limit, offset) 按时间从新到旧列出你 之前的 execute 调用，包含参数、条目数、时间和 cache_key。query 会匹配参数中的文本；since 和 until 接受 ISO 8601 格式的时间。用它代替重新获取同样的数据。

故障排查

消息	解决方法
No data found for this cache_key. It may have expired — re-run execute().	结果已超过 7 天，或 key 不正确。请重新获取。
No items matched the given conditions (N items in cache). Check condition fields and values.	字段名或取值与条目不匹配。先用 get_page 看一条具体的条目。
Invalid operator: … / Invalid aggregate: …	请使用上面列出的运算符或函数之一。
Unsupported format '…'. Use: json, csv, jsonl, xlsx	请选择一个受支持的 output_format。
cache_keys must contain at least 2 different cache_key values / Too many cache_keys / Too many rows to merge	合并的结果数量应在 2 到 20 个之间，总行数不超过 10 万行。