Skip to content

fix: model content annotations as nested objects #242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
+321 −10
Closed

fix: model content annotations as nested objects #242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d55d404
fix: model annotations as nested objects
LucaButBoring May 16, 2025
253e360
fix: add backwards compat shims for old annotations
LucaButBoring May 16, 2025
90eefe9
Merge branch 'main' into fix/content-annotations
LucaButBoring Jun 10, 2025
8526daa
chore: generalize annotation tests to all transports
LucaButBoring Jun 16, 2025
917dd96
Merge branch 'main' of https://github.com/modelcontextprotocol/java-s…
LucaButBoring Jun 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions mcp-test/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,11 @@
<artifactId>junit-jupiter-api</artifactId>
<version>${junit.version}</version>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-params</artifactId>
<version>${junit.version}</version>
</dependency>
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
Expand Down
61 changes: 61 additions & 0 deletions mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Disabled;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;
Expand All @@ -42,6 +44,7 @@
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.assertj.core.api.Assertions.fail;

/**
* Test suite for the {@link McpAsyncClient} that can be used with different
Expand Down Expand Up @@ -208,6 +211,64 @@ void testCallToolWithInvalidTool() {
});
}

@ParameterizedTest
@ValueSource(strings = { "success", "error", "debug" })
void testCallToolWithMessageAnnotations(String messageType) {
McpClientTransport transport = createMcpTransport();

withClient(transport, mcpAsyncClient -> {
StepVerifier.create(mcpAsyncClient.initialize()
.then(mcpAsyncClient.callTool(new McpSchema.CallToolRequest("annotatedMessage",
Map.of("messageType", messageType, "includeImage", true)))))
.consumeNextWith(result -> {
assertThat(result).isNotNull();
assertThat(result.isError()).isNotEqualTo(true);
assertThat(result.content()).isNotEmpty();
assertThat(result.content()).allSatisfy(content -> {
switch (content.type()) {
case "text":
McpSchema.TextContent textContent = assertInstanceOf(McpSchema.TextContent.class,
content);
assertThat(textContent.text()).isNotEmpty();
assertThat(textContent.annotations()).isNotNull();

switch (messageType) {
case "error":
assertThat(textContent.annotations().priority()).isEqualTo(1.0);
assertThat(textContent.annotations().audience())
.containsOnly(McpSchema.Role.USER, McpSchema.Role.ASSISTANT);
break;
case "success":
assertThat(textContent.annotations().priority()).isEqualTo(0.7);
assertThat(textContent.annotations().audience())
.containsExactly(McpSchema.Role.USER);
break;
case "debug":
assertThat(textContent.annotations().priority()).isEqualTo(0.3);
assertThat(textContent.annotations().audience())
.containsExactly(McpSchema.Role.ASSISTANT);
break;
default:
throw new IllegalStateException("Unexpected value: " + content.type());
}
break;
case "image":
McpSchema.ImageContent imageContent = assertInstanceOf(McpSchema.ImageContent.class,
content);
assertThat(imageContent.data()).isNotEmpty();
assertThat(imageContent.annotations()).isNotNull();
assertThat(imageContent.annotations().priority()).isEqualTo(0.5);
assertThat(imageContent.annotations().audience()).containsExactly(McpSchema.Role.USER);
break;
default:
fail("Unexpected content type: " + content.type());
}
});
})
.verifyComplete();
});
}

@Test
void testListResourcesWithoutInitialization() {
verifyCallSucceedsWithImplicitInitialization(client -> client.listResources(null), "listing resources");
Expand Down
57 changes: 57 additions & 0 deletions mcp-test/src/main/java/io/modelcontextprotocol/client/AbstractMcpSyncClientTests.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,16 @@
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.assertj.core.api.Assertions.fail;

/**
* Unit tests for MCP Client Session functionality.
Expand Down Expand Up @@ -183,6 +186,60 @@ void testCallTools() {
});
}

@ParameterizedTest
@ValueSource(strings = { "success", "error", "debug" })
void testCallToolWithMessageAnnotations(String messageType) {
McpClientTransport transport = createMcpTransport();

withClient(transport, client -> {
client.initialize();

McpSchema.CallToolResult result = client.callTool(new McpSchema.CallToolRequest("annotatedMessage",
Map.of("messageType", messageType, "includeImage", true)));

assertThat(result).isNotNull();
assertThat(result.isError()).isNotEqualTo(true);
assertThat(result.content()).isNotEmpty();
assertThat(result.content()).allSatisfy(content -> {
switch (content.type()) {
case "text":
McpSchema.TextContent textContent = assertInstanceOf(McpSchema.TextContent.class, content);
assertThat(textContent.text()).isNotEmpty();
assertThat(textContent.annotations()).isNotNull();

switch (messageType) {
case "error":
assertThat(textContent.annotations().priority()).isEqualTo(1.0);
assertThat(textContent.annotations().audience()).containsOnly(McpSchema.Role.USER,
McpSchema.Role.ASSISTANT);
break;
case "success":
assertThat(textContent.annotations().priority()).isEqualTo(0.7);
assertThat(textContent.annotations().audience()).containsExactly(McpSchema.Role.USER);
break;
case "debug":
assertThat(textContent.annotations().priority()).isEqualTo(0.3);
assertThat(textContent.annotations().audience())
.containsExactly(McpSchema.Role.ASSISTANT);
break;
default:
throw new IllegalStateException("Unexpected value: " + content.type());
}
break;
case "image":
McpSchema.ImageContent imageContent = assertInstanceOf(McpSchema.ImageContent.class, content);
assertThat(imageContent.data()).isNotEmpty();
assertThat(imageContent.annotations()).isNotNull();
assertThat(imageContent.annotations().priority()).isEqualTo(0.5);
assertThat(imageContent.annotations().audience()).containsExactly(McpSchema.Role.USER);
break;
default:
fail("Unexpected content type: " + content.type());
}
});
});
}

@Test
void testPingWithoutInitialization() {
verifyCallSucceedsWithImplicitInitialization(client -> client.ping(), "pinging the server");
Expand Down
90 changes: 80 additions & 10 deletions mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1384,22 +1384,68 @@ else if (this instanceof EmbeddedResource) {
@JsonInclude(JsonInclude.Include.NON_ABSENT)
@JsonIgnoreProperties(ignoreUnknown = true)
public record TextContent( // @formatter:off
@JsonProperty("audience") List<Role> audience,
@JsonProperty("priority") Double priority,
@JsonProperty("text") String text) implements Content { // @formatter:on
@JsonProperty("annotations") Annotations annotations,
@JsonProperty("text") String text) implements Annotated, Content { // @formatter:on

public TextContent(String content) {
this(null, null, content);
this(null, content);
}

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link TextContent#TextContent(Annotations, String)} instead.
*/
public TextContent(List<Role> audience, Double priority, String content) {
this(audience != null || priority != null ? new Annotations(audience, priority) : null, content);
}

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link TextContent#annotations()} instead.
*/
public List<Role> audience() {
return annotations == null ? null : annotations.audience();
}

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link TextContent#annotations()} instead.
*/
public Double priority() {
return annotations == null ? null : annotations.priority();
}
}

@JsonInclude(JsonInclude.Include.NON_ABSENT)
@JsonIgnoreProperties(ignoreUnknown = true)
public record ImageContent( // @formatter:off
@JsonProperty("audience") List<Role> audience,
@JsonProperty("priority") Double priority,
@JsonProperty("annotations") Annotations annotations,
@JsonProperty("data") String data,
@JsonProperty("mimeType") String mimeType) implements Content { // @formatter:on
@JsonProperty("mimeType") String mimeType) implements Annotated, Content { // @formatter:on

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link ImageContent#ImageContent(Annotations, String, String)} instead.
*/
public ImageContent(List<Role> audience, Double priority, String data, String mimeType) {
this(audience != null || priority != null ? new Annotations(audience, priority) : null, data, mimeType);
}

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link ImageContent#annotations()} instead.
*/
public List<Role> audience() {
return annotations == null ? null : annotations.audience();
}

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link ImageContent#annotations()} instead.
*/
public Double priority() {
return annotations == null ? null : annotations.priority();
}
}

@JsonInclude(JsonInclude.Include.NON_ABSENT)
Expand All @@ -1413,9 +1459,33 @@ public record AudioContent( // @formatter:off
@JsonInclude(JsonInclude.Include.NON_ABSENT)
@JsonIgnoreProperties(ignoreUnknown = true)
public record EmbeddedResource( // @formatter:off
@JsonProperty("audience") List<Role> audience,
@JsonProperty("priority") Double priority,
@JsonProperty("resource") ResourceContents resource) implements Content { // @formatter:on
@JsonProperty("annotations") Annotations annotations,
@JsonProperty("resource") ResourceContents resource) implements Annotated, Content { // @formatter:on

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link EmbeddedResource#EmbeddedResource(Annotations, ResourceContents)}
* instead.
*/
public EmbeddedResource(List<Role> audience, Double priority, ResourceContents resource) {
this(audience != null || priority != null ? new Annotations(audience, priority) : null, resource);
}

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link EmbeddedResource#annotations()} instead.
*/
public List<Role> audience() {
return annotations == null ? null : annotations.audience();
}

/**
* @deprecated Only exists for backwards-compatibility purposes. Use
* {@link EmbeddedResource#annotations()} instead.
*/
public Double priority() {
return annotations == null ? null : annotations.priority();
}
}

// ---------------------------
Expand Down
61 changes: 61 additions & 0 deletions mcp/src/test/java/io/modelcontextprotocol/client/AbstractMcpAsyncClientTests.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Disabled;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;
Expand All @@ -42,6 +44,7 @@
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.assertj.core.api.Assertions.fail;

/**
* Test suite for the {@link McpAsyncClient} that can be used with different
Expand Down Expand Up @@ -209,6 +212,64 @@ void testCallToolWithInvalidTool() {
});
}

@ParameterizedTest
@ValueSource(strings = { "success", "error", "debug" })
void testCallToolWithMessageAnnotations(String messageType) {
McpClientTransport transport = createMcpTransport();

withClient(transport, mcpAsyncClient -> {
StepVerifier.create(mcpAsyncClient.initialize()
.then(mcpAsyncClient.callTool(new McpSchema.CallToolRequest("annotatedMessage",
Map.of("messageType", messageType, "includeImage", true)))))
.consumeNextWith(result -> {
assertThat(result).isNotNull();
assertThat(result.isError()).isNotEqualTo(true);
assertThat(result.content()).isNotEmpty();
assertThat(result.content()).allSatisfy(content -> {
switch (content.type()) {
case "text":
McpSchema.TextContent textContent = assertInstanceOf(McpSchema.TextContent.class,
content);
assertThat(textContent.text()).isNotEmpty();
assertThat(textContent.annotations()).isNotNull();

switch (messageType) {
case "error":
assertThat(textContent.annotations().priority()).isEqualTo(1.0);
assertThat(textContent.annotations().audience())
.containsOnly(McpSchema.Role.USER, McpSchema.Role.ASSISTANT);
break;
case "success":
assertThat(textContent.annotations().priority()).isEqualTo(0.7);
assertThat(textContent.annotations().audience())
.containsExactly(McpSchema.Role.USER);
break;
case "debug":
assertThat(textContent.annotations().priority()).isEqualTo(0.3);
assertThat(textContent.annotations().audience())
.containsExactly(McpSchema.Role.ASSISTANT);
break;
default:
throw new IllegalStateException("Unexpected value: " + content.type());
}
break;
case "image":
McpSchema.ImageContent imageContent = assertInstanceOf(McpSchema.ImageContent.class,
content);
assertThat(imageContent.data()).isNotEmpty();
assertThat(imageContent.annotations()).isNotNull();
assertThat(imageContent.annotations().priority()).isEqualTo(0.5);
assertThat(imageContent.annotations().audience()).containsExactly(McpSchema.Role.USER);
break;
default:
fail("Unexpected content type: " + content.type());
}
});
})
.verifyComplete();
});
}

@Test
void testListResourcesWithoutInitialization() {
verifyCallSucceedsWithImplicitInitialization(client -> client.listResources(null), "listing resources");
Expand Down
Loading
Loading