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.

Visual Studio Adding Support for MCP Servers

 

https://code.visualstudio.com/docs/copilot/chat/mcp-servers 

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.  

OSGi Services with gRPC - Let's be reactive

ECF has just introduced an upgrade to the grpc distribution provider.   Previously, this distribution provider used ReaxtiveX java version 2 only.  With this release, ReactiveX java version 3 is also supported.

As many know, gRPC allows services (both traditional call/response [aka unary] and streaming services) to be defined by a 'proto3' file.  For example, here is a simple service with four methods, one unary (check) and 3 streaming (server streaming, client streaming, and bi-directional streaming)

syntax = "proto3";

package grpc.health.v1;

option java_multiple_files = true;
option java_outer_classname = "HealthProto";
option java_package = "io.grpc.health.v1.rx3";

message HealthCheckRequest {
  string message = 1;
}

message HealthCheckResponse {
  enum ServingStatus {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
    SERVICE_UNKNOWN = 3;  // Used only by the Watch method.
  }
  ServingStatus status = 1;
}

service HealthCheck {
  // Unary method
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  // Server streaming method
  rpc WatchServer(HealthCheckRequest) returns (stream HealthCheckResponse);
  // Client streaming method
  rpc WatchClient(stream HealthCheckRequest) returns (HealthCheckResponse);
  // bidi streaming method
  rpc WatchBidi(stream HealthCheckRequest) returns (stream HealthCheckResponse);
}

The gRPC project provides a plugin so that when protoc is run, java code (or other language code) is generated that can then be used on the server and/or clients.

With some additional plugins, the classes generated by protoc can use the ReactiveX API for generating code.   So, for example, here is the java code generated by running protoc, grpc, reactive-grpc, and the osgi-generator plugins on the above HealthCheck service definition.  

Note in particular the HealthCheckService interface generated by the osgi-generator protoc plugin:

package io.grpc.health.v1.rx3;

import io.reactivex.rxjava3.core.Single;
import io.reactivex.rxjava3.core.Flowable;

@javax.annotation.Generated(
value = "by grpc-osgi-generator (REACTIVEX) - A protoc plugin for ECF's grpc remote services distribution provider at https://github.com/ECF/grpc-RemoteServiceSProvider ",
comments = "Source: health.proto.  ")
public interface HealthCheckService {
    /**
     * <pre>
     *  Unary method
     * </pre>
     */
    default Single<io.grpc.health.v1.rx3.HealthCheckResponse> check(Single<io.grpc.health.v1.rx3.HealthCheckRequest> requests)  {
        return null;
    }
    /**
     * <pre>
     *  Server streaming method
     * </pre>
     */
    default Flowable<io.grpc.health.v1.rx3.HealthCheckResponse> watchServer(Single<io.grpc.health.v1.rx3.HealthCheckRequest> requests)  {
        return null;
    }
    /**
     * <pre>
     *  Client streaming method
     * </pre>
     */
    default Single<io.grpc.health.v1.rx3.HealthCheckResponse> watchClient(Flowable<io.grpc.health.v1.rx3.HealthCheckRequest> requests)  {
        return null;

    }

    /**
     * <pre>
     *  bidi streaming method
     * </pre>
     */
    default Flowable<io.grpc.health.v1.rx3.HealthCheckResponse> watchBidi(Flowable<io.grpc.health.v1.rx3.HealthCheckRequest> requests)  {
        return null;
    }
}

Note that it uses the two ReactiveX 3 classes: io.reactivex.rxjava3.core.Single, and io.reactivex.rxjava3.core.Flowable. These two classes provide api for event-driven/reactive sending and receiving of unary (Single) and streaming (Flowable) arguments and return values.

The ReactiveX API...particularly Flowable...makes it very easy to implement both consumers and implementers of the streaming API, while maintaining ordered delivery and non-blocking communication.

For example, this is a simple implementation of the HealthCheckService. Note how the Single and flowable methods are able to express the implementation logic through methods such as Flowable.map.
Here is a simple implementation of a consumer of the HealthCheckService.

The use of the ReactiveX API simplifies both the implementation and the consumer use of both unary and streaming services. As an added bonus: the reactive-grpc library used in the ECF Distribution provider provides *flow-control* using backpressure.

In next article I'll describe how OSGi Remote Services can be easily used to export, publish, discover, and import remote services with full support for service versioning, security, and dynamics. I'll also describe one can use tools like maven or bndtools+eclipse to generate source code (as above) from a proto3 file and easily run a generated service as an OSGi Remote Service.

gRPC Remote Services Development with Bndtools - video tutorials

Here are four new videos that show how to define, implement and run/debug gRPC-based remote services using bndtools, eclipse, and ECF remote services.

Part 1 - API Generation - The generation of a OSGi remote service API using bndtools code generation and the protoc/gRPC compiler. The example service API has both unary and streaming gRPC method types supported by the reactivex API.

Part 2 - Implementation and Part 3 - Consumer - bndtools-project-template-based creation of remote service impl and consumer projects

Part 4 - Debugging - Eclipse/bndtools-based running/debugging of the remote service creating in parts 1-3.

gRPC and OSGi Remote Services

 gRPC is a popular framework for creating high-performance remote procedure call-based microservices.  

OSGi Remote Services is a transport-agnostic specification for creating dynamic, versionable, modular, remote services.

The ECF project provides an open implementation of the OSGi Remote Services spec, and has a provider implementation based-upon gRPC.   What this means is that gRPC can be used to create and run as an OSGi remote service, with all the support for service dynamics (particularly important for network-based services), versioning, and other features provided by OSGi remote services.

The architectural fit between gRPC and OSGi Remote Services is very good, since gRPC is concerned with transport-level efficiency (i.e. http/2, binary serialization format), and OSGi Remote Services are completely transport-agnostic, and focuses instead upon service-level concerns (e.g. dynamics, versioning, and service discovery).

gRPC offers support for server and client-based streaming.   In ECF's implementation, streaming rpcs are mapped to the reactivex api.  This means that consumers and implementers of a streaming rpc can simply call methods and provide callbacks (using Flowable), and non-blocking streaming calls will be made.  In addition, the use of reactivex and backpressure will result in transport-level flow control for these streaming APIs!

Another advantage of gRPC for OSGi remote services is it's polyglot nature.   This means that if (for example) a gRPC remote service is run as an OSGi/Java server, clients can be easily implemented in any of the languages supported by gRPC.  As well, servers written in some other language can easily created and accessed from OSGi consumers.  An example of this is the ECF etcd3 discovery provider, which communicates with an etcd server (written in Go) to publish and discover OSGi remote services.

Finally, with bndtools (an Eclipse plugin for OSGi bundle development), ECF Remote Service workspace template, and it's support for generating code as part of Eclipse's incremental build, gRPC code generation can be seemlessly integrated into the Eclipse development environment so that gRPC code generation, compile, and bundle packaging can happen immediately and continuously as part of gRPC remote service development.  For a video tutorial demonstrating this, please see here.

gRPC Code Generation using Bndtools and ECF Remote Services

There's a new video tutorial that demonstrates using ECF Remote Services, bndtools, and Eclipse to create an OSGi Remote Service.   

Bndtools has recently added the ability to run code generators as part of a bnd-based project, and with ECF's bndtools workspace template, a single proto3 file added to a project will automatically generate an entire Java remote service API and update/regenerate the API as changes are made to the proto3 file.   No command-line execution of protoc needed.

Further with ECF's project templates, the generated API can be easily implemented and exported as an OSGi Remote Service.

Please watch the video here

ECF 3.14.19 released - simplify remote service discovery via properties

 ECF 3.14.19 has been released.

Along with the usual bug fixes, this release includes new documentation on the use of properties for discovering and importing remote services.   The docs describe the use of properties files for simplifying the import of remote services.   

This capability is especially useful for Eclipse RCP clients accessing Jax-RS/REST remote services.

Patrick Paulin describes a production usage his blog posting here.

Using properties to simplify discovery of OSGi Remote Services

OSGi Remote Services are discovered by ECF's Remote Services implementation in two ways:  

1. Via a network discovery protocol provider such as:  Zeroconf, jSLP, etcd, Zookeeper, or some custom protocol

2. Via an xml format known as an Endpoint Description Extender Format (EDEF)

 The EDEF format is specified by the OSGi Remote Service Admin specification.   

When importing an EDEF-defined remote service, it's typically necessary to construct the entire EDEF file 'by hand' rather than having he EDEF generated automatically.  This can be quite complicated to construct by hand as some properties are required, others are optional and it's not obvious what all of the values must be for successful import.

A new capability has been added to ECF's Remote Service Admin implementation that allows EDEF Properties to be used with the EDEF, thus simplifying the creation of remote service consumers that use EDEF for import.

This capability was added to support the usage of JaxRS Remote Services in an Eclipse RCP client.  See a description of this use case here.

Using gRPC-java code generation to create OSGi Services

OSGi Services are usually first created by declaring a java service interface class.  As an OSGi service, this interface class serves as both the name for the service in the service registry, and defines the service contract (i.e. the interface method signatures...i.e. the method name, argument types, and return types) for that version of the service.

gRPC (Google RPC) is a popular and high-performance rpc approach that allows developers to define networked services based upon protocol buffers (proto3).

By extending bndtools recently-added code generation capability, it's now possible to generate an OSGi (remote) service API from just a proto3 service declaration.  All the classes necessary for an OSGi Remote Service API (service interface, arg and return types) can be generated by bndtools within Eclipse from a single proto3 file, immediately and completely.

Ready to implement-and-consume OSGi Services can be generated by Eclipse+bndtools + a proto3 service declaration.

Further, the proto3 service declaration can be modified, and the tooling will immediately generate new service API classes, compile, and package them into a bundle, all from within Eclipse+bndtools.

To get this bndtools-grpc generation with an example see here.

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.

Using Google's grpc-java for OSGi Remote Services

A cool thing about Google's grpc is that a service creator can declare a service via a protocol buffers file (.proto file), and then the protoc compiler (along with grpc-java compiler plugin) generates many of the Java classes for both implementing and using that service.

OSGi Remote Services require a service interface to represent the service contract, and this service interface is usually created directly by the programmer.   Through a additional plugin, protoc can now generate a OSGi service interface along with all grpc classes... from the .proto file service declaration.   

For example, consider the following protocol buffers input file:

syntax = "proto3";
package grpc.health.v1;
option java_multiple_files = true;
option java_outer_classname = "HealthProto";
option java_package = "io.grpc.health.v1";
message HealthCheckRequest {
  string message = 1;
}
message HealthCheckResponse {
  enum ServingStatus {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
    SERVICE_UNKNOWN = 3;  // Used only by the Watch method.
  }
  ServingStatus status = 1;
}
service HealthCheck {
  // Unary method
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  // Streaming method
  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
}

Running protoc+grpc-java+grpc-osgi-generator on this file results in generation of a HealthCheckService class along with all message classes (e.g. HealthCheckRequest, HealthCheckResponse, HealthProto, etc).   All of the Java classes in this example directory were created simply by running protoc+grpc-java+grpc-osgi-generator on the above proto file.

The generated Java classes can then be used to implement an OSGi Remote Service, with HealthCheckService as the service interface.   Tt runtime, the HealthCheckServiceImpl can be exported (via the Grpc Provider) which uses grpc to provide the comm and json serialization for the HealthCheckService method calls.

The net effect is that remote service programmers can easily and quickly go from abstract service declaration (in proto file) to a running/functioning OSGi remote service:

1. Declare a service in proto file -- example proto file
2. Run protoc+grpc-java+grpc-osgi-generator to generate the Java code for the declared service - example Java generated code
3. Implement the service API - example service implementation
4. Use Declarative Services to export using ECF Remote Services + Grpc Distribution Provider - example (see @Component annotation for OSGi Remote Services-required service properties to trigger export)

The remote service programmer writes no communication nor serialization code (both are provided by the Grpc distribution provider).   See here for the complete generated healthcheck api plugin, here for the impl plugin, and here for a simple remote service consumer.

ECF 3.14.7 released

ECF 3.14.7 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

Enhanced:  Hazelcast-based Distribution Provider v1.7.0.  Upgraded to use Hazelcast 4
Enhanced:  System and Service-Properties docs for Distribution Providers and Discovery Providers

Bndtools Development

Enhanced:  Bndtools Workspace template with new Bndrun templates for Remote Services Development
Enhanced:  Tutorial for using Bndtools for Remote Services Development

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

 

OSGi Remote Services with Apache Dubbo

ECF's implementation of OSGi R7 Remote Services allows for replacing the underlying distribution system (repsonsible for the object serialization, transport, and other things). 

This makes it relatively easy to replace one kind of distribution (e.g. Jersey, ActiveMQ) with other/new distribution systems. 

Apache Dubbo has recently been contributed to Apache, and we've created a distribution provider based upon Apache Dubbo.

Here's a list of open ECF Remote Service distribution providers.   If you would like Remote Services support for a particular transport, or you've created your own distribution (or discovery) based upon some other transport and wish to make it available to others please let us know.

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+.

ECF 3.14.4 released

ECF 3.14.4 was recently released.  This was a bug-fix release.  There are notes on some of the recent additions here.

ECF 3.14.3 released

ECF 3.14.3 has been released.  This is a bug fix release, but in addition to the fixes a number of usage examples have been created:

Remote Services Between Java and Python and Python for OSGi Remote Services

RESTful Remote Services Using either CXF or Jersey

Using OSGi R7 Async Remote Services

Using Gogo Commands and RSA for Controlling Remote Services

Using BndTools 4 for Developing OSGi Remote Services

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.