MCP / API REFERENCE

接口与工具

完整参数、返回结构与调用规则。连接授权后，按客户端实际发现的工具名称与 schema 调用。

MCP 工具接口说明

以下是 MCP 工具参数，不是 REST 表单或 OAuth 参数。客户端通过 tools/call 调用工具，令牌由客户端管理。示例使用合成数据与虚构任务 ID；不要仅为连接测试创建报告。

create_report

用途：在已授权工作区异步创建一份新报告。OAuth 权限：reports.write。每次调用都会创建新任务。

参数	类型	必填	默认值	说明
outline	string	是	—	完整 Markdown 报告大纲，包含核实后的结论、指标与聚合图表数据；非空，最多 1,000,000 UTF-8 字节。
locale	string	否	zh-CN	报告语言，例如 zh-CN 或 en。当前接口未将其限制为枚举。

outline 必须符合完整大纲规范：# 主标题、> 副标题、meta 信息、## 页面标题及页面布局。服务从第一个非空 # 标题提取报告名（最多 300 UTF-8 字节），必须至少有一个非空 ## 页面；meta.pages 应与实际页数一致。不要把 JSON 对象或文件路径当作 outline 字符串。

不要传递 title、outline_markdown、workspace_id、idempotency_key 或其他额外参数。标题来自 outline，工作区来自 OAuth 授权。

完整请求参数示例（合成数据）

展开完整 JSON 示例

{
  "outline": "# Agency Client Performance Review\n\n> Synthetic demonstration data for July–September 2026; not a real client report.\n\n<!-- meta\ngoal: Review campaign efficiency and agree on next month's priorities\nskill: agency-client-review\nstyle: default\nlang: business\npages: 3\naudience: Client marketing lead\ndate_range: 2026-07-01 to 2026-09-30\ngenerated: 2026-10-05\n-->\n\n---\n\n## Data overview\n`layout: KPI Ledger`\n`layout_intent: Summarize verified quarterly performance before reviewing definitions.`\n`layout_slots: kpi-summary`\n\n- [slot: kpi-summary] Quarterly performance [smart_layout]\n  | Metric | Current value | Description |\n  |---|---|---|\n  | Ad spend | USD 30,000 | Total July–September campaign spend |\n  | Attributed revenue | USD 105,000 | Revenue attributed using the demo's fixed 7-day click window |\n  | ROAS | 3.50x | USD 105,000 / USD 30,000; excludes agency fees |\n  Evidence: Monthly ROAS increased from 3.00x in July to 4.00x in September.\n  Attribution: These aggregates show an efficiency trend, but do not establish its cause.\n  Recommendation: Review channel and campaign breakdowns before reallocating budget.\n\n---\n\n## Data definitions\n`layout: Specification Sheet`\n`layout_intent: Define the source, attribution window and calculation scope.`\n`layout_slots: spec-body`\n\n- [slot: spec-body] Measurement scope [smart_layout]\n  | Definition | Value |\n  |---|---|\n  | Source | Synthetic monthly campaign aggregates for this example |\n  | Scope | July–September 2026; all amounts in USD |\n  | Spend by month | July 10,000; August 10,000; September 10,000 |\n  | Revenue by month | July 30,000; August 35,000; September 40,000 |\n  | ROAS definition | Attributed revenue / ad spend; fixed 7-day click window |\n  Footnote: Agency fees, organic revenue and refunds are excluded. No causal or incremental-lift conclusion can be made from these aggregates.\n\n---\n\n## Validate the efficiency trend before increasing investment\n`layout: Closing Statement`\n`layout_intent: Turn the measured trend into specific next steps without asserting causality.`\n`layout_slots: takeaways`\n\n- [slot: takeaways] Findings and next steps [smart_layout]\n  Findings:\n  01. Quarterly ROAS was 3.50x on USD 30,000 of spend.\n  02. Monthly attributed revenue rose from USD 30,000 to USD 40,000 while spend stayed constant.\n  03. The aggregate data cannot isolate the drivers or confirm incremental revenue.\n  Actions:\n  P1. Marketing lead: validate attribution and refund handling before the next review.\n  P2. Agency analyst: compare channels and campaigns using consistent attribution definitions.\n  P3. Account lead: agree on a controlled budget test after validating the breakdown.\n  Goal: Confirm a repeatable efficiency improvement before scaling spend.\n",
  "locale": "en"
}

创建成功时的返回数据

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "status": "running",
  "report_url": "https://www.algforce.com/report/preview/11111111-1111-4111-8111-111111111111?b=report",
  "poll_after_seconds": 15
}

返回字段	类型	说明
job_id	string	新任务 ID，保存并用于后续查询。
status	string	创建成功时为 running，仅说明已提交。
report_url	string	公开只读预览地址；立即向用户展示原始返回链接。
poll_after_seconds	integer	建议查询间隔，当前为 15 秒。

get_report

用途：查询当前用户在授权工作区内创建的任务。OAuth 权限：reports.read；不会修改报告。

参数	类型	必填	说明
job_id	string	是	create_report 返回的任务 ID，不是 report_id、分享 ID 或完整链接；无默认值。

{
  "job_id": "11111111-1111-4111-8111-111111111111"
}

生成中的完整返回数据示例

{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "operation": "create",
  "status": "running",
  "stage": "generating",
  "completed_pages": 1,
  "pages_started": 2,
  "total_pages": 3,
  "report_id": null,
  "report_url": "https://www.algforce.com/report/preview/11111111-1111-4111-8111-111111111111?b=report",
  "share_url": null,
  "poll_after_seconds": 15,
  "error_code": null,
  "error_message": null
}

返回字段	类型	说明
job_id	string	本次查询的任务 ID。
operation	string	本连接器新建任务为 create。
status	string	running：继续查询；completed：生成完成；failed：失败并停止查询。
stage	string	后端阶段标签，不应假设固定阶段枚举或据此推算百分比。
completed_pages	integer	后端报告的完成页数。
pages_started	integer	生成中的启动进度计数，不等于完成页数；任务结束后可为 0。
total_pages	integer	根据大纲 ## 标题统计的总页数。
report_id	string or null	报告资源 ID，生成中可能为空；不能用于 get_report 的 job_id 参数。
report_url	string	报告预览入口，生成中也存在；存在链接不代表完成。
share_url	string or null	完成后的底层公开分享地址，可能为空。默认展示 report_url。
poll_after_seconds	integer or null	running 时当前为 15 秒，结束后为 null。
error_code	string or null	任务错误或分享准备警告码，无错误时为空。
error_message	string or null	对应错误或警告说明。

completed 或 failed 后立即停止查询。生成成功仍可能带分享准备警告，请说明返回的警告。若调用创建超时，已有 job_id 就查询原任务；没有 job_id 时提交结果不确定，需先询问再重建。

MCP 返回封装与错误

上面的示例是业务返回数据。实际 MCP 成功结果同时包含 structuredContent 和 content[0].text（业务数据的 JSON 字符串），isError 为 false。请优先读取客户端提供的结构化数据，不要只检查 HTTP 状态。

{
  "isError": true,
  "structuredContent": {
    "error_code": "INVALID_ARGUMENT",
    "message": "Invalid create_report arguments"
  },
  "content": [
    {
      "type": "text",
      "text": "INVALID_ARGUMENT: Invalid create_report arguments"
    }
  ]
}

错误类型	含义与处理
INVALID_ARGUMENT	参数或大纲无效，按实际错误信息修正。
NOT_FOUND	任务不存在，或当前用户/工作区无权查询；核对原 job_id 与授权身份。
SERVER_ERROR	服务无法创建或读取任务；不要因未知提交结果自动重建。
HTTP 401	缺少或无效令牌，通过客户端重新授权。
HTTP 403	令牌缺少所需权限，按 WWW-Authenticate 提示重新授权所需 scope。
status: failed	工具查询成功但报告生成失败；读取 error_code / error_message，停止轮询。