Agent skill

usage-report

Generate a usage report for MCP Gateway Registry by SSHing into the telemetry bastion host, exporting telemetry data from DocumentDB, and producing a formatted markdown report with deployment insights.

View SKILL.md on GitHub Repository
Stars 576
Forks 133

Install this agent skill to your Project

npx add-skill https://github.com/agentic-community/mcp-gateway-registry/tree/main/.claude/skills/usage-report

Metadata

Additional technical details for this skill

author
mcp-gateway-registry
version
1.0

SKILL.md

Usage Report Skill

Export telemetry data from the MCP Gateway Registry's DocumentDB telemetry collector and generate a usage report showing deployment patterns, version adoption, and feature usage in the wild.

Prerequisites

  1. SSH key at ~/.ssh/id_ed25519 with access to the bastion host
  2. Terraform state available in terraform/telemetry-collector/ (to read bastion IP)
  3. Bastion host enabled (bastion_enabled = true in terraform/telemetry-collector/terraform.tfvars)
  4. AWS credentials configured on the bastion host (for Secrets Manager access)

Input

The skill accepts optional parameters:

/usage-report [OUTPUT_DIR]
  • OUTPUT_DIR - Directory to save the report (default: .scratchpad/usage-reports/)

If OUTPUT_DIR is not provided, save to .scratchpad/usage-reports/.

Workflow

Step 1: Get Bastion IP

bash
cd terraform/telemetry-collector && terraform output -raw bastion_public_ip

If the output is "Bastion not enabled", tell the user to set bastion_enabled = true in terraform/telemetry-collector/terraform.tfvars and run terraform apply.

Step 2: Copy Export Script to Bastion

bash
scp -o StrictHostKeyChecking=no -i ~/.ssh/id_ed25519 \
  terraform/telemetry-collector/bastion-scripts/telemetry_db.py \
  ec2-user@$BASTION_IP:~/telemetry_db.py

Step 3: Run Export on Bastion

bash
ssh -o StrictHostKeyChecking=no -i ~/.ssh/id_ed25519 \
  ec2-user@$BASTION_IP \
  'python3 telemetry_db.py export --output /tmp/registry_metrics.csv 2>&1'

Capture the full output -- it contains the summary statistics printed by telemetry_db.py.

Step 4: Download the CSV

bash
scp -o StrictHostKeyChecking=no -i ~/.ssh/id_ed25519 \
  ec2-user@$BASTION_IP:/tmp/registry_metrics.csv \
  OUTPUT_DIR/registry_metrics.csv

Step 5: Install Python Dependencies and Generate Charts

First, ensure matplotlib and seaborn are available on the system Python:

bash
/usr/bin/python3 -c "import matplotlib, seaborn" 2>/dev/null || pip install --break-system-packages matplotlib seaborn

Then generate the deployment distribution chart:

bash
/usr/bin/python3 .claude/skills/usage-report/generate_charts.py \
  --csv OUTPUT_DIR/registry_metrics.csv \
  --output OUTPUT_DIR/deployment-distribution-YYYY-MM-DD.png

This produces a single faceted PNG with 6 subplots: Cloud Provider, Compute Platform, Storage Backend, Auth Provider, Version Type, and Deployment Mode. Each subplot shows counts and percentages.

Step 5b: Generate Timeseries Chart

Generate a timeseries chart showing unique registry installs per cloud provider over time. This reads ALL CSV files in the output directory to build a complete historical view:

bash
/usr/bin/python3 .claude/skills/usage-report/generate_timeseries_chart.py \
  --csv-dir OUTPUT_DIR \
  --output OUTPUT_DIR/registry-installs-timeseries-YYYY-MM-DD.png

This produces a PNG with two subplots:

  • Cumulative Unique Registry Installs -- running total of unique registry_ids per cloud provider
  • Daily Active Registry Installs -- unique registry_ids seen each day per cloud provider

Step 5c: Generate Instance Lifetime Chart

Generate a density plot showing the distribution of instance lifetimes (age in days). This reads the metrics JSON produced by the analysis step, so it must run after Step 6. However, the SKILL.md lists it here for logical grouping with other charts:

bash
/usr/bin/python3 .claude/skills/usage-report/generate_lifetime_chart.py \
  --metrics OUTPUT_DIR/metrics-YYYY-MM-DD.json \
  --output OUTPUT_DIR/instance-lifetime-YYYY-MM-DD.png

This produces a PNG with two panels:

  • Age Distribution -- histogram with KDE density overlay showing instance ages in days, with stats annotation (mean, max, multi-day vs single-day counts)
  • Age Buckets -- horizontal bar chart grouping instances into age ranges (0 days, 1-2 days, 3-5 days, etc.) with counts and percentages

Note: Run this after Step 6 (telemetry analysis) since it reads the metrics JSON.

Step 6: Run Telemetry Analysis

Run the analysis script to compute all distributions, instance timelines, and metrics. This produces two files:

  • tables-YYYY-MM-DD.md -- pre-formatted markdown tables ready to embed in the report (with executive summary comparison at the top)
  • metrics-YYYY-MM-DD.json -- raw computed metrics as JSON (includes per_cloud_unique_installs)

The script automatically finds the most recent previous metrics-*.json file in the output directory and generates an executive summary with deltas at the top of the tables file. You can also specify a previous metrics file explicitly:

bash
/usr/bin/python3 .claude/skills/usage-report/analyze_telemetry.py \
  --csv OUTPUT_DIR/registry_metrics.csv \
  --output-dir OUTPUT_DIR \
  --date YYYY-MM-DD

Or with an explicit previous metrics file:

bash
/usr/bin/python3 .claude/skills/usage-report/analyze_telemetry.py \
  --csv OUTPUT_DIR/registry_metrics.csv \
  --output-dir OUTPUT_DIR \
  --date YYYY-MM-DD \
  --previous-metrics OUTPUT_DIR/metrics-PREVIOUS-DATE.json

Step 7: Generate the Usage Report

Read the generated tables-YYYY-MM-DD.md and include its tables directly in the report. Add narrative sections (Executive Summary, Architecture Patterns, Recommendations) around the data tables. The tables file contains:

  • Key Metrics table
  • Registry Instance Lifetime table (age in days, sorted descending)
  • Identified and Unidentified instance tables
  • Cloud, Compute, Architecture, Storage, Auth distribution tables
  • Version Adoption table
  • Feature Adoption table
  • Search Usage table
  • Per-instance daily timelines (with servers, agents, skills, search queries)

Report Structure

markdown
# AI Registry -- Usage Report

*Report Date: YYYY-MM-DD*
*Data Source: Telemetry Collector (DocumentDB)*
*Collection Period: [earliest ts] to [latest ts]*

---

## Executive Summary

Lead with the number of new registry installs since the last report (if available), then total unique installs since tracking began, dominant cloud/compute/IdP, average daily install rate, and notable growth trends. Follow immediately with the timeseries chart.

![Registry Installs Timeseries](registry-installs-timeseries-YYYY-MM-DD.png)

### Comparison with Previous Report
- Deltas for total events, unique instances, heartbeat events, null registry_id count
- Per-cloud-provider unique registry installs comparison table

## Deployment Distribution

![Deployment Distribution](deployment-distribution-YYYY-MM-DD.png)

## Key Metrics
| Metric | Value |
|--------|-------|
| Total Events | N |
| Unique Registry Instances | N |
| ... | ... |

## Registry Instance Lifetime
Commentary on average/max lifetime, how many are multi-day vs single-day.
Density chart showing age distribution (histogram + KDE) and age buckets.
Table sorted by age (days) descending showing each instance with cloud, compute, auth, first seen, last seen, age in days, and event count.

## Deployment Landscape

### Registry Instances
Table of unique registry_id values with their cloud, compute, storage, auth, federation status.

### Cloud Provider Distribution
Count and percentage of each cloud value (aws, azure, gcp, unknown).

### Compute Platform Distribution
Count and percentage of each compute value (docker, ecs, kubernetes, etc).

### Storage Backend Distribution
Count and percentage of each storage value (mongodb-ce, documentdb, etc).

### Auth Provider Distribution
Count and percentage of each auth value (auth0, keycloak, entra, cognito, none).

## Version Adoption

### By Events
Table of version strings with event counts and percentages. Note which are release vs dev/branch versions.

### By Unique Registry Instances
Table of version strings with unique registry instance counts. Shows how many distinct deployments run each version (an instance is counted under the latest version it reported).

### Last Seen Version per Registry Instance
Table showing each registry_id with its cloud, compute, last reported version, and last seen date. Sorted by last seen date descending. Useful for tracking which instances are on old versions.

## Feature Adoption
- Federation enabled rate
- with-gateway vs registry-only mode
- Heartbeat opt-in rate

## Search Usage
- Total queries, average per instance, max from single instance

## Architecture Patterns Observed
Identify 3-5 distinct deployment patterns from the data (e.g., "Dev Setup", "AWS Production", "Azure Enterprise").

## Recommendations
3-5 actionable insights based on the data.

Save the report to OUTPUT_DIR/ai-registry-usage-report-YYYY-MM-DD.md.

Step 8: Generate Self-Contained HTML

Convert the markdown report to a single self-contained HTML file using pandoc. The chart PNG is base64-embedded so the HTML works standalone. Run from the OUTPUT_DIR so relative image paths resolve:

bash
cd OUTPUT_DIR && pandoc ai-registry-usage-report-YYYY-MM-DD.md \
  -o ai-registry-usage-report-YYYY-MM-DD.html \
  --embed-resources --standalone \
  --css=.claude/skills/usage-report/report-style.css \
  --metadata title="AI Registry - Usage Report YYYY-MM-DD"

The report-style.css file in the skill directory provides a clean, professional layout. Pandoc must be installed:

bash
which pandoc >/dev/null || sudo apt-get install -y pandoc

Step 9: Present Results

After generating the report:

  1. Display the Executive Summary (with comparison deltas) and Key Metrics directly in the conversation
  2. Tell the user the full report path, HTML path, CSV path, and chart paths
  3. Highlight the most interesting findings and notable changes from the previous report

Error Handling

  • SSH connection fails: Check that the bastion IP is correct and security group allows your IP. The allowed CIDRs are in terraform/telemetry-collector/terraform.tfvars under bastion_allowed_cidrs.
  • Export returns 0 documents: The telemetry collector may not have received any events yet. Check that telemetry_enabled is true in registry settings and the collector endpoint is reachable.
  • Terraform output fails: Make sure you're in the right directory and have run terraform init.

Example Usage

User: /usage-report

Output:

Executive Summary: 68 startup events from ~7 unique registry instances over 4 days...
Compared to previous report (2026-03-30): +12 events (+21%), +2 new instances (+40%)

Full report: .scratchpad/usage-reports/ai-registry-usage-report-2026-03-31.md
HTML report: .scratchpad/usage-reports/ai-registry-usage-report-2026-03-31.html
Charts:
  - .scratchpad/usage-reports/deployment-distribution-2026-03-31.png
  - .scratchpad/usage-reports/registry-installs-timeseries-2026-03-31.png
CSV data: .scratchpad/usage-reports/registry_metrics.csv

User: /usage-report /tmp/reports

Output saved to /tmp/reports/.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

agentic-community/mcp-gateway-registry

agentcore-register

Given an MCP server URL, probe the server via curl to discover its metadata and tools, then generate a markdown file with copy-pasteable content for each field in the Amazon Bedrock AgentCore "Create record" form.

576 133
Explore
agentic-community/mcp-gateway-registry

macos-setup

Complete macOS setup and teardown for MCP Gateway & Registry (AI-registry). Clones the repository, installs all services, configures Keycloak auth, registers the Cloudflare docs server, and verifies the full stack. Also supports complete teardown. Can be run directly from its GitHub URL without the repository already cloned. Uses an interactive or default-values mode chosen at startup.

576 133
Explore
agentic-community/mcp-gateway-registry

generate-server-card

Generate an MCP server card JSON (mcp-gateway-registry format) by analyzing server source code in a folder or GitHub URL. Studies code to detect server name, tools, transport, auth, and generates a registry-compatible config.

576 133
Explore
agentic-community/mcp-gateway-registry

generate-agent-card

Generate an A2A agent card JSON by analyzing agent source code in a folder or GitHub URL. Studies the code to detect agent name, skills, tools, auth, protocol, and generates a spec-compliant agent card.

576 133
Explore
agentic-community/mcp-gateway-registry

pr-review

Review a GitHub pull request using multiple expert personas. Takes a PR URL as input, analyzes the changes, and generates comprehensive review feedback from different perspectives (Merge Specialist, Frontend, Backend, Security, DevOps, AI/Agent, SRE, Chief Architect).

576 133
Explore
agentic-community/mcp-gateway-registry

create-milestone

Create a GitHub milestone for an upcoming release. Suggests the next version based on the latest release, gathers all merged PRs and closed issues since that release, presents a draft with two tables (Issues and PRs) for user approval, then creates the milestone and assigns all approved items.

576 133
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results