Building MCP Servers - part 2: Example Using Remote Services and Bndtools

In a previous post, I described how using dynamic remote tools could make building MCP Servers more flexible, more secure, and more scalable.  In this post, I show an example MCP Server that uses remote services and Bndtools to build.

To use/try this example yourself see Installing Bndtools with Remote Services Support below.

Create a Bndtools Workspace via File->New->Bndtools Workspace, and choose the ECF/bndtools.workspace template from this dialog

Choose Next->Finish

Choose File->New->Bnd OSGi Project to show this dialog

There are 4 project templates.  They should each be created in your workspace in turn:

1. MCP ArithmeticTools API Project  (example name: org.test.api)

2. MCP ArithmeticTools Impl Server Project (ArimethicTools RS Server) (example name: org.test.impl)

3. MCP ArithmeticTools Consumer Project (MCP Server Impl/ArithmeticTools Consumer) (example name: org.test.mcpserver)

4. MCP ArithmeticTools Test Client Project (MCP Client) (example name: org.test.mcpclient)

Note:  For the Impl/Consumer/Test Client project creations you will be prompted to provide the name of the project that you specified for the API Project (1)

Click Finish for each of the first 3 (server) projects.

If you wish to use your own MCP Client, and start the MCP Server (MCP ArithmeticTools Consumer Project) from your own MCP Client (stdio transport), see the Readme.md in the MCP ArithmeticTools Consumer project.

MCP ArithmeticTools Example Test Client

There is also a MCP Example Test Client Project template, implemented via the MCP Java SDK that makes a couple of test calls to the MCP Server/Arithmetic Tools Consumer server.

Note:  When creating the test client, the project template will as for you to specify the names of the API project (1) and the MCP Server/ArithmeticTools Consumer project (3).   For example:

Click Finish

You should have these four projects in the Bndtools Explorer

You can open source for any/all the projects, set breakpoints, etc.

Launching the ArithmeticTools Remote Service Impl server

The ArithmeticTools Impl server (2) must be launched first

To launch the ArithmeticTools Impl (2), see the Readme.md in that project

Launching MCP Client and MCP Server (with stdio transport)

The MCP Client (4) may then be launched, and it will launch the MCP Server (3) and use the MCP stdio transport.   The MCP Client (4) Readme.md more info on launch and expected output of the MCP Client.

You may examine or set breakpoints in the ArithmeticTools Impl Server (2) or the MCP Client (4) to examine the communication sequence for calling the ArithmeticTools.add or multiple tools.

Installing Bndtools with Remote Services Support

1. Install Bndtools 7.1 

2. Add ECF Latest Update site to Eclipse install with URL: https://download.eclipse.org/rt/ecf/latest/site.p2

3. Install Feature:  SDK for Bndtools 7.1+

Building MCP Servers: Integration via Remote Tools

It has become popular to build Model Context Protocol Servers.  This makes a lot of sense from the developer-as-integrator point of view, since the MCP specification and multi-language SDKs make it possible to easily integrate resources, prompts, and tools into multiple LLMs without having to use the model-and-language-specific model APIs directly.

MCP tools spec provides a general way for LLMs to use tool meta-data (e.g. text descriptions) for the tool's required input data, behavior, and output data.  These text descriptions can then be used by the LLM...in combination with interaction with the user...to decide when and how to use the tool...i.e. to call the function and provide some output to the LLM and/or the user.

Building an MCP Server

When creating a new MCP Server, it's easiest to create the tool metadata and implement the tool functionality as part of a new MCP server implementation.   But this approach requires that every new tool (or integration with existing API/servers) results in a new MCP server or an update/new version of an existing MCP server.

Remote Tools

It's frequently better architecture to decouple the meta-data declaration and implementation of a given tool from the MCP Server itself, and allow the MCP Server to dynamically add/remove tools at runtime, as tools can then be discovered, added, meta-data made available to the model(s), called, evaluated, and potentially removed or updated without the creation of an entirely new MCP Server, but rather dynamically discovering, securing, importing, using, evaluating, updating, and removing tools from an MCP Server.  

This approach is potentially more secure (as it allows tool-specific authentication and access control), more flexible, and more scalable, since remote tools can be distributed on multiple hosts over a network.  And it allows easy integration with existing APIs.

In the next post I describe a working example that uses remote tools.

Remote Tools for Model Context Protocol (MCP) Servers

The Model Context Protocol (MCP) is a new protocol for integrating AI/LLMs with existing software services.  MCP Server Tools allow LLMs get additional context-relevant data, write/change remote data, and to take actions.

Most current MCP servers declare their tools statically.  When the MCP server starts up it's available tools and any tool meta-data (such as text descriptions of the tool behavior provided in decorators or annotations) are made available to MCP clients that connect to an MCP server.  The MCP client (LLM) can then call an available tool at the appropriate time, providing tool-specific input data, and the tool can take actions, get additional data, and provide those data to the client.

OSGi Remote Services/Remote Service Admin provides a open, standardized, multi-protocol, modular,  extensible way to discover, dynamically export and import, and secure inter-process communication between services.  Combining Remote Services with MCP Tool meta-data allows the creation of dynamic remote tools.

Remote Tools for MCP Servers

This README.md shows an example 'Arithmetic' service, with 'add' and 'multiply' tools defined and described via Java annotations to an ArithmeticTools service. The python MCP Server communicates with the Java Server (startup and after) to dynamically add to/update from its set of tools that it exposes to MCP Clients.

Here is a simple diagram showing the communication between and MCP client, the Python MCP Server, and a Java Arithmetic Service Server.

MCP Client (LLM)  <- MCP -> Python MCP Server <- Arithmetic Service -> Java Server

The ArithmeticTools service is a simple example, but exposes a powerful and general capability,  Arbitrary remote tool services may be declared and provided with the appropriate tool description meta-data, and then made dynamically available to any MCP servers created in Python, Java, or other languages.  Both the MCP and RS/RSA are transport agnostic, allowing the service developer and service provider to use the remote-tool-appropriate-and-secure communication protocol.  

ECF 3.14.12 released - Now with gRPC for OSGi Remote Services

ECF 3.14.12 was just released

Highlights of this Release

New OSGi Remote Services Distribution provider based upon gRPC/Protocol Buffers. Along with a grpc-osgi-generator project...which allows the generation of a service API from a proto3 service declaration...this provider allows gRPC-based services to be exported and imported as OSGi Remote Services.  This now includes support for unary, server-streaming, and client-streaming gRPC calls.

Enhanced Support for Bndtools-based development of OSGi Remote Services.   The ECF Bndtools Workspace now includes the latest version of ECF Remote Services, along with the gRPC distribution provider, a Hazelcast-based discovery and distribution provider, and project and bndrun templates for creating, running, testing, and debugging OSGi Remote Services in Eclipse+Bndtools 5.

ECF 3.14.6 Released

ECF 3.14.6 has been released and may be downloaded here.

In concert with this bug fix release have been a number of additions to ECF's github projects for Remote Services Development.

Distribution and Discovery Providers

New:  Apache Dubbo-based Distribution Provider
Enhanced:  Hazelcast-based Distribution Provider and New: Discovery Provider
Enhanced:  System and Service-Properties docs for Distribution Providers and Discovery Providers

Bndtools Development

Enhanced:  Bndtools Workspace, Project, and Bndrun templates for Remote Services Development
New:  Bndtools Workspace with Jersey JaxRS Distribution Provider and Tasklist Example
Enhanced:  Tutorial for using Bndtools for Remote Services Development

 

New Release: Python<->Java Remote Services

There is a new release (2.9.0) of the ECF distribution provider for OSGi R7 Remote Services between Java and Python.

This release has:

An upgraded version of Py4j
An upgraded version of Google Protocol Buffers
Enhancements to the distribution provider based upon the improved Py4j and Protobuf libs

In this previous blog posting there are links to tutorials and examples showing how to use remote services between Python<->Java.

Python<->Java remote services can be consumed or implemented in either Java or Python.

RESTful OSGi R7 Remote Services with Jersey 2.28 or Apache CXF 3.3

For some time, ECF has had remote service distribution providers that use the Jersey or the CXF implementation of standard Java API for RESTful Web Services (JaxRS). 

These distribution providers allow OSGi R7 Remote Services to be defined via JaxRS annotations and implemented by either Jersey 2.28 or CXF 3.3. 

OSGi R7 Remote Services provides support for renite service discovery, dynamics, versioning, configuration and extension of the distribution providers, and asynchronous remote calls as well as other features of the OSGi R7 Remote Services and Remote Service Admin specs.

This tutorial shows the use of OSGi Remote Services with these JaxRS distribution providers on Apache Karaf.

There is also a new version of the ECF Bndtools workspace template with example Bndtools projects showing the use of these distribution providers to define, configure, run and deploy RESTful OSGi R7 Remote Services with Bndtools 4.2+.

OSGi Remote Services Between Python and Java

In a previous post, I described the support for OSGi Remote Services and Remote Service Admin in iPOPO 0.8.0 release.   The previous post refers to a tutorial showing a Python service impl and Python consumer.

Python<->Java Distribution Provider

Included with iPOPO 0.8.0 is a distribution provider that allows remote services between Java and Python frameworks.   For example, this is a tutorial, that uses Karaf on the Java side as the remote service implementation, and has a Python consumer that calls the Java-implemented remote service.

Python Service Implementation with Java Consumers

This distribution provider also supports Python-implemented remote services, with Java/OSGi consumers.   With iPOPO for dynamic service injection in Python, and Declarative Services for Java/OSGi, this allows very easy Python<->Java service-level interaction, with support for all dynamics, RSA management agent, extensible/customizable topology management, management of complicated service dependencies, pluggable local and network discovery, and other RS/RSA features handled consistently in both Java and Python.  As well, the use of OSGi-specified EndpointDescription service metadata allows service-level interoperability across languages.

Python<->Java with Protocol Buffers Serialization

Also included with this distribution provider is serialization using Google's protocol buffers.  This allows open, extensible, and efficient rpc between Python and Java.

Python for OSGi Remote Services

The iPOPO project is a Python implementation of key parts of a standard OSGi framework...e.g. bundles, the service registry and servicereference api, and a dynamic service injection framework similar to the Apache iPOJO project...thus the name iPOPO.

With the 0.8.0 release of iPOPO, there is now a Python implementation of the OSGi Remote Services and Remote Service Admin (RSA) specifications.   To distinguish from the previously-provided remote services in iPOPO, this is known as RSA Remote Services.

iPOPO's RSA Remote Services has many of the same advantages as Java-based Remote Services/RSA.  Some of these advantages:

Decoupling - name/service contract is decoupled from the implementation (and distribution)

Dynamics - The service registry dynamics behavior, along with all notifications, etc is available in Python

Injection and Service Dependency Management - iPOPO provides service injection and dependency management, built upon the Python API

Standard RemoteServiceAdmin Management Agent, RSA Console Commands

API for Distribution and Discovery Providers - There are documented APIs for creating new distribution and discovery providers, making it easy to support other transports and implementations for distribution (e.g. REST/JaxRS, Jsonrpc, MQTT, Zeroconf Discovery, etc).

Other advantages of Java-based OSGi services are described here.   All of these advantages apply to Python/iPOPO-based services, but Python can be used to implement and/or consume services.

Currently, there are two distribution providers included with iPOPO 0.8.0:  XmlRpc, Python-Java and one discovery provider: etcd.   See here for tutorials showing their usage with included sample remote services. 

Other distribution and discovery providers are being considered or worked on.  If you are interested in seeing a particular transport supported for distribution or discovery please open an issue on the iPOPO project.

Remote Services between Python and Java

The Python-Java distribution provider makes it possible to use OSGi Remote Services between Python and Java...on both sides.    This allows Remote Services to be exported from Python, and discovered/imported and consumed in Java, or exported from Java and discovered/imported/consumed from Python.  See here for a sample and tutorial.   These capabilities and the underlying distribution provider will be described in more detail in a subsequent posting.

Rest Remote Services with CXF or Jersey

ECF's Photon Release now includes an example of using Karaf with the JaxRS distribution provider.

This distribution provider now fully supports OSGi R7 remote services, including async remote services, using either the Jersey or CXF JaxRS implementations.

This allows service developers to easily use only JAX-RS annotations to define and implement OSGi R7 remote services.

ECF Photon supports OSGi R7 Async Services - part 2

In a previous post, I described a usage of OSGi R7's Async Remote Services. This specification makes it easy to define, implement and use non-blocking remote services. ECF's implementation allows the use of pluggable transports...known as distribution providers.

Here's a partial list of distribution providers:

R-OSGi
ECF generic
JMS/ActiveMQ
XML-RPC
Hazelcast
MQTT
Jax-RS Jersey
Jax-RS CXF
JavaGroups
Python.Java (Supports async remote services between Java and Python with protocol buffers serialization)

 It's also straightforward to creation your own distribution provider, using private or legacy transport and/or serialization. This can be done by extending one of the distribution providers above or creating a new one.

Most of these distribution providers have updated examples and/or tutorials, and many of them now have templates included in the Bndtools (4.0+) Support added for Photon.

Separating the remote service contract from the underlying distribution provider via OSGi remote services allows implementers and consumers to create, debug, and test remote services without being bound to a single transport, while still allowing consistent (specified) runtime behavior.

For more info and links, please see the New and Noteworthy.

ECF Photon adds Gogo Commands

A third major enhancement for ECF's implementation of OSGi Remote Services is the addition of Apache Gogo console commands for examining the existing state of remote services, and the ability to export a service and import an endpoint from the OSGi console.

See this wiki page describing the new commands and their usage.

ECF Photon supports Bndtools

A second major enhancement for ECF Photon is adding support for using Bndtools to develop and test OSGi Remote Services.   Bndtools is increasingly popular for developing OSGi-based applications and frameworks, and we've added support for Bndtools Workspace, Project, and Run Descriptor templates for developing and testing remote services.

Initial documentation is available at Bndtools Support for Remote Services Development.

Note that these templates and the RSA impl may change slightly before ECF Photon, and new/additional templates will be added to (e.g.) support other distribution and discovery providers.

ECF 3.13.8 and etcd discovery for remote services

ECF 3.13.8 has been available since September, but there are some new things available:

ECF 3.13.8 changes have distributed to maven central

There is a new release (1.3.0) of the etcd discovery provider.    This provider uses an ectd cluster to publish and discover remote services allow complete integration with systems like Kubernetes, which also use etcd for service discovery.

ECF 3.13.7 Oxygen: Maven and Python OSGi Services

ECF 3.13.7 has been released as part of the Oxygen Simultaneous Release.  ECF's work recently has emphasized it's implementation of OSGi Remote Services, and the 3.13.7 continues this emphasis.

Highlights:

1. ECF has multiple distribution providers, and most have been moved to Maven-based builds
2. Remote Services/RSA is now available via Maven Central, and the Karaf Feature Install uses Maven install.
3. A new distribution provider that allows Python code as OSGi Services.   See this tutorial for a description.
4. Many bug fixes and small improvements

ECF 3.13.4 now available

ECF 3.13.4 is now available.  This was a maintenance release, with bug fixes for the Eclipse tooling for OSGi Remote Services and an update of the Apache Httpclient filetransfer provider contributed to Eclipse.

ECF 3.13.3 Available

ECF 3.13.3 is now available.

3.13.3 is a maintenance release, focused on fixes for ECF's implementation of OSGi Remote Services and Remote Service Admin.   Among other things, the tutorial that uses Karaf as the remote service host and Eclipse as the remote service consumer has been simplified and updated to use take maximum advantage of Java8 and Eclipse Neon.

ECF 3.13.2

ECF 3.13.2 is now available.

This is a maintenance/bug fix release, but includes new documentation on growing set of ECF distribution providers to support our implementation of OSGi Remote Services.

New and Noteworthy here.

Polyglot Remote Services

ECF has a growing number of distribution providers that implement the OSGi Remote Service Admin (RSA) specification.   Recently, a provider based upon Google RPC was introduced, and now a provider based upon XML-RPC is available.   It's also now much easier to create custom distribution providers using any desired transport.   All ECF distribution providers fully and automatically implement the OSGi RSA specification.

Several of these new distribution providers also support non-OSGi and even non-Java servers and/or clients...i.e. written in JavaScript, Python, C++ and other languages.   This has a number of use cases allowing cross-language interoperability and backward compatibility.  Some examples:

It's possible to take an existing/deployed service (written in any language) and easily create an RSA client for it.   This allows RSA/OSGi to be used for discovery, deal with remote service dynamics, use of DS or Spring, and service versioning on the consumer/client.

It's possible to export an OSGi Remote Service and use any/all clients (written in any language  supported by the exporting distribution provider).

It's possible to take an existing web server implementation, and move/refactor it to OSGi RSA without breaking backward compatibility for existing clients (written in any language).

Microservices Granularity for the Internet of Things

In a 2014 blog posting, Martin Fowler discussed issues around creating networked services in Microservices and the First Law of Distributed Objects.   One of his points is that networked services should generally be more coarse-grained than local (in-process) services. The reason for this is that distribution always has costs (bandwidth, performance), and these costs easily can become large with fine-grained remote calls.

But as Fowler points out, there are good reasons (e.g. complexity) to make a networked API as fine-grained as possible.   How granular/coarse should IoT microservices be?  In his blog posting, Fowler suggested that granularity was an open question, and that experience with different systems with different levels of microservices granularity would provide eventual insight.

I agree with Fowler's view that experience is necessary to decide on 'appropriate' granularity.   I think it's particularly true for the Internet of Things, where multiple people and organizations are attempting attempting to create consistent abstractions for the relatively-limited input and output capabilities exposed by newly networked devices...aka 'things'.

But when actually defining remote services, often the first thing done is to bind the service to a particular transport+protocol+impl framework (e.g. https+json+jersey).   Once bound to a transport, the service API may become very difficult to refactor and version.  This is especially true once a service has been deployed, but frequently deployment is the only way to get enough real experience to be more (or less) granular!

One way to provide flexibility...and allow future change to a service is to remain as transport-independent as possible.   As described by this article, new standards such as OSGi Remote Services/RSA and ECF's modular implementation makes it possible to design and refactor services independent of the transport.  Such independence will make it easier to update the granularity of a microservice when necessary.