Skip to content

Ean Schuessler / mo-mcp

Go to a project
Toggle navigation
Toggle navigation pinning
3a39f97b by Ean Schuessler
Options

Refactor MCP servlet to adapter architecture 

Introduce clean adapter layer between Moqui infrastructure and MCP protocol:

- transport/MoquiMcpTransport: Interface abstracting transport concerns
- transport/SseTransport: SSE implementation with session management
- adapter/McpSessionAdapter: Maps Moqui Visit to MCP sessions
- adapter/McpToolAdapter: Maps MCP tools/methods to Moqui services
- adapter/MoquiNotificationMcpBridge: Bridges Moqui notifications to MCP

Simplify EnhancedMcpServlet to orchestrator role, removing inline session
management, SSE logic, and tool dispatch. Remove redundant session
validation in Initialize service (MoquiAuthFilter handles auth).

Delete obsolete files:
- VisitBasedMcpSession.groovy (replaced by McpSessionAdapter)
- JsonRpcMessage.groovy (using plain Maps)
- MoquiMcpTransport.groovy (replaced by new interface)
1 parent 9aefba5e
Expand all
Inline Side-by-side
Showing 10 changed files with 843 additions and 344 deletions
......@@ -37,46 +37,11 @@
// Permissions are handled by Moqui's artifact authorization system
// Users must be in appropriate groups (McpUser, MCP_BUSINESS) with access to McpServices artifact group
// Disable authz to prevent automatic Visit updates during MCP operations
// Authentication is handled by MoquiAuthFilter - user context is already set
// No need to re-validate session ownership here
ec.artifactExecution.disableAuthz()
// Get Visit (session) created by servlet and validate access
def visit = ec.entity.find("moqui.server.Visit")
.condition("visitId", sessionId)
.one()
if (!visit) {
throw new Exception("Invalid session: ${sessionId}")
}
if (visit.userId != ec.user.userId) {
throw new Exception("Access denied for session: ${sessionId}")
}
// Update Visit with MCP initialization data
UserInfo adminUserInfo = null
try {
adminUserInfo = ec.user.pushUser("ADMIN")
def metadata = [:]
try {
metadata = groovy.json.JsonSlurper().parseText(visit.initialRequest ?: "{}") as Map
} catch (Exception e) {
ec.logger.debug("Failed to parse Visit metadata: ${e.message}")
}
metadata.mcpInitialized = true
metadata.mcpProtocolVersion = protocolVersion
metadata.mcpCapabilities = capabilities
metadata.mcpClientInfo = clientInfo
metadata.mcpInitializedAt = System.currentTimeMillis()
// Session metadata stored in memory only - no Visit updates to prevent lock contention
ec.logger.info("SESSIONID: ${sessionId} - metadata stored in memory")
} finally {
if (adminUserInfo != null) {
ec.user.popUser()
}
}
ec.logger.info("MCP Initialize for session ${sessionId}, user ${ec.user.userId}")
// Validate protocol version - support common MCP versions with version negotiation
def supportedVersions = ["2025-11-25", "2025-06-18", "2024-11-05", "2024-10-07", "2023-06-05"]
......
/*
* This software is in the public domain under CC0 1.0 Universal plus a
* Grant of Patent License.
*
* To the extent possible under law, author(s) have dedicated all
* copyright and related and neighboring rights to this software to the
* public domain worldwide. This software is distributed without any
* warranty.
*
* You should have received a copy of the CC0 Public Domain Dedication
* along with this software (see the LICENSE.md file). If not, see
* <http://creativecommons.org/publicdomain/zero/1.0/>.
*/
package org.moqui.mcp
import groovy.json.JsonOutput
/**
* Simple JSON-RPC Message classes for MCP compatibility
*/
class JsonRpcMessage {
String jsonrpc = "2.0"
String toJson() {
return JsonOutput.toJson(this)
}
}
class JsonRpcResponse extends JsonRpcMessage {
Object id
Object result
Map error
JsonRpcResponse(Object result, Object id) {
this.result = result
this.id = id
}
JsonRpcResponse(Map error, Object id) {
this.error = error
this.id = id
}
}
class JsonRpcNotification extends JsonRpcMessage {
String method
Object params
JsonRpcNotification(String method, Object params = null) {
this.method = method
this.params = params
}
}
\ No newline at end of file
/*
* This software is in the public domain under CC0 1.0 Universal plus a
* Grant of Patent License.
*
* To the extent possible under law, author(s) have dedicated all
* copyright and related and neighboring rights to this software to the
* public domain worldwide. This software is distributed without any
* warranty.
*
* You should have received a copy of the CC0 Public Domain Dedication
* along with this software (see the LICENSE.md file). If not, see
* <http://creativecommons.org/publicdomain/zero/1.0/>.
*/
package org.moqui.mcp
/**
* Simple transport interface for MCP messages
*/
interface MoquiMcpTransport {
void sendMessage(JsonRpcMessage message)
boolean isActive()
String getSessionId()
}
\ No newline at end of file
/*
* This software is in the public domain under CC0 1.0 Universal plus a
* Grant of Patent License.
*
* To the extent possible under law, author(s) have dedicated all
* copyright and related and neighboring rights to this software to the
* public domain worldwide. This software is distributed without any
* warranty.
*
* You should have received a copy of the CC0 Public Domain Dedication
* along with this software (see the LICENSE.md file). If not, see
* <http://creativecommons.org/publicdomain/zero/1.0/>.
*/
package org.moqui.mcp
import org.moqui.context.ExecutionContext
import org.moqui.impl.context.ExecutionContextImpl
import org.moqui.entity.EntityValue
import org.slf4j.Logger
import org.slf4j.LoggerFactory
import java.util.concurrent.atomic.AtomicBoolean
import java.util.concurrent.atomic.AtomicLong
/**
* MCP Session implementation that uses Moqui's Visit entity directly
* Eliminates custom session management by leveraging Moqui's built-in Visit system
*/
class VisitBasedMcpSession implements MoquiMcpTransport {
protected final static Logger logger = LoggerFactory.getLogger(VisitBasedMcpSession.class)
private final EntityValue visit // The Visit entity record
private final PrintWriter writer
private final ExecutionContextImpl ec
private final AtomicBoolean active = new AtomicBoolean(true)
private final AtomicBoolean closing = new AtomicBoolean(false)
private final AtomicLong messageCount = new AtomicLong(0)
VisitBasedMcpSession(EntityValue visit, PrintWriter writer, ExecutionContextImpl ec) {
this.visit = visit
this.writer = writer
this.ec = ec
// Initialize MCP session in Visit if not already done
initializeMcpSession()
}
private void initializeMcpSession() {
try {
def metadata = getSessionMetadata()
if (!metadata.mcpSession) {
// Mark this Visit as an MCP session
metadata.mcpSession = true
metadata.mcpProtocolVersion = "2025-11-25"
metadata.mcpCreatedAt = System.currentTimeMillis()
metadata.mcpTransportType = "SSE"
metadata.mcpMessageCount = 0
saveSessionMetadata(metadata)
logger.debug("MCP Session initialized for Visit ${visit.visitId}")
}
} catch (Exception e) {
logger.warn("Failed to initialize MCP session for Visit ${visit.visitId}: ${e.message}")
}
}
@Override
void sendMessage(JsonRpcMessage message) {
if (!active.get() || closing.get()) {
logger.warn("Attempted to send message on inactive or closing session ${visit.visitId}")
return
}
try {
String jsonMessage = message.toJson()
sendSseEvent("message", jsonMessage)
messageCount.incrementAndGet()
// Session activity now managed at servlet level to avoid lock contention
} catch (Exception e) {
logger.error("Failed to send message on session ${visit.visitId}: ${e.message}")
if (e.message?.contains("disconnected") || e.message?.contains("Client disconnected")) {
close()
}
}
}
void closeGracefully() {
if (!active.compareAndSet(true, false)) {
return // Already closed
}
closing.set(true)
logger.debug("Gracefully closing MCP session ${visit.visitId}")
try {
// Send graceful shutdown notification
def shutdownMessage = new JsonRpcNotification("shutdown", [
sessionId: visit.visitId,
timestamp: System.currentTimeMillis()
])
sendMessage(shutdownMessage)
// Give some time for message to be sent
Thread.sleep(100)
} catch (Exception e) {
logger.warn("Error during graceful shutdown of session ${visit.visitId}: ${e.message}")
} finally {
close()
}
}
void close() {
if (!active.compareAndSet(true, false)) {
return // Already closed
}
logger.debug("Closing MCP session ${visit.visitId} (messages sent: ${messageCount.get()})")
try {
// Send final close event if writer is still available
if (writer && !writer.checkError()) {
sendSseEvent("close", groovy.json.JsonOutput.toJson([
type: "disconnected",
sessionId: visit.visitId,
messageCount: messageCount.get(),
timestamp: System.currentTimeMillis()
]))
}
} catch (Exception e) {
logger.warn("Error during session close ${visit.visitId}: ${e.message}")
}
}
@Override
boolean isActive() {
return active.get() && !closing.get() && writer && !writer.checkError()
}
@Override
String getSessionId() {
return visit.visitId
}
String getVisitId() {
return visit.visitId
}
EntityValue getVisit() {
return visit
}
/**
* Get session statistics
*/
Map getSessionStats() {
return [
sessionId: visit.visitId,
visitId: visit.visitId,
createdAt: visit.fromDate,
messageCount: messageCount.get(),
active: active.get(),
closing: closing.get(),
duration: System.currentTimeMillis() - visit.fromDate.time
]
}
/**
* Send SSE event with proper formatting
*/
private void sendSseEvent(String eventType, String data) throws IOException {
if (!writer || writer.checkError()) {
throw new IOException("Writer is closed or client disconnected")
}
writer.write("event: " + eventType + "\n")
writer.write("data: " + data + "\n\n")
writer.flush()
if (writer.checkError()) {
throw new IOException("Client disconnected during write")
}
}
// Session activity management moved to servlet level to avoid database lock contention
// This method is no longer called - servlet manages session updates throttled
// Session end management moved to servlet level to avoid database lock contention
// Servlet will handle Visit updates when connections close
/**
* Get session metadata from Visit's initialRequest field
*/
Map getSessionMetadata() {
try {
def metadataJson = visit.initialRequest
if (metadataJson) {
return groovy.json.JsonSlurper().parseText(metadataJson) as Map
}
} catch (Exception e) {
logger.debug("Failed to parse session metadata: ${e.message}")
}
return [:]
}
/**
* Add custom metadata to session
*/
void addSessionMetadata(String key, Object value) {
def metadata = getSessionMetadata()
metadata[key] = value
saveSessionMetadata(metadata)
}
/**
* Save session metadata to Visit's initialRequest field
*/
private void saveSessionMetadata(Map metadata) {
// Session metadata stored in memory only - no Visit updates to prevent lock contention
try {
sessionMetadata.putAll(metadata)
} catch (Exception e) {
logger.debug("Failed to save session metadata: ${e.message}")
}
}
}
\ No newline at end of file
/*
* This software is in the public domain under CC0 1.0 Universal plus a
* Grant of Patent License.
*
* To the extent possible under law, author(s) have dedicated all
* copyright and related and neighboring rights to this software to the
* public domain worldwide. This software is distributed without any
* warranty.
*
* You should have received a copy of the CC0 Public Domain Dedication
* along with this software (see the LICENSE.md file). If not, see
* <http://creativecommons.org/publicdomain/zero/1.0/>.
*/
package org.moqui.mcp.adapter
import org.moqui.entity.EntityValue
import org.slf4j.Logger
import org.slf4j.LoggerFactory
import java.util.concurrent.ConcurrentHashMap
/**
* Adapter that maps Moqui Visit sessions to MCP sessions.
* Provides in-memory session tracking to avoid database lock contention.
*/
class McpSessionAdapter {
protected final static Logger logger = LoggerFactory.getLogger(McpSessionAdapter.class)
// Visit ID → MCP Session state
private final Map<String, McpSession> sessions = new ConcurrentHashMap<>()
// User ID → Set of Visit IDs (for user-targeted notifications)
private final Map<String, Set<String>> userSessions = new ConcurrentHashMap<>()
// Session-specific locks to avoid sessionId.intern() deadlocks
private final Map<String, Object> sessionLocks = new ConcurrentHashMap<>()
/**
* Create a new MCP session from a Moqui Visit
* @param visit The Moqui Visit entity
* @return The created McpSession
*/
McpSession createSession(EntityValue visit) {
String visitId = visit.visitId?.toString()
String userId = visit.userId?.toString()
if (!visitId) {
throw new IllegalArgumentException("Visit must have a visitId")
}
def session = new McpSession(
visitId: visitId,
userId: userId,
state: McpSession.STATE_INITIALIZED
)
sessions.put(visitId, session)
// Track user → sessions mapping
if (userId) {
def userSet = userSessions.computeIfAbsent(userId) { new ConcurrentHashMap<>().newKeySet() }
userSet.add(visitId)
}
logger.debug("Created MCP session ${visitId} for user ${userId}")
return session
}
/**
* Create a new MCP session with explicit parameters
* @param visitId The Visit/session ID
* @param userId The user ID
* @return The created McpSession
*/
McpSession createSession(String visitId, String userId) {
if (!visitId) {
throw new IllegalArgumentException("visitId is required")
}
def session = new McpSession(
visitId: visitId,
userId: userId,
state: McpSession.STATE_INITIALIZED
)
sessions.put(visitId, session)
// Track user → sessions mapping
if (userId) {
def userSet = userSessions.computeIfAbsent(userId) { new ConcurrentHashMap<>().newKeySet() }
userSet.add(visitId)
}
logger.debug("Created MCP session ${visitId} for user ${userId}")
return session
}
/**
* Close and remove a session
* @param visitId The session/visit ID to close
*/
void closeSession(String visitId) {
def session = sessions.remove(visitId)
if (session) {
// Remove from user tracking
if (session.userId) {
def userSet = userSessions.get(session.userId)
if (userSet) {
userSet.remove(visitId)
if (userSet.isEmpty()) {
userSessions.remove(session.userId)
}
}
}
// Clean up session lock
sessionLocks.remove(visitId)
logger.debug("Closed MCP session ${visitId}")
}
}
/**
* Get a session by visit ID
* @param visitId The session/visit ID
* @return The McpSession or null if not found
*/
McpSession getSession(String visitId) {
return sessions.get(visitId)
}
/**
* Check if a session exists and is active
* @param visitId The session/visit ID
* @return true if the session exists
*/
boolean hasSession(String visitId) {
return sessions.containsKey(visitId)
}
/**
* Get all session IDs for a specific user
* @param userId The user ID
* @return Set of session/visit IDs (empty set if none)
*/
Set<String> getSessionsForUser(String userId) {
return userSessions.get(userId) ?: Collections.emptySet()
}
/**
* Get all active session IDs
* @return Set of all session IDs
*/
Set<String> getAllSessionIds() {
return sessions.keySet()
}
/**
* Get the count of active sessions
* @return Number of active sessions
*/
int getSessionCount() {
return sessions.size()
}
/**
* Get a session-specific lock for synchronized operations
* @param visitId The session/visit ID
* @return The lock object
*/
Object getSessionLock(String visitId) {
return sessionLocks.computeIfAbsent(visitId) { new Object() }
}
/**
* Update session state
* @param visitId The session/visit ID
* @param state The new state
*/
void setSessionState(String visitId, int state) {
def session = sessions.get(visitId)
if (session) {
session.state = state
logger.debug("Session ${visitId} state changed to ${state}")
}
}
/**
* Update session activity timestamp
* @param visitId The session/visit ID
*/
void touchSession(String visitId) {
def session = sessions.get(visitId)
if (session) {
session.touch()
}
}
/**
* Get session statistics for monitoring
* @return Map of session statistics
*/
Map getStatistics() {
return [
totalSessions: sessions.size(),
usersWithSessions: userSessions.size(),
sessionsPerUser: userSessions.collectEntries { userId, sessionSet ->
[(userId): sessionSet.size()]
}
]
}
}
/**
* Represents an MCP session state
*/
class McpSession {
static final int STATE_UNINITIALIZED = 0
static final int STATE_INITIALIZING = 1
static final int STATE_INITIALIZED = 2
String visitId
String userId
int state = STATE_UNINITIALIZED
long lastActivity = System.currentTimeMillis()
long createdAt = System.currentTimeMillis()
// SSE writer reference (for active connections)
PrintWriter sseWriter
// Notification queue for this session
List<Map> notificationQueue = Collections.synchronizedList(new ArrayList<>())
// Subscriptions (method names this session is subscribed to)
Set<String> subscriptions = Collections.newSetFromMap(new ConcurrentHashMap<>())
void touch() {
lastActivity = System.currentTimeMillis()
}
boolean isActive() {
return state == STATE_INITIALIZED && sseWriter != null && !sseWriter.checkError()
}
boolean hasActiveWriter() {
return sseWriter != null && !sseWriter.checkError()
}
long getDurationMs() {
return System.currentTimeMillis() - createdAt
}
Map toMap() {
return [
visitId: visitId,
userId: userId,
state: state,
lastActivity: lastActivity,
createdAt: createdAt,
durationMs: getDurationMs(),
active: isActive(),
hasWriter: sseWriter != null,
queuedNotifications: notificationQueue.size(),
subscriptions: subscriptions.toList()
]
}
}
/*
* This software is in the public domain under CC0 1.0 Universal plus a
* Grant of Patent License.
*
* To the extent possible under law, author(s) have dedicated all
* copyright and related and neighboring rights to this software to the
* public domain worldwide. This software is distributed without any
* warranty.
*
* You should have received a copy of the CC0 Public Domain Dedication
* along with this software (see the LICENSE.md file). If not, see
* <http://creativecommons.org/publicdomain/zero/1.0/>.
*/
package org.moqui.mcp.adapter
import org.moqui.context.ExecutionContext
import org.slf4j.Logger
import org.slf4j.LoggerFactory
/**
* Adapter that maps MCP tool calls to Moqui services.
* Provides a clean translation layer between MCP protocol and Moqui service framework.
*/
class McpToolAdapter {
protected final static Logger logger = LoggerFactory.getLogger(McpToolAdapter.class)
// MCP tool name → Moqui service name mapping
private static final Map<String, String> TOOL_SERVICE_MAP = [
'moqui_browse_screens': 'McpServices.mcp#BrowseScreens',
'moqui_search_screens': 'McpServices.mcp#SearchScreens',
'moqui_get_screen_details': 'McpServices.mcp#GetScreenDetails',
'moqui_get_help': 'McpServices.mcp#GetHelp'
]
// MCP method → Moqui service name mapping for JSON-RPC methods
private static final Map<String, String> METHOD_SERVICE_MAP = [
'initialize': 'McpServices.mcp#Initialize',
'ping': 'McpServices.mcp#Ping',
'tools/list': 'McpServices.list#Tools',
'tools/call': 'McpServices.mcp#ToolsCall',
'resources/list': 'McpServices.mcp#ResourcesList',
'resources/read': 'McpServices.mcp#ResourcesRead',
'resources/templates/list': 'McpServices.mcp#ResourcesTemplatesList',
'resources/subscribe': 'McpServices.mcp#ResourcesSubscribe',
'resources/unsubscribe': 'McpServices.mcp#ResourcesUnsubscribe',
'prompts/list': 'McpServices.mcp#PromptsList',
'prompts/get': 'McpServices.mcp#PromptsGet',
'roots/list': 'McpServices.mcp#RootsList',
'sampling/createMessage': 'McpServices.mcp#SamplingCreateMessage',
'elicitation/create': 'McpServices.mcp#ElicitationCreate'
]
// Tool descriptions for MCP tool definitions
private static final Map<String, String> TOOL_DESCRIPTIONS = [
'moqui_browse_screens': 'Browse Moqui screen hierarchy and render screen content',
'moqui_search_screens': 'Search for screens by name to find their paths',
'moqui_get_screen_details': 'Get screen field details including dropdown options',
'moqui_get_help': 'Fetch extended documentation for a screen or service'
]
/**
* Call an MCP tool, translating to the appropriate Moqui service
* @param ec The execution context
* @param toolName The MCP tool name
* @param arguments The tool arguments
* @return The result map or error map
*/
Map callTool(ExecutionContext ec, String toolName, Map arguments) {
String serviceName = TOOL_SERVICE_MAP.get(toolName)
if (!serviceName) {
logger.warn("Unknown tool: ${toolName}")
return [error: [code: -32601, message: "Unknown tool: ${toolName}"]]
}
logger.debug("Calling tool ${toolName} -> service ${serviceName} with args: ${arguments}")
try {
ec.artifactExecution.disableAuthz()
def result = ec.service.sync()
.name(serviceName)
.parameters(arguments ?: [:])
.call()
logger.debug("Tool ${toolName} completed successfully")
// Extract result from service response if wrapped
if (result?.containsKey('result')) {
return result.result
}
return result ?: [:]
} catch (Exception e) {
logger.error("Error calling tool ${toolName}: ${e.message}", e)
return [error: [code: -32000, message: e.message]]
} finally {
ec.artifactExecution.enableAuthz()
}
}
/**
* Call an MCP method, translating to the appropriate Moqui service
* @param ec The execution context
* @param method The MCP method name
* @param params The method parameters
* @return The result map or error map
*/
Map callMethod(ExecutionContext ec, String method, Map params) {
String serviceName = METHOD_SERVICE_MAP.get(method)
if (!serviceName) {
logger.warn("Unknown method: ${method}")
return [error: [code: -32601, message: "Method not found: ${method}"]]
}
logger.debug("Calling method ${method} -> service ${serviceName}")
try {
ec.artifactExecution.disableAuthz()
def result = ec.service.sync()
.name(serviceName)
.parameters(params ?: [:])
.call()
logger.debug("Method ${method} completed successfully")
// Extract result from service response if wrapped
if (result?.containsKey('result')) {
return result.result
}
return result ?: [:]
} catch (Exception e) {
logger.error("Error calling method ${method}: ${e.message}", e)
return [error: [code: -32603, message: "Internal error: ${e.message}"]]
} finally {
ec.artifactExecution.enableAuthz()
}
}
/**
* Check if a tool name is valid
* @param toolName The tool name to check
* @return true if the tool is known
*/
boolean isValidTool(String toolName) {
return TOOL_SERVICE_MAP.containsKey(toolName)
}
/**
* Check if a method name is valid (has a service mapping)
* @param method The method name to check
* @return true if the method has a service mapping
*/
boolean isValidMethod(String method) {
return METHOD_SERVICE_MAP.containsKey(method)
}
/**
* Get the service name for a given tool
* @param toolName The tool name
* @return The service name or null if not found
*/
String getServiceForTool(String toolName) {
return TOOL_SERVICE_MAP.get(toolName)
}
/**
* Get the service name for a given method
* @param method The method name
* @return The service name or null if not found
*/
String getServiceForMethod(String method) {
return METHOD_SERVICE_MAP.get(method)
}
/**
* Get the list of available tools with their definitions
* @return List of tool definition maps
*/
List<Map> listTools() {
return TOOL_SERVICE_MAP.keySet().collect { toolName ->
[
name: toolName,
description: TOOL_DESCRIPTIONS.get(toolName) ?: "MCP tool: ${toolName}",
serviceName: TOOL_SERVICE_MAP.get(toolName)
]
}
}
/**
* Get tool description
* @param toolName The tool name
* @return The tool description or null if not found
*/
String getToolDescription(String toolName) {
return TOOL_DESCRIPTIONS.get(toolName)
}
/**
* Get all supported tool names
* @return Set of tool names
*/
Set<String> getToolNames() {
return TOOL_SERVICE_MAP.keySet()
}
/**
* Get all supported method names
* @return Set of method names
*/
Set<String> getMethodNames() {
return METHOD_SERVICE_MAP.keySet()
}
}
/*
* This software is in the public domain under CC0 1.0 Universal plus a
* Grant of Patent License.
*
* To the extent possible under law, author(s) have dedicated all
* copyright and related and neighboring rights to this software to the
* public domain worldwide. This software is distributed without any
* warranty.
*
* You should have received a copy of the CC0 Public Domain Dedication
* along with this software (see the LICENSE.md file). If not, see
* <http://creativecommons.org/publicdomain/zero/1.0/>.
*/
package org.moqui.mcp.adapter
import org.moqui.context.ExecutionContextFactory
import org.moqui.context.NotificationMessage
import org.moqui.context.NotificationMessageListener
import org.moqui.mcp.transport.MoquiMcpTransport
import org.slf4j.Logger
import org.slf4j.LoggerFactory
/**
* Bridge that connects Moqui's NotificationMessage system to MCP notifications.
* Implements NotificationMessageListener to receive all Moqui notifications
* and forwards them to MCP clients via the transport layer.
*/
class MoquiNotificationMcpBridge implements NotificationMessageListener {
protected final static Logger logger = LoggerFactory.getLogger(MoquiNotificationMcpBridge.class)
private ExecutionContextFactory ecf
private MoquiMcpTransport transport
// Topic prefix for MCP-specific notifications (optional filtering)
private static final String MCP_TOPIC_PREFIX = "mcp."
// Whether to forward all notifications or only MCP-prefixed ones
private boolean forwardAllNotifications = true
/**
* Initialize the bridge with the ECF and transport
* Note: This method signature matches what the ECF registration expects
*/
@Override
void init(ExecutionContextFactory ecf) {
this.ecf = ecf
logger.info("MoquiNotificationMcpBridge initialized (transport not yet set)")
}
/**
* Set the transport after initialization
* @param transport The MCP transport to use for sending notifications
*/
void setTransport(MoquiMcpTransport transport) {
this.transport = transport
logger.info("MoquiNotificationMcpBridge transport configured: ${transport?.class?.simpleName}")
}
/**
* Configure whether to forward all notifications or only MCP-prefixed ones
* @param forwardAll If true, forward all notifications; if false, only forward those with topic starting with 'mcp.'
*/
void setForwardAllNotifications(boolean forwardAll) {
this.forwardAllNotifications = forwardAll
logger.info("MoquiNotificationMcpBridge forwardAllNotifications set to: ${forwardAll}")
}
@Override
void onMessage(NotificationMessage nm) {
if (transport == null) {
logger.trace("Transport not configured, skipping notification: ${nm.topic}")
return
}
// Optionally filter by topic prefix
if (!forwardAllNotifications && !nm.topic?.startsWith(MCP_TOPIC_PREFIX)) {
logger.trace("Skipping non-MCP notification: ${nm.topic}")
return
}
try {
// Convert Moqui notification → MCP notification format
Map mcpNotification = convertToMcpNotification(nm)
// Get target users
Set<String> notifyUserIds = nm.getNotifyUserIds()
if (notifyUserIds && !notifyUserIds.isEmpty()) {
// Send to each target user's active MCP sessions
int sentCount = 0
for (String userId in notifyUserIds) {
try {
transport.sendNotificationToUser(userId, mcpNotification)
sentCount++
logger.debug("Sent MCP notification to user ${userId}: ${nm.topic}")
} catch (Exception e) {
logger.warn("Failed to send MCP notification to user ${userId}: ${e.message}")
}
}
logger.info("Forwarded Moqui notification '${nm.topic}' to ${sentCount} users via MCP")
} else {
// No specific users, could broadcast or log
logger.debug("Notification '${nm.topic}' has no target users, skipping MCP forward")
}
} catch (Exception e) {
logger.error("Error converting/sending Moqui notification to MCP: ${e.message}", e)
}
}
/**
* Convert a Moqui NotificationMessage to MCP notification format
* @param nm The Moqui notification
* @return The MCP notification map
*/
private Map convertToMcpNotification(NotificationMessage nm) {
return [
jsonrpc: "2.0",
method: "notifications/message",
params: [
topic: nm.topic,
subTopic: nm.subTopic,
title: nm.title,
type: nm.type,
message: nm.getMessageMap() ?: [:],
link: nm.link,
showAlert: nm.isShowAlert(),
notificationMessageId: nm.notificationMessageId,
timestamp: System.currentTimeMillis()
]
]
}
/**
* Create a custom MCP notification and send to specific users
* @param topic The notification topic
* @param title The notification title
* @param message The message content
* @param userIds The target user IDs
*/
void sendMcpNotification(String topic, String title, Map message, Set<String> userIds) {
if (transport == null) {
logger.warn("Cannot send MCP notification: transport not configured")
return
}
Map mcpNotification = [
jsonrpc: "2.0",
method: "notifications/message",
params: [
topic: topic,
title: title,
message: message,
timestamp: System.currentTimeMillis()
]
]
for (String userId in userIds) {
try {
transport.sendNotificationToUser(userId, mcpNotification)
logger.debug("Sent custom MCP notification to user ${userId}: ${topic}")
} catch (Exception e) {
logger.warn("Failed to send custom MCP notification to user ${userId}: ${e.message}")
}
}
}
/**
* Broadcast an MCP notification to all active sessions
* @param topic The notification topic
* @param title The notification title
* @param message The message content
*/
void broadcastMcpNotification(String topic, String title, Map message) {
if (transport == null) {
logger.warn("Cannot broadcast MCP notification: transport not configured")
return
}
Map mcpNotification = [
jsonrpc: "2.0",
method: "notifications/message",
params: [
topic: topic,
title: title,
message: message,
timestamp: System.currentTimeMillis()
]
]
try {
transport.broadcastNotification(mcpNotification)
logger.info("Broadcast MCP notification: ${topic}")
} catch (Exception e) {
logger.error("Failed to broadcast MCP notification: ${e.message}", e)
}
}
/**
* Send a tools/list_changed notification to inform clients that available tools have changed
*/
void notifyToolsChanged() {
if (transport == null) {
logger.warn("Cannot send tools changed notification: transport not configured")
return
}
Map notification = [
jsonrpc: "2.0",
method: "notifications/tools/list_changed",
params: [:]
]
try {
transport.broadcastNotification(notification)
logger.info("Broadcast tools/list_changed notification")
} catch (Exception e) {
logger.error("Failed to broadcast tools changed notification: ${e.message}", e)
}
}
/**
* Send a resources/list_changed notification
*/
void notifyResourcesChanged() {
if (transport == null) return
Map notification = [
jsonrpc: "2.0",
method: "notifications/resources/list_changed",
params: [:]
]
try {
transport.broadcastNotification(notification)
logger.info("Broadcast resources/list_changed notification")
} catch (Exception e) {
logger.error("Failed to broadcast resources changed notification: ${e.message}", e)
}
}
/**
* Send a progress notification for a long-running operation
* @param sessionId The target session
* @param progressToken The progress token
* @param progress Current progress value
* @param total Total progress value (optional)
*/
void sendProgressNotification(String sessionId, String progressToken, Number progress, Number total = null) {
if (transport == null) return
Map notification = [
jsonrpc: "2.0",
method: "notifications/progress",
params: [
progressToken: progressToken,
progress: progress,
total: total
]
]
try {
transport.sendNotification(sessionId, notification)
logger.debug("Sent progress notification to session ${sessionId}: ${progress}/${total ?: '?'}")
} catch (Exception e) {
logger.warn("Failed to send progress notification: ${e.message}")
}
}
@Override
void destroy() {
logger.info("MoquiNotificationMcpBridge destroyed")
this.ecf = null
this.transport = null
}
}
/*
* This software is in the public domain under CC0 1.0 Universal plus a
* Grant of Patent License.
*
* To the extent possible under law, author(s) have dedicated all
* copyright and related and neighboring rights to this software to the
* public domain worldwide. This software is distributed without any
* warranty.
*
* You should have received a copy of the CC0 Public Domain Dedication
* along with this software (see the LICENSE.md file). If not, see
* <http://creativecommons.org/publicdomain/zero/1.0/>.
*/
package org.moqui.mcp.transport
/**
* Transport interface for MCP messages.
* Abstracts transport concerns so implementations can be swapped (SSE, WebSocket, etc.)
*/
interface MoquiMcpTransport {
// Session lifecycle
/**
* Open a new MCP session for the given user
* @param sessionId The session ID (typically Visit ID)
* @param userId The user ID associated with this session
*/
void openSession(String sessionId, String userId)
/**
* Close an existing MCP session
* @param sessionId The session ID to close
*/
void closeSession(String sessionId)
/**
* Check if a session is currently active
* @param sessionId The session ID to check
* @return true if the session is active
*/
boolean isSessionActive(String sessionId)
// Message sending
/**
* Send a JSON-RPC message to a specific session
* @param sessionId The target session ID
* @param message The message to send (will be JSON-serialized)
*/
void sendMessage(String sessionId, Map message)
/**
* Send an MCP notification to a specific session
* @param sessionId The target session ID
* @param notification The notification to send
*/
void sendNotification(String sessionId, Map notification)
/**
* Send an MCP notification to all sessions for a specific user
* @param userId The target user ID
* @param notification The notification to send
*/
void sendNotificationToUser(String userId, Map notification)
// Broadcast
/**
* Broadcast a notification to all active sessions
* @param notification The notification to broadcast
*/
void broadcastNotification(Map notification)
/**
* Get the number of active sessions
* @return count of active sessions
*/
int getActiveSessionCount()
/**
* Get session IDs for a specific user
* @param userId The user ID
* @return Set of session IDs for this user
*/
Set<String> getSessionsForUser(String userId)
}