confluentinc / confluentinc/mcp-confluent

Thread `connectionId` through tool handlers that depend on connection-specific config

Open
#367 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
168
Forks
62
Avg merge
6d 22h
Merged PRs (30d)
4

Description

Problem

The runtime currently assumes a single connection. runtime.clientManager (https://github.com/confluentinc/mcp-confluent/blob/1a3cd3c/src/server-runtime.ts) throws on 0 or >1 managers, and many handlers reach for runtime.requireDirectClientManager() or getSoleDirectConnection(). With multi-connection support arriving as the next milestone after #151, every tool that operates on connection-specific resources (Kafka topics, Flink statements, Schema Registry, etc.) needs a way for the caller to specify which connection to target.

Proposed design (initial sketch - expected to be broken down further)
  1. Add runtime.getClientManager(connectionId: string): BaseClientManager (or similar id-based lookup) to https://github.com/confluentinc/mcp-confluent/blob/1a3cd3c/src/server-runtime.ts.
  2. Audit handlers under https://github.com/confluentinc/mcp-confluent/blob/1a3cd3c/src/confluent/tools/handlers/. For each handler that depends on a specific connection's config:
    • Add connectionId: string to the input schema.
    • Replace runtime.clientManager / requireDirectClientManager() with the new id-based lookup.
  3. Decide the routing UX:
    • Required connectionId is safest - no break-on-promotion behavior when a second connection is configured (matches the decision made for #365).
    • Optional with sole-connection fallback is friendlier in single-connection setups but breaks once a second connection lands.
Open questions
  • Per-handler decision on required vs optional connectionId, or a project-wide policy?
  • Migration cadence: one mega-PR auditing every handler, or a domain-by-domain rollout (kafka, then flink, then schema, etc.)?
  • Failure modes when a handler is called with an id whose connection lacks the required block (e.g., list-flink-statements against a connection with no flink: block) - error in the handler, or rely on enabledConnectionIds + #358 so clients never call it that way?

This issue is intentionally rough and will be broken down into smaller children as the design firms up.

Relationships
  • Tracks against: #151 (single-connection YAML migration) and the planned multi-connection epic that follows it.
  • Becomes load-bearing for: #364, #365, #366 (the discovery / config-help track) - those tools can ship before this one, but their value lights up once routing lands.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/server-runtime.ts to understand the current client-manager assumptions, then audit the handlers under src/confluent/tools/handlers/. Review the proposed required-versus-optional connectionId routing and the listed failure modes. Done for this issue means agreeing on the routing and migration approach and breaking the audit into actionable child issues.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.