ADR-014: Evaluation of Heng Sin's idempiere-mcp Project for MCP Data Tools

Status

Accepted

Context

We evaluated Heng Sin's idempiere-mcp project to understand if components could be adopted for AI integration in idempiere-cli.

Our AI Strategy

idempiere-cli uses LangChain4j with @Tool annotations (ADR-013) for AI integration:

• Natural language routing via ask command
• Shared tool logic (org.idempiere.cli.ai.shared)
• Multi-provider support (Ollama local, Claude, OpenAI)
• No external MCP server required

> Note: ADR-010 (External MCP Server) has been superseded by ADR-013.

Project Reference

• Author: Heng Sin (iDempiere Core Developer)
• Repository: https://github.com/hengsin/idempiere-mcp
• Type: Proof-of-concept MCP server for iDempiere

Heng Sin's idempiere-mcp Project Overview

The idempiere-mcp project is a proof-of-concept MCP server that:

• Runs as an OSGi bundle inside iDempiere server
• Depends on iDempiere-rest project (REST API endpoints)
• Exposes MCP tools via SSE and Streamable HTTP transports
• Uses iDempiere's Rest Auth Token for authentication
• Supports multi-tenant access

Key Architectural Differences

Decision

We will NOT adopt Heng Sin's idempiere-mcp because we have a different architectural approach (LangChain4j embedded tools vs. external MCP server).

Rationale

Why Not Adopt Heng Sin's idempiere-mcp Directly

1. Different Architectural Philosophy

   • idempiere-mcp runs INSIDE iDempiere as an OSGi bundle
   • idempiere-cli MCP runs OUTSIDE iDempiere as a standalone tool
   • These are fundamentally different deployment models

2. Heavy Dependencies

   • Requires full iDempiere server running
   • Requires iDempiere-rest project (additional OSGi bundle)
   • Not suitable for developer workstations without iDempiere

3. Transport Limitations

   • Only HTTP-based transports (SSE, Streamable HTTP)
   • No stdio support = Claude Desktop integration issues
   • stdio is the preferred transport for local AI tools

4. Proof of Concept Status

   • Author notes "use with care"
   • Known issues with Claude Desktop compatibility
   • Not production-ready

5. Coupling to iDempiere Server

   • Requires running iDempiere for any MCP operation
   • Cannot work in "offline" or "design-time" scenarios
   • Heavier footprint for AI-assisted development

What We Can Learn/Adopt from Heng Sin's Work

1. REST API Data Access Pattern

   • Heng Sin's approach of using iDempiere REST API for data access is valid
   • We already support this via RestApiBackend in ADR-010
   • Could expose REST-based data tools for production scenarios

2. Multi-Tenant Token Authentication

   • The Rest Auth Token pattern is useful for multi-tenant scenarios
   • Can be adopted when implementing SSE transport for remote access

3. Exposed Capabilities Reference (from Heng Sin's demos)

   • Search operations (Business Partner queries)
   • Process execution
   • Record creation via Message windows
   • Server job management

Implementation Path

We continue with our LangChain4j-based AI integration (ADR-013):

┌─────────────────────────────────────────────────────────────────┐
│                    User (CLI or IDE)                             │
└──────────────────────────┬──────────────────────────────────────┘
                           │ idempiere-cli ask "..."
┌──────────────────────────▼──────────────────────────────────────┐
│              idempiere-cli (LangChain4j Integration)             │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ LangChain4j @Tool Annotations:                             │ │
│  │  - RegistryToolLogic (listTables, describeTable, etc.)     │ │
│  │  - QueryToolLogic (executeQuery, explainQuery)             │ │
│  │  - TableToolLogic (createTable, syncTable)                 │ │
│  │  - GeneratorToolLogic (generateModel, generatePlugin)      │ │
│  └────────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ LLM Providers:                                              │ │
│  │  - Ollama (local, offline)                                 │ │
│  │  - Claude API (cloud)                                      │ │
│  │  - OpenAI API (cloud)                                      │ │
│  └────────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Data Access:                                                │ │
│  │  - Direct DB (JDBC) - default                              │ │
│  │  - REST API (OpenAPI client) - optional                    │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Comparison Matrix

Consequences

Positive

• Maintain lightweight standalone deployment model
• Native Claude Desktop/Claude Code support via stdio
• Can work without running iDempiere server
• Optional REST API backend when iDempiere is available
• Learn from Heng Sin's idempiere-mcp for data access patterns

Negative

• Cannot leverage OSGi runtime features
• Must implement own REST API client (already done in ADR-009)
• No direct integration with iDempiere session management

Neutral

• Two MCP solutions exist in the iDempiere ecosystem
• Different use cases: development (idempiere-cli) vs. production (Heng Sin's idempiere-mcp)
• Potential for future collaboration/convergence with Heng Sin's project

Related Decisions

• ADR-010: MCP Server Architecture - Our MCP implementation
• ADR-009: OpenAPI REST Client - REST API integration
• ADR-006: CLI as M2M API - Machine-to-machine interface

References

• Heng Sin's idempiere-mcp GitHub
• Model Context Protocol
• MCP Java SDK
• Quarkus MCP Server Extension
• MCP Specification Tools
• MCP Overview - Phil Schmid
• MCP Introduction - Keywords AI