googleapis / googleapis/gcloud-mcp

feat(observability-mcp): add smart metric discovery tool (fuzzy search)

Open
#351 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
904
Forks
83
PR merge metrics
No merged PRs in 30d

Description

### What is the feature or problem you’d like to solve?

I propose adding a new tool, `search_metric_descriptors`, to the `observability-mcp` package to improve how users and agents find the correct Google Cloud metrics.

Currently, the `listMetricDescriptors` tool relies on the official Monitoring API `filter` parameter. This API filter is strict and only supports `starts_with` or exact matches on the `metric.type` (the long path string). It **does not** support searching by human-readable keywords in the `description` or `display_name` fields.

### Why do you need this feature?

1. **Reduce Hallucinations**: LLMs often invent metric names that sound plausible but don't exist. A fuzzy search tool allows the agent to "look up" the real name before constructing a query.
2. **Bridge the Semantic Gap**: Users think in concepts ("CPU," "Memory," "Errors"), but the API requires specific schema paths. This tool connects natural language intents to technical schema names.
3. **Unlock Rich Metadata**: The API contains rich `description` text for every metric. This tool would allow the agent to search that text to find the most relevant metric for a specific debugging scenario.

### Example prompts, workflows, or additional information

**Example Workflows:**
1. **User**: "Find a metric for disk errors on my VM."
* **Agent**: Calls `search_metric_descriptors(query="disk error", service_prefix="compute")`.
* **Tool**: Fetches broad compute metrics -> Filters client-side for "disk" AND "error" in `description` -> Returns `compute.googleapis.com/guest/disk/operation_errors_count`.
2. **User**: "What metrics do you have for Redis memory?"
* **Agent**: Calls `search_metric_descriptors(query="memory", service_prefix="redis")`.
* **Tool**: Returns sorted list including `redis.googleapis.com/stats/memory/usage`.

**Implementation Plan:**
This tool should implement a "Smart Search" logic:
1. **Broad Fetch**: Use the API to fetch a set of descriptors (optionally filtered by a `service_prefix` like "compute" or "kubernetes" to reduce payload size).
2. **Client-Side Scoring**: iterate through the results and apply a fuzzy matching or scoring algorithm against the user's `query`.
* Weight matches in `display_name` higher than `description`.
* Return the top 10-20 most relevant results to the agent.

**References:**
* [MetricDescriptors.list API Documentation](https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors/list) (Note the limitations on the `filter` field).

Contributor guide

Open the contributing guide

Research direction

Start in the observability-mcp package by locating the existing listMetricDescriptors tool, then review the MetricDescriptors.list API documentation and its filter limitations. Add the proposed search_metric_descriptors entry point with optional service_prefix filtering and ranked results; done means it can find relevant descriptors from display names and descriptions and returns the top matches.

Written by the indexing model from the issue text.

Assessment

Tech stack
gcp, typescript
Domain
api, observability
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.