Skip to content

Commit 503baad

Browse files
jspahrsummersjspahrsummers
authored
Merge pull request modelcontextprotocol#50 from modelcontextprotocol/baxen/annotations
Add optional annotations
2 parents 641392e + 76abe9a commit 503baad

File tree

2 files changed

+174
-22
lines changed

2 files changed

+174
-22
lines changed

‎schema/schema.json

Lines changed: 129 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,30 @@
11
{
22
"$schema": "http://json-schema.org/draft-07/schema#",
33
"definitions": {
4+
"Annotated": {
5+
"description": "Base for objects that include optional annotations for the client. The client can use annotations to inform how objects are used or displayed",
6+
"properties": {
7+
"annotations": {
8+
"properties": {
9+
"audience": {
10+
"description": "Describes who the intended customer of this object or data is.\n\nIt can include multiple entries to indicate content useful for multiple audiences (e.g., `[\"user\", \"assistant\"]`).",
11+
"items": {
12+
"$ref": "#/definitions/Role"
13+
},
14+
"type": "array"
15+
},
16+
"priority": {
17+
"description": "Describes how important this data is for operating the server.\n\nA value of 1 means \"most important,\" and indicates that the data is\neffectively required, while 0 means \"least important,\" and indicates that\nthe data is entirely optional.",
18+
"maximum": 1,
19+
"minimum": 0,
20+
"type": "number"
21+
}
22+
},
23+
"type": "object"
24+
}
25+
},
26+
"type": "object"
27+
},
428
"BlobResourceContents": {
529
"properties": {
630
"blob": {
@@ -393,11 +417,7 @@
393417
"type": "string"
394418
},
395419
"role": {
396-
"enum": [
397-
"assistant",
398-
"user"
399-
],
400-
"type": "string"
420+
"$ref": "#/definitions/Role"
401421
},
402422
"stopReason": {
403423
"description": "The reason why sampling stopped, if known.",
@@ -418,6 +438,24 @@
418438
"EmbeddedResource": {
419439
"description": "The contents of a resource, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render embedded resources for the benefit\nof the LLM and/or the user.",
420440
"properties": {
441+
"annotations": {
442+
"properties": {
443+
"audience": {
444+
"description": "Describes who the intended customer of this object or data is.\n\nIt can include multiple entries to indicate content useful for multiple audiences (e.g., `[\"user\", \"assistant\"]`).",
445+
"items": {
446+
"$ref": "#/definitions/Role"
447+
},
448+
"type": "array"
449+
},
450+
"priority": {
451+
"description": "Describes how important this data is for operating the server.\n\nA value of 1 means \"most important,\" and indicates that the data is\neffectively required, while 0 means \"least important,\" and indicates that\nthe data is entirely optional.",
452+
"maximum": 1,
453+
"minimum": 0,
454+
"type": "number"
455+
}
456+
},
457+
"type": "object"
458+
},
421459
"resource": {
422460
"anyOf": [
423461
{
@@ -502,6 +540,24 @@
502540
"ImageContent": {
503541
"description": "An image provided to or from an LLM.",
504542
"properties": {
543+
"annotations": {
544+
"properties": {
545+
"audience": {
546+
"description": "Describes who the intended customer of this object or data is.\n\nIt can include multiple entries to indicate content useful for multiple audiences (e.g., `[\"user\", \"assistant\"]`).",
547+
"items": {
548+
"$ref": "#/definitions/Role"
549+
},
550+
"type": "array"
551+
},
552+
"priority": {
553+
"description": "Describes how important this data is for operating the server.\n\nA value of 1 means \"most important,\" and indicates that the data is\neffectively required, while 0 means \"least important,\" and indicates that\nthe data is entirely optional.",
554+
"maximum": 1,
555+
"minimum": 0,
556+
"type": "number"
557+
}
558+
},
559+
"type": "object"
560+
},
505561
"data": {
506562
"description": "The base64-encoded image data.",
507563
"format": "byte",
@@ -584,6 +640,10 @@
584640
"capabilities": {
585641
"$ref": "#/definitions/ServerCapabilities"
586642
},
643+
"instructions": {
644+
"description": "Instructions describing how to use the server and its features.\n\nThis can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a \"hint\" to the model. For example, this information MAY be added to the system prompt.",
645+
"type": "string"
646+
},
587647
"protocolVersion": {
588648
"description": "The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect.",
589649
"type": "string"
@@ -1295,11 +1355,7 @@
12951355
]
12961356
},
12971357
"role": {
1298-
"enum": [
1299-
"assistant",
1300-
"user"
1301-
],
1302-
"type": "string"
1358+
"$ref": "#/definitions/Role"
13031359
}
13041360
},
13051361
"required": [
@@ -1416,6 +1472,24 @@
14161472
"Resource": {
14171473
"description": "A known resource that the server is capable of reading.",
14181474
"properties": {
1475+
"annotations": {
1476+
"properties": {
1477+
"audience": {
1478+
"description": "Describes who the intended customer of this object or data is.\n\nIt can include multiple entries to indicate content useful for multiple audiences (e.g., `[\"user\", \"assistant\"]`).",
1479+
"items": {
1480+
"$ref": "#/definitions/Role"
1481+
},
1482+
"type": "array"
1483+
},
1484+
"priority": {
1485+
"description": "Describes how important this data is for operating the server.\n\nA value of 1 means \"most important,\" and indicates that the data is\neffectively required, while 0 means \"least important,\" and indicates that\nthe data is entirely optional.",
1486+
"maximum": 1,
1487+
"minimum": 0,
1488+
"type": "number"
1489+
}
1490+
},
1491+
"type": "object"
1492+
},
14191493
"description": {
14201494
"description": "A description of what this resource represents.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.",
14211495
"type": "string"
@@ -1504,6 +1578,24 @@
15041578
"ResourceTemplate": {
15051579
"description": "A template description for resources available on the server.",
15061580
"properties": {
1581+
"annotations": {
1582+
"properties": {
1583+
"audience": {
1584+
"description": "Describes who the intended customer of this object or data is.\n\nIt can include multiple entries to indicate content useful for multiple audiences (e.g., `[\"user\", \"assistant\"]`).",
1585+
"items": {
1586+
"$ref": "#/definitions/Role"
1587+
},
1588+
"type": "array"
1589+
},
1590+
"priority": {
1591+
"description": "Describes how important this data is for operating the server.\n\nA value of 1 means \"most important,\" and indicates that the data is\neffectively required, while 0 means \"least important,\" and indicates that\nthe data is entirely optional.",
1592+
"maximum": 1,
1593+
"minimum": 0,
1594+
"type": "number"
1595+
}
1596+
},
1597+
"type": "object"
1598+
},
15071599
"description": {
15081600
"description": "A description of what this template is for.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.",
15091601
"type": "string"
@@ -1566,6 +1658,14 @@
15661658
},
15671659
"type": "object"
15681660
},
1661+
"Role": {
1662+
"description": "The sender or recipient of messages and data in a conversation.",
1663+
"enum": [
1664+
"assistant",
1665+
"user"
1666+
],
1667+
"type": "string"
1668+
},
15691669
"Root": {
15701670
"description": "Represents a root directory or file that the server can operate on.",
15711671
"properties": {
@@ -1622,11 +1722,7 @@
16221722
]
16231723
},
16241724
"role": {
1625-
"enum": [
1626-
"assistant",
1627-
"user"
1628-
],
1629-
"type": "string"
1725+
"$ref": "#/definitions/Role"
16301726
}
16311727
},
16321728
"required": [
@@ -1815,6 +1911,24 @@
18151911
"TextContent": {
18161912
"description": "Text provided to or from an LLM.",
18171913
"properties": {
1914+
"annotations": {
1915+
"properties": {
1916+
"audience": {
1917+
"description": "Describes who the intended customer of this object or data is.\n\nIt can include multiple entries to indicate content useful for multiple audiences (e.g., `[\"user\", \"assistant\"]`).",
1918+
"items": {
1919+
"$ref": "#/definitions/Role"
1920+
},
1921+
"type": "array"
1922+
},
1923+
"priority": {
1924+
"description": "Describes how important this data is for operating the server.\n\nA value of 1 means \"most important,\" and indicates that the data is\neffectively required, while 0 means \"least important,\" and indicates that\nthe data is entirely optional.",
1925+
"maximum": 1,
1926+
"minimum": 0,
1927+
"type": "number"
1928+
}
1929+
},
1930+
"type": "object"
1931+
},
18181932
"text": {
18191933
"description": "The text content of the message.",
18201934
"type": "string"

‎schema/schema.ts

Lines changed: 45 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,12 @@ export interface InitializeResult extends Result {
167167
protocolVersion: string;
168168
capabilities: ServerCapabilities;
169169
serverInfo: Implementation;
170+
/**
171+
* Instructions describing how to use the server and its features.
172+
*
173+
* This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.
174+
*/
175+
instructions?: string;
170176
}
171177

172178
/**
@@ -411,7 +417,7 @@ export interface ResourceUpdatedNotification extends Notification {
411417
/**
412418
* A known resource that the server is capable of reading.
413419
*/
414-
export interface Resource {
420+
export interface Resource extends Annotated {
415421
/**
416422
* The URI of this resource.
417423
*
@@ -442,7 +448,7 @@ export interface Resource {
442448
/**
443449
* A template description for resources available on the server.
444450
*/
445-
export interface ResourceTemplate {
451+
export interface ResourceTemplate extends Annotated {
446452
/**
447453
* A URI template (according to RFC 6570) that can be used to construct resource URIs.
448454
*
@@ -581,14 +587,19 @@ export interface PromptArgument {
581587
required?: boolean;
582588
}
583589

590+
/**
591+
* The sender or recipient of messages and data in a conversation.
592+
*/
593+
export type Role = "user" | "assistant";
594+
584595
/**
585596
* Describes a message returned as part of a prompt.
586597
*
587598
* This is similar to `SamplingMessage`, but also supports the embedding of
588599
* resources from the MCP server.
589600
*/
590601
export interface PromptMessage {
591-
role: "user" | "assistant";
602+
role: Role;
592603
content: TextContent | ImageContent | EmbeddedResource;
593604
}
594605

@@ -598,7 +609,7 @@ export interface PromptMessage {
598609
* It is up to the client how best to render embedded resources for the benefit
599610
* of the LLM and/or the user.
600611
*/
601-
export interface EmbeddedResource {
612+
export interface EmbeddedResource extends Annotated {
602613
type: "resource";
603614
resource: TextResourceContents | BlobResourceContents;
604615
}
@@ -792,14 +803,41 @@ export interface CreateMessageResult extends Result, SamplingMessage {
792803
* Describes a message issued to or received from an LLM API.
793804
*/
794805
export interface SamplingMessage {
795-
role: "user" | "assistant";
806+
role: Role;
796807
content: TextContent | ImageContent;
797808
}
798809

810+
/**
811+
* Base for objects that include optional annotations for the client. The client can use annotations to inform how objects are used or displayed
812+
*/
813+
export interface Annotated {
814+
annotations?: {
815+
/**
816+
* Describes who the intended customer of this object or data is.
817+
*
818+
* It can include multiple entries to indicate content useful for multiple audiences (e.g., `["user", "assistant"]`).
819+
*/
820+
audience?: Role[];
821+
822+
/**
823+
* Describes how important this data is for operating the server.
824+
*
825+
* A value of 1 means "most important," and indicates that the data is
826+
* effectively required, while 0 means "least important," and indicates that
827+
* the data is entirely optional.
828+
*
829+
* @TJS-type number
830+
* @minimum 0
831+
* @maximum 1
832+
*/
833+
priority?: number;
834+
}
835+
}
836+
799837
/**
800838
* Text provided to or from an LLM.
801839
*/
802-
export interface TextContent {
840+
export interface TextContent extends Annotated {
803841
type: "text";
804842
/**
805843
* The text content of the message.
@@ -810,7 +848,7 @@ export interface TextContent {
810848
/**
811849
* An image provided to or from an LLM.
812850
*/
813-
export interface ImageContent {
851+
export interface ImageContent extends Annotated {
814852
type: "image";
815853
/**
816854
* The base64-encoded image data.

0 commit comments

Comments
 (0)