@belvador/mcp 0.7.2 → 0.8.0

package/dist/cli.js

@@ -214,7 +214,7 @@ function docsFetcher(siteUrl, fetcher = fetch, now = () => Date.now()) {
 import { CLIENT_CAPABILITIES_META_KEY, inputRequired, McpServer } from "@modelcontextprotocol/server";
 
 // ../src/shared/contracts/mcp-tools.ts
-import { z as z33 } from "zod";
+import { z as z34 } from "zod";
 
 // ../src/shared/contracts/api-ops/access.ts
 import { z as z3 } from "zod";
@@ -2056,6 +2056,7 @@ var INCIDENT_OPERATIONS = [
     input: I.workspace,
     workspace: true,
     idempotency: "none",
+    paged: true,
     mcp: "investigate",
     summary: "Rules that turn alerts into incidents: match, grouping, window and recovery wait.",
     ui: []
@@ -2101,6 +2102,7 @@ var INCIDENT_OPERATIONS = [
     input: I.workspace,
     workspace: true,
     idempotency: "none",
+    paged: true,
     mcp: "investigate",
     summary: "Notification policies: quiet hours, digest, fallback chain and escalation.",
     ui: []
@@ -4014,7 +4016,7 @@ var NODE_OPERATIONS = [
     path: "/v1/spans",
     scope: "traces:read",
     input: N.spansList,
-    node: { path: "q/spans", list: "spans", window: true },
+    node: { path: "q/spans", list: "spans", modeLists: ["traces"], window: true },
     paged: true,
     summary: "Spans (or whole traces with `mode=traces`) in a window of at most 7 days."
   }),
@@ -5185,6 +5187,9 @@ function approvalRequestSchema(operationId, input) {
   return input.omit(Object.fromEntries(human.map((k) => [k, true])));
 }
 
+// ../src/shared/contracts/api-ops/openapi.ts
+import { z as z33 } from "zod";
+
 // ../src/shared/contracts/api-ops/wire.ts
 import { z as z32 } from "zod";
 var toSnake = (s) => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
@@ -5407,7 +5412,7 @@ function wireInput(operationId, opts = {}) {
   for (const [k, v] of Object.entries(op.input.shape))
     if (!omit.has(k))
       shape[toSnake(k)] = v;
-  return z33.object(shape);
+  return z34.object(shape);
 }
 var BUDGETS = [
   { stringBytes: MCP_LIMITS.untrustedStringMaxBytes, listMax: MCP_LIMITS.listMax },
@@ -5500,52 +5505,52 @@ function errorResult(o) {
     }
   };
 }
-var TOOL_OUTPUT_SCHEMA = z33.object({
-  untrusted: z33.object({
-    data: z33.unknown(),
-    provenance: z33.object({
-      source: z33.enum(["node", "control_plane", "docs"]),
-      operations: z33.array(z33.string())
+var TOOL_OUTPUT_SCHEMA = z34.object({
+  untrusted: z34.object({
+    data: z34.unknown(),
+    provenance: z34.object({
+      source: z34.enum(["node", "control_plane", "docs"]),
+      operations: z34.array(z34.string())
     })
   }).optional(),
-  doc: z33.object({
-    slug: z33.string(),
-    locale: z33.enum(["en", "vi"]),
-    url: z33.string(),
-    markdown: z33.string(),
-    truncated: z33.boolean()
+  doc: z34.object({
+    slug: z34.string(),
+    locale: z34.enum(["en", "vi"]),
+    url: z34.string(),
+    markdown: z34.string(),
+    truncated: z34.boolean()
   }).optional(),
-  results: z33.array(z33.object({
-    slug: z33.string(),
-    title: z33.string(),
-    description: z33.string(),
-    section: z33.string(),
-    url: z33.string()
+  results: z34.array(z34.object({
+    slug: z34.string(),
+    title: z34.string(),
+    description: z34.string(),
+    section: z34.string(),
+    url: z34.string()
   })).optional(),
-  next_cursor: z33.string().nullable().optional(),
-  complete: z33.boolean().optional(),
-  omitted: z33.array(z33.object({ part: z33.string(), reason: z33.string(), scope: z33.string().optional() })).optional(),
-  truncated: z33.literal(true).optional(),
-  suspicious_unicode: z33.literal(true).optional(),
-  error: z33.object({
-    code: z33.string(),
-    status: z33.number(),
-    detail: z33.string().optional(),
-    scope: z33.string().optional(),
-    retry_after: z33.number().optional()
+  next_cursor: z34.string().nullable().optional(),
+  complete: z34.boolean().optional(),
+  omitted: z34.array(z34.object({ part: z34.string(), reason: z34.string(), scope: z34.string().optional() })).optional(),
+  truncated: z34.literal(true).optional(),
+  suspicious_unicode: z34.literal(true).optional(),
+  error: z34.object({
+    code: z34.string(),
+    status: z34.number(),
+    detail: z34.string().optional(),
+    scope: z34.string().optional(),
+    retry_after: z34.number().optional()
   }).optional(),
-  operations: z33.array(z33.record(z33.string(), z33.unknown())).optional(),
-  operation: z33.record(z33.string(), z33.unknown()).optional(),
-  plan: z33.record(z33.string(), z33.unknown()).optional(),
-  status: z33.enum(["done", "approval_required", "approval_pending", ...APPROVAL_STATES]).optional(),
-  approval: z33.object({
-    approval_id: z33.string(),
-    approval_url: z33.string(),
-    expires_at: z33.string(),
-    state: z33.enum(APPROVAL_STATES),
-    result_code: z33.string().nullable().optional(),
-    result: z33.record(z33.string(), z33.unknown()).optional(),
-    next: z33.string().optional()
+  operations: z34.array(z34.record(z34.string(), z34.unknown())).optional(),
+  operation: z34.record(z34.string(), z34.unknown()).optional(),
+  plan: z34.record(z34.string(), z34.unknown()).optional(),
+  status: z34.enum(["done", "approval_required", "approval_pending", ...APPROVAL_STATES]).optional(),
+  approval: z34.object({
+    approval_id: z34.string(),
+    approval_url: z34.string(),
+    expires_at: z34.string(),
+    state: z34.enum(APPROVAL_STATES),
+    result_code: z34.string().nullable().optional(),
+    result: z34.record(z34.string(), z34.unknown()).optional(),
+    next: z34.string().optional()
   }).optional()
 });
 var spec = (name) => {
@@ -5591,10 +5596,10 @@ var has = (rt, operationId) => {
   return !!op && rt.scopes.includes(op.scope);
 };
 var isoWindow = {
-  start: z33.string().max(40).describe("RFC 3339 start of the window, e.g. 2026-10-26T00:00:00Z. Required with end."),
-  end: z33.string().max(40).describe("RFC 3339 end of the window. The plan limits its length.")
+  start: z34.string().max(40).describe("RFC 3339 start of the window, e.g. 2026-10-26T00:00:00Z. Required with end."),
+  end: z34.string().max(40).describe("RFC 3339 end of the window. The plan limits its length.")
 };
-var traceIdSchema = z33.string().regex(/^[0-9a-fA-F]{32}$/);
+var traceIdSchema = z34.string().regex(/^[0-9a-fA-F]{32}$/);
 var MONITOR_KINDS2 = {
   cron: { list: "monitors.list", get: "monitors.get", idField: "monitor_id" },
   uptime: { list: "uptime.list", get: "uptime.get", idField: "check_id" },
@@ -5658,8 +5663,8 @@ function describe(op, scopes) {
     destructive: isDestructiveOperation(op)
   };
 }
-var params = z33.record(z33.string(), z33.unknown()).default({}).describe("Operation fields in wire names (snake_case), as describe_operation's args_schema shows.");
-var operationIdArg = z33.string().min(3).max(80).describe("An operation id from search_operations, e.g. `monitors.update`.");
+var params = z34.record(z34.string(), z34.unknown()).default({}).describe("Operation fields in wire names (snake_case), as describe_operation's args_schema shows.");
+var operationIdArg = z34.string().min(3).max(80).describe("An operation id from search_operations, e.g. `monitors.update`.");
 function approvalBlock(t, next) {
   return {
     approval_id: t.approval_id,
@@ -5679,7 +5684,7 @@ var MCP_TOOL_DEFS = [
     title: "Workspace and node",
     description: "The workspace this token belongs to (name, plan, limits) and the state of its node, the server that stores errors, traces and logs. Start here to learn what the token can reach.",
     operations: ["workspace.get", "node.get"],
-    input: z33.object({}),
+    input: z34.object({}),
     async run(_args, rt) {
       const [ws, node] = await Promise.all([rt.call("workspace.get", {}), rt.call("node.get", {})]);
       if (!ws.ok)
@@ -5701,9 +5706,9 @@ var MCP_TOOL_DEFS = [
     title: "Get an issue",
     description: "One issue with its 24 h and 30 d counts and, when the token can read events, its latest event (stack trace, request, breadcrumbs — scrubbed on the node). A resolved issue also carries `fix_status` when the token can read releases: fixed, unverified, not_fixed (with the event that broke it) or unknown, per environment.",
     operations: ["issues.get", "events.get", "issues.fix_status"],
-    input: z33.object({
-      issue_id: z33.number().int().positive().describe("Issue id from search_issues."),
-      include_latest_event: z33.boolean().default(true)
+    input: z34.object({
+      issue_id: z34.number().int().positive().describe("Issue id from search_issues."),
+      include_latest_event: z34.boolean().default(true)
     }),
     async run(args, rt) {
       const omitted = [];
@@ -5744,9 +5749,9 @@ var MCP_TOOL_DEFS = [
     title: "Get a trace",
     description: "Summary of one distributed trace (services, duration, errors) by its 32-hex trace id, and optionally its spans (errors only, or the first page).",
     operations: ["traces.get", "traces.spans"],
-    input: z33.object({
+    input: z34.object({
       trace_id: traceIdSchema.describe("W3C trace id, 32 hex characters."),
-      spans: z33.enum(["none", "errors", "all"]).default("none")
+      spans: z34.enum(["none", "errors", "all"]).default("none")
     }),
     async run(args, rt) {
       const sum = await rt.call("traces.get", { trace_id: args["trace_id"] });
@@ -5778,17 +5783,17 @@ var MCP_TOOL_DEFS = [
     title: "Query metrics",
     description: "OpenTelemetry metrics of one project. Without `name`: the metric catalog (name, type, unit, series count, last seen; `q` narrows by name) and the node's series caps. With `name` plus start and end: the metric aggregated per step — `aggregation` defaults to rate for counters, p95 for histograms and avg for gauges — optionally filtered by attributes (`attrs`, JSON list of {k, op, v}) and grouped by up to two attribute keys (`group_by`, comma-separated). Exemplar trace ids open with get_trace.",
     operations: ["metrics.names", "metrics.query"],
-    input: z33.object({
-      project: z33.number().int().positive().describe("Numeric project id from list_projects."),
-      name: z33.string().regex(METRIC_NAME_RE).optional().describe("Metric name from the catalog, e.g. http.server.request.duration."),
-      q: z33.string().max(255).optional().describe("Catalog only: part of a metric name."),
-      aggregation: z33.enum(METRIC_AGGREGATIONS).optional(),
+    input: z34.object({
+      project: z34.number().int().positive().describe("Numeric project id from list_projects."),
+      name: z34.string().regex(METRIC_NAME_RE).optional().describe("Metric name from the catalog, e.g. http.server.request.duration."),
+      q: z34.string().max(255).optional().describe("Catalog only: part of a metric name."),
+      aggregation: z34.enum(METRIC_AGGREGATIONS).optional(),
       start: isoWindow.start.optional(),
       end: isoWindow.end.optional(),
-      step: z33.number().int().min(60).max(86400).multipleOf(60).optional().describe("Seconds per point (whole minutes); picked from the window when absent."),
-      attrs: z33.string().max(2000).optional(),
-      group_by: z33.string().max(600).optional(),
-      environment: z33.string().max(2000).optional().describe("Comma-separated environments.")
+      step: z34.number().int().min(60).max(86400).multipleOf(60).optional().describe("Seconds per point (whole minutes); picked from the window when absent."),
+      attrs: z34.string().max(2000).optional(),
+      group_by: z34.string().max(600).optional(),
+      environment: z34.string().max(2000).optional().describe("Comma-separated environments.")
     }),
     async run(args, rt) {
       const scope = {
@@ -5843,8 +5848,8 @@ var MCP_TOOL_DEFS = [
     title: "Release health",
     description: "What changed with a release (spec 13). With `version`: that release in one environment against the previous one (or `compare`) — three lists for its first 24 hours: new issues, regressed issues and increased issues (≥ 2× events per hour and ≥ 10 events), up to 50 each with hourly sparklines, plus its deploy markers. Without `version`: the project's releases, newest deploy first, with those three counts. `environment` defaults to production (else the busiest). Whether a resolved issue is really fixed: get_issue returns its fix status.",
     operations: ["releases.list", "releases.health"],
-    input: z33.object({
-      project: z33.number().int().positive().describe("Numeric project id from list_projects."),
+    input: z34.object({
+      project: z34.number().int().positive().describe("Numeric project id from list_projects."),
       version: releaseNameSchema.optional().describe("Release name exactly as the SDK sends it, e.g. web@1.4.2."),
       environment: environmentNameSchema.optional().describe("One environment, e.g. production."),
       compare: releaseNameSchema.optional().describe("With version: compare against this release instead of the previous one.")
@@ -5876,11 +5881,11 @@ var MCP_TOOL_DEFS = [
     title: "Correlate by trace or run",
     description: "Everything that shares one W3C trace id or one Belvador run id (`belvador.run.id`, set by job monitors) in a time window: the trace summary, its error spans and the logs. Give exactly one of trace_id or run_id.",
     operations: ["traces.get", "traces.spans", "spans.list", "logs.list"],
-    input: z33.object({
+    input: z34.object({
       trace_id: traceIdSchema.optional(),
-      run_id: z33.string().min(1).max(128).optional(),
+      run_id: z34.string().min(1).max(128).optional(),
       ...isoWindow,
-      project: z33.string().max(2000).optional().describe("Comma-separated project ids.")
+      project: z34.string().max(2000).optional().describe("Comma-separated project ids.")
     }),
     async run(args, rt) {
       const trace = args["trace_id"];
@@ -5939,10 +5944,10 @@ var MCP_TOOL_DEFS = [
     title: "List monitors",
     description: "Monitors (cron, heartbeat, count, assertion, deadline, progress), uptime checks and SLOs with their current status. `kind` narrows to one family; `project_id` to one project (cron and uptime).",
     operations: ["monitors.list", "uptime.list", "slos.list"],
-    input: z33.object({
-      kind: z33.enum(["all", "cron", "uptime", "slo"]).default("all"),
-      project_id: z33.number().int().positive().optional(),
-      limit: z33.number().int().min(1).max(200).default(50)
+    input: z34.object({
+      kind: z34.enum(["all", "cron", "uptime", "slo"]).default("all"),
+      project_id: z34.number().int().positive().optional(),
+      limit: z34.number().int().min(1).max(200).default(50)
     }),
     async run(args, rt) {
       const kinds = args["kind"] && args["kind"] !== "all" ? [args["kind"]] : ["cron", "uptime", "slo"];
@@ -5977,10 +5982,10 @@ var MCP_TOOL_DEFS = [
       "monitors.occurrences",
       "monitors.backtest"
     ],
-    input: z33.object({
-      kind: z33.enum(["cron", "uptime", "slo"]),
-      id: z33.guid(),
-      backtest: z33.boolean().default(false)
+    input: z34.object({
+      kind: z34.enum(["cron", "uptime", "slo"]),
+      id: z34.guid(),
+      backtest: z34.boolean().default(false)
     }),
     async run(args, rt) {
       const k = MONITOR_KINDS2[args["kind"]];
@@ -6040,9 +6045,9 @@ var MCP_TOOL_DEFS = [
     title: "Send a test event",
     description: "Asks the node to send one tagged test error through the public intake of a project, proving the path real errors take. Not read-only: it creates one test event (reuse idempotency_key to retry without a second one).",
     operations: ["projects.send_test_event"],
-    input: z33.object({
-      project_id: z33.number().int().positive(),
-      idempotency_key: z33.string().min(8).max(255).optional()
+    input: z34.object({
+      project_id: z34.number().int().positive(),
+      idempotency_key: z34.string().min(8).max(255).optional()
     }),
     async run(args, rt) {
       const r = await rt.call("projects.send_test_event", { project_id: args["project_id"] }, { idempotencyKey: args["idempotency_key"] ?? rt.newKey() });
@@ -6060,9 +6065,9 @@ var MCP_TOOL_DEFS = [
     title: "Find a configuration change",
     description: "Searches what this token can change in its Belvador workspace: projects, keys and tokens, monitors of every type, maintenance windows, occurrences, uptime checks, SLOs, alert rules and destinations, members, service accounts and the node. Returns operation ids for describe_operation and plan_change, whether a person must approve the change, and whether this token holds the scope.",
     operations: [],
-    input: z33.object({
-      query: z33.string().min(1).max(200).describe("Words such as `rotate dsn key`, `heartbeat monitor`, `slack alert`."),
-      limit: z33.number().int().min(1).max(20).default(10)
+    input: z34.object({
+      query: z34.string().min(1).max(200).describe("Words such as `rotate dsn key`, `heartbeat monitor`, `slack alert`."),
+      limit: z34.number().int().min(1).max(20).default(10)
     }),
     async run(args, rt) {
       const q = words(String(args["query"]));
@@ -6090,7 +6095,7 @@ var MCP_TOOL_DEFS = [
     title: "Describe a configuration change",
     description: "Everything needed to call one operation: its fields (JSON Schema, wire names), the scope, whether it needs If-Match (call plan_change for the current ETag), an idempotency key, or a person's approval, and which fields the approving person types on belvador.dev instead of the agent.",
     operations: [],
-    input: z33.object({ operation_id: operationIdArg }),
+    input: z34.object({ operation_id: operationIdArg }),
     async run(args, rt) {
       const op = configureOp(args["operation_id"]);
       if (!op || op.method === "GET")
@@ -6119,7 +6124,7 @@ var MCP_TOOL_DEFS = [
     title: "Check a change before applying it",
     description: "Validates params for one operation without changing anything: field errors, missing scope, whether a person must approve, and — when the resource can be read — its current state, the fields that would change and the ETag to pass as if_match.",
     operations: [],
-    input: z33.object({ operation_id: operationIdArg, params }),
+    input: z34.object({ operation_id: operationIdArg, params }),
     async run(args, rt) {
       const op = configureOp(args["operation_id"]);
       if (!op || op.method === "GET")
@@ -6168,11 +6173,11 @@ var MCP_TOOL_DEFS = [
     title: "Apply a configuration change",
     description: "Runs one operation with params (validate first with plan_change). Always send idempotency_key: repeating a call with the same key never applies it twice. Sensitive operations answer approval_required with an approval_url a person opens on belvador.dev; nothing changes until they approve with their authenticator code.",
     operations: [],
-    input: z33.object({
+    input: z34.object({
       operation_id: operationIdArg,
       params,
-      idempotency_key: z33.string().min(8).max(255).describe("Unique per change; reuse it to retry or to fetch the result."),
-      if_match: z33.string().max(200).optional().describe("ETag from plan_change, for operations that need it.")
+      idempotency_key: z34.string().min(8).max(255).describe("Unique per change; reuse it to retry or to fetch the result."),
+      if_match: z34.string().max(200).optional().describe("ETag from plan_change, for operations that need it.")
     }),
     async run(args, rt) {
       const op = configureOp(args["operation_id"]);
@@ -6233,7 +6238,7 @@ var MCP_TOOL_DEFS = [
     title: "Follow an approval",
     description: "State of a change waiting for a person's approval: pending, approved, executed (with the ids it produced), rejected, expired or failed (with the error code).",
     operations: ["approvals.get"],
-    input: z33.object({ approval_id: z33.guid().describe("approval_id from apply_change.") }),
+    input: z34.object({ approval_id: z34.guid().describe("approval_id from apply_change.") }),
     async run(args, rt) {
       const r = await rt.call("approvals.get", { approval_id: args["approval_id"] });
       if (!r.ok)
@@ -6253,10 +6258,10 @@ var MCP_TOOL_DEFS = [
     title: "Search Belvador docs",
     description: "Searches the public Belvador documentation (titles and summaries) and returns the best pages with their slugs for get_doc.",
     operations: [],
-    input: z33.object({
-      query: z33.string().min(1).max(200),
-      locale: z33.enum(["en", "vi"]).default("en"),
-      limit: z33.number().int().min(1).max(10).default(5)
+    input: z34.object({
+      query: z34.string().min(1).max(200),
+      locale: z34.enum(["en", "vi"]).default("en"),
+      limit: z34.number().int().min(1).max(10).default(5)
     }),
     async run(args, rt) {
       const locale = args["locale"] ?? "en";
@@ -6272,9 +6277,9 @@ var MCP_TOOL_DEFS = [
     title: "Read a docs page",
     description: "The Markdown of one public Belvador docs page by slug (e.g. `quickstart`, `sdk/react`, `reference/api`).",
     operations: [],
-    input: z33.object({
-      slug: z33.string().regex(/^[a-z0-9][a-z0-9/-]{0,120}$/),
-      locale: z33.enum(["en", "vi"]).default("en")
+    input: z34.object({
+      slug: z34.string().regex(/^[a-z0-9][a-z0-9/-]{0,120}$/),
+      locale: z34.enum(["en", "vi"]).default("en")
     }),
     async run(args, rt) {
       const locale = args["locale"] ?? "en";
@@ -6468,7 +6473,7 @@ function findToken(env = process.env, keychain = keychainToken) {
 }
 
 // packages/mcp/src/cli.ts
-var PACKAGE_VERSION = "0.7.2";
+var PACKAGE_VERSION = "0.8.0";
 var HELP = `belvador-mcp ${PACKAGE_VERSION} — Belvador MCP server (stdio)
 
 Usage: npx -y @belvador/mcp [--toolsets=${MCP_DEFAULT_TOOLSETS.join(",")}]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/mcp",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Belvador MCP server over stdio: the same read-only tools as api.belvador.dev/mcp (issues, events, traces, logs, monitors, docs), with node data read straight from the edge.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",
@@ -30,7 +30,7 @@
     "node": ">=20.10"
   },
   "dependencies": {
-    "@belvador/api": "0.7.2",
+    "@belvador/api": "0.8.0",
     "@modelcontextprotocol/server": "2.4.0",
     "zod": "4.6.7"
   },