# Oracle Fusion HCM MCP

Local Oracle Fusion HCM MCP server backed by normalized Oracle REST API
catalogs.

The current server intentionally has no caller authentication. It binds to
`127.0.0.1` by default for local and demo-pod development. Oracle credentials,
when configured, are used only by the outbound Oracle connector.

## Included

- Organization, environment and Oracle HCM reference-data schemas
- REST, SOAP, named-SQL and HAR capability catalog
- Default-deny authorization policy model
- Read-only named query templates
- Standard MCP tool result and error envelopes
- Fusion AI Agent Studio-ready per-tool `outputSchema`, `structuredContent`,
  compact JSON fallback, presentation hints, and server usage instructions
- Single-copy MCP embedded resources for binary catalog, Publisher, and report
  artifacts
- Privacy-conscious audit events
- Sanitized API artifact registry
- Official Oracle OpenAPI importer and normalized operation catalog
- MCP Streamable HTTP server with `hcm_catalog_search`
- Full operation and schema inspection with `hcm_describe_operation`
- Multi-organization environment registry with secret references
- Connection and Basic Auth diagnostics for each Oracle pod
- Explicit capability report for REST, SQL, security and BPM by environment
- Contract-validated execution of official Oracle REST GET, POST, PUT, PATCH
  and DELETE operations, controlled by each environment's `writeMode`
- Searchable ESS process catalog plus request submission, recurring schedules,
  status polling, bounded waiting, listing and cancellation
- Reviewed named SQL and guarded ad-hoc SQL through BI Publisher Get SQL
- Allowlisted BI Publisher report execution
- Reusable OTBI `.catalog` dependency check, recursive export, local import
  preview, confirmed asynchronous import, and job verification
- Typed `WebCatalogService` item inspection/listing and BI Publisher
  `CatalogService` folder listing, object metadata, existence, individual
  download/upload, and folder creation tools
- HCM security diagnostics for SCIM users, roles, data roles, profiles, role
  mappings, Areas of Responsibility and security-policy reports
- BPM approval-rule inventory, rule/task inspection, usage search, snapshots
  and cross-environment comparison
- BPM runtime Worklist, task history, HCM transaction context, Transaction
  Console search and combined task diagnosis
- Approval Rules simulation reports and simulation history
- Optimistic-lock and confirmation protected BPM draft/deploy support,
  disabled by default
- Allowlisted BPM runtime task actions with optimistic state/date checks and an
  identical code path for every target environment
- Batch Transaction Console approve, reject, reassign, resubmit and withdraw
  actions with fresh-status checks, preview, exact confirmation and post-action
  verification
- Reusable Oracle REST client with Basic Auth, pagination and retry handling
- Read-only end-to-end smoke command using the official MCP client
- Valid configuration examples and security invariant tests

## Commands

```bash
npm install
npm run check
npm run start:local
npm run hcm:smoke -- <environmentId>
npm run import:openapi
```

See [the data model](docs/data-model.md) for the entity relationships and
security invariants. See [the OpenAPI importer](docs/openapi-import.md) for
source and generated-catalog details. See [the local MCP server guide](docs/mcp-server.md)
for tools and the current authentication boundary. See
[environment configuration](docs/environments.md) for multi-pod setup and
connection tests. See [Catalog/Support tools](docs/catalog-support-tools.md)
for SQL, security and BPM configuration. See the
[BI catalog bundle guide](docs/bip-catalog-bundle.md) for packaging Get SQL and
Security reports once and deploying them to other pods. See
[Oracle BI catalog tools](docs/bi-catalog-tools.md) for the WebCatalogService
and Publisher CatalogService boundary. See the
[Fusion AI Agent Studio integration guide](docs/fusion-ai-agent-studio.md) for
MCP registration, the common result contract, workflow rendering, and
debugging. The [v0.10 test report](docs/test-report-v0.10.md) records the
SDK, schema, sanitization, and binary-delivery validation; the
[v0.8 test report](docs/test-report-v0.8.md) remains the latest demo-pod
connector validation.