# 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:

```xml
<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

```xml
<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

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

#### 2. Resources List

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

**Response:**

```json
{
  "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

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

#### 4. Tools List

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

#### 5. Tools Call

```json
{
  "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:

```java
@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:

```java
// 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

```java
// 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:**

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

**Example Response:**

```json
{
  "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:**

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

**Example Response:**

```json
{
  "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:**

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

**Example Response:**

```json
{
  "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:**

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

**Example Response:**

```json
{
  "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:**

```json
{
  "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:

```bash
# 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:

```bash
#!/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