# MCP Integration Architecture for Imixs BPM Suite

## 1. Core Concept

The **Model Context Protocol (MCP)** is an open standard that enables AI systems to interact with external tools and data sources through a unified protocol.

### Current State (without MCP)

```
User → Orchestrator → LLM → Response
                ↓
         Internal REST APIs only
```

The LLM is **passive** – it can only respond to requests and call internal APIs that we explicitly implement.

### Future State (with MCP)

```
User → Orchestrator → LLM → Tool Selection
                         ↓
              ┌──────────┴──────────┐
              ↓                     ↓
       Internal Tools         External MCP Servers
       (Imixs REST)           (SAP, Salesforce, ...)
```

The LLM becomes **active** – it can discover and invoke tools from any MCP-compliant system, including third-party enterprise applications.

---

## 2. Benefits

| Benefit                        | Description                                                                           |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| **Standardized Protocol**      | One integration pattern for all external systems instead of custom implementations    |
| **Tool Discovery**             | LLM automatically learns available tools from connected MCP servers                   |
| **Bidirectional Integration**  | Imixs can consume external tools AND expose its own tools to external AI systems      |
| **Reduced Development Effort** | Leverage existing MCP servers (SAP, Microsoft, etc.) without building custom adapters |
| **Future-Proof**               | As more vendors adopt MCP, integration becomes plug-and-play                          |

---

## 3. Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Imixs BPM Suite                                   │
│                          (Jakarta EE 10)                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌───────────────────────────────────────────────────────────────────┐     │
│   │                    AI Orchestrator (CDI Bean)                     │     │
│   │                                                                   │     │
│   │   ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐      │     │
│   │   │    Tool      │   │  LLM Client  │   │   MCP Client     │      │     │
│   │   │   Registry   │◄─►│ (OpenAI API) │   │ (external tools) │      │     │
│   │   └──────────────┘   └──────────────┘   └──────────────────┘      │     │
│   └───────────────────────────────────────────────────────────────────┘     │
│                              │                                              │
│               ┌──────────────┴──────────────┐                               │
│               ▼                             ▼                               │
│   ┌───────────────────────┐     ┌─────────────────────────────────┐         │
│   │  Internal Tools       │     │       MCP Server Endpoint       │         │
│   │  (REST Services)      │     │          (JAX-RS)               │         │
│   │                       │     │                                 │         │
│   │  • WorkflowService    │     │  GET  /mcp/tools    (discovery) │         │
│   │  • DocumentService    │     │  POST /mcp/execute  (invoke)    │         │
│   │  • TaskService        │     │                                 │         │
│   └───────────────────────┘     └─────────────────────────────────┘         │
│                                              │                              │
└──────────────────────────────────────────────┼──────────────────────────────┘
                                               │
                                               ▼
                                    External MCP Clients
                                   (Claude, SAP, etc.)
```

### Key Components

| Component           | Responsibility                                                    |
| ------------------- | ----------------------------------------------------------------- |
| **Tool Registry**   | Manages all available tools (internal + external MCP)             |
| **AI Orchestrator** | Routes user requests to LLM, handles tool selection and execution |
| **MCP Client**      | Connects to external MCP servers (e.g., SAP)                      |
| **MCP Server**      | Exposes Imixs tools to external AI systems                        |

---

## 4. Use Cases

### Use Case 1: Cross-System Process Automation

**Scenario:** User says _"Create a new invoice in Imixs and sync the customer address from SAP"_

```
1. Orchestrator sends prompt + available tools to LLM
2. LLM selects: imixs.startProcess + sap.getCustomerAddress
3. Orchestrator calls SAP MCP Server → gets address
4. Orchestrator calls Imixs REST API → creates invoice with address
5. LLM formulates response for user
```

### Use Case 2: External AI Access to Imixs

**Scenario:** A consultant uses Claude Desktop and asks _"Show me all open approval tasks in Imixs"_

```
1. Claude Desktop connects to Imixs MCP Server
2. Calls GET /mcp/tools → discovers available tools
3. Calls POST /mcp/execute → invokes "getOpenTasks"
4. Claude presents the task list to the user
```

### Use Case 3: Intelligent Document Routing

**Scenario:** User uploads an invoice and says _"Process this invoice"_

```
1. LLM analyzes document (existing RAG capability)
2. LLM selects tools: imixs.startProcess + sap.validateVendor
3. Orchestrator validates vendor in SAP
4. Orchestrator starts approval workflow in Imixs
5. User receives confirmation with process ID
```

### Use Case 4: Multi-System Reporting

**Scenario:** User asks _"Compare our open orders in Imixs with pending deliveries in SAP"_

```
1. LLM selects: imixs.searchWorkitems + sap.getPendingDeliveries
2. Orchestrator fetches data from both systems
3. LLM correlates and summarizes the data
4. User receives a consolidated report
```

---

## 5. Next Steps

1. **Phase 1:** Implement basic Orchestrator with internal tool registry
2. **Phase 2:** Add MCP Server endpoint to expose Imixs tools
3. **Phase 3:** Implement MCP Client for external server connections
4. **Phase 4:** Integration testing with SAP MCP Server

---

## 6. References

- [MCP Specification](https://modelcontextprotocol.io/)
- [Imixs-Workflow Documentation](https://www.imixs.org)
- [Jakarta EE 10 Specification](https://jakarta.ee/)