Catalog MCP

Standalone read-only MCP server for browsing Oracle HDL business object metadata from the local business-object ingestion repository.

The catalog index treats attributes/*.json as the source of truth. manifest.json is optional supplemental metadata used only when it matches an indexed attribute document.

Local setup

1. Create a virtual environment with Python 3.10+.

2. Install dependencies.

3. Point CATALOG_MCP_DATA_ROOT at the business-object ingestion repo if you do not want the default sibling path.

'/Users/justin/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3' -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
cp .env.example .env

You can optionally scope the server to one or more exact business objects:

CATALOG_MCP_ALLOWED_OBJECTS=Worker

or:

CATALOG_MCP_ALLOWED_OBJECTS=Worker,Location

Run the server

.venv/bin/python -m catalog_mcp.server

The server runs over stdio by default.

You can also use the checked-in launcher, which defaults CATALOG_MCP_DATA_ROOT to the sibling business-object repo on this laptop:

./scripts/run_catalog_mcp.sh

Register with Codex

Add the server to local Codex MCP config:

codex mcp add businessObjectCatalog -- /Users/justin/Documents/Codex/Projects/MCP/scripts/run_catalog_mcp.sh

Verify the registration:

codex mcp list
codex mcp get businessObjectCatalog

Test

.venv/bin/pytest

Run the end-to-end pressure matrix:

.venv/bin/python scripts/pressure_test_catalog.py

Public MCP surface

• Tools:

  • catalog_health

  • get_catalog_stats

  • list_catalog_entries

  • get_catalog_entry

  • get_catalog_component

  • get_catalog_attribute

  • search_catalog

  • search_catalog_attributes

  • get_related_entries

  • refresh_catalog_index

• Resources:

  • catalog://summary

  • catalog://product-areas

  • catalog://stats

  • catalog://entries/{entry_id}

Exact-Scope Retrieval

If an agent already knows the object, component, or field, prefer exact retrieval over broad search.

Examples:

{"identifier":"Worker"}

{"identifier":"Worker","component_name":"Worker"}

{"identifier":"Worker","component_name":"Worker","attribute_name":"WorkerNumber"}