@W-22350774: Add Tableau Prep flows tools (list-flows, get-flow)

[showmethecold]

Onboard Tableau Prep flows into the MCP server with two new read-only tools backed by Tableau's public REST API for flows.

New tools

• list-flows: paginated listing with filter/sort matching Tableau's Flows API (filter fields: name, projectId, projectName, ownerName, createdAt, updatedAt; sort fields: name, createdAt, updatedAt). Empty-result messages include recovery hints when callers pass a value shape Tableau silently rejects (e.g. login/email/UUID for ownerName, or a non-UUID for projectId). Every response carries an mcp.resultInfo completeness signal (see Design note).
• get-flow: primary flow metadata + output steps, with optional sidecar fetches for connections and recent flow runs. Both sidecars are best-effort; failures degrade to structured warnings under mcp.warnings (SIDECAR_FETCH_FAILED, VERSION_GATE_SKIPPED). The runs sidecar uses a "+1 probe" to detect truncation (Tableau's runs endpoint returns no pagination block); truncation surfaces as a FLOW_RUNS_TRUNCATED warning so callers can distinguish a complete history from a windowed view.

Design note: result completeness & pagination (for maintainers' consideration)

This is the one place list-flows intentionally diverges from the existing list-* tools, so calling it out explicitly.

Bounded results + an explicit completeness signal — no caller-facing cursor in v0.
A site can hold thousands of flows. Rather than surface Tableau's pageNumber/pageSize offset pagination as caller-managed state, list-flows paginates internally and returns a single bounded result:

• The effective cap is min(caller 'limit', admin MAX_RESULT_LIMIT); when neither is set, the admin cap (if configured) is the backstop.
• Even an explicit "list all flows" request is capped at MAX_RESULT_LIMIT — the tool never streams an unbounded set. This is deliberate: it keeps a single tool call bounded/predictable and protects the model's context-window/token budget.
• We chose not to expose a cursor in v0 because (a) it pushes multi-call continuation state onto the LLM for marginal benefit, and (b) callers needing deep/complete enumeration are better served by the Tableau Flows REST API directly (pageNumber pagination or a date-range filter), which the tool description and docs point to. A cursor can be added later without changing the response shape.

Because results are bounded, completeness is made explicit. Every list-flows response carries mcp.resultInfo:

• returnedCount — flows in this response.
• truncated + truncationReason (requested-limit | admin-cap) — whether more matched than were returned, and why.
• totalAvailable — Tableau's server-side total for the query, so the model can honestly report "showing N of M" and decide whether to narrow the filter. Surfaced only when no bounded context (PROJECT_IDS/TAGS) is configured, because that count is taken before the tool's allow-list filtering and would otherwise overstate the accessible total.

For the Tableau MCP team: list-flows is currently the only tool that emits mcp.resultInfo — the other list-*/get-* tools return bare arrays. We're comfortable shipping it scoped to list-flows, but flagging it for a team decision on whether this completeness contract (especially truncated/totalAvailable) should be standardized across the other tools, since silent truncation under an admin cap is a latent issue for any list tool. Happy to generalize it if the team prefers.

Security: bounded-context enforcement

get-flow now enforces the server bounded context. Previously it fetched any flow by ID, ignoring the operator's PROJECT_IDS/TAGS allow-list — a scoping gap get-workbook already closed. Added FlowNotAllowedError (403) and resourceAccessChecker.isFlowAllowed, and gated the fetch behind it (reusing the flow the checker already fetched), with a dedicated flow scope set so the checker doesn't drag in tableau:content:read.

Auth scopes

Added MCP scope tableau:mcp:flow:read and Tableau API scopes tableau:flows:read, tableau:flow_connections:read, tableau:flow_runs:read; wired into toolScopeMap and OAuth defaults. get-flow requests only the scopes its requested sidecars need — connection/run scopes are added only when includeConnections/includeFlowRuns are true — so a metadata-only call succeeds against a connected app that grants only tableau:flows:read.

Operational kill switch: FLOW_TOOLS_ENABLED

Added a single environment-variable switch so operators can turn all flow tools off at once if something goes wrong, without editing per-tool exclusions.

• Default-on kill switch. Flow tools ship enabled; they are disabled only when FLOW_TOOLS_ENABLED is explicitly set to false (any other value — or unset — leaves them on). This mirrors the existing ADMIN_TOOLS_ENABLED gating pattern, with the default inverted since these tools ship on.
• One switch, whole group. Implemented via config.flowToolsEnabled and each tool's disabled provider (disabled: !config.flowToolsEnabled), so server.web.ts filters both list-flows and get-flow out of the manifest at registration time. Any future flow tool gated the same way is covered automatically.
• Operators can still disable individual flow tools with EXCLUDE_TOOLS (e.g. EXCLUDE_TOOLS=flow drops the whole flow group); FLOW_TOOLS_ENABLED=false is the one-switch shortcut.
• Documented in env-vars.md and registered in the Claude MCP bundle manifest.

Shared parser fix

parseAndValidateFilterString previously split filter strings on every comma, shredding multi-element :in: lists like name:in:[A,B] into broken sub-expressions. Live verification on REST 3.30 confirmed every list-* tool that advertises :in: was silently broken on multi-element lists. Replaced the naive split with a bracket-aware top-level split (repo-wide fix).

Descriptions: leaner & version-agnostic

Trimmed the tool descriptions (~−23%) for token budget (some clients cap the whole toolset ~5k tokens) and to follow the repo convention that descriptions stay version-agnostic (runtime gating handles version compatibility): de-duplicated repeated filter contracts, collapsed the run-history section, merged the sizing sections, trimmed examples, and removed >= 3.10 / REST 3.30 references from the descriptions.

Tests & docs

• Unit tests for both tools and the parser fix, covering filter field/operator validation and rejection, pagination + the mcp.resultInfo truncation signaling, the ownerName/projectId recovery hints, every get-flow sidecar combination, bounded-context allow/deny (isFlowAllowed), the FLOW_RUNS_TRUNCATED "+1 probe" cases, and bracket-aware :in: parsing. Full unit suite green.
• Kill-switch coverage for FLOW_TOOLS_ENABLED: config parsing (default-on, false disables, any non-false value stays on), per-tool disabled gating on both list-flows and get-flow, and end-to-end server-registration tests driving the real registerTools() pipeline — both flow tools drop from the manifest when FLOW_TOOLS_ENABLED=false while unrelated tools (e.g. list-datasources) remain registered.
• Description-quality eval (tests/eval/flows.test.ts, site-data-independent) guarding tool selection + argument generation, so the trimmed descriptions still steer the model correctly.
• Manual end-to-end validation against a live Tableau Cloud site: filtering across each supported field/operator, sort direction, limit/pagination truncation + totalAvailable, get-flow sidecar combinations, live run-history truncation, recovery hints, and error paths (invalid filter, unknown flow id).
• User docs under docs/docs/tools/flows/ with sizing guidance, filter semantics (case sensitivity, whitespace, ISO 8601 Z requirement), the recovery-hints contract, and a "Required Tableau API scopes" section per tool (flows use the dedicated tableau:flows:read scope). Documented FLOW_TOOLS_ENABLED in env-vars.md (default, false-to-disable semantics, and the EXCLUDE_TOOLS=flow alternative).

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Related Issues

Closes #373

Checklist

• I have updated the version in the package.json file by using npm run version. For example,
  use npm run version:patch for a patch version bump.
• I have made any necessary changes to the documentation
• 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
• I have documented any breaking changes in the PR description. For example, renaming a config
  environment variable or changing its default value.

Contributor Agreement

By submitting this pull request, I confirm that:

• I have read the CONTRIBUTING guidelines for this project and followed
  its Contribution Checklist.

[mattcfilbert]

@showmethecold — 🤖 MattGPT (Matt Filbert's agent)

Onboards Tableau Prep flows with two read-only tools (list-flows, get-flow), and lands a few things beyond the headline feature. CI is green on both Node versions; tests, eval, and live Cloud validation are included.

Highest-signal points for reviewers:

• Repo-wide parser fix — the :in: fix in parseAndValidateFilterString isn't scoped to flows. Live verification showed every existing list-* tool advertising :in: was shredding multi-element lists on commas. Worth calling out in the changelog independently of the flows work.
• Bounded-context enforcement (FlowNotAllowedError / isFlowAllowed) closes a real scoping gap where get-flow ignored PROJECT_IDS / TAGS allow-lists — matches the get-workbook pattern.
• New auth scopes (tableau:mcp:flow:read + API scopes) — worth a focused look that the scope surface is minimal and consistent with existing read tools.

One open decision: list-flows is currently the only list-* tool with the explicit mcp.resultInfo truncation/completeness contract. The reasoning is sound — the question for the team is whether to standardize it across the other list-* tools now or defer to a follow-on.

[ccrick-tableau]

Thank you! These work great in my local testing. Appreciate adding these.

[jarhun88]

ideally we should utilize the defined scopes from scopes.ts, instead of defining them. maybe we could have the getflow scopes var as the minimum instead of maximum scopes, and then add these other scopes as variables also from scopes.ts? i dont like the magic scope values floating around here

[showmethecold]

Pulled all four scope values into named constants in scopes.ts:

GET_FLOW_BASE_API_SCOPES (the always-required minimum: flows:read + mcp_site_settings:read)
GET_FLOW_CONNECTIONS_API_SCOPE and GET_FLOW_RUNS_API_SCOPE for the optional sidecars
getFlow.ts now starts from the base (minimum) set and conditionally appends the connections/runs scopes only when the caller opts into those sidecars — all imported from scopes.ts. And toolScopeMap['get-flow'] (the max set for the OAuth gate) is composed from those same constants, so it's a single source of truth for both the per-call minimum and the maximum surface.