mozdata-claude-plugin

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Mozdata Plugin for Claude Code

> **⚠️ This repository has moved.** The plugin is now maintained in Mozilla's official internal plugin repository: [mozilla/internal-aidev-plugins](https://github.com/mozilla/internal-aidev-plugins/tree/main/plugins/mozdata). Please install from there to receive updates.

A Claude Code plugin for working with Mozilla's data platform: telemetry probe discovery, BigQuery query writing, and Airflow DAG failure debugging.

## Installation

```bash
claude plugin marketplace add akkomar/mozdata-claude-plugin
claude plugin install mozdata@akomar-mozdata-marketplace
```

## Usage

### Just ask (skills auto-activate)

The plugin includes skills that Claude automatically invokes when relevant — no commands needed. Just ask questions naturally:

```
How do I find probes for accessibility in Firefox Desktop?
Write a query for Firefox Android DAU by country
Why did the bqetl_main_summary DAG fail last night?
Run Airflow triage for today
Who is on Airflow triage this week?
```

The right skill activates based on your question:
- Probe/metric questions → probe-discovery skill
- Query/table questions → query-writing skill
- Airflow failures → airflow-debugging skill
- Daily Airflow triage summaries → airflow-triage skill
- Airflow triage rotation → airflow-triage-assignment skill

### /mozdata:ask (explicit, loads all context)

For questions that span multiple areas (e.g., "find me the DAU metric and write a query for it"), use the slash command to load all knowledge modules at once:

```
/mozdata:ask How do I query Firefox Desktop DAU?
/mozdata:ask Find probes related to accessibility and write a query
```

## Optional Setup

The plugin works out of the box with the bundled Glean Dictionary MCP server. The following optional setup unlocks additional capabilities.

### Auto-approve plugin file reads

The plugin's skills reference knowledge files that Claude reads on demand. Depending on your permission settings, you may be prompted to approve each read. To auto-approve, add this permission rule:

```
/permissions
→ Add a new rule
→ Read(~/.claude/plugins/cache/akomar-mozdata-marketplace/mozdata/**)
```

The airflow-debugging skill requires `gcloud` authentication and access to `gs://airflow-remote-logs-prod-prod`. It only activates when relevant.

### DataHub MCP (BigQuery schema access)

Enables Claude to query BigQuery table schemas and column details via DataHub.

1. Get a Personal Access Token from https://mozilla.acryl.io/settings/tokens

2. Configure the MCP server (replace `YOUR_TOKEN`):
   ```bash
   claude mcp add --transport http --scope user dataHub "https://mozilla.acryl.io/integrations/ai/mcp/?token=YOUR_TOKEN"
   ```

3. Verify:
   ```bash
   claude mcp list
   # Should show: dataHub (...) (HTTP) - ✓ Connected
   ```

Note: DataHub can't be bundled directly in the plugin's `.mcp.json` due to a [Claude Code bug](https://github.com/anthropics/claude-code/issues/9427) with remote MCP servers that require tokens.

### BigQuery MCP (direct query execution)

Claude can execute BigQuery queries via `bq` CLI without any additional setup. This MCP server, built on Google's [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox), adds controlled access: writes are restricted to `mozdata.analysis` and `mozdata.tmp` datasets only. This makes it safe to auto-approve BigQuery tool calls, which is especially useful for users with write permissions to derived datasets. Write restrictions are enforced via [`allowedDatasets` config](https://github.com/akkomar/mozdata-claude-plugin/blob/HEAD/bigquery/tools.yaml).

1. Authenticate with Google Cloud:
   ```bash
   gcloud auth login YOUR_EMAIL@mozilla.com --update-adc
   ```

2. Install MCP Toolbox (macOS Apple Silicon):
   ```bash
   mkdir -p ~/.local/bin/genai-toolbox
   curl -L -o ~/.local/bin/genai-toolbox/toolbox \
     https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/arm64/toolbox
   chmod +x ~/.local/bin/genai-toolbox/toolbox
   ```
   For other platforms, download from the [releases page](https://storage.googleapis.com/genai-toolbox/v0.28.0/).

3. Configure the MCP server:
   ```bash
   claude mcp add --scope user bigquery -- ~/.local/bin/genai-toolbox/toolbox --tools-file ~/.claude/plugins/marketplaces/akomar-mozdata-marketplace/bigquery/tools.yaml --stdio
   ```

4. Verify:
   ```bash
   claude mcp list
   # Should show: bigquery (...) - ✓ Connected
   ```

### Atlassian MCP (Confluence and Jira access)

Enables Claude to search Mozilla's Confluence for metric definitions, runbooks, and team documentation.

```bash
claude mcp add --transport sse --scope user atlassian https://mcp.atlassian.com/v1/sse
```

You'll be prompted to authenticate via browser on first use.

## Example

```
> /mozdata:ask how to find most common device that Fenix runs on in Japan?

⏺ I'll help you find the most common device that Fenix (Firefox Android) runs on
  in Japan. Let me explore what device-related metrics are available.

⏺ dataHub - search (MCP)(query: "fenix baseline", ...)
  ⎿  { "count": 5, "total": 195, … }

⏺ dataHub - get_entity (MCP)(urn: "urn:li:dataset:(...mozdata.fenix.baseline_clients_daily...)")
  ⎿  { "urn": "...", … }

⏺ Best table to use: mozdata.fenix.baseline_clients_daily

  This table contains device information at the client-day level:
  - device_manufacturer (e.g., Samsung, Google, Xiaomi)
  - device_model (e.g., SM-G991B, Pixel 6)
  - country (use 'JP' for Japan)

  SELECT
    device_manufacturer,
    device_model,
    COUNT(DISTINCT client_id) AS unique_clients,
    ROUND(COUNT(DISTINCT client_id) * 100.0 /
      SUM(COUNT(DISTINCT client_id)) OVER (), 2) AS pct_of_clients
  FROM mozdata.fenix.baseline_clients_daily
  WHERE submission_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
    AND country = 'JP'
    AND device_model IS NOT NULL
  GROUP BY device_manufacturer, device_model
  ORDER BY unique_clients DESC
  LIMIT 20
```

## How it works

The plugin provides Claude with Mozilla-specific data platform knowledge through a set of knowledge modules:
- Data platform architecture (BigQuery structure, Glean schema, cross-product gotchas)
- Metric/probe discovery (Glean Dictionary, ProbeInfo API, naming conventions)
- Table selection (aggregation hierarchy, deprecated tables, DataHub discovery)
- Query patterns (required filters, templates, anti-patterns, mozfun UDFs)
- External sources (Confluence routing, UDF discovery, app/channel discovery)

Skills and the `/mozdata:ask` command reference these modules. The modules also teach Claude to look things up at runtime via Confluence, DataHub, Glean Dictionary, and BigQuery's INFORMATION_SCHEMA.

## Keeping the Plugin Updated

### Enable Auto-Updates (Recommended)

Third-party marketplaces have auto-update disabled by default:

1. Run `/plugin` to open the plugin manager
2. Select the Marketplaces tab
3. Choose `akomar-mozdata-marketplace`
4. Select Enable auto-update

### Manual Updates

```bash
claude plugin update mozdata@akomar-mozdata-marketplace
```

## License

MPL-2.0

Mozdata Plugin for Claude Code

⚠️ This repository has moved. The plugin is now maintained in Mozilla's official internal plugin repository: mozilla/internal-aidev-plugins. Please install from there to receive updates.

A Claude Code plugin for working with Mozilla's data platform: telemetry probe discovery, BigQuery query writing, and Airflow DAG failure debugging.

Installation

claude plugin marketplace add akkomar/mozdata-claude-plugin
claude plugin install mozdata@akomar-mozdata-marketplace

Usage

Just ask (skills auto-activate)

The plugin includes skills that Claude automatically invokes when relevant — no commands needed. Just ask questions naturally:

How do I find probes for accessibility in Firefox Desktop?
Write a query for Firefox Android DAU by country
Why did the bqetl_main_summary DAG fail last night?
Run Airflow triage for today
Who is on Airflow triage this week?

The right skill activates based on your question:

Probe/metric questions → probe-discovery skill
Query/table questions → query-writing skill
Airflow failures → airflow-debugging skill
Daily Airflow triage summaries → airflow-triage skill
Airflow triage rotation → airflow-triage-assignment skill

/mozdata:ask (explicit, loads all context)

For questions that span multiple areas (e.g., "find me the DAU metric and write a query for it"), use the slash command to load all knowledge modules at once:

/mozdata:ask How do I query Firefox Desktop DAU?
/mozdata:ask Find probes related to accessibility and write a query

Optional Setup

The plugin works out of the box with the bundled Glean Dictionary MCP server. The following optional setup unlocks additional capabilities.

Auto-approve plugin file reads

The plugin's skills reference knowledge files that Claude reads on demand. Depending on your permission settings, you may be prompted to approve each read. To auto-approve, add this permission rule:

/permissions
→ Add a new rule
→ Read(~/.claude/plugins/cache/akomar-mozdata-marketplace/mozdata/**)

The airflow-debugging skill requires gcloud authentication and access to gs://airflow-remote-logs-prod-prod. It only activates when relevant.

DataHub MCP (BigQuery schema access)

Enables Claude to query BigQuery table schemas and column details via DataHub.

Get a Personal Access Token from https://mozilla.acryl.io/settings/tokens

Configure the MCP server (replace YOUR_TOKEN):

claude mcp add --transport http --scope user dataHub "https://mozilla.acryl.io/integrations/ai/mcp/?token=YOUR_TOKEN"

Verify:

claude mcp list
# Should show: dataHub (...) (HTTP) - ✓ Connected

Note: DataHub can't be bundled directly in the plugin's .mcp.json due to a Claude Code bug with remote MCP servers that require tokens.

BigQuery MCP (direct query execution)

Claude can execute BigQuery queries via bq CLI without any additional setup. This MCP server, built on Google's MCP Toolbox for Databases, adds controlled access: writes are restricted to mozdata.analysis and mozdata.tmp datasets only. This makes it safe to auto-approve BigQuery tool calls, which is especially useful for users with write permissions to derived datasets. Write restrictions are enforced via allowedDatasets config.

Authenticate with Google Cloud:

gcloud auth login YOUR_EMAIL@mozilla.com --update-adc

Install MCP Toolbox (macOS Apple Silicon):

mkdir -p ~/.local/bin/genai-toolbox
curl -L -o ~/.local/bin/genai-toolbox/toolbox \
  https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/arm64/toolbox
chmod +x ~/.local/bin/genai-toolbox/toolbox

For other platforms, download from the releases page.

Configure the MCP server:

claude mcp add --scope user bigquery -- ~/.local/bin/genai-toolbox/toolbox --tools-file ~/.claude/plugins/marketplaces/akomar-mozdata-marketplace/bigquery/tools.yaml --stdio

Verify:

claude mcp list
# Should show: bigquery (...) - ✓ Connected

Atlassian MCP (Confluence and Jira access)

Enables Claude to search Mozilla's Confluence for metric definitions, runbooks, and team documentation.

claude mcp add --transport sse --scope user atlassian https://mcp.atlassian.com/v1/sse

You'll be prompted to authenticate via browser on first use.

Example

> /mozdata:ask how to find most common device that Fenix runs on in Japan?

⏺ I'll help you find the most common device that Fenix (Firefox Android) runs on
  in Japan. Let me explore what device-related metrics are available.

⏺ dataHub - search (MCP)(query: "fenix baseline", ...)
  ⎿  { "count": 5, "total": 195, … }

⏺ dataHub - get_entity (MCP)(urn: "urn:li:dataset:(...mozdata.fenix.baseline_clients_daily...)")
  ⎿  { "urn": "...", … }

⏺ Best table to use: mozdata.fenix.baseline_clients_daily

  This table contains device information at the client-day level:
  - device_manufacturer (e.g., Samsung, Google, Xiaomi)
  - device_model (e.g., SM-G991B, Pixel 6)
  - country (use 'JP' for Japan)

  SELECT
    device_manufacturer,
    device_model,
    COUNT(DISTINCT client_id) AS unique_clients,
    ROUND(COUNT(DISTINCT client_id) * 100.0 /
      SUM(COUNT(DISTINCT client_id)) OVER (), 2) AS pct_of_clients
  FROM mozdata.fenix.baseline_clients_daily
  WHERE submission_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
    AND country = 'JP'
    AND device_model IS NOT NULL
  GROUP BY device_manufacturer, device_model
  ORDER BY unique_clients DESC
  LIMIT 20

How it works

The plugin provides Claude with Mozilla-specific data platform knowledge through a set of knowledge modules:

Data platform architecture (BigQuery structure, Glean schema, cross-product gotchas)
Metric/probe discovery (Glean Dictionary, ProbeInfo API, naming conventions)
Table selection (aggregation hierarchy, deprecated tables, DataHub discovery)
Query patterns (required filters, templates, anti-patterns, mozfun UDFs)
External sources (Confluence routing, UDF discovery, app/channel discovery)

Skills and the /mozdata:ask command reference these modules. The modules also teach Claude to look things up at runtime via Confluence, DataHub, Glean Dictionary, and BigQuery's INFORMATION_SCHEMA.

Keeping the Plugin Updated

Enable Auto-Updates (Recommended)

Third-party marketplaces have auto-update disabled by default:

Run /plugin to open the plugin manager
Select the Marketplaces tab
Choose akomar-mozdata-marketplace
Select Enable auto-update

Manual Updates

claude plugin update mozdata@akomar-mozdata-marketplace

License

MPL-2.0