Skip to content

SPEC.md

Latest commit

 

History

History
126 lines (85 loc) · 3.6 KB

SPEC.md

File metadata and controls

126 lines (85 loc) · 3.6 KB
Raw

Context Specification

Version: 0.1

Purpose

Context defines a structured packet for transmitting what a user is seeing, selecting, or marking in a web interface to an AI agent or chat system.

The packet is transport-agnostic. It can be sent over MCP, HTTP, browser extension messaging, postMessage, SDK calls, or stored for later use.

Design principles

  • Explicit beats scraping. Prefer app-authored semantic metadata when available.
  • User intent matters. Packets should preserve the gesture or capture mode that created them.
  • Privacy is part of the format. Redaction and consent metadata are required.
  • Provenance is required. Consumers should know who produced a packet and how.
  • Packets are structured first. Prompt strings can be derived from packets, but should not be the canonical form.
  • Transport is separate from the data model. MCP is a major bridge, not the owner of the packet shape.

Packet envelope

Every packet MUST include:

  • protocol: currently askable.context
  • version: currently 0.1
  • source: where the context came from
  • capture: how the context was captured
  • privacy: redaction and consent state
  • provenance: producer and method

Capture modes

The initial capture modes are:

  • text-selection: selected text or range
  • element-focus: focused, hovered, clicked, or selected UI element
  • viewport: visible page region
  • full-page: full document or app page
  • region: rectangular region
  • lasso: freeform selected region
  • circle: user circled a region
  • semantic: app-provided context without a DOM element
  • custom: implementation-specific mode

Gestures

Gestures describe what the user or runtime did:

  • click
  • hover
  • focus
  • keyboard
  • drag
  • circle
  • lasso
  • programmatic
  • custom

Target

target describes the main thing the user pointed at.

Fields:

  • text: safe text representation
  • role: semantic or accessibility role
  • label: human-readable label
  • selector: optional selector or durable app identifier
  • bounds: viewport-relative rectangle
  • metadata: app-provided structured data or string
  • screenshot: optional visual crop

Surrounding context

surrounding can include:

  • ancestors: parent context chain
  • nearby: related nearby items
  • visible: visible annotated items
  • history: recent context entries

Consumers SHOULD treat surrounding context as secondary. The target is the user's primary context.

Privacy

privacy is required.

Fields:

  • redacted: whether redaction/sanitization was applied
  • consent: explicit, implicit, or none
  • omitted: optional list of omitted fields or categories

Consumers SHOULD NOT assume unredacted packets are safe to send to a model. Producers SHOULD redact sensitive data before packet construction whenever possible.

Provenance

provenance is required.

Fields:

  • producer: package, app, extension, or service name
  • method: app, dom, extension, mcp, or manual

MCP mapping

MCP servers SHOULD expose Context packets as structured JSON from tools or resources.

Recommended MCP surface:

  • Resource: context://schema
  • Tool: get_current_context
  • Tool: get_context_schema
  • Tool: format_context_for_prompt

MCP tools SHOULD return packets, not only prompt strings.

Versioning

Packet versions follow semver-like compatibility:

  • Patch-level schema clarifications do not change the packet version.
  • Additive optional fields may remain in 0.1 while the format is experimental.
  • Breaking changes require a new packet version.

Consumers SHOULD ignore unknown optional fields unless their validator is intentionally strict.