googleapis / googleapis/gcloud-mcp
feat(observability-mcp): add smart metric discovery tool (fuzzy search)
- 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
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