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.

If a matching canonical markdown file exists, entry payloads also include a canonicalDoc block sourced from Oracle Documentation/canonical/<safe_name>.md. Exact entry payloads also include a combinedText field that merges the catalog data and the Oracle documentation into one agent-friendly text block. Missing docs never fail the catalog response.

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.
4. Optionally point CATALOG_MCP_CANONICAL_DOCS_ROOT at a different canonical-doc directory.

'/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}

Entry payloads now include canonicalDoc:

{
  "present": true,
  "filename": "Example_Object.md",
  "content": "# Example Object\n..."
}

When no matching file exists, the field is still present:

{
  "present": false,
  "filename": "Example_Object.md"
}

Exact entry payloads also include combinedText, which combines the structured catalog details and the canonical markdown into one text response for agents that prefer a single blob of text.

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"}