imixs/office-dynamixs-ai
imixs/office-dynamixs-ai
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
office-dynamixs-ai/doc/MCP.md

12 KiB
Raw Blame History

Model Context Protocol (MCP) Implementation

This implementation provides the Model Context Protocol (MCP) for your BPM platform. MCP allows LLMs to access workflow resources and execute workflow tools.

Overview

Core Components

  1. MCPResource.java - Represents workflow resources (readable content)
  2. MCPTool.java - Represents workflow tools (executable functions)
  3. MCPService.java - Parses BPMN models and extracts MCP definitions
  4. MCPRestService.java - REST endpoint for MCP JSON-RPC 2.0 protocol

MCP vs. A2A Unterschiede

Aspekt A2A MCP
Protokoll JSON-RPC 2.0 (Agent-to-Agent) JSON-RPC 2.0 (Model Context Protocol)
Hauptkonzepte Skills (Fähigkeiten) Resources + Tools
Zweck Agent-Kommunikation LLM-Kontext-Erweiterung
Identifikation Skill ID: {model}_{task}_{event} Resource URI: imixs://workflow/{model}/{task}/{event}

BPMN-Konfiguration

For MCP Resources

Add the following XML configuration to your BPMN events:

<imixs-ai name="RESOURCE">
    <description>Beschreibung der Ressource</description>
    <mimetype>text/plain</mimetype>
    <tags>workflow,document,process</tags>
    <category>business-process</category>
    <content>Hier steht der eigentliche Inhalt der Ressource</content>
</imixs-ai>

Für MCP Tools

<imixs-ai name="TOOL">
    <name>custom_tool_name</name>
    <description>Beschreibung des Tools</description>
    <tags>automation,processing</tags>
    <example>Beispiel für die Tool-Verwendung</example>
</imixs-ai>

API Endpoints

Base URL

/mcp/v1

Supported MCP Methods

1. Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "Test Client",
      "version": "1.0.0"
    }
  }
}

2. Resources List

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resources": [
      {
        "uri": "imixs://workflow/invoice-de-1.0/100/10",
        "name": "Invoice Processing",
        "description": "Process invoice documents",
        "mimeType": "text/plain",
        "annotations": {
          "tags": "invoice,processing",
          "category": "finance"
        }
      }
    ]
  }
}

3. Resources Read

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "imixs://workflow/invoice-de-1.0/100/10"
  }
}

4. Tools List

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/list"
}

5. Tools Call

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "invoice_de_1_0_100_10",
    "arguments": {
      "workitem": {
        "$modelversion": "invoice-de-1.0",
        "$taskid": 100,
        "$eventid": 10,
        "invoice.number": "INV-2024-001",
        "invoice.amount": 1500.0
      }
    }
  }
}

Deployment

1. JAX-RS Application Configuration

Ensure your JAX-RS Application registers the MCP services:

@ApplicationPath("/api")
public class RestApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> classes = new HashSet<>();
        classes.add(MCPRestService.class);
        // ... other services
        return classes;
    }
}

2. CDI Beans

The services use CDI injection and must be available as managed beans:

// MCPService is automatically registered as @Stateless EJB
// MCPRestService is registered as @RequestScoped CDI Bean

Usage by LLMs

An LLM can now:

  1. List resources - View all available workflow documentation and content
  2. Read resources - Retrieve specific workflow documentation or configuration
  3. List tools - View all available workflow operations
  4. Execute tools - Create or process workflow instances

Security

  • Use the existing Imixs-Workflow security architecture
  • The @RolesAllowed annotations in MCPService control access
  • Additional authentication can be implemented in MCPRestService

Monitoring and Logging

  • All MCP operations are logged
  • Error handling follows JSON-RPC 2.0 standard
  • Performance monitoring via existing Jakarta EE mechanisms

Example Integration

// In a client (e.g., LLM application)
public class MCPClient {
    public void useWorkflowResources() {
        // 1. Initialize MCP connection
        // 2. List available resources
        // 3. Read specific workflow documentation
        // 4. Execute workflow tools based on context
    }
}

This implementation extends your existing A2A infrastructure with MCP support and enables LLMs to have direct access to your workflow resources and tools.

MCP Debug Service Endpoint

The MCP Debug Service provides a set of convenient endpoints for testing and debugging your Model Context Protocol (MCP) implementation. These endpoints allow you to quickly verify that your MCP server is working correctly and inspect available resources and tools without needing a full MCP client.

Base URL

/mcp/debug/

Available Endpoints

1. Health Check

Endpoint: GET /mcp/health

Provides a quick health status of the MCP server including basic statistics.

Example Request:

curl -X GET http://localhost:8080/api/mcp/health

Example Response:

{
  "status": "healthy",
  "timestamp": "2025-06-29T10:30:45.123Z",
  "server": "Dynamixs.AI MCP Server",
  "version": "1.0.0",
  "protocol": "MCP 2024-11-05",
  "endpoint": "http://localhost:8080/api/mcp/v1",
  "resources_count": 5,
  "tools_count": 3
}

2. Server Information

Endpoint: GET /mcp/server-info

Returns comprehensive server information including capabilities, available resources, and tools. This is the MCP equivalent of the A2A Agent Card.

Example Request:

curl -X GET http://localhost:8080/api/mcp/server-info

Example Response:

{
  "protocol": {
    "name": "Model Context Protocol",
    "version": "2024-11-05",
    "transport": "HTTP/JSON-RPC 2.0"
  },
  "server": {
    "name": "Dynamixs.AI MCP Server",
    "version": "1.0.0",
    "description": "MCP server for Imixs-Workflow BPM platform",
    "vendor": "Dynamixs.AI",
    "platform": "Jakarta EE 10 / Imixs-Workflow"
  },
  "capabilities": {
    "resources": {
      "subscribe": false,
      "listChanged": false
    },
    "tools": {},
    "logging": {}
  },
  "endpoints": {
    "jsonrpc": "http://localhost:8080/api/mcp/v1",
    "health": "http://localhost:8080/api/mcp/health",
    "server_info": "http://localhost:8080/api/mcp/server-info",
    "test_resources": "http://localhost:8080/api/mcp/test/resources",
    "test_tools": "http://localhost:8080/api/mcp/test/tools"
  },
  "statistics": {
    "resources_available": 5,
    "tools_available": 3,
    "last_updated": "2025-06-29T10:30:45.123Z"
  },
  "resource_summary": [
    {
      "uri": "imixs://workflow/invoice-de-1.0/100/10",
      "name": "Invoice Processing",
      "mimeType": "text/plain"
    }
  ],
  "tool_summary": [
    {
      "name": "invoice_approval_1_0_100_10",
      "description": "Approve invoices after financial review and compliance check"
    }
  ]
}

3. Test Resources

Endpoint: GET /mcp/test/resources

Lists all available MCP resources parsed from your BPMN models.

Example Request:

curl -X GET http://localhost:8080/api/mcp/test/resources

Example Response:

{
  "status": "success",
  "count": 2,
  "resources": [
    {
      "uri": "imixs://workflow/invoice-de-1.0/100/10",
      "name": "Invoice Processing",
      "description": "Process invoice documents",
      "mimeType": "text/plain",
      "annotations": {
        "tags": "invoice,processing",
        "category": "finance"
      }
    },
    {
      "uri": "imixs://workflow/purchase-order-1.0/200/20",
      "name": "Purchase Order Workflow",
      "description": "Handle purchase order approval process",
      "mimeType": "application/json",
      "annotations": {
        "tags": "purchase,order,approval",
        "category": "procurement"
      }
    }
  ]
}

4. Test Tools

Endpoint: GET /mcp/test/tools

Lists all available MCP tools parsed from your BPMN models.

Example Request:

curl -X GET http://localhost:8080/api/mcp/test/tools

Example Response:

{
  "status": "success",
  "count": 1,
  "tools": [
    {
      "name": "invoice_approval_1_0_100_10",
      "description": "Approve invoices after financial review and compliance check. This action moves the invoice to the payment processing stage and triggers",
      "inputSchema": {
        "type": "object",
        "properties": {
          "workitem": {
            "type": "object",
            "description": "Workflow item data",
            "properties": {
              "$modelversion": {
                "type": "string",
                "description": "Workflow model version"
              },
              "$taskid": {
                "type": "integer",
                "description": "Task ID"
              },
              "$eventid": {
                "type": "integer",
                "description": "Event ID"
              }
            },
            "required": ["$modelversion", "$taskid", "$eventid"]
          }
        },
        "required": ["workitem"]
      }
    }
  ]
}

Error Responses

All endpoints return structured error responses when something goes wrong:

Example Error Response:

{
  "error": "Failed to parse tools",
  "message": "Model version 'invoice-de-1.0' not found"
}

HTTP Status Codes:

  • 200 OK - Success
  • 500 Internal Server Error - Server error
  • 503 Service Unavailable - Health check failed

Usage Scenarios

Development Testing

Use these endpoints during development to verify that your BPMN models are correctly configured with MCP tags:

# Quick check if server is running
curl http://localhost:8080/api/mcp/health

# See what tools are available
curl http://localhost:8080/api/mcp/test/tools

# Get complete server overview
curl http://localhost:8080/api/mcp/server-info

Integration Testing

Incorporate these endpoints into your CI/CD pipeline to ensure MCP functionality:

#!/bin/bash
# Test script for MCP server
BASE_URL="http://localhost:8080/api/mcp"

# Health check
echo "Testing health..."
curl -f "$BASE_URL/health" || exit 1

# Check if tools are available
echo "Testing tools..."
TOOL_COUNT=$(curl -s "$BASE_URL/test/tools" | jq '.count')
if [ "$TOOL_COUNT" -eq 0 ]; then
  echo "No tools found!"
  exit 1
fi

echo "MCP server tests passed!"

Debugging BPMN Configuration

If your tools or resources don't appear, use these endpoints to debug:

  1. Check if the server is healthy: /mcp/health
  2. Verify tools are parsed: /mcp/test/tools
  3. Check specific resource configuration: /mcp/test/resources
  4. Review complete server info: /mcp/server-info

Security Considerations

  • These debug endpoints should be secured in production environments
  • Consider restricting access to development/testing networks only
  • Monitor access logs for these endpoints in production

Next Steps

After verifying your MCP server works with these debug endpoints, you can:

  1. Test the full MCP JSON-RPC 2.0 protocol via /mcp/v1
  2. Integrate with MCP client libraries
  3. Connect LLM applications to your workflow tools and resources