Is a complete model necessary?

[Azquelt]

The complete model of data objects for MCP might be useful in implementing an MCP server or client, but I think it comes with some drawbacks when using it as an API:

• the model contains lots of objects that users should never use
  • for example, in any framework where features can be added using annotations, there's no need for the user to use the JSONRPCResponse class
  • this makes the API harder to use
• the model is tied directly to a specific version of MCP and new versions of the protocol might require the model to change in an incompatible way

Could we consider providing just the data objects that are needed to support the annotations and API?

Although we might still run into a situation where the spec evolves in an incompatible way, having our objects not directly reflect the protocol schema would allow implementations to either adapt the object into an appropriate message, or to raise an error.

[Azquelt]

I'm going to experiment with adding everything needed for the annotations to the API, and making the model separate from both.

[cescoffier]

No it's not necessary, it was just an attempt.

[Azquelt]

I've opened #19 with what I've done so far.

Where the user needs to create objects for server function, they inject an object which allows them to create a builder which lets them create the object.

For example for a tool that returns a custom response:

@Inject Tools tools;

@Inject Contents contents;

@Tool
ToolResponse lookupWord(@ToolArg String word) {
    String definition = dictionary.getDefinition(word);
    byte[] image = dictionary.getIllustration(word);

    var responseBuilder = tools.newResult()
               .addContent(contents.newTextContent(definition));
    if (image != null) {
        responseBuilder.addContent(contents.newImageContent().setData(data).setMimeType("image/png").build());
    }
    return responseBuilder.build();
}