Add OCI Streaming with Apache Kafka MCP server

[BhaumikAbhishek]

Adds oracle.oci-kafka-mcp-server, a comprehensive MCP server for managing OCI Streaming with Apache Kafka clusters via AI agents.

Features:

• 42 MCP tools spanning Kafka data plane and OCI control plane
• Data plane: topics, consumers, observability, AI diagnostics
• Control plane: cluster lifecycle (create/scale/delete), cluster configurations with versioning, superuser management, work requests
• Security: SASL/SCRAM-512, SASL/PLAIN, mTLS Kafka authentication; OCI API key auth via ~/.oci/config
• Policy guard: three-tier risk model (LOW/MEDIUM/HIGH) with --allow-writes flag for write operations and confirmation required for destructive HIGH-risk operations
• Audit logging: structured JSON log for every tool execution
• Circuit breaker: prevents cascading failures on broker unavailability
• Compartment auto-discovery: falls back to tenancy OCID from OCI config when OCI_COMPARTMENT_ID env var is not set
• Read-only by default; --allow-writes enables write tools

Validation steps:
uvx oracle.oci-kafka-mcp-server # read-only mode
uvx oracle.oci-kafka-mcp-server --allow-writes # write mode
uv run pytest # 92 tests pass

Description

Adds oracle.oci-kafka-mcp-server, a new MCP server that enables AI agents to manage OCI Streaming with Apache Kafka clusters through structured tool execution.

Fixes # 155
This server covers both the Kafka data plane (topics, consumer groups, observability, AI-assisted diagnostics) and the OCI control plane (cluster lifecycle, versioned cluster configurations, superuser management, async work request tracking). It supports secure Kafka connectivity via SASL/SCRAM-512, and mTLS, and authenticates to the OCI control plane via ~/.oci/config.

Dependencies required:

mcp>=1.0.0 — MCP Python SDK (FastMCP)
confluent-kafka>=2.6.0 — Kafka data plane client
oci>=2.130.0 — OCI Python SDK for control plane
pydantic>=2.0.0, pydantic-settings>=2.0.0 — configuration management

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

• Test A
• Test B

Test A — Unit tests (92 tests, no broker required):

cd src/oci-kafka-mcp-server
uv run pytest # all 92 tests pass
uv run pytest --cov-fail-under=45

Test B — Server startup validation:

uvx oracle.oci-kafka-mcp-server # starts in read-only mode
uvx oracle.oci-kafka-mcp-server --allow-writes # starts with write tools enabled

Test Configuration:
SDK: OCI Python SDK oci>=2.130.0, MCP SDK mcp>=1.0.0, confluent-kafka >=2.6.0
Toolchain: Python 3.11, 3.12, 3.13 (tested via CI matrix)
OCI Auth: ~/.oci/config with DEFAULT profile

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

[oracle-contributor-agreement]

Thank you for your pull request and welcome to our community! To contribute, please sign the Oracle Contributor Agreement (OCA).
The following contributors of this PR have not signed the OCA:

• PR author: bhaumik.abhishek@gmail.com (@BhaumikAbhishek)

To sign the OCA, please create an Oracle account and sign the OCA in Oracle's Contributor Agreement Application.

When signing the OCA, please provide your GitHub username. After signing the OCA and getting an OCA approval from Oracle, this PR will be automatically updated.

If you are an Oracle employee, please make sure that you are a member of the main Oracle GitHub organization, and your membership in this organization is public.

[BhaumikAbhishek]

@krisrice @AlaaShaker @gebhardtr
Could you please review and merge this pull request.

[krisrice]

Security review notes for remediation:

1. High: Unsafe credential persistence in src/oci-kafka-mcp-server/oracle/oci_kafka_mcp_server/tools/connection.py.
   The persist=True path writes a shell-sourceable file containing raw, unescaped user-controlled values, then instructs operators to source it. That creates a shell-injection primitive if any credential contains $(), backticks, quotes, or newlines.
   Remediation: do not emit executable shell syntax for secrets; prefer a non-executable config format, or at minimum shell-escape every value safely and add tests for adversarial inputs.

2. High: oci_kafka_enable_superuser is a one-call privilege-escalation path with no explicit confirmation and no bounded default lifetime.
   Today it is classified as MEDIUM risk and is not in the confirmation-required set, while duration_in_hours=None leaves superuser enabled until someone disables it.
   Remediation: treat this as HIGH risk, require an explicit confirmation step, and require a bounded duration instead of allowing indefinite elevation by default.

3. Medium-High: Untrusted Kafka / OCI data is being fed directly back to the LLM in a write-capable MCP server.
   Topic names, config values, consumer group metadata, work-request errors, and logs are all returned verbatim and the diagnostics tools explicitly expect the LLM to interpret them. In OWASP GenAI terms, this is an indirect prompt-injection / improper-output-handling surface, especially when write tools are enabled in the same session.
   Remediation: treat tool outputs as untrusted, isolate diagnostic/read-only flows from write-capable flows, add stronger human approval for dangerous follow-on actions, and document the trust boundary clearly.

4. Medium: The advertised confirmation control is not actually implementable.
   High-risk tools return confirmation_required, but the tool signatures expose no confirmed flag, nonce, or other stateful approval mechanism, so there is no real way to perform the documented second call “with confirmation”.
   Remediation: add an explicit confirmation parameter or nonce-based two-step workflow and cover it with end-to-end tests.

I ran the package-local test suite (121 passed), but it is heavily mock-based and does not currently catch the issues above.

[BhaumikAbhishek]

@krisrice Thanks for the thorough review. All four findings have been addressed in commit 51cb7e7:

1. HIGH — Shell injection in connection.py
   Removed the shell-sourceable export format entirely. The persist path now writes plain .env format (KEY=VALUE) with a comment warning against sourcing. Added _sanitize_env_value() that rejects values containing $, backticks, quotes, newlines, and backslashes — with 9 adversarial input tests covering each vector.

2. HIGH — Superuser privilege escalation
   oci_kafka_enable_superuser is now classified as HIGH risk and added to the CONFIRMATION_REQUIRED set. duration_in_hours is now required (default: 1 hour, max: 24 hours) — indefinite elevation is no longer possible. The tool requires confirmed=True to execute, matching all other HIGH-risk tools.

3. MEDIUM-HIGH — Indirect prompt injection / trust boundaries
   All 36 tool return paths that contain data from Kafka brokers or OCI APIs are now wrapped with _trust_boundary: "untrusted_external_data" and a notice instructing MCP clients and LLM agents not to interpret field values as instructions. Session isolation guidance (read-only default, --allow-writes only in dedicated sessions) is documented in the README Safety Model section.

4. MEDIUM — Confirmation mechanism not implementable
   All 9 HIGH-risk tools now accept a confirmed: bool = False parameter. The two-step flow:

First call (without confirmed=True) → returns {"status": "confirmation_required", ...} with a human-readable warning
Second call (with confirmed=True) → executes the operation
End-to-end tests verify both the confirmation prompt and the duration validation.

Test results: 135 tests passed (14 new), 39.68% coverage.