docs(AI-3692): Data Catalog RFC — bucket sharing tools

[Matovidlo]

Description

Linear: AI-3692

Change Type

• Major (breaking changes, significant new features)
• Minor (new features, enhancements, backward compatible)
• Patch (bug fixes, small improvements, no new features)

Summary

RFC-only PR — no tool/client code. Adds feature_spec/data_catalog/RFC.md and
brainstorm.md designing the producer side of the Data Catalog workflow: three new tools,
share_bucket_to_organization, share_bucket_to_project, and unshare_bucket, wrapping the
Storage API's share-organization / share-organization-project / DELETE .../share
endpoints. All three are always branch-scoped and async (the endpoints have no sync option),
and poll their Storage job to completion inside the tool call rather than exposing a separate
job-status tool.

This builds on top of PR #646 (get_shared_buckets + link_shared_bucket, the consumer
side — discovery + linking), which is not yet merged (currently CONFLICTING against main;
rebasing/merging it is a separate, already-identified follow-up, not part of this PR). Together
they complete the loop: build a pipeline → share it (this RFC) → discover + link it
elsewhere (#646) → reuse it.

One open risk flagged explicitly in the RFC: share_bucket_to_project's target-project request
body is undocumented in the Storage OpenAPI spec and needs live verification (same diligence
#646 applied to link_shared_bucket) before the follow-up implementation PR.

Per CONTRIBUTING.md's RFC Requirement table, new MCP tools require an agreed RFC before
implementation — this PR is that RFC. The actual share_bucket_to_organization /
share_bucket_to_project / unshare_bucket tool code, the new AsyncStorageClient methods,
the Storage-job poll helper, and the system-prompt edit all land in a separate implementation PR
once this RFC is agreed.

Testing

• Tested with Cursor AI desktop (Streamable-HTTP transports)

Optional testing

• Tested with Cursor AI desktop (all transports)
• Tested with claude.ai web and canary-orion MCP (Streamable-HTTP)
• Tested with In Platform Agent on canary-orion
• Tested with RO chat on canary-orion

Checklist

• Self-review completed
• Unit tests added/updated (if applicable) — N/A, docs only
• Integration tests added/updated (if applicable) — N/A, docs only
• Project version bumped according to the change type — N/A, no code change
• Documentation updated (if applicable) — RFC + brainstorm added

[linear-code]

AI-3692

[Matovidlo]

@claude review

[Copilot]

Pull request overview

This PR adds an RFC (plus its supporting brainstorm artifact) for the producer-side of the Data Catalog sharing workflow in Keboola MCP Server. It specifies three new Storage write tools for sharing/unsharing existing Storage buckets across an organization/projects, designed to be branch-scoped and always-async, with the tools polling Storage jobs to completion within a single tool call.

Changes:

• Add feature_spec/data_catalog/RFC.md defining proposed tools (share_bucket_to_organization, share_bucket_to_project, unshare_bucket) and the planned client/job-polling design.
• Add feature_spec/data_catalog/brainstorm.md capturing discovery notes, constraints, alternatives, and open questions that feed into the RFC.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
feature_spec/data_catalog/RFC.md	RFC specifying the intended tool surface, API endpoints, polling strategy, scope boundaries, and open questions for bucket sharing/unsharing.
feature_spec/data_catalog/brainstorm.md	Pre-RFC discovery document documenting motivation, constraints, alternatives, and implementation impact analysis for the sharing tools.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[keboola-pr-reviewer-bot]

Verdict: auto_approve (risk 1/5) · profile keboola-mcp-server

Docs-only RFC under feature_spec/**, auto-approvable per policy.

[cjayyy]

Heads-up before these ship: AI-3737 — a bare share_bucket_to_project shares the bucket but not the semantic definitions built on it, so a consumer silently gets tables with no metrics. The UI path (ui#7885) shares both. Worth deciding what "share" should mean before both exist.

[Matovidlo]

@cjayyy nice catch, I see 2 options

1. Having data catalog sharing as separate tool and semantic tooling as follow up in system prompt
2. Couple both to single tool call, seems a little bit weird but as its coupeled it either is fully done or never and rolled back.
   WDYT ? cc @tomasfejfar

[tomasfejfar]

I vote to mirror the UI. Also the sharing is deterministic - you know what semantic layer parts you need to share when sharing a bucket. If you share only the relevant parts (touching the shared resources) it's imho fine. If you can't share only the related resources but share something more, we are open to the "unsharing" problem. When you unshare you should be aware that you may remove parts of the semantic layer others are building on. For buckets/tables we're aware and it fails predictably. Not sure about semantic layer, if it's somehow resilient against such situations.

Dismissing prior approval — a new commit was pushed and this review was for an earlier SHA. Run @keboola-pr-reviewer-bot review to get a fresh verdict.

[keboola-pr-reviewer-bot]

New commit on a8ee903 — dismissed 1 stale bot approval. Comment @keboola-pr-reviewer-bot review when you want a fresh review.

[Matovidlo]

@cjayyy addressed — added a "Semantic layer interaction (AI-3737)" section that mirrors the UI's resolved design (ui#7885): sharing composes Storage buckets + Metastore semantic-object scope, buckets-first on share / scope-first on unshare, reported (not thrown) partial failure via a degraded reason. Per @tomasfejfar's comment, going with mirroring the UI rather than the atomic-coupling alternative.

Blocking gap called out explicitly: MCP has no Metastore scoping primitive today, so share_semantic_model/unshare_semantic_model are deferred to a follow-up RFC once that backend endpoint exists (same spot the UI prototype is in). In the meantime the system-prompt addendum makes the three bucket-only tools say plainly that they don't carry semantic definitions with them, so this doesn't ship as a silent gap.

Requesting re-review — thanks for catching this before it merged.

[cjayyy]

@Matovidlo @tomasfejfar — flagging a cross-repo conflict before this RFC section sets, because the design it now mirrors was reversed about 20 minutes before it was written, in a Linear thread neither of you would have seen.

Timeline (UTC, 13 Aug):

• 08:17 @tomasfejfar: "I vote to mirror the UI"
• 08:21 @david.esner on AI-3703: "bucket-driven. The bucket stays the unit of sharing. The semantic model is an additional layer on top... it is not itself a shareable object." — and to my question about whether to finish the plumbing: "stop before finishing the plumbing."
• 08:41 this RFC gains a section mirroring ui#7885's model-level composition

So the "UI's resolved design" phrasing is unfortunately my fault — I described #7885 that way in AI-3737 while the direction question was still open. It was a prototype following a brief in David's ui#7739, which opens "Not for merge. This is a working prototype to make a design decision discussable." I read it as a spec; it wasn't one.

What this means for the RFC as written. The part you deferred is fine and unaffected — share_semantic_model/unshare_semantic_model are blocked on a Metastore scoping primitive either way. The part worth revisiting is the framing: composing a bucket share with a metastore rescope, as a model-level operation, is the specific thing AI-3703 decided against. David's reasoning is that bucket sharing is already ingrained and a bucket precedes its model, so model-as-unit adds a second sharing concept plus two non-transactional APIs.

Notably, @tomasfejfar's own argument points the same way as the decision: "the sharing is deterministic — you know what semantic layer parts you need to share when sharing a bucket." That is bucket-driven with model awareness, which is exactly what David proposes. The disagreement is narrower than it looks — it is about whether a model-level share primitive should exist, not about whether definitions should follow their data.

Also worth knowing, since it bears on the deferral: targeted scope is no longer blocked. go-monorepo#565 merged at 10:14 today with @vojtabiberle approving, and the implementation is now a 5-PR stack (#578–#582, all open, #578 and #582 at CHANGES_REQUESTED). #582 is the one that enables targeted/organization on the six non-model object types, so it gates whatever scoping primitive MCP eventually calls.

Two open questions David flagged that the RFC will need answers to regardless of framing: how the model↔bucket link is represented (he is explicit that nothing should be built before that is decided), and sensitive models that must not become discoverable just because their buckets are.

Not asking for a change right now — a live sync on this was set for today and I have not found a written outcome. Just don't want ui#7885 cited as settled when it is being redirected.

🤖 Flagged by Claude Code