[dustin-sale]

Description

Improve the OCI JavaScript MCP server’s tool contracts so clients can discover valid inputs and outputs, identify execution failures, and use SDK discovery without silently falling back to a shallower level.

• Extract tool metadata, schemas, discovery validation, and result serialization into src/tool-contracts.ts.
• Advertise tool titles, output schemas, and execution risk annotations.
• Mark failed run_javascript executions with MCP isError: true while preserving the six structured result fields and matching JSON text content.
• Reject malformed discovery identifiers, missing parent identifiers, and invalid discovery results while preserving valid SDK extraction data.
• Expand execution guidance with constructed-client examples, bounded pagination, response limits, and resource reconciliation before retrying mutations.
• Update the README, changelog, and package engineering guide, and add contract, sandbox, stdio integration, and packaging regression coverage.

Breaking changes:

• Clients must handle the outer isError flag for failed executions.
• Invalid discover_oci inputs that previously fell back to a shallower discovery level now return tool errors.

Tracking issue: Not identified in the branch; add the issue reference before submission.

Dependencies: No package dependency changes or dependent PRs identified.

Type of change

• 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?

The branch adds tests covering:

• Execution output schema validation, JSON value preservation, and equivalence between text and structured results.
• Error signaling for execution errors, timeouts, nonzero exit codes, and provider startup or cleanup failures.
• Discovery input validation before host RPC, all four discovery result variants, preservation of additional extraction data, and rejection of malformed results.
• MCP stdio tool metadata, advertised output schemas, execution examples, and discovery errors.
• Bounded pagination, response and result limits, and a mutation that completes before a later script failure.

Run from the repository root:

• moon run oci-javascript-mcp-server:test — run unit and integration tests with the configured 90% line-coverage gate.
• moon run oci-javascript-mcp-server:check — check TypeScript source and test types.
• moon run oci-javascript-mcp-server:build — validate npm package creation.

These tests use mocked OCI behavior and a fake Podman control plane; real OCI operations and Podman deployment isolation remain unverified.

Test Configuration:

• Firmware version: Not applicable.
• Hardware: Not recorded.
• Toolchain: Package requires Node.js 26+ and declares npm 11.12.1; validation runs through Moon.
• SDK: Declared dependencies include @modelcontextprotocol/sdk ^1.31.0, oci-sdk ^2.132.0, and zod ^4.4.3.

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

No dependent module changes were identified. Author self-review, passing validation, Oracle Contributor Agreement status, and the required commit signoff remain unverified.