confluentinc / confluentinc/mcp-confluent
Thread `connectionId` through tool handlers that depend on connection-specific config
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)
- Add
runtime.getClientManager(connectionId: string): BaseClientManager(or similar id-based lookup) to https://github.com/confluentinc/mcp-confluent/blob/1a3cd3c/src/server-runtime.ts. - 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: stringto the input schema. - Replace
runtime.clientManager/requireDirectClientManager()with the new id-based lookup.
- Add
- Decide the routing UX:
- Required
connectionIdis 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.
- Required
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-statementsagainst a connection with noflink:block) - error in the handler, or rely onenabledConnectionIds+ #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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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