mcp_osgi by laeubi - MCP Server

mcp_osgi

A MCP server dedicated to bring tools useful in OSGi context

🎯 Primary Use Case: This MCP server is designed for GitHub Copilot Coding Agent in repository-scoped agent mode. The agent runs in GitHub Actions and connects to the server via HTTP/SSE transport.

📖 Documentation: Extend Coding Agent with MCP

Note: This project now uses the official MCP Java SDK (v0.14.1) instead of a homebrew implementation. This provides a standardized, production-ready implementation of the Model Context Protocol with better maintainability and feature support.

Introduction

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. MCP provides:

Standardized Integration: A universal protocol for connecting AI assistants with various tools and data sources
Tool Exposure: A way to expose tools that can be discovered and invoked by AI agents
Bi-directional Communication: JSON-RPC 2.0 based protocol for client-server communication
Rich Capabilities: Support for resources, prompts, and tools with structured schemas

MCP is particularly useful for AI workflows like GitHub Copilot Coding Agents, which can use MCP servers to access specialized tools and domain-specific functionality.

What is OSGi?

OSGi (Open Services Gateway initiative) is a Java framework for developing and deploying modular software programs and libraries. Key features include:

Modularity: Applications are built from reusable bundles (JAR files with metadata)
Dynamic Service Model: Services can be dynamically installed, started, stopped, updated, and uninstalled at runtime
Versioning: Sophisticated dependency management with version ranges
Service Registry: A dynamic service registry for loose coupling between components
Lifecycle Management: Complete control over bundle lifecycle

OSGi is widely used in enterprise applications, IDE platforms (like Eclipse), and embedded systems.

Preliminary Work & Use Cases

Current Implementation Status

This project provides an example MCP server implementation that exposes OSGi-related tools through the MCP protocol, enabling AI agents to interact with OSGi environments.

Example Tools Implemented:

hello_osgi - A demonstration tool showing basic MCP server functionality with OSGi context
bundle_info - Analyzes JAR or MANIFEST.MF files to determine if they are OSGi bundles and returns metadata
find - Searches for OSGi packages, bundles, or capabilities and returns download information

Potential OSGi Tools for MCP Exposure

The following OSGi tools and commands would be valuable to expose through MCP for AI-assisted development:

Bundle Management

list_bundles - List all installed bundles with their state, version, and symbolic name
bundle_info - Get detailed information about a specific bundle
install_bundle - Install a new bundle from a URL or local path
start_bundle - Start a specific bundle
stop_bundle - Stop a specific bundle
update_bundle - Update an existing bundle
uninstall_bundle - Uninstall a bundle

Service Management

list_services - List all registered OSGi services
service_info - Get detailed information about a service (interfaces, properties, using bundles)
service_references - Find service references matching a filter

Dependency Analysis

check_dependencies - Analyze bundle dependencies and identify missing requirements
why_not_resolved - Diagnose why a bundle is not resolved
package_wiring - Show package wiring between bundles
capability_requirements - Analyze bundle capabilities and requirements

Configuration & Management

list_configurations - List Configuration Admin configurations
get_configuration - Retrieve a specific configuration
update_configuration - Update configuration properties
delete_configuration - Delete a configuration

Diagnostics & Troubleshooting

diagnose_framework - Get OSGi framework state and diagnostics
bundle_headers - Display bundle manifest headers
bundle_classpath - Show bundle classpath entries
find_class - Find which bundle exports a specific class/package

Build & Development

resolve_bundles - Attempt to resolve bundles
refresh_bundles - Refresh bundle wiring
validate_manifest - Validate a bundle manifest file
generate_manifest - Generate OSGi manifest from Maven/Gradle metadata

Benefits for AI-Assisted Development

By exposing OSGi tools through MCP, AI coding agents can:

Understand OSGi Applications: Analyze bundle structures, dependencies, and service relationships
Troubleshoot Issues: Diagnose bundle resolution problems, missing dependencies, and configuration issues
Automate Tasks: Perform routine OSGi management tasks like installing, starting, and configuring bundles
Generate Code: Create properly structured OSGi bundles with correct manifests and metadata
Provide Guidance: Offer context-aware suggestions based on actual OSGi framework state

Example: Hello OSGi MCP Server

This repository includes a Maven-based example MCP server that demonstrates how to:

Set up a Java MCP server using the official MCP Java SDK
Define and expose tools through the MCP protocol
Implement tool handlers with OSGi context
Support multiple transport modes: stdio and HTTP with SSE (Server-Sent Events)

The server uses the official MCP Java SDK v0.14.1 which provides:

Standardized implementation of the Model Context Protocol
Built-in stdio transport for inter-process communication
HTTP/SSE transport for server-based deployments
Asynchronous server capabilities with Project Reactor
JSON schema validation and tool registration APIs

Building and Running

# Build the project
mvn clean package

The server supports two transport modes:

stdio mode (default): Communicates via JSON-RPC 2.0 over stdin/stdout. Useful for local testing and development.
server mode: Runs an embedded HTTP server with SSE (Server-Sent Events) transport. This is the mode used by GitHub Copilot Coding Agent.

Note: GitHub Copilot Coding Agent automatically builds and starts the server - you don't need to run it manually. The commands below are for local development and testing only.

# Run the MCP server in stdio mode (for local testing)
java -jar target/mcp-osgi-server-1.0.0-SNAPSHOT.jar

# Run the MCP server in server mode (for testing GitHub Copilot configuration locally)
java -jar target/mcp-osgi-server-1.0.0-SNAPSHOT.jar server 3000

Using with GitHub Copilot Coding Agent

This MCP server is designed to be used with GitHub Copilot Coding Agent in repository-scoped agent mode, where the agent runs in GitHub Actions and can access custom tools through MCP servers.

📖 Official Documentation: Extend Coding Agent with MCP

How It Works

Navigate to your repository on GitHub.com
Invoke GitHub Copilot Coding Agent from the web interface
Automatic Setup: The agent automatically:
- Runs the .github/workflows/copilot-setup-steps.yml workflow to build the server
- Starts the server in HTTP/SSE mode using the configuration in .mcp/config.json
- Connects to the server via SSE (Server-Sent Events) transport
- Makes all registered tools available to the Copilot agent

Configuration Files

.mcp/config.json - MCP server configuration for GitHub Copilot Coding Agent:

{
  "mcpServers": {
    "osgi": {
      "command": "java",
      "args": ["-jar", "/home/runner/tools/osgi_mcp/server.jar", "server", "3000"],
      "url": "http://localhost:3000/mcp/sse"
    }
  }
}

.github/workflows/copilot-setup-steps.yml - Workflow that builds and deploys the MCP server JAR to the expected location.

⚠️ Important: These files are configured specifically for the GitHub Copilot Coding Agent environment. The workflow job and step names must match GitHub's requirements and should not be modified unless explicitly needed.

Available Tools

The server exposes the following tools to the Copilot agent:

hello_osgi - Demonstration tool showing basic MCP server functionality
bundle_info - Analyzes JAR or MANIFEST.MF files to determine if they are OSGi bundles
find - Searches for OSGi packages, bundles, or capabilities and returns download information

For more details about the configuration, see .mcp/README.md.

Local Development and Testing

While this server is primarily designed for GitHub Copilot Coding Agent, you can also run it locally for development and testing purposes.

Running the Server Locally

# Build the project
mvn clean package

# Run in stdio mode (default - for command-line testing)
java -jar target/mcp-osgi-server-1.0.0-SNAPSHOT.jar

# Run in server mode (HTTP/SSE - for testing the GitHub Copilot configuration locally)
java -jar target/mcp-osgi-server-1.0.0-SNAPSHOT.jar server 3000

Testing with stdio Mode

In stdio mode, the server communicates via JSON-RPC 2.0 over stdin/stdout:

# Start the server and pipe a test request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0"}}}' | java -jar target/mcp-osgi-server-1.0.0-SNAPSHOT.jar

Testing with Server Mode (HTTP/SSE)

In server mode, the server runs an HTTP server with SSE transport:

# Start the server
java -jar target/mcp-osgi-server-1.0.0-SNAPSHOT.jar server 3000

# In another terminal, test the SSE endpoint
curl http://localhost:3000/mcp/sse

Note: stdio mode is useful for local testing and development, but it is not used by GitHub Copilot Coding Agent. The GitHub agent exclusively uses HTTP/SSE server mode as configured in .mcp/config.json.

Project Structure

mcp_osgi/
├── .github/
│   ├── workflows/
│   │   ├── pr-verification.yml              # CI workflow for PR verification
│   │   └── copilot-setup-steps.yml          # Setup steps for Copilot Coding Agent
│   └── copilot-instructions.md              # GitHub Copilot instructions
├── src/
│   ├── main/
│   │   └── java/
│   │       └── io/github/laeubi/mcp/osgi/
│   │           └── OsgiMcpServer.java       # Main MCP server implementation
│   └── test/
│       └── java/
│           └── io/github/laeubi/mcp/osgi/
│               ├── OsgiMcpServerTest.java          # Tests for stdio mode
│               └── OsgiMcpServerModeTest.java      # Tests for server mode
├── pom.xml                                  # Maven build configuration
├── local-development-config-example.json    # Example config for local stdio testing (NOT for GitHub Copilot)
├── .gitignore                               # Git ignore patterns
├── README.md                                # This file
└── LICENSE                                  # Eclipse Public License 2.0

Key Files

OsgiMcpServer.java: The main MCP server implementation using the official MCP Java SDK that exposes OSGi tools (hello_osgi, bundle_info, find)
pom.xml: Maven configuration with dependencies for the MCP Java SDK (v0.14.1) and SLF4J (logging)
local-development-config-example.json: Example stdio configuration for local testing (not for GitHub Copilot)
copilot-setup-steps.yml: GitHub Actions workflow for setting up the environment in Copilot Coding Agent

Implementation Details

The server implementation leverages the official MCP Java SDK:

Transport Layer: Uses StdioServerTransportProvider for stdio-based communication
Server Type: Built with McpServer.async() for non-blocking asynchronous operations
Tool Registration: Tools are registered using the SDK's toolCall() method with proper schema definitions
JSON Handling: Uses the SDK's built-in Jackson integration for JSON serialization
Reactive Streams: Tool handlers return Mono<CallToolResult> for reactive processing

Contributing

Contributions are welcome! Please feel free to submit pull requests with:

Additional OSGi tools for MCP exposure
Improvements to existing tools
Documentation enhancements
Bug fixes

License

This project is licensed under the Eclipse Public License 2.0 - see the file for details.