Add OCI Speech MCP Server

[Prabhutva]

Description

Adds the initial release of the OCI Speech MCP Server (v1.0.0), a locally run stdio MCP server that enables agents and MCP clients to use OCI Speech through the OCI Python SDK.

Transcription Jobs

Adds the following tools:

• create_transcription_job
• get_transcription_job
• list_transcription_jobs
• update_transcription_job
• delete_transcription_job
• cancel_transcription_job
• change_transcription_job_compartment
• list_transcription_tasks
• get_transcription_task
• cancel_transcription_task
• download_transcription_results
• transcribe_local_file

The transcribe_local_file tool provides an end-to-end local transcription workflow. It validates and uploads a local media file to OCI Object Storage, creates and optionally monitors the transcription job, and downloads successful JSON and SRT outputs to a restricted local directory.

Transcription features include diarization, configurable speaker counts, punctuation, profanity filtering, multiple transcription models and domains, Whisper prompting, and SRT output.

Resources and prompts provide guidance for:

• Creating and managing transcription jobs and tasks
• Transcribing local audio files
• Choosing whether to enable diarization
• Troubleshooting unsuccessful jobs
• Safely handling local files and downloaded results

Customizations

Adds the following tools:

• create_customization
• get_customization
• list_customizations
• update_customization
• delete_customization
• change_customization_compartment

Customization inputs support inline entities, pronunciations, reference examples, Object Storage datasets, and reusable entity customizations.

The accompanying resource and prompt explain how to select, structure, create, train, update, and reuse OCI Speech customizations.

Text to Speech

Adds the following tools:

• list_voices
• synthesize_speech

Speech synthesis supports plain text and SSML, configurable voices, audio formats, sample rates, and safe local output handling.

The TTS and SSML resources include examples and guidance for:

• Selecting an appropriate voice
• Adding pauses, emphasis, and pronunciation hints
• Controlling speaking rate, pitch, and volume
• Reading dates, numbers, telephone numbers, and characters
• Validating SSML before synthesis
• Helping an agent transform plain text into customized SSML

Extras

Adds the following tool:

• setup_transcription_notifications

This tool creates or reuses an OCI Notifications topic and creates OCI Events rules for transcription job completion and failure events. Subscription creation remains an explicit user action so confirmation endpoints are not configured without consent.

Additional resources and prompts cover:

• OCI Speech prerequisites
• Required IAM policies
• Service limits
• OCI Events and Notifications
• Troubleshooting
• OCI Realtime Speech integration
• Live transcription using the OCI AI Speech Realtime Python SDK

Realtime transcription guidance keeps the persistent WebSocket connection in the user's application, where audio capture and playback occur, instead of holding a long-running connection inside the stdio MCP server.

Motivation and context

This server makes OCI Speech workflows directly accessible to MCP-compatible agents while continuing to use the user's existing OCI credentials and authorization policies.

It reduces the setup required for workflows involving Object Storage, transcription result retrieval, diarization, customizations, SSML generation, speech synthesis, and transcription job notifications.

The implementation separates tools, prompts, and resources by capability so future OCI Speech modules can be added without expanding the server entry point.

The server also provides:

• Authentication through oracle-mcp-common
• A package-derived oci-speech-mcp/1.0.0 OCI SDK user agent
• Bounded pagination
• Sanitized OCI error responses
• Restricted local input and output paths
• Protection against credential and sensitive-file access

Dependencies and prerequisites

Runtime dependencies include:

• Python 3.13
• fastmcp==3.4.5
• oci==2.185.1
• oracle-mcp-common>=0.1.0,<0.2.0
• pydantic>=2.13.4,<3

Users require a configured OCI authentication profile and the appropriate OCI Speech, Object Storage, Events, Notifications, and IAM permissions for the operations they intend to use.

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

The server was validated with:

moon run oci-speech-mcp-server:test
moon run root:lint

Automated validation results:

• 52 unit tests passed
• 95.06% branch-aware code coverage, exceeding the required 90% threshold
• Repository lint checks passed
• All supported OCI authentication paths apply the expected oci-speech-mcp/1.0.0 user agent

Live stdio MCP validation confirmed discovery of all 21 tools, 11 resources, and 9 prompts. Every resource was read and every prompt was rendered.

Transcription Jobs

• Uploaded and transcribed local audio, including create-only collision handling that preserved a pre-existing caller-named object
• Monitored the transcription job through completion
• Downloaded JSON and SRT results
• Tested job creation, retrieval, listing, update, compartment change, and deletion
• Tested transcription task listing and retrieval
• Exercised job and task cancellation requests, Oracle and Whisper models, diarization, profanity filters, punctuation, prompts, tags, output formats, sorting, filtering, pagination bounds, and ETag preconditions

Customizations

• Created and trained inline reusable, contextual reuse, audio-pronunciation, and Object Storage text-dataset customizations
• Retrieved and listed customizations
• Updated and deleted a customization
• Validated dataset mappings, reference examples, entity weights, sounds-like values, tags, name restrictions, and compartment changes

Text to Speech

• Listed available voices with language, model, and display-name filters
• Synthesized plain text with standard and natural voices in MP3 and OGG
• Synthesized speech from SSML
• Validated SSML, JSON word/sentence speech marks, sample rates, and non-overwriting atomic local output handling

Extras

• Created an OCI Notifications topic
• Created OCI Events rules for transcription job completion and failure using both new and existing Notifications topics
• Validated the prerequisite, IAM policy, service-limit, notification, and realtime guidance
• Removed all temporary jobs, customizations, event rules, topics, objects, and the test bucket after live validation

To reproduce the live tests:

1. Configure a valid OCI profile.
2. Ensure the profile has access to OCI Speech and a test compartment.
3. Configure the MCP server as documented in its README.
4. Connect through an MCP client using stdio.
5. Exercise the transcription, customization, TTS, and notification tools.

Test Configuration:

• Hardware: Apple Silicon Mac
• Toolchain: Python 3.13.2, uv 0.10.0, pytest 9.1.1, repository lint tooling
• SDK: OCI Python SDK 2.185.1, FastMCP 3.4.5
• OCI region: us-phoenix-1
• Authentication: OCI DEFAULT profile through oracle-mcp-common

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 feature works
• New and existing applicable unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules (N/A: no dependent changes are required)

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

• src/oci-speech-mcp-server/oracle/oci_speech_mcp_server/utils/responses.py:129 — [P1] Write local artifacts privately and atomically.
• src/oci-speech-mcp-server/oracle/oci_speech_mcp_server/tools/transcription.py:468 — [P1] Preserve or clean uploaded media when job creation fails.

Additional review notes

• [P2] Surface created notification resources after partial failure.
• [P2] Validate model-specific transcription options.
• [P2] Preserve actionable local I/O errors.

Validation

• make test project=oci-speech-mcp-server passed: 45 tests and 97.21% coverage.
• make lint and all reported GitHub checks passed. Live OCI operations were not rerun.

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

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

• src/oci-speech-mcp-server/oracle/oci_speech_mcp_server/tools/transcription.py:37 — [P1] Recognize supported Whisper model identifiers.
• src/oci-speech-mcp-server/oracle/oci_speech_mcp_server/tools/transcription.py:475 — [P1] Preserve recovery state after side effects begin.

Additional review notes

• src/oci-speech-mcp-server/oracle/oci_speech_mcp_server/__init__.py:8 — [P2] Derive the package version from distribution metadata.

Validation

• make lint passed.
• make test project=oci-speech-mcp-server passed with 47 tests and 96.54% coverage; all current GitHub checks also pass.

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

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

• src/oci-speech-mcp-server/oracle/oci_speech_mcp_server/tools/transcription.py:579 — [P1] Protect caller-named Object Storage inputs from overwrite and cleanup deletion.

Additional review notes

• src/oci-speech-mcp-server/pyproject.toml:15 — [P2] Declare the Common dependency in Moon.
• src/oci-speech-mcp-server/README.md:383 — [P2] Replace removed Make validation commands.

Validation

• moon run oci-speech-mcp-server:test passed: 49 tests and 96.46% coverage.
• Moon lint, lock check, and build passed; current GitHub checks pass.
• git diff --check reports five extra blank lines at EOF.

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

[dustin-sale]

Review by @dustin-sale via Codex.

Requested changes

• src/oci-speech-mcp-server/oracle/oci_speech_mcp_server/tools/transcription.py:641 — [P1] Preserve uploaded input when job creation has an unknown outcome.

Additional review notes

• src/oci-speech-mcp-server/oracle/oci_speech_mcp_server/tools/transcription.py:700 — [P2] Preserve partial downloads and make retry resumable.

Validation

• moon run oci-speech-mcp-server:test passed: 52 tests and 95.06% coverage.
• Moon lint, lock check, build, and current GitHub checks passed; git diff --check passed. Live OCI operations were not rerun.

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