mcp no longer works in OSGi

[benken-parasoft]

Bug description
In version 0.12, there was a single "mcp" jar which happens to be a valid OSGi bundle having a valid OSGi manifest. Its dependencies all happen to be OSGi bundles as well. So, mcp and all its dependencies have been loading in OSGi without issue.

In version 0.13, the "mcp" jar has been replaced with "mcp-core" and "mcp-json-jackson2". Although "mcp-core" is still an OSGi bundle, "mcp-json-jackson2" is not.

Environment
I have been using an Apache Felix Servlet Bridge setup but the OSGi container shouldn't matter.

Steps to reproduce
Building an McpServer from an OSGi container results in the following:

java.lang.IllegalStateException: No default JsonSchemaValidatorSupplier implementation found
 at io.modelcontextprotocol.json.schema.JsonSchemaInternal.lambda$createDefaultValidator$2(JsonSchemaInternal.java:66)
 at java.base/java.util.Optional.orElseThrow(Optional.java:403)
 at io.modelcontextprotocol.json.schema.JsonSchemaInternal.createDefaultValidator(JsonSchemaInternal.java:61)
 at io.modelcontextprotocol.json.schema.JsonSchemaInternal.getDefaultValidator(JsonSchemaInternal.java:30)
 at io.modelcontextprotocol.json.schema.JsonSchemaValidator.getDefault(JsonSchemaValidator.java:61)
 at io.modelcontextprotocol.server.McpServer$StreamableSyncSpecification.build(McpServer.java:848)

Expected behavior

The "mcp-json-jackson2" jar should have an OSGi manifest. The mcp bundles should have proper "Require-Capability" and "Provide-Capability" headers to support the OSGi Service Loader mechanism, like what's implemented by Apache SPI Fly: https://aries.apache.org/documentation/modules/spi-fly.html#specconf

Minimal Complete Reproducible example

The original Servlet Bridge example is here:
https://github.com/apache/felix-dev/tree/8c10c79ff48b6a8938e9fc8088964a2facb42da1/http/samples/bridge

You would need to add your own OSGi bundle with a bundle Activator that starts an MCP server and registers its transport using the OSGi HTTP service. Some detail: https://github.com/apache/felix-dev/blob/master/http/README.md#using-the-httpservice

Workaround

The workaround is to wrap the "mcp-json-jackson2" jar inside of a custom OSGi bundle and to explicitly call "Builder.jsonMapper" and "jsonSchemaValidator" methods on everything to avoid the broken service lookup.

[garpinc]

One other osgi issue to be addressed.. io.modelcontextprotocol.server.transport.StdioServerTransportProvider; and io.modelcontextprotocol.server.transport.WebMvcStreamableServerTransportProvider are in the same package but in 2 different jars. This causes an issue when you osgi import the package in that it either finds one or the other. In my particular application I need both transports so I am currently forced to copy the source of one of the transports into my code base which is not at all ideal. Ideally if a class is in a different jar it should have a different package to support osgi constructs.

The same happened with the newly refactored jar separations. Packages are share between the jackson and mcp jars.

[scottslewis]

I'm seeing this problem also,

In version 0.13, the "mcp" jar has been replaced with "mcp-core" and "mcp-json-jackson2". Although "mcp-core" is still an OSGi bundle, "mcp-json-jackson2" is not.

Has anyone yet tried just adding the bnd plugin to the build of 'mcp-json-jackson2' yet? That could be the whole problem. I'll try that on my fork later today.

[scottslewis]

I've looked into this and opened new issue #574.

It seems to me that the mcp-json project and the mcp-json-jackson2 project do not have the maven bnd plugins like the mcp-core project has to generate the OSGi bundle manifest.mf contents. It's pretty easy to add, and I'll happily produce a pr, but I think #574 will have to be dealt with first, because in my fork of the mcp-sdk I've updated the mcp-json pom.xml and the mcp-json-jackson2 pom.xml....and they produce fine OSGi bundle meta-data, but it still doesn't work because of issue #574 .

One other thing to say to this audience is that as OSGi does classloading differently, the ServiceLoader mechanism doesn't work 'out of the box' with OSGi frameworks. There is a mediator spec

and an implementation of this mediator spec in the Apache Aries spi-fly project. If the osgi folks would like assistance for using spi-fly to use the ServiceLoader (now in mcp-json and mcp-json-jackson2 projects/jars/soon to be bundles), just LMK.

[benken-parasoft]

I use other bundles which work nicely with Apache SPI Fly. In particular, you can look at how this is done for SLF4J bundles which I use in both Felix and Equinox containers with SPI Fly. I believe the bundles just need the appropriate "Require-Capability" and "Provide-Capability" headers as described in section from the SPI Fly docs that I referenced earlier.

[scottslewis]

Unfortunately, there is apparently a deeper problem here than adding osgi meta-data to the mcp-json and mcp-json-jackson2 projects...see #574 (comment)

[scottslewis]

Unfortunately, there is apparently a deeper problem here than adding osgi meta-data to the mcp-json and mcp-json-jackson2 projects...see #574 (comment)

I want to expand on this a little bit, just so that it's clear to everyone what I perceive is happening with this issue and #574.

For those interested, a short, technical description of the issue is given by the osgi sl mediator spec...in the introduction (2nd paragraph).

I wasn't privy to any technical discussions, but it appears to me that the mcp sdk was recently broken up into three parts corresponding to projects/jars for deployment: mcp-core, mcp-json, and mcp-json-jackson2. There may be others (mcp-spring), but these three are now necessary to do almost anything wrt server creation (e.g. to create a sync server). I expect that's true for client side as well, as json parsing/object mapping is required for clients of course.

mcp-core still has the maven plugins for bnd...which is a tool for producing a jar with osgi meta-data (mostly in manifest.mf).

mcp-json and mcp-json-jackson2 don't yet have the maven plugins for producing maven metadata. I've added them on my fork of the project here the two poms are here and here. I've built these locally and the osgi meta-data is added appropriately.

Even with mcp-json and mcp-json-jackson2 as bundles the same errors reported are occurring in my test runs. That's because in osgi there is a separate classloader for each bundle, and so the mcp-json bundle's classloader cannot 'see' the mcp-json-jackson2 META-INF/services/* files. As described in the mediator spec, OSGi doesn't use the thread context classloader, and so the ServiceLoader fails to load the classes specified in the mcp-json-jackson2/services/* files, and so can't load any default impls for these two required services.

So...how to fix this? Well, one question I have is: What was driving the decision to break out the mcp-json and mcp-json-jackson2 jars/projects from mcp-core? Is this necessary, done for some other perceived reason?

If the structure remains the same, there are some possible technical solutions...and I'm playing around with these now:

Split packages. This is not recommended as it requires the use of Require-Bundle rather than Import-Package by the library consumer, which defeats a lot of the value of osgi in terms of versioning and other things, and creates a terrible burden of maintenance for the library producers; Also doesn't work well at all with OSGi tooling...as again it is 'anti-modularity'. My opinion is it would be a very bad idea to introduce such a requirement on osgi-based mcp sdk consumers before even version 1.0.0 is released.

Fragments. This is also not recommended as it also 'breaks' modularity, but fragments use their host bundle's classloader...and I think that this means that if mcp-json was a host bundle and mcp-json-jackson2 was a fragment (with mcp-json as it's host bundle) that the ServiceLoader in mcp-json would see the META-INF/services/* files and use them. I'm not certain of that though.

Neither of the above solutions is very good, and will have many costs on both the consumers/community and the producers of the sdk. My previous experiences with both split packages and fragments is that they should be avoided if at all possible by library/sdk producers. Thus the question above about what the driving force was behind the mcp sdk split into multiple projects/jars.