apex-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

apex-mcp is an MCP (Model Context Protocol) server for Oracle APEX 24.2 that exposes 116+ tools to AI clients (Claude, GPT, Gemini, Cursor, VS Code). It generates APEX applications programmatically via PL/SQL using the wwv_flow_imp_page.* internal API (same as APEX's own import/export).

Build & Run

# Install
pip install -e ".[dev]"

# Run (stdio — default for local AI clients)
python -m apex_mcp
apex-mcp                    # equivalent, via entry point

# Run with HTTP transport
python -m apex_mcp --transport streamable-http --port 8000
python -m apex_mcp --transport sse --port 9000

Testing

# Unit tests only (no Oracle DB required)
pytest tests/ -v -m "not integration"

# All tests (requires live Oracle ADB + env vars)
pytest tests/ -v

# Single test file
pytest tests/test_session.py -v

# Single test
pytest tests/test_ids.py::test_unique_ids -v

Tests require ORACLE_DB_USER, ORACLE_DB_PASS, ORACLE_DSN, ORACLE_WALLET_DIR, ORACLE_WALLET_PASSWORD, APEX_WORKSPACE_ID, APEX_SCHEMA, APEX_WORKSPACE_NAME env vars for integration tests.

Architecture

Core Singletons (module-level instances)

• db (apex_mcp/db.py) -- ConnectionManager singleton. Thread-safe Oracle connection via oracledb thin driver + mTLS wallet. Has auto-reconnect on transient ORA errors (03113, 03114, 12170, 25408), dry-run mode (logs PL/SQL without executing), and batch mode (queues PL/SQL, executes in one commit). Also provides safe_col() / column_exists() for APEX version-safe column access with caching.
• session (apex_mcp/session.py) -- ImportSession singleton. Tracks all components (pages, regions, items, buttons, LOVs, auth schemes, charts, processes, branches, dynamic actions) created during the apex_create_app() to apex_finalize_app() lifecycle. Tools use it to resolve cross-references like region IDs. Thread-safe via threading.RLock.
• ids (apex_mcp/ids.py) -- IdGenerator singleton. Produces unique IDs (base 8,900,000,000,000,000 + random salt + counter) with a named registry to avoid collisions within a session. Reset on each apex_create_app() call.