Add OCI Document Understanding MCP Server

[antimverma]

Description

Adds the OCI Document Understanding MCP server under src/oci-document-understanding-mcp-server.

This server provides stdio MCP tools for OCI Document Understanding extraction and classification workflows. It supports extracting text, key-value pairs, tables, and document elements, as well as document classification for inline base64 documents and OCI Object Storage document sources.

The implementation follows the repository MCP server structure and public packaging expectations:

• Adds pyproject.toml, uv.lock, README.md, CHANGELOG.md, LICENSE.txt, and oracle/ package source.
• Exposes the package entry point as oracle.oci-document-understanding-mcp-server.
• Supports stdio transport only.
• Supports OCI SDK session-token, API-key, and instance-principal authentication, plus deterministic stub mode for local testing without OCI calls.
• Documents that HTTP, streamable HTTP, OAuth, IDCS bearer-token validation, /mcp, and /.well-known/* endpoints are not exposed.
• Adds document_extract for text, key-value, table, and document-element extraction.
• Adds document_classify for document classification and confidence-aware candidate results.
• Supports inline base64 and OCI Object Storage document sources.
• Adds request validation, OCI request mapping, response parsing, and structured error handling.
• Adds OCI SDK additional_user_agent telemetry derived from package metadata.
• Includes unit tests with a coverage threshold set to 90%.

Fixes: N/A

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Validated locally from src/oci-document-understanding-mcp-server:

• uv run pytest --cov=. --cov-branch --cov-report=term-missing
  • 39 passed
  • Coverage: 93.73%
• uv build
  • Successfully built sdist and wheel.
• MCP stub-mode smoke testing
  • Started the server locally with DOCUMENT_MCP_MODE=stub and OCI_AUTH_MODE=none.
  • Verified document_extract through the local stdio MCP server.
  • Verified document_classify through the local stdio MCP server.
  • Confirmed both tools completed without OCI credentials or OCI service calls.

Test Configuration:

• OS: macOS
• Python: 3.13.2
• Package manager: uv
• MCP transport: stdio
• Stub-mode auth: OCI_AUTH_MODE=none

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules (N/A)

[antimverma]

@krisrice @AlaaShaker Can you please help review and approve this PR to add the OCI Document Understanding MCP Server.

[dustin-sale]

Please migrate the OCI SDK client setup to oracle-mcp-common’s build_auth_context() as required by this repository, and make include_confidence=false actually suppress confidence output (or remove the unsupported option). The scoped tests otherwise pass with 93.73% coverage.

[antimverma]

Hi @dustin-sale, addressed your comments. Please approve.

[dustin-sale]

@antimverma the two prior review requests are resolved. Further review found two more defects, please see my comments.

[antimverma]

Hi @dustin-sale thanks for the review and comments, I addressed your latest comments. Please check.

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

No blocking changes requested.

Additional review notes

None.

Validation

• make lint passed.
• make test project=oci-document-understanding-mcp-server passed (47 tests; 94.35% coverage).

See the inline comments in this review for evidence, impact, and suggested remediation.

[antimverma]

Hi @krisrice Please help approve/merge this PR.

[gebhardtr]

can this be adapted to use the common auth module? https://github.com/oracle/mcp/blob/main/src/common/oracle_mcp_common/auth.py

[antimverma]

@gebhardtr Addressed this in the latest commit.

[robander]

Feedback from an automated review:

P1 security: OCI_DOCUMENT_ENDPOINT permits any endpoint, including plain HTTP, and sends document contents there via the authenticated SDK client. This bypasses the repository’s recent endpoint-hardening direction and could exfiltrate sensitive documents. Remove the override or strictly derive/validate an official OCI Document Understanding endpoint.

[robander]

This pull request is creating version 0.1.0, should these "unreleased" changes be included with the 0.1.0 list below?

[antimverma]

@robander Fixed.

[antimverma]

Feedback from an automated review:

P1 security: OCI_DOCUMENT_ENDPOINT permits any endpoint, including plain HTTP, and sends document contents there via the authenticated SDK client. This bypasses the repository’s recent endpoint-hardening direction and could exfiltrate sensitive documents. Remove the override or strictly derive/validate an official OCI Document Understanding endpoint.

@robander Also addressed this.

[antimverma]

@gebhardtr @robander All comments are addressed. Please review/approve.