@yawlabs/aws-mcp 1.0.1 → 1.1.0

package/README.md

@@ -84,6 +84,7 @@ The rest -- SSO device-code re-login, CCAPI CRUD with dry-run diffs, multi-regio
 | `aws_call` | Run any AWS API operation. `service: 's3api', operation: 'list-buckets'`, optional `params` (PascalCase JSON), optional `query` (JMESPath). Returns parsed JSON. |
 | `aws_paginate` | Fetch one page of a paginated list/describe operation. Supports `query` too. Returns `nextToken`/`hasMore`; call again with the token to continue. |
 | `aws_logs_tail` | Fetch recent CloudWatch Logs events for a log group. Wraps `aws logs tail --format json` with `since`, `filterPattern`, and stream-name filters; returns events as a parsed array. |
+| `aws_metrics_query` | Query CloudWatch metrics via GetMetricData (the modern multi-metric / expression-capable API). Pass `queries: [{id, namespace, metricName, dimensions?, statistic?, period?}]` or expression-based queries; `startTime`/`endTime` accept ISO 8601 or relative shorthand (`'15m'`, `'1h'`, `'1d'`). Period auto-picks from the time range. Returns `{series, periodSeconds, messages?}`. |
 | `aws_resource_get` | Read an AWS resource via Cloud Control API by `typeName` + `identifier` (e.g. `AWS::Lambda::Function` + function name). Returns parsed Properties. |
 | `aws_resource_list` | List resources of a type via CCAPI, paginated. Returns `{identifier, properties}` per entry plus a `nextToken`/`hasMore`. |
 | `aws_resource_create` | Create an AWS resource via CCAPI. Async — returns top-level `requestToken` + `operationStatus`. Pass `awaitCompletion: true` to have the server poll to terminal state in one call. |
@@ -247,16 +248,16 @@ From 1.0 onward this package follows [Semantic Versioning](https://semver.org/sp
 
 **Stable in 1.x (anything below is a breaking change requiring a major bump):**
 
-- **Tool names** -- the 24 tool names listed in the Tools table above will not be renamed or removed.
+- **Tool names** -- the 25 tool names listed in the Tools table above will not be renamed or removed.
 - **Tool annotations** -- `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. These signal to MCP hosts how to gate calls; flipping them silently would break host UIs.
 - **Required input fields** -- the required fields per tool will not change shape or be removed. New *optional* fields may be added.
 - **Success envelope shape per tool** -- the `data` object on `{ok: true, data}` responses, specifically:
   - `aws_call` -> `{command, result}`
   - `aws_paginate` -> `{command, result, nextToken, hasMore}`
   - `aws_multi_region` -> `{service, operation, regionCount, okCount, errorCount, results: [{region, ok, data?, command?, error?, errorKind?}]}`
-  - `aws_whoami` -> `{account, userId, arn, profile, region, ssoToken: {expiresAt, minutesLeft, startUrl} | null}`
+  - `aws_whoami` -> `{account, userId, arn, profile, region, ssoToken: {expiresAt, minutesLeft, startUrl?} | null}` (`startUrl` is omitted when the cached token didn't record one)
   - `aws_login_start` -> `{sessionId, profile, verificationUrl, userCode, instructions, reused?}` (`reused: true` when re-surfacing an in-flight login for the same profile)
-  - `aws_login_complete` -> `{loggedIn, account, userId, arn, profile, region, ssoToken}` (same `ssoToken` shape as `aws_whoami`)
+  - `aws_login_complete` -> `{loggedIn, account, userId, arn, profile, region, ssoToken}` (same `ssoToken` shape as `aws_whoami`, including the optional `startUrl`)
   - `aws_refresh_if_expiring_soon` -> **one of two shapes by branch:** `{status: "ok", minutesLeft, expiresAt, profile}` when the cached token has more than `thresholdMinutes` left, or `{status: "refreshing", reason, sessionId, profile, verificationUrl, userCode, reused?, instructions}` when a refresh is in flight. Discriminate on `status`.
   - `aws_assume_role` -> `{profile, credentialsPath, expiration, assumedRoleArn, assumedRoleId, sourceProfile, hint}`
   - `aws_list_profiles` -> `{configPath, profiles: [{name, region?, ssoStartUrl?, ssoRegion?, ssoSession?, isSso}]}`
@@ -266,9 +267,10 @@ From 1.0 onward this package follows [Semantic Versioning](https://semver.org/sp
   - `aws_resource_create` / `_update` / `_delete` / `_status` -> flat-promoted `{command, requestToken, operationStatus, identifier, errorCode, statusMessage, retryAfter, progressEvent}` plus an `awaited: {attempts, elapsedMs}` block when `awaitCompletion: true` was passed
   - `aws_resource_diff` -> `{command, typeName, identifier, before, after, changes, changeCount}`
   - `aws_logs_tail` -> `{command, logGroupName, since, eventCount, events}`
+  - `aws_metrics_query` -> `{command, startTime, endTime, periodSeconds, series: [{id, label?, timestamps, values, statusCode?}], messages?: [{code?, value?}]}` (`messages` is omitted when empty; per-series `label` / `statusCode` are present when CloudWatch returns them)
   - `aws_iam_simulate` -> `{command, principalArn, summary: {allowed, denied, total}, results, evaluationResults}`
   - `aws_script` -> `{result, logs, truncatedLogs, durationMs}` where `result` is whatever the script `return`ed (any JSON-serializable value, including `undefined`)
-  - `aws_docs_search` -> `{query, count, results: [{title, url, summary, excerpt}]}`
+  - `aws_docs_search` -> `{query, count, results: [{title, url, summary?, excerpt?}]}` (`summary` / `excerpt` are present only when the upstream search backend returns them)
   - `aws_docs_read` -> `{url, cached, content, startIndex, endIndex, totalLength, hasMore, nextStartIndex}`
 - **Error envelope** -- `{ok: false, error: string, rawBody?: string}`. The `error` string is human-readable; its *wording* is best-effort (see below).
 - **`errorKind` enum on `aws_multi_region`** -- `"sso_expired" | "no_creds" | "bad_input" | "spawn_failure" | "timeout" | "output_too_large" | "nonzero_exit"`. New variants may be added (additive); existing ones won't be renamed or repurposed.

package/dist/index.js

@@ -55448,6 +55448,225 @@ var logsTools = [
   }
 ];
 
+// src/tools/metrics.ts
+var SIMPLE_STATS = ["Average", "Sum", "Maximum", "Minimum", "SampleCount"];
+var EXTENDED_STAT_RE = /^(p|tm|tc|wm|pr|ts|iqm)(\d{1,3}(\.\d{1,3})?)?$/i;
+function isValidStatistic(s) {
+  if (SIMPLE_STATS.includes(s)) return true;
+  return EXTENDED_STAT_RE.test(s);
+}
+var QUERY_ID_RE = /^[a-z][A-Za-z0-9_]*$/;
+var MAX_QUERIES = 100;
+var PERIOD_3H_MS = 3 * 60 * 60 * 1e3;
+var PERIOD_24H_MS = 24 * 60 * 60 * 1e3;
+var PERIOD_15D_MS = 15 * 24 * 60 * 60 * 1e3;
+function pickAutoPeriodSeconds(startMs, endMs) {
+  const rangeMs = Math.max(0, endMs - startMs);
+  if (rangeMs <= PERIOD_3H_MS) return 60;
+  if (rangeMs <= PERIOD_24H_MS) return 300;
+  if (rangeMs <= PERIOD_15D_MS) return 900;
+  return 3600;
+}
+var RELATIVE_TIME_RE = /^\d+[smhdw]$/;
+var UNIT_MS = {
+  s: 1e3,
+  m: 60 * 1e3,
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3,
+  w: 7 * 24 * 60 * 60 * 1e3
+};
+function resolveTime(input, now) {
+  if (input === "now") return new Date(now);
+  const rel = input.match(RELATIVE_TIME_RE);
+  if (rel) {
+    const num = Number(input.slice(0, -1));
+    const unit = input.slice(-1);
+    const ms = UNIT_MS[unit];
+    if (!ms || !Number.isFinite(num)) return null;
+    return new Date(now - num * ms);
+  }
+  const t = new Date(input);
+  if (Number.isNaN(t.getTime())) return null;
+  return t;
+}
+function buildMetricDataQueries(inputs, autoPeriod) {
+  return inputs.map((q) => {
+    const base = { Id: q.id };
+    if (q.label !== void 0) base.Label = q.label;
+    if (q.returnData !== void 0) base.ReturnData = q.returnData;
+    if (q.expression !== void 0) {
+      base.Expression = q.expression;
+      if (q.period !== void 0) base.Period = q.period;
+      return base;
+    }
+    const dimensions = q.dimensions ? Object.entries(q.dimensions).map(([Name, Value]) => ({ Name, Value })) : void 0;
+    const stat = {
+      Metric: {
+        Namespace: q.namespace,
+        MetricName: q.metricName,
+        ...dimensions ? { Dimensions: dimensions } : {}
+      },
+      Period: q.period ?? autoPeriod,
+      Stat: q.statistic ?? "Average"
+    };
+    if (q.unit !== void 0) stat.Unit = q.unit;
+    base.MetricStat = stat;
+    return base;
+  });
+}
+var metricsTools = [
+  {
+    name: "aws_metrics_query",
+    description: "Query CloudWatch metrics via GetMetricData (the modern multi-metric / expression-capable API, not the legacy get-metric-statistics). Pass `queries` as a flat array of {id, namespace, metricName, dimensions?, statistic?, period?, expression?, label?}; the tool shapes them into MetricDataQueries for you. `startTime`/`endTime` accept ISO 8601 or relative shorthand ('15m', '1h', '1d', '1w'); endTime defaults to 'now'. Period is auto-picked from the time range when omitted (60s for <=3h, 300s for <=24h, 900s for <=15d, 3600s otherwise) to stay under CloudWatch's ~100,800-datapoint response cap. Returns {series: [{id, label?, timestamps, values, statusCode?}], messages?, periodSeconds}. Use for 'show me the CPU on this instance for the last hour', 'sum lambda invocations across these 3 functions', or expression-based 'p99 latency divided by average latency' lookups.",
+    annotations: {
+      title: "Query CloudWatch metrics (GetMetricData)",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      queries: external_exports3.array(
+        external_exports3.object({
+          id: external_exports3.string().regex(QUERY_ID_RE, "id must match /^[a-z][A-Za-z0-9_]*$/ (CloudWatch's MetricDataQuery.Id contract)"),
+          namespace: external_exports3.string().min(1).optional().describe("AWS metric namespace, e.g. 'AWS/Lambda', 'AWS/EC2'. Required unless `expression` is set."),
+          metricName: external_exports3.string().min(1).optional().describe("Metric name, e.g. 'Invocations', 'CPUUtilization'. Required unless `expression` is set."),
+          dimensions: external_exports3.record(external_exports3.string(), external_exports3.string()).optional().describe("Dimension Name -> Value map, e.g. {FunctionName: 'my-fn'}."),
+          statistic: external_exports3.string().optional().describe(
+            "Statistic: Average | Sum | Maximum | Minimum | SampleCount, or an extended stat like 'p99', 'p99.9', 'tm95'. Default 'Average'."
+          ),
+          period: external_exports3.number().int().positive().optional().describe("Period in seconds. Defaults to an auto-pick from the time range (60s/300s/900s/3600s)."),
+          expression: external_exports3.string().min(1).optional().describe(
+            `CloudWatch metric math expression, e.g. 'SUM([m1, m2])' or 'AVG(METRICS("AWS/Lambda"))'. Mutually exclusive with namespace/metricName/dimensions.`
+          ),
+          label: external_exports3.string().optional().describe("Human-readable label for the series in the response."),
+          returnData: external_exports3.boolean().optional().describe(
+            "Set false to compute this query but not return its data (useful for intermediate values in expressions). Default true."
+          ),
+          unit: external_exports3.string().optional().describe(
+            "Restrict to a specific Unit (e.g. 'Seconds', 'Bytes'). Default: no filter. Only meaningful on metric-stat queries."
+          )
+        })
+      ).min(1).max(MAX_QUERIES).describe(`1-${MAX_QUERIES} queries. Each is either a metric-stat (namespace + metricName) or an expression.`),
+      startTime: external_exports3.string().optional().describe("ISO 8601 timestamp or relative shorthand ('15m', '1h', '1d', '1w'). Default '1h' (one hour ago)."),
+      endTime: external_exports3.string().optional().describe("ISO 8601 timestamp or relative shorthand. Default 'now'."),
+      scanBy: external_exports3.enum(["TimestampAscending", "TimestampDescending"]).optional().describe("Sort order for returned datapoints. Default 'TimestampDescending' (matches CloudWatch's default)."),
+      maxDataPoints: external_exports3.number().int().positive().optional().describe(
+        "Soft cap on returned datapoints across all queries. CloudWatch's hard cap is ~100,800; lower this to keep response sizes manageable."
+      ),
+      profile: external_exports3.string().optional().describe("Override session profile for this call."),
+      region: external_exports3.string().optional().describe("Override session region for this call."),
+      timeoutMs: external_exports3.number().int().positive().optional().describe("Timeout in milliseconds. Default 60000 (60s).")
+    }),
+    handler: async (input) => {
+      const i = input;
+      const seenIds = /* @__PURE__ */ new Set();
+      for (const q of i.queries) {
+        if (seenIds.has(q.id)) {
+          return {
+            ok: false,
+            error: `Duplicate query id '${q.id}'. Each MetricDataQuery.Id must be unique in a batch.`
+          };
+        }
+        seenIds.add(q.id);
+        const hasMetricStat = q.namespace !== void 0 || q.metricName !== void 0 || q.dimensions !== void 0;
+        const hasExpression = q.expression !== void 0;
+        if (hasMetricStat && hasExpression) {
+          return {
+            ok: false,
+            error: `Query '${q.id}' mixes metric-stat fields (namespace/metricName/dimensions) with 'expression'. Pick one shape per query.`
+          };
+        }
+        if (!hasMetricStat && !hasExpression) {
+          return {
+            ok: false,
+            error: `Query '${q.id}' has neither metric-stat (namespace+metricName) nor 'expression'. One is required.`
+          };
+        }
+        if (hasMetricStat && (q.namespace === void 0 || q.metricName === void 0)) {
+          return {
+            ok: false,
+            error: `Query '${q.id}' must include BOTH 'namespace' and 'metricName' (or use 'expression' instead).`
+          };
+        }
+        if (q.statistic !== void 0 && !isValidStatistic(q.statistic)) {
+          return {
+            ok: false,
+            error: `Query '${q.id}' has invalid statistic '${q.statistic}'. Use Average | Sum | Maximum | Minimum | SampleCount, or an extended stat like p99 / p99.9 / tm95.`
+          };
+        }
+      }
+      const now = Date.now();
+      const startStr = i.startTime ?? "1h";
+      const endStr = i.endTime ?? "now";
+      const startDate = resolveTime(startStr, now);
+      const endDate = resolveTime(endStr, now);
+      if (!startDate) {
+        return {
+          ok: false,
+          error: `Invalid startTime '${startStr}'. Use ISO 8601 (e.g. '2026-05-16T10:00:00Z') or relative shorthand (e.g. '1h', '15m', '1d').`
+        };
+      }
+      if (!endDate) {
+        return {
+          ok: false,
+          error: `Invalid endTime '${endStr}'. Use ISO 8601 or relative shorthand, or 'now' for the current moment.`
+        };
+      }
+      if (endDate.getTime() <= startDate.getTime()) {
+        return {
+          ok: false,
+          error: `endTime (${endDate.toISOString()}) must be after startTime (${startDate.toISOString()}).`
+        };
+      }
+      const periodSeconds = pickAutoPeriodSeconds(startDate.getTime(), endDate.getTime());
+      const metricDataQueries = buildMetricDataQueries(i.queries, periodSeconds);
+      const params = {
+        MetricDataQueries: metricDataQueries,
+        StartTime: startDate.toISOString(),
+        EndTime: endDate.toISOString(),
+        ScanBy: i.scanBy ?? "TimestampDescending"
+      };
+      if (i.maxDataPoints !== void 0) params.MaxDatapoints = i.maxDataPoints;
+      const result = await runAwsCall({
+        service: "cloudwatch",
+        operation: "get-metric-data",
+        profile: i.profile,
+        region: i.region,
+        timeoutMs: i.timeoutMs,
+        outputFormat: "json",
+        params
+      });
+      if (!result.ok) {
+        return { ok: false, error: result.error, rawBody: result.rawStderr ?? result.rawStdout };
+      }
+      const raw = result.data ?? {};
+      const series = (raw.MetricDataResults ?? []).map((r) => ({
+        id: r.Id ?? "",
+        ...r.Label !== void 0 ? { label: r.Label } : {},
+        timestamps: r.Timestamps ?? [],
+        values: r.Values ?? [],
+        ...r.StatusCode !== void 0 ? { statusCode: r.StatusCode } : {}
+      }));
+      const messages = raw.Messages?.filter((m) => m.Code || m.Value).map((m) => ({
+        code: m.Code,
+        value: m.Value
+      }));
+      return {
+        ok: true,
+        data: {
+          command: result.command,
+          startTime: startDate.toISOString(),
+          endTime: endDate.toISOString(),
+          periodSeconds,
+          series,
+          ...messages && messages.length > 0 ? { messages } : {}
+        }
+      };
+    }
+  }
+];
+
 // src/tools/multi-region.ts
 var DEFAULT_CONCURRENCY = 8;
 var MAX_CONCURRENCY = 32;
@@ -56678,7 +56897,7 @@ var sessionTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "1.0.1" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "1.1.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
@@ -56692,6 +56911,7 @@ var allTools = [
   ...paginateTools,
   ...assumeTools,
   ...logsTools,
+  ...metricsTools,
   ...resourceTools,
   ...multiRegionTools,
   ...iamSimulateTools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/aws-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "mcpName": "io.github.YawLabs/aws-mcp",
   "description": "AWS MCP server — call any AWS API from AI assistants, with first-class SSO re-login (no more 'browser won't open' dead ends)",
   "license": "MIT",