Agent Integration Guide

RichView is designed as a presentation layer for AI agents. Agents create structured report schemas (JSON or YAML), and RichView renders them into self-contained HTML. This guide covers the two integration paths: CLI and MCP.

CLI Workflow

The CLI is the simplest integration. An agent writes a schema file to disk and calls richview commands. This works in any environment with Node.js installed.

Generate, lint, publish

# 1. Write a schema file (agent outputs JSON or YAML)
cat > report.yaml << 'EOF'
title: Daily Stock Summary
subtitle: Generated by trading-agent
sections:
  - type: big-number
    label: S&P 500
    value: "5,234.18"
    change:
      value: 1.2
      direction: up
      period: vs yesterday
  - type: markdown
    content: |
      Markets rose on strong earnings reports from the tech sector.
      Volume was above the 20-day average.
EOF

# 2. Validate the schema
richview validate report.yaml

# 3. Lint for quality issues
richview lint report.yaml

# 4. Generate HTML
richview generate report.yaml -o dist/

# 5. Publish to richview.uk
richview publish report.yaml --slug daily-stocks

Self-verification

Agents can verify their own output using describe and screenshot:

# Text description of what was rendered
richview describe report.yaml

# PNG screenshot for visual verification (requires Chrome)
richview screenshot report.yaml --width 1440 --full-page

Combined quality check

The check command runs validation, linting, and assertion verification in one pass:

richview check report.yaml

MCP Workflow

The MCP server exposes RichView as tool calls for Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. The agent never writes files to disk -- everything happens through structured tool calls.

Setup

Add to your MCP client configuration:

{
  "mcpServers": {
    "richview": {
      "command": "npx",
      "args": ["@richview/mcp-server"]
    }
  }
}

For remote access, start in HTTP mode:

npx @richview/mcp-server --http --port 3001

Core tool sequence

A typical agent workflow using MCP tools:

1. Read the schema: call richview://schemas/report resource to get the report JSON Schema
2. Read the guide: call richview://guide resource for report creation best practices
3. Pick a template: call richview.template-report with { action: "list" } to see available templates
4. Create the report: call richview.generate-report with the report object
5. Verify quality: call richview.lint-report to check for issues
6. Run assertions: call richview.verify-report to check data assertions
7. Get a summary: call richview.summary-report for a compact text overview
8. Take a screenshot: call richview.screenshot-report for visual verification

Editing an existing report

richview.add-section      — add a new section
richview.update-section   — modify an existing section by ID
richview.remove-section   — delete a section by ID
richview.reorder-sections — change section order

Fetching live data

The MCP server includes data tools that require no API keys:

richview.fetch-stock   — stock prices from Yahoo Finance
richview.fetch-crypto  — crypto prices from CoinGecko
richview.fetch-weather — weather from Open-Meteo
richview.fetch-fx      — forex rates from Frankfurter (ECB)

An agent can fetch data, build a report section, and render it in a single conversation turn.

Chart YAML Spec

Agents describe charts using a YAML spec instead of raw ECharts JSON. The spec is simpler and RichView translates it to publication-quality ECharts output.

type: bar
config:
  xAxis:
    field: region
  yAxis:
    field: revenue
    format: currency
  series:
    - dataKey: revenue
      name: Revenue
data:
  type: inline
  columns: [region, revenue]
  values:
    - [East, 68000]
    - [West, 42000]
    - [Central, 32000]

Supported chart types: bar, line, area, pie, donut, scatter, heatmap, treemap, gauge, radar, funnel, waterfall, candlestick.

Validating chart specs

CLI:

richview chart validate my-chart.yaml

MCP: include the chart in a report section and call richview.validate-schema.

Converting from JSON

If an agent has existing ECharts-style JSON, convert it to the YAML spec:

richview chart convert chart.json -o chart.yaml

Access Control

API key authentication

For automated publishing, set the RICHVIEW_API_KEY environment variable. The CLI reads this for server-side operations (publish, db, connect).

export RICHVIEW_API_KEY=rv_key_abc123
richview publish report.yaml --slug weekly-update

Self-hosted instances

Point the CLI to your own server:

export RICHVIEW_SERVER=https://reports.example.com
richview publish report.yaml

Or per-command:

richview publish report.yaml --server https://reports.example.com

Complete Example: Agent Pipeline

Here is a complete agent workflow that fetches live data, builds a report, validates it, and publishes.

#!/bin/bash
set -e

# Fetch stock data
STOCK_DATA=$(richview data fetch stocks AAPL -f json)

# Write report schema
cat > daily-report.yaml << EOF
title: AAPL Daily Update
subtitle: $(date +%Y-%m-%d)
generatedBy:
  tool: trading-agent
  version: "1.0"
sections:
  - type: big-number
    label: AAPL Close
    value: "\$$(echo "$STOCK_DATA" | jq -r '.price')"
    change:
      value: $(echo "$STOCK_DATA" | jq -r '.changePercent')
      direction: $(echo "$STOCK_DATA" | jq -r 'if .change >= 0 then "up" else "down" end')
      period: vs previous close

  - type: markdown
    content: |
      Automated daily price summary for Apple Inc.
      Report generated at $(date -u +%H:%M) UTC.

  - type: chart
    title: 20-Day Price History
    chart:
      type: line
      xAxis: { field: date }
      yAxis: { field: close, format: currency }
      series:
        - dataKey: close
          name: Close Price
    data:
      type: inline
      columns: [date, close]
      values: $(echo "$STOCK_DATA" | jq -c '[.history[] | [.date, .close]]')

assertions:
  - type: range-check
    section: 0
    field: value
    min: 0
    max: 1000
EOF

# Validate and lint
richview check daily-report.yaml

# Generate HTML
richview generate daily-report.yaml -o dist/

# Publish
richview publish daily-report.yaml --slug aapl-daily

Prompt Templates

The MCP server includes prompt templates for common report types. Agents can use these as starting points:

Prompt	Use case
richview.analysis-report	Data analysis with charts and tables
richview.executive-summary	High-level business summary
richview.portfolio-report	Investment portfolio review
richview.competitive-analysis	Market competitor comparison
richview.incident-postmortem	Incident root cause analysis
richview.data-quality-report	Data quality assessment
richview.sales-report	Sales performance dashboard
richview.technical-spec	Technical specification document

To use a prompt in Claude Desktop, type /richview.analysis-report in the chat and fill in the parameters.