Publish a `mcp-annotations` module with just annotations for MCP Server primitives annotations.

[sdelamo]

Would you be open to publish a new module mcp-annotations with just a "standard" set of annotations for MCP Server Primitives (@Tool, @ToolArg, @Prompt, ...)?.

Those annotations could be used by frameworks downstream. That way we would avoid having to duplicate these annotations in the different frameworks.

E.g. Quarkus @Tool annotation:

https://github.com/quarkiverse/quarkus-mcp-server/blob/main/core/runtime/src/main/java/io/quarkiverse/mcp/server/Tool.java

[lambochen]

Related: https://github.com/spring-ai-community/mcp-annotations

[tzolov]

Hey @sdelamo, we're exploring using MCP annotations in our mcp-annotations project.

We currently support these Client and Server annotations. The sub-project is currently Spring-agnostic, but we plan to move some/all of this work to spring-ai for better auto-configuration support.

Our concern: since annotations aren't part of the spec and will likely remain implementation-specific, we don't want to impose annotations that may not be useful for other frameworks.

But if you're interested in trying to reuse (a subset of) the mcp annotations for a different framework, and it works, then we can make those annotations part of the SDK.

What do you think?

[sdelamo]

Annotations should be in this repository. They should be published to the coordinate io.modelcontextprotocol.sdk:mcp-annotations with no extra dependencies.

There are items in this repository that are not specified in the spec but are helpful in Java implementations of MCP servers.

If we don't ship framework-agnostic annotations in a framework-agnostic repository, we are going to end up repeating annotations in every framework — similar problem with the nullability annotations.

I think we can agree on a set of annotations. An annotation for tool, an annotation for argument, and annotation for prompt etc.

[scottslewis]

I would recommend that when moved to mcp-java-sdk, the annotations package/classes be distributed as a separate maven module/jar/osgi bundle (i.e. not in mcp-core or any other existing module). If help implementing this change is desired, I can and will contribute.

Also for reference, this mcp-annotations issue is requesting the same thing as this issue:

spring-ai-community/mcp-annotations#10

[tzolov]

To clarify: OSGi/Java modules are not a priority for the MCP project and won't drive design decisions here. Support for them would be provided as best effort and treated as an implementation detail.

Regarding MCP Annotations, an important question is: which of the available MCP Client and Server annotations should we include in the mcp-java-sdk project, and what argument signatures will best support the spec?

[scottslewis]

To clarify: OSGi/Java modules are not a priority for the MCP project and won't drive design decisions here. Support for them would be provided as best effort and treated as an implementation detail.

FWIW. By saying this:

a separate maven module/jar/osgi bundle (i.e. not in mcp-core or any other existing module).

I was just saying that it could/should be deployed as a separate jar...if possible. If I contribute this refactoring/move (which I'm willing to do), then I will be responsible for the best effort in supporting osgi...along with a commitment for support/maintenance.

Regarding MCP Annotations, an important question is: which of the available MCP Client and Server annotations should we include in the mcp-java-sdk project, and what argument signatures will best support the spec?

Right. I'm taking a look at that myself in my fork as we speak. Comments and discussion on technical specifics are welcome. I will endeavor to produce a pr within a couple of days that can be reviewed/commented on/changed/modified.