Apache Hop MCP 0.2.0

apache-hop-mcp exposes Apache Hop projects to MCP-capable agents such as Codex. Version 0.2 adds a bundled Java semantic bridge that loads the same Hop engine classes and plugin registry used by Hop itself instead of relying only on raw XML.

The Python MCP remains the control/security layer. The Java bridge is local-only, persistent, and communicates with Python over stdin/stdout; it does not open an additional network port.

Project status: community project; it is not an official Apache Software Foundation or Apache Hop project. Apache Hop is a trademark of the Apache Software Foundation.

Architecture

Codex / MCP client
       |
       | MCP
       v
apache-hop-mcp (Python)
  |  security / backups / search / SQL extraction / Hop Server
  |
  +---- native mode ------------------------------+
  |                                               |
  |                              local stdin/stdout protocol
  |                                               v
  |                                  Hop Java Bridge 0.2
  |                                               |
  |                         HopEnvironment.init() / PluginRegistry
  |                                               |
  |                         PipelineMeta / WorkflowMeta / metadata
  |                                               |
  +---- python fallback ---> safe XML parser <----+
                          .hpl / .hwf / metadata/

Apache Hop's SDK explicitly initializes engine-side plugins through HopEnvironment.init() and loads project metadata with JsonMetadataProvider. The bridge follows that model and runs against the JARs/plugins in the configured HOP_HOME.

Related MCP server: void-bridge

What's new in 0.2

• Bundled apache-hop-mcp-bridge-0.2.0.jar with source.

• Native inspection through PipelineMeta / WorkflowMeta.

• Native plugin identity and missing-plugin detection.

• Native hop graph and local lineage.

• Native transform/action inventory from PluginRegistry.

• Native structural validation of component names, installed plugins and hop endpoints.

• Optional deep validation through Hop's own checkTransforms() / checkActions() APIs.

• auto | native | python engine selection.

• Hybrid hop_inspect: Hop supplies authoritative structure; the bounded Python parser adds SQL and static file-reference extraction.

• Persistent JVM process instead of starting Java for every tool call.

• Java @argfile classpath startup to avoid Windows command-line length limits.

• Cross-platform bridge timeout and deterministic fallback.

• v0.1 tools remain available with the same names.

Engine modes

Set:

HOP_MCP_NATIVE_MODE=auto

auto is recommended. If HOP_HOME and the bundled bridge are usable, semantic tools prefer the native Hop model. If native initialization fails, read-only analysis falls back to the Python parser and marks the result with engine: python and native_fallback: true.

Use HOP_MCP_NATIVE_MODE=native when a native Hop load is mandatory. Errors are returned instead of falling back.

Use HOP_MCP_NATIVE_MODE=python for the original parser-only behavior.

Requirements

• Python 3.10+

• For native mode: Apache Hop 2.19.x and Java 21

• HOP_HOME pointing at the unpacked Hop installation

• Optional hop-run.sh / hop-run.bat for execution

• Optional Hop Server for remote execution/status

The bridge JAR contains only the MCP bridge classes. Apache Hop libraries and marketplace/custom plugins are loaded from the user's actual Hop installation, so the bridge does not ship a duplicate Hop runtime.

Install

python -m venv .venv

Linux/macOS:

. .venv/bin/activate
pip install apache_hop_mcp-0.2.0-py3-none-any.whl

Windows PowerShell:

.venv\Scripts\Activate.ps1
pip install apache_hop_mcp-0.2.0-py3-none-any.whl

For development:

pip install -e .

Configuration

Minimal native configuration:

HOP_PROJECT_ROOT=/opt/hop/config/projects/my-project
HOP_PROJECT_NAME=my-project
HOP_HOME=/opt/hop
HOP_MCP_NATIVE_MODE=auto
HOP_MCP_ALLOW_WRITE=false
HOP_MCP_ALLOW_EXECUTE=false

Optional:

HOP_RUN=/opt/hop/hop-run.sh
HOP_RUN_CONFIG=local
HOP_LOG_LEVEL=BASIC
HOP_MCP_NATIVE_TIMEOUT_SECONDS=45
HOP_MCP_BRIDGE_JAR=/custom/path/apache-hop-mcp-bridge-0.2.0.jar
HOP_MCP_JAVA=/custom/jdk/bin/java
HOP_PLUGIN_BASE_FOLDERS=/opt/hop/plugins,/opt/company-hop-plugins

HOP_MCP_BRIDGE_JAR is normally unnecessary because the wheel contains the bridge.

Diagnostics

Configuration only:

apache-hop-mcp --doctor

Actually start Java, initialize Hop and enumerate plugins:

apache-hop-mcp --doctor --native-probe

MCP tools

Version 0.2 exposes 24 MCP tools.

Example Codex configuration

See examples/codex-config.toml.

[mcp_servers.apache-hop]
command = "apache-hop-mcp"
args = ["--transport", "stdio"]

[mcp_servers.apache-hop.env]
HOP_PROJECT_ROOT = "/opt/hop/config/projects/my-project"
HOP_PROJECT_NAME = "my-project"
HOP_HOME = "/opt/hop"
HOP_MCP_NATIVE_MODE = "auto"
HOP_MCP_ALLOW_WRITE = "false"
HOP_MCP_ALLOW_EXECUTE = "false"

Suggested first prompt:

Use apache-hop-mcp. Probe the native bridge, list the installed transform plugins,
inspect U2020_UMTS/Main.hwf, build its dependency graph, and identify any missing
plugins or broken hops. Do not modify or execute anything.

Safety model

Mutation and execution remain deny-by-default:

HOP_MCP_ALLOW_WRITE=false
HOP_MCP_ALLOW_EXECUTE=false

File operations are confined to HOP_PROJECT_ROOT, including resolved symlinks. XML with DTD/entity declarations is rejected by the Python parser. Writes use timestamped backups, atomic replacement and rollback on structural validation failure.

The Java bridge independently canonicalizes every .hpl/.hwf path and verifies it remains under the configured project root.

The bridge deliberately uses no TCP listener. It inherits the MCP process' OS permissions and only receives commands from its parent Python process.

Bridge source/build

Source is in bridge/. The Maven project compiles against Apache Hop 2.19.0 hop-core and hop-engine as provided dependencies and targets Java 21.

cd bridge
mvn -DskipTests package

The runtime JAR intentionally has no embedded Hop dependencies.

Tests

python -m pytest

hop_native_validate is structural and does not deliberately invoke transform/action connectivity checks. hop_native_check calls Apache Hop's own deep checker. Depending on the transforms/actions involved, the deep checker can resolve fields or contact configured databases/services; invoke it intentionally.

AI-assisted development

Coding agents such as Codex CLI and Codex Cloud should read AGENTS.md before making changes. Detailed setup and build guidance lives in docs/AI_DEVELOPMENT.md.

License

MIT. Apache Hop is an Apache Software Foundation project. apache-hop-mcp is independent and is not an official Apache Hop component.