Resource URIs

Access audit data and UX guidelines through MCP resource URIs. Resources provide read-only access to data without calling tools.

What Are MCP Resources?

MCP resources are URIs that AI assistants can read to access data. Unlike tools (which perform actions), resources are read-only data sources.

Example:

"Show me the summary from vertaa://audits/aud_abc123/summary"

Your AI assistant reads the resource and displays the data.

vertaa:// URI Scheme

All VertaaUX resources use the vertaa:// URI scheme:

vertaa://[resource-type]/[identifier]/[sub-resource]

Available Resources

Audit Data

URI Pattern	Description
`vertaa://audits/{auditId}`	Full audit result with all findings
`vertaa://audits/{auditId}/summary`	Lightweight audit summary
`vertaa://audits/{auditId}/findings/{findingId}`	Single finding detail

Screenshots

URI Pattern	Description
`vertaa://screenshots/{auditId}`	Screenshot metadata (dimensions, timestamp)
`vertaa://screenshots/{auditId}/annotated`	Annotated screenshot with finding overlays

History

URI Pattern	Description
`vertaa://history/{encodedUrl}`	Audit history for a specific URL
`vertaa://history/{encodedUrl}/trend`	Score trend over time

Guidelines

URI Pattern	Description
`vertaa://guidelines/{topic}`	UX guidelines for a specific topic

Audit Resources

Full Audit

vertaa://audits/aud_abc123

Returns complete audit data including all findings, scores, and metadata.

"Show me the full audit data from my last audit"

Audit Summary

vertaa://audits/aud_abc123/summary

Lightweight summary suitable for quick overview:

{
  "audit_id": "aud_abc123",
  "url": "https://example.com",
  "status": "completed",
  "scores": {
    "overall": 78,
    "accessibility": 72,
    "ux": 85
  },
  "finding_counts": {
    "critical": 2,
    "serious": 4,
    "moderate": 8,
    "minor": 3
  },
  "completed_at": "2024-01-15T10:32:15Z"
}

Single Finding

vertaa://audits/aud_abc123/findings/fnd_xyz789

Returns detailed information about a specific finding:

{
  "id": "fnd_xyz789",
  "rule_id": "color-contrast",
  "severity": "serious",
  "message": "Text contrast ratio is 3.2:1 (minimum: 4.5:1)",
  "element": {
    "selector": ".hero-text",
    "html": "<p class=\"hero-text\">Welcome</p>"
  },
  "wcag": "1.4.3",
  "remediation_hint": "Increase text color darkness or background lightness"
}

Screenshot Resources

Screenshot Metadata

vertaa://screenshots/aud_abc123

Returns screenshot information:

{
  "audit_id": "aud_abc123",
  "width": 1920,
  "height": 1080,
  "format": "png",
  "captured_at": "2024-01-15T10:30:30Z",
  "url": "https://storage.vertaaux.ai/screenshots/aud_abc123.png"
}

Annotated Screenshot

vertaa://screenshots/aud_abc123/annotated

Screenshot with visual overlays showing finding locations:

{
  "audit_id": "aud_abc123",
  "url": "https://storage.vertaaux.ai/screenshots/aud_abc123_annotated.png",
  "annotations": [
    {
      "finding_id": "fnd_xyz789",
      "x": 100,
      "y": 200,
      "width": 300,
      "height": 50,
      "color": "#ff0000"
    }
  ]
}

History Resources

Audit History

vertaa://history/https%3A%2F%2Fexample.com

Note: URL must be encoded. Returns all audits for that URL:

{
  "url": "https://example.com",
  "audits": [
    {
      "audit_id": "aud_abc123",
      "completed_at": "2024-01-15T10:32:15Z",
      "overall_score": 78,
      "finding_count": 17
    },
    {
      "audit_id": "aud_def456",
      "completed_at": "2024-01-08T14:20:00Z",
      "overall_score": 72,
      "finding_count": 23
    }
  ]
}

"Show me the audit history for example.com"

Score Trend

vertaa://history/https%3A%2F%2Fexample.com/trend

Returns score progression over time:

{
  "url": "https://example.com",
  "trend": [
    { "date": "2024-01-15", "score": 78 },
    { "date": "2024-01-08", "score": 72 },
    { "date": "2024-01-01", "score": 65 }
  ],
  "improvement": 13,
  "direction": "up"
}

Guidelines Resources

Access UX best practices by topic:

Available Topics

Topic	URI
Buttons	`vertaa://guidelines/buttons`
Forms	`vertaa://guidelines/forms`
Navigation	`vertaa://guidelines/navigation`
Color Contrast	`vertaa://guidelines/color-contrast`
Error Messages	`vertaa://guidelines/errors`
Content	`vertaa://guidelines/content`

Example: Button Guidelines

"What are the accessibility guidelines for buttons?"

Claude reads vertaa://guidelines/buttons and returns:

{
  "topic": "buttons",
  "guidelines": [
    {
      "rule": "Accessible name required",
      "description": "All buttons must have an accessible name via text content, aria-label, or aria-labelledby",
      "wcag": "4.1.2"
    },
    {
      "rule": "Keyboard accessible",
      "description": "Buttons must be operable via keyboard (Enter/Space)",
      "wcag": "2.1.1"
    },
    {
      "rule": "Focus visible",
      "description": "Buttons must have visible focus indicator",
      "wcag": "2.4.7"
    }
  ],
  "examples": {
    "good": "<button aria-label=\"Close dialog\">X</button>",
    "bad": "<div onclick=\"close()\">X</div>"
  }
}