feat: add MCP research figures and examples

Author: cuNuo

.codex/skills/keepa-agent-research/SKILL.md

@@ -52,8 +52,9 @@ With MCP, call structured tools instead of CLI strings:
 - `keepa.workflow_plan`
 - `keepa.research_graph_merge`
 - `keepa.research_brief_export`
+- `keepa.figures_research`
 
-Use `tools/list` with `toolset=research` by default. Switch to `audit` for `keepa.audit_cost` and cassette tools, `reports` for local report/browse builders, and `tracking-readonly` only for read-only tracking state. Add `profile=offline_fixture_only` or `profile=dry_run_default` during early research; inactive tools include `x-keepa.active=false`, and `tools/call` returns `inactive_tool` before service execution when a profile disallows a tool.
+Use `tools/list` with `toolset=research` by default. Switch to `audit` for `keepa.audit_cost` and cassette tools, `reports` for local report/browse/SVG figure builders, and `tracking-readonly` only for read-only tracking state. Add `profile=offline_fixture_only` or `profile=dry_run_default` during early research; inactive tools include `x-keepa.active=false`, and `tools/call` returns `inactive_tool` before service execution when a profile disallows a tool.
 
 Use `resources/list` before loading long docs. Stable resources are `keepa://context/policy`, `keepa://schema/products-agent-view`, `keepa://schema/risk-taxonomy`, `keepa://schema/workflow-runtime-contract`, `keepa://fixtures/manifest`, `keepa://guides/cassette-promotion`, `keepa://evidence/recent`, and `keepa://workflow/runtime-contract`. Use `resources/templates/list` to discover `keepa://schema/{name}`, `keepa://fixtures/{name}`, `keepa://workflow/{encoded_params}/policy`, `keepa://research/{cache_key}`, `keepa://research/{cache_key}/brief`, `keepa://research/{cache_key}/graph`, `keepa://graphs/{root}`, `keepa://chunk/{encoded_path}`, and `keepa://output/{encoded_path}`. Use `keepa://schema/risk-taxonomy` to validate risk codes, severity, and evidence paths, `keepa://workflow/runtime-contract` to discover resolver-enabled tools and follow its `schema_resource_uri` for validation, `keepa://workflow/{encoded_params}/policy` to read compact workflow execution policy from base64url JSON workflow params, `keepa://research/{cache_key}` to audit same-session cached results, `keepa://research/{cache_key}/brief` to reload an exported brief, and `keepa://graphs/{root}` to audit graph sources before writing conclusions. For tool results with `mcp_resource_manifest`, load `keepa://chunk/...` or `keepa://output/...` only when the summary is insufficient.
 
@@ -75,6 +76,17 @@ When executing later MCP steps, prefer `resource_uri` / `resource_uris` over cop
 
 Use `keepa.research_agent_start` prompt when a client supports MCP prompts. It encodes the policy -> resolve -> context -> plan -> execute -> graph merge order.
 
+For a copyable MCP client integration sample, run:
+
+```powershell
+.\.venv\Scripts\python.exe scripts\mcp_agent_workflow_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_tracking_audit_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_report_research_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_report_research_example.py --json --save-summary evidence\runtime\mcp-report-summary.json
+```
+
+The examples demonstrate `workflow.plan`, `keepa://schema/risk-taxonomy`, `keepa://research/{cache_key}` resource chaining, risk schema validation, graph merge, brief export, report build, tracking-readonly boundaries, and local graph -> brief -> browse/report handoff in fixture-backed stdio sessions. Use `--save-summary` when an Agent pipeline needs to persist the compact integration summary to a controlled path.
+
 ## Read Order
 
 For each product, read in this order:
@@ -101,6 +113,8 @@ Use `research_brief.export` / `keepa.research_brief_export` after graph merge or
 
 Use `reports.build` on the merged graph JSON when a human-readable or downstream relationship report is needed. Markdown includes entity and relationship tables; JSON includes `research_graph_report`.
 
+Use `figures.research` / `keepa.figures_research` when a report needs a visual artifact. It creates one SVG plus source JSON from product comparison rows, risk codes, graph entity counts, and temporal signals. In MCP, read the `image/svg+xml` `keepa://output/...` resource from `mcp_resource_manifest` and insert that SVG into the downstream report; load source JSON only for audit.
+
 ## Cassette Promotion
 
 After an approved live request, convert the response into regression assets before reusing it:

.codex/skills/keepa-cli/SKILL.md

@@ -51,22 +51,36 @@ kc --mcp
 
 Use `keepa.products_get` for single-product research and `keepa.products_compare` for multi-ASIN deal comparison. Product Agent views include `agent_brief`, `risk_taxonomy`, `research_graph`, `data_quality`, `selection_signals`, `next_actions`, and `evidence_index`; read those before loading raw output or chunks.
 
-MCP `tools/list` defaults to `toolset=research`. Use `toolset=audit` for `keepa.audit_cost` and cassette tools, `toolset=reports` for local report/browse/brief export tools, `toolset=tracking-readonly` for read-only tracking, and `toolset=all` only when debugging schema discovery. Add `profile=offline_fixture_only`, `dry_run_default`, `live_read_allowed`, `tracking_readonly`, or `fixture_curation` when a client supports staged tool discovery. Inactive tools are marked with `x-keepa.active=false`, and `tools/call` with the same profile returns `inactive_tool` before service execution. Research tools include `keepa.categories_finder_selection`, `keepa.research_graph_merge`, and `keepa.research_brief_export`.
+MCP `tools/list` defaults to `toolset=research`. Use `toolset=audit` for `keepa.audit_cost` and cassette tools, `toolset=reports` for local report/browse/SVG figure/brief export tools, `toolset=tracking-readonly` for read-only tracking, and `toolset=all` only when debugging schema discovery. Add `profile=offline_fixture_only`, `dry_run_default`, `live_read_allowed`, `tracking_readonly`, or `fixture_curation` when a client supports staged tool discovery. Inactive tools are marked with `x-keepa.active=false`, and `tools/call` with the same profile returns `inactive_tool` before service execution. Research tools include `keepa.categories_finder_selection`, `keepa.research_graph_merge`, and `keepa.research_brief_export`.
 
 MCP `resources/list` exposes `keepa://context/policy`, `keepa://schema/products-agent-view`, `keepa://schema/risk-taxonomy`, `keepa://schema/workflow-runtime-contract`, `keepa://fixtures/manifest`, `keepa://guides/cassette-promotion`, `keepa://evidence/recent`, and `keepa://workflow/runtime-contract`. `resources/templates/list` exposes `keepa://schema/{name}`, `keepa://fixtures/{name}`, `keepa://workflow/{encoded_params}/policy`, `keepa://research/{cache_key}`, `keepa://research/{cache_key}/brief`, `keepa://research/{cache_key}/graph`, `keepa://graphs/{root}`, `keepa://chunk/{encoded_path}`, and `keepa://output/{encoded_path}`. Use `keepa://schema/risk-taxonomy` when an Agent needs to validate risk codes, severity, and evidence paths without loading the full product schema; use `keepa://workflow/runtime-contract` to discover resolver-enabled tools and follow its `schema_resource_uri` for validation, `keepa://workflow/{encoded_params}/policy` to read a compact `workflow_policy` from base64url JSON workflow params, `keepa://research/{cache_key}` to audit same-session cached results, `keepa://research/{cache_key}/brief` to reload an exported brief, and `keepa://graphs/{root}` to audit graph sources before writing conclusions. If a tool text fallback includes `mcp_resource_manifest`, load `keepa://chunk/...` or `keepa://output/...` with `resources/read` instead of asking for the whole raw body again.
 
 For general research Agents, read `keepa://context/policy`, call `keepa.resolve_research_target`, then call `keepa.query_research_context` before running live-capable product/category tools. `tools/list` accepts `allow_tools`, `exclude_tools`, and `profile` filters for small per-workflow schemas; use `profile=offline_fixture_only` when the Agent must not execute live-capable tools.
 
 `workflow.plan` returns `workflow_inputs`, `artifacts`, `resource_templates`, and `workflow_policy` for MCP execution control. It supports `category-research`, `product-research`, `report-research`, and `tracking-audit`. Read it before running steps: apply `tool_discovery.params` to `tools/list`, follow `profile_switch_points`, treat `inactive_tools` as deliberate stage gates, connect steps with `input_refs` / `artifact_refs`, and only add `yes=true` after explicit confirmation for the listed `confirmation_policy.step_ids`. MCP `tools/call` accepts `resource_uri`, `resource_uris`, `artifact`, `artifacts`, `workflow_inputs`, and `workflow_context` to resolve prior outputs into concrete params; it also understands `artifact.output.path` / `artifact.data.output.path` and nested `workflow_context.steps` / `outputs` / `results` for local graph -> brief -> reports chains. Inspect `data.workflow_resolution` or `error.kind=missing_inputs`. `report-research` is local-only through the `reports` toolset; `tracking-audit` is read-only through `tracking-readonly`.
 
+For a copyable Agent MCP client example:
+
+```powershell
+.\.venv\Scripts\python.exe scripts\mcp_agent_workflow_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_tracking_audit_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_report_research_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_report_research_example.py --json --save-summary evidence\runtime\mcp-report-summary.json
+```
+
+The scripts use a single `python -m keepa_cli --mcp` stdio session to run `workflow.plan -> resource_uri -> risk schema validation -> graph/brief/report`, tracking-readonly audit, and local report-research handoff with fixtures only. `--save-summary` writes the compact integration summary to a controlled path for Agent pipelines.
+
 For local workflows:
 
 ```powershell
 kc --json batch asins asins.txt --domain US --dry-run --out batch.json
 kc --json reports build --input batch.json --format markdown --out report.md
 kc --json browse snapshot --input batch.json --out-dir keepa-browse
+kc --json figures research --input batch.json --out-dir keepa-figures
 ```
 
+`browse.snapshot` can render rows from raw product bodies or `research_graph` product nodes. `figures research` emits one SVG plus source JSON; through MCP, `keepa.figures_research` exposes the SVG as an `image/svg+xml` `keepa://output/...` resource suitable for reports.
+
 `reports build` can also consume a merged research graph JSON and emit entity/relationship report sections:
 
 ```powershell

README.md

@@ -189,6 +189,7 @@ Build an offline batch plan, report, and local HTML browse snapshot:
 kc --json batch asins .\asins.txt --domain US --dry-run --out .\batch.json
 kc --json reports build --input .\batch.json --format markdown --out .\report.md
 kc --json browse snapshot --input .\batch.json --out-dir .\keepa-browse
+kc --json figures research --input .\batch.json --out-dir .\keepa-figures
 ```
 
 Use built-in workflow templates:
@@ -285,10 +286,23 @@ MCP JSON-RPC over stdio:
 '{"jsonrpc":"2.0","id":4,"method":"prompts/list","params":{}}' | kc --mcp
 ```
 
-MCP defaults to the compact `research` toolset and accepts structured JSON arguments, not CLI strings. Use `tools/list` with `toolset` set to `research`, `docs`, `audit`, `reports`, `tracking-readonly`, or `all` to control context size; `allow_tools` and `exclude_tools` can further narrow the per-workflow schema. `profile` can mark tools inactive for a session stage (`offline_fixture_only`, `dry_run_default`, `live_read_allowed`, `tracking_readonly`, `fixture_curation`); `tools/call` returns `inactive_tool` before service execution when a profile disallows a tool. Research tools include context policy, target resolution, local context query, product, category, local Finder scaffold, Finder, Deals, seller, ranking, workflow planning, docs index/read, `keepa.research_graph_merge`, and `keepa.research_brief_export`; audit tools include cost estimation plus cassette sanitize/promote and `keepa.cassettes_promote_and_verify`; reports tools expose graph merge, local report, browse snapshot, and brief export builders; tracking exposes read-only tracking plus cost audit. Agent results include `risk_taxonomy` where applicable and a cross-command `research_graph`; tool envelopes include `structuredContent`, compact JSON text fallback, `cache_key`, `cache_hit`, and `budget_ledger`.
+MCP defaults to the compact `research` toolset and accepts structured JSON arguments, not CLI strings. Use `tools/list` with `toolset` set to `research`, `docs`, `audit`, `reports`, `tracking-readonly`, or `all` to control context size; `allow_tools` and `exclude_tools` can further narrow the per-workflow schema. `profile` can mark tools inactive for a session stage (`offline_fixture_only`, `dry_run_default`, `live_read_allowed`, `tracking_readonly`, `fixture_curation`); `tools/call` returns `inactive_tool` before service execution when a profile disallows a tool. Research tools include context policy, target resolution, local context query, product, category, local Finder scaffold, Finder, Deals, seller, ranking, workflow planning, docs index/read, `keepa.research_graph_merge`, and `keepa.research_brief_export`; audit tools include cost estimation plus cassette sanitize/promote and `keepa.cassettes_promote_and_verify`; reports tools expose graph merge, local report, browse snapshot, SVG figure generation, and brief export builders; tracking exposes read-only tracking plus cost audit. Agent results include `risk_taxonomy` where applicable and a cross-command `research_graph`; tool envelopes include `structuredContent`, compact JSON text fallback, `cache_key`, `cache_hit`, and `budget_ledger`.
 
 MCP resources expose stable reference material without enlarging `tools/list`: `keepa://context/policy`, `keepa://schema/products-agent-view`, `keepa://schema/risk-taxonomy`, `keepa://schema/workflow-runtime-contract`, `keepa://fixtures/manifest`, `keepa://guides/cassette-promotion`, `keepa://evidence/recent`, `keepa://tools/index`, `keepa://prompts/index`, `keepa://zread/wiki/current`, `keepa://zread/wiki/toc`, and `keepa://zread/wiki/pages`. `resources/templates/list` also advertises `keepa://schema/{name}`, `keepa://fixtures/{name}`, `keepa://cache-key/{command}/{encoded_params}`, `keepa://workflow/{encoded_params}/policy`, `keepa://research/{cache_key}`, `keepa://research/{cache_key}/brief`, `keepa://research/{cache_key}/graph`, `keepa://graphs/{root}`, `keepa://toolsets/{toolset}`, `keepa://tools/{name}`, `keepa://prompts/{name}`, `keepa://asin/{asin}/fixture`, `keepa://evidence/{encoded_logical_path}`, `keepa://zread/wiki/page/{slug_or_file}`, `keepa://chunk/{encoded_path}`, and `keepa://output/{encoded_path}` so Agents can discover resource URI shapes instead of hard-coding them. `keepa://schema/risk-taxonomy` gives external Agents the stable risk enum and evidence-bearing item contract; `keepa://workflow/{encoded_params}/policy` reads the compact `workflow_policy` and step summary from base64url JSON plan params; `keepa://workflow/runtime-contract` now points to `keepa://schema/workflow-runtime-contract` for client-side validation; `keepa://research/{cache_key}` audits a same-session cached result; `keepa://research/{cache_key}/brief` reloads an exported brief; `keepa://graphs/{root}` finds graph summaries in session cache and local fixtures. Large tool responses keep the full payload in `structuredContent`; the text fallback returns a summary plus `mcp_resource_manifest` entries so Agents can load heavy sections only when needed. MCP prompts include product research, category research, deal comparison, project onboarding, and `keepa.research_agent_start` playbooks.
 
+Copyable Agent integration example:
+
+```powershell
+.\.venv\Scripts\python.exe scripts\mcp_agent_workflow_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_tracking_audit_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_report_research_example.py --json
+.\.venv\Scripts\python.exe scripts\mcp_report_research_example.py --json --save-summary evidence\runtime\mcp-report-summary.json
+```
+
+These examples start `python -m keepa_cli --mcp` as a stdio server and keep one session alive for cache keys, resource URIs, and budget ledgers. `mcp_agent_workflow_example.py` calls `keepa.workflow_plan`, reads `keepa://schema/risk-taxonomy`, executes fixture-backed category products and compare steps through `resource_uri`, validates emitted risk objects, merges the research graph, exports an Agent brief, and builds a JSON report. `mcp_tracking_audit_example.py` demonstrates the `tracking-readonly` toolset/profile boundary and proves tracking write tools are not exposed. `mcp_report_research_example.py` demonstrates the local `reports` toolset by turning an existing graph fixture into graph, brief, browse snapshot, SVG figure resource, and report outputs. All examples support `--save-summary <path>` for controlled Agent pipeline summaries. The shared helper `scripts/mcp_example_support.py` is intentionally standard-library only so other Agents can copy the client pattern without extra dependencies.
+
+`browse.snapshot` reads product rows from raw Keepa product bodies and from `research_graph` product nodes, so merged graphs produce useful HTML even when no raw product rows are present. `figures research` generates a single SVG plus source JSON from product comparison, risk taxonomy, graph entity counts, and temporal signals. Through MCP, `keepa.figures_research` returns the SVG as a `keepa://output/...` resource with `image/svg+xml`, which lets Agents insert a stable figure into downstream reports without loading large raw JSON.
+
 Contracts:
 
 - [Agent contract](docs/agent-contract.md)