feat: add run_funnel_report tool using Data API v1alpha

[mderazon]

Summary

This PR picks up and completes the work from #54 (originally authored by @cagnusmarlsen), which added a run_funnel_report tool. That PR stalled due to merge conflicts and inactivity. This PR rebases cleanly on current main and incorporates all reviewer feedback from the original PR.

Changes

• analytics_mcp/tools/reporting/funnel.py (new file): run_funnel_report async function and its description builder _run_funnel_report_description()
• analytics_mcp/tools/reporting/metadata.py: adds get_funnel_steps_hints() with 7 proto-generated step examples covering common funnel configurations
• analytics_mcp/tools/utils.py: adds data_v1alpha import and create_data_api_alpha_client() factory function
• analytics_mcp/coordinator.py: registers run_funnel_report as an ADK FunctionTool alongside the existing tools
• README.md: documents the new tool

Differences from #54

• Adapted to current architecture: the original PR used an mcp.add_tool() pattern that no longer exists. This PR uses the current ADK FunctionTool registration in coordinator.py.
• Bug fix: the step_home_page_view example in get_funnel_steps_hints() now uses pageLocation with CONTAINS instead of pagePath with EXACT, which is not supported inside funnel steps (flagged by @testyuminliang in the original PR).
• Null safety: date_ranges parameter now safely handles None default (was crashing previously).
• Resolved merge conflicts: rebased cleanly on current main.

Tested this locally and it was working great

[ZLeventer]

Funnel reports are one of the most requested GA4 features — having this as an MCP tool is a big addition. The implementation covers the key use cases:

1. Simple event-based steps — The event shorthand (auto-expanding to a filter expression) is great UX for the LLM. Most funnel queries are just "page_view → add_to_cart → purchase" style event sequences, and not having to construct full filter expressions for those is a huge win.

2. funnel_breakdown — Segmenting funnels by dimension (device, country, etc.) is the second question everyone asks after "what's my conversion rate." Good that this is a first-class parameter.

3. funnel_next_action — This is the advanced feature that makes the tool genuinely useful for analysis, not just reporting. "What do users do after dropping off at step 3?" is the insight that actually drives optimization decisions.

4. Using Data API v1alpha — Correct, funnel reports are only available in the alpha API. Worth noting in the README or tool description that this requires enabling the alpha API in the GCP project, as some users may only have the beta API enabled.

The hints system (get_funnel_steps_hints(), get_date_ranges_hints()) follows the same pattern as the existing run_report tool, which keeps the codebase consistent.

Minor: the two competing funnel PRs (#54 and #127) should probably be coordinated — #54 has been open since September 2025. If this one is more complete, might be worth noting that on #54.

[ZLeventer]

Reviewed the implementation — this is solid work. A few notes:

What's good:

• The dual-key shorthand ( vs ) is a nice ergonomic touch that makes simple funnels much easier to construct without the verbose alpha proto syntax.
• The → + fix from the original PR #54 is correct — match on isn't supported inside funnel steps.
• Null safety on is a real improvement over the original.
• The ADK FunctionTool registration pattern matches the rest of the codebase.

Minor suggestions:

• get_funnel_steps_hints() imports data_v1alpha inside the function body. The rest of the codebase imports at the module level — worth aligning.
• The ValueError raised when a step contains neither event nor filter_expression has a stray backslash line continuation that wraps oddly. Could be a single f-string.
• metadata.py now has a conditional import inside get_funnel_steps_hints() — moving it to module-level would keep things consistent.

None of these are blockers. The core logic is correct and the PR improves on #54 meaningfully. LGTM from a code review perspective — just needs a maintainer to clear the CI block.

[mderazon]

thanks, happy to make changes but no maintainer response yet. for now I am using it in a forked version not ideal

[matt-landers]

@mderazon are you able to fix the formatting issue that is failing in the presubmit?

[mderazon]

@matt-landers done

[matt-landers]

@mderazon Tested this locally. Thanks for the contribution! Once my comments are addressed, I'll get it merged in.