Protocol specification

The current protocol version is 0.1.

Provider API

Providers can be implemented:

  • as an HTTP endpoint.
  • as a JavaScript file (with a default export). See "Creating a provider".

Both ways of implementing a provider use the same methods and types for communication. For simplicity, this document describes the protocol as implemented over HTTP.

A provider is specified by a URL that responds to HTTP POST requests.

  • Request body (JSON): interface RequestMessage { method: string, params?: object, settings?: object }
  • Response body (JSON): interface ResponseMessage { result?: object, error?: { code: integer, message: string, data?: any } }

Providers are stateless.

Providers must implement 2 API methods:

Capabilities

The capabilities request is sent by the client to the provider to retrieve information about the provider's capabilities and when it should be invoked. This avoids unnecessary invocations of the provider on resources where it would not have any items.

Request: { method: "capabilities", params: CapabilitiesParams, settings?: object }


interface CapabilitiesParams {
// empty for now
}

Response: { result: CapabilitiesResult } or { error: { code, integer, data? } }


interface CapabilitiesResult {
/**
* Selects the scope in which this provider should be called.
*
* If one or more selectors are given, all must be satisfied for the
* provider to be called. If undefined, the provider is called on all resources.
* If empty, the provider is never invoked.
*/
selector?: Selector[]
}
/**
* Defines a scope in which a provider is called.
*
* To satisfy a selector, all of the selector's conditions must be met. For
* example, if both `path` and `content` are specified, the resource must satisfy
* both conditions.
*/
interface Selector {
/**
* A glob that must match the resource's hostname and path.
*/
path?: string
/**
* A literal string that must be present in the resource's content for the
* provider to be called.
*/
contentContains?: string
}

Items

The items request is sent by the client to the provider to fetch a list of items for a resource.

Request: { method: "items", params: ItemsParams, settings?: object }


interface ItemsParams {
/** The resource's URI (e.g., `file:///home/alice/foo.js`). **/
uri: string
/** The resource's content. **/
content: string
}

Response: { result: ItemsResult } or { error: { code, integer, data? } }


type ItemsResult = Item[]
/**
* An item describes information relevant to a resource (or a range within a resource).
*/
interface Item {
/**
* A descriptive title of the item.
*/
title: string
/**
* An external URL with more information about the item.
*/
url?: string
/**
* The human user interface of the item, with information for human consumption.
*/
ui?: UserInterface
/**
* Information from the item intended for consumption by AI, not humans.
*/
ai?: AssistantInfo
/**
* The range in the resource that this item applies to. If not set, the item applies to the entire resource.
*/
range?: { start: Position; end: Position }
}
/**
* The human user interface of the item, with information for human consumption.
*/
export interface UserInterface {
/**
* Additional information for the human, shown in a tooltip-like widget when they interact with the item.
*/
hover?: { markdown?: string, text?: string }
}
/**
* Information from the item intended for consumption by AI, not humans.
*/
export interface AssistantInfo {
/**
* Text content for AI to consume.
*/
content?: string
}
interface Position {
/** Line number (0-indexed). */
line: number
/** Character offset on line (0-indexed). */
character: number
}