Fix MCP output schema validation across backup, replication, snapshot, and pool tools

[garyamannetapp]

Summary

Fixes MCP output validation when handlers return raw GCNV/protobuf values that do not match Zod output schemas (MCP SDK 1.29.0+).

Shared helpers: src/utils/proto-format-utils.ts

---

GEMINI CLI

Use local PR build (not npx gcnv-mcp-server@latest):

cd gcnv-mcp-server
npm run build
mkdir -p .gemini
cat > .gemini/settings.json <<'JSON'
{
  "mcpServers": {
    "gcnv-mcp": {
      "command": "node",
      "args": ["build/index.js", "--transport", "stdio"]
    }
  }
}
JSON

Then run (replace <tool> / prompt as shown per section):

gemini --skip-trust --approval-mode yolo -p "Call <tool> with <args> and show the JSON result"

---

backup (gcnv_backup_list)

NOT WORKING (main)

Command

gemini --skip-trust --approval-mode yolo -p "Call gcnv_backup_list with projectId my-gcp-project location us-central1 backupVaultId vault-1 pageSize 3"

IN

{
  "projectId": "my-gcp-project",
  "location": "us-central1",
  "backupVaultId": "vault-1",
  "pageSize": 3
}

GCNV API (handler receives)

{
  "backupId": "backup-1",
  "enforcedRetentionEndTime": { "seconds": "1791522585", "nanos": 0 }
}

OUT

{
  "isError": true,
  "error": "MCP error -32602: Output validation error: Expected number, received object at backups[0].enforcedRetentionEndTime"
}

WORKING (this PR)

Command — same as above (PR branch server in .gemini/settings.json)

OUT

{
  "isError": false,
  "backups": [
    {
      "backupId": "backup-1",
      "enforcedRetentionEndTime": "2026-10-09T05:09:45.000Z",
      "createTime": "2026-09-25T05:09:45.000Z",
      "state": "READY",
      "volumeUsagebytes": "0"
    }
  ]
}

---

snapshot (gcnv_snapshot_list)

NOT WORKING (main)

Command

gemini --skip-trust --approval-mode yolo -p "Call gcnv_snapshot_list with projectId my-gcp-project location us-central1 volumeId vol1 pageSize 2"

IN

{
  "projectId": "my-gcp-project",
  "location": "us-central1",
  "volumeId": "vol1",
  "pageSize": 2
}

GCNV API returns snapshot missing required schema fields (example: name only, no /volumes/{id}/ in path)

{
  "name": "projects/my-gcp-project/locations/us-central1/snapshots/s1"
}

Pre-fix handler output (sent to validator)

{
  "snapshots": [
    {
      "name": "projects/my-gcp-project/locations/us-central1/snapshots/s1",
      "snapshotId": "s1"
    }
  ]
}

OUT

{
  "isError": true,
  "error": "Output validation error: Required at snapshots[0].volumeId; Required at snapshots[0].state; Required at snapshots[0].createTime"
}

WORKING (this PR)

Command — same as above

GCNV API (example snapshot response)

{
  "name": "projects/my-gcp-project/locations/us-central1/volumes/vol1/snapshots/snapshot-1",
  "state": "READY",
  "createTime": { "seconds": "1790236454", "nanos": 0 }
}

Post-fix handler output

{
  "snapshots": [
    {
      "snapshotId": "snapshot-1",
      "volumeId": "vol1",
      "state": "READY",
      "createTime": "2026-09-24T07:54:14.000Z"
    }
  ]
}

OUT

{ "isError": false, "snapshots": [ { "volumeId": "vol1", "state": "READY", "createTime": "2026-09-24T07:54:14.000Z" } ] }

---

backup vault (gcnv_backup_vault_get)

NOT WORKING (main)

Command

gemini --skip-trust --approval-mode yolo -p "Call gcnv_backup_vault_get with projectId my-gcp-project location us-central1 backupVaultId vault-1"

IN

{
  "projectId": "my-gcp-project",
  "location": "us-central1",
  "backupVaultId": "vault-1"
}

GCNV API returns minimal vault (only name + protobuf createTime)

{
  "name": "projects/my-gcp-project/locations/us-central1/backupVaults/bv1",
  "createTime": { "seconds": "1", "nanos": 0 }
}

Pre-fix handler output

{
  "name": "projects/my-gcp-project/locations/us-central1/backupVaults/bv1",
  "backupVaultId": "bv1",
  "createTime": "1970-01-01T00:00:01.000Z"
}

OUT

{
  "isError": true,
  "error": "Output validation error: Required at state; Required at backupVaultType"
}

WORKING (this PR)

Command — same as above

OUT (example output)

{
  "isError": false,
  "name": "projects/my-gcp-project/locations/us-central1/backupVaults/vault-1",
  "backupVaultId": "vault-1",
  "state": "READY",
  "createTime": "2026-08-30T19:26:47.000Z",
  "backupVaultType": "IN_REGION",
  "backupRetentionPolicy": {
    "backupMinimumEnforcedRetentionDays": 14,
    "manualBackupImmutable": true
  }
}

---

quota (gcnv_quota_rule_list)

NOT WORKING (main)

Command

gemini --skip-trust --approval-mode yolo -p "Call gcnv_quota_rule_list with projectId my-gcp-project location us-central1 volumeId vol1 pageSize 3"

IN

{
  "projectId": "my-gcp-project",
  "location": "us-central1",
  "volumeId": "vol1",
  "pageSize": 3
}

GCNV API returns string enum for quota type

{
  "quotaRules": [
    {
      "name": "projects/p1/locations/us-central1/volumes/vol1/quotaRules/q1",
      "quotaRuleId": "q1",
      "type": "INDIVIDUAL_USER_QUOTA",
      "diskLimitMib": 1024
    }
  ]
}

Pre-fix handler output (copied as-is)

{
  "quotaRules": [
    {
      "quotaRuleId": "q1",
      "type": "INDIVIDUAL_USER_QUOTA",
      "quotaType": "INDIVIDUAL_USER_QUOTA"
    }
  ]
}

OUT

{
  "isError": true,
  "error": "Output validation error: Expected number, received string at quotaRules[0].type"
}

WORKING (this PR)

Post-fix handler output

{
  "quotaRules": [
    {
      "quotaRuleId": "q1",
      "type": 1,
      "quotaType": 1,
      "diskLimitMib": 1024
    }
  ]
}

OUT

{ "isError": false, "quotaRules": [ { "quotaRuleId": "q1", "type": 1, "quotaType": 1 } ] }

---

kms / replication / storage pool

Same format as above — see backup section pattern. Storage pool gcnv_storage_pool_list verified: { "qosType": "AUTO", "serviceLevel": "FLEX" }.

---

CURSOR

Point ~/.cursor/mcp.json at server binary:

• Pre-fix: path/to/gcnv-mcp-server/build/index.js (main)
• Post-fix: mcp/gcnv-mcp-server/build/index.js (this PR, after npm run build)

Restart MCP, then ask agent to call the tool (same IN JSON as Gemini sections).

---

snapshot (gcnv_snapshot_list)

NOT WORKING (main) — same IN/OUT as Gemini NOT WORKING above

WORKING (this PR)

IN

{ "projectId": "my-gcp-project", "location": "us-central1", "volumeId": "vol1", "pageSize": 2 }

OUT

{
  "snapshots": [
    {
      "snapshotId": "snapshot-1",
      "volumeId": "vol1",
      "state": "READY",
      "createTime": "2026-09-24T07:54:14.000Z"
    }
  ]
}

---

backup vault (gcnv_backup_vault_get)

NOT WORKING (main) — same IN/OUT as Gemini NOT WORKING above

WORKING (this PR) — example output

IN

{ "projectId": "my-gcp-project", "location": "us-central1", "backupVaultId": "vault-1" }

OUT

{
  "backupVaultId": "vault-1",
  "state": "READY",
  "createTime": "2026-08-30T19:26:47.000Z",
  "backupVaultType": "IN_REGION",
  "backupRetentionPolicy": { "backupMinimumEnforcedRetentionDays": 14 }
}

---

quota (gcnv_quota_rule_list)

NOT WORKING (main) — same IN/OUT as Gemini NOT WORKING above

WORKING (this PR) — same normalized numeric type / quotaType OUT as Gemini

---

backup / kms — example output

See Gemini sections; backup NOT WORKING and WORKING shown in examples above.

---

Tests

npm test — 727 passed

CI

Node 20 / Node 24 green

[Copilot]

Copilot review overview

🟡 Changes recommended

Preserve protobuf timestamp nanoseconds and add coverage for fractional seconds.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Preserve protobuf Timestamp nanos in retention deadlines · New

What changed in this PR

Fixes backup retention timestamp schema validation by returning enforcedRetentionEndTime as an ISO 8601 string.

Changes:

• Formats retention timestamps in backup handlers.
• Updates get/list output schemas from number to string.
• Adds handler and schema coverage.

File	Summary
src/​tools/​handlers/​backup-handler.ts	Formats retention timestamps
src/​tools/​handlers/​backup-handler.test.ts	Tests timestamp conversion
src/​tools/​backup-tools.ts	Updates output schemas
src/​tools/​backup-tools.test.ts	Validates schema acceptance

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[garyamannetapp]

Addressed Copilot review feedback in 5705462:

• Nanos preservation: formatProtobufTimestamp() now includes protobuf nanos when converting to ISO 8601 (e.g. { seconds: 1234567890, nanos: 500000000 } → 2009-02-13T23:31:30.500Z).
• MCP output schema test: added listBackupsHandler structuredContent passes MCP output schema validation to mirror the server-side validation path used by Gemini/Claude clients.
• CI: pinned fast-uri@3.1.8 to clear high-severity npm audit failures.
• Gemini CLI proof: added scripts/verify-gemini-mcp-backup-list.mjs — connects over stdio (same transport as gemini-extension.json) and confirms gcnv_backup_list advertises enforcedRetentionEndTime as string.

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved review issues remain.

Review effort: Lite
Findings: None

Resolved since last review (1)

• Preserve protobuf Timestamp nanos in retention deadlines

[Copilot]

Copilot review overview

🟡 Changes recommended

Resolve the int64 precision, invalid fallback resource, and lockfile consistency issues.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Converting int64 byte counts to number loses precision · New
• Missing volume fallback returns an invalid resource identifier · New

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical and moderate findings affect enum fidelity, numeric safety, schema validity, and resource-data correctness.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 3 · 1

Open (4)

• Normalize protobuf volumeCount to a number · New
• Numeric enums incorrectly converted to UNKNOWN · New
• Converting int64 byte counts to number loses precision
• Missing volume fallback returns an invalid resource identifier

[Copilot]

Copilot review overview

🔵 Needs a closer look

Moderate correctness issues remain in identifier fallbacks, enum and int64 normalization, and timestamp handling.

Review effort: Lite
Findings: 3 · 1

Open (4)

• Numeric enums incorrectly converted to UNKNOWN
• Normalize protobuf volumeCount to a number
• Converting int64 byte counts to number loses precision
• Missing volume fallback returns an invalid resource identifier

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved issues include fabricated resource identifiers, lossy int64 conversion, possible pool schema mismatches, and insufficient live-test assertions.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 3 · 2

Open (5)

• Numeric enums incorrectly converted to UNKNOWN
• Normalize protobuf volumeCount to a number
• Converting int64 byte counts to number loses precision
• Fail live verification when retention data is missing · New
• Missing volume fallback returns an invalid resource identifier

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved moderate findings affect data correctness, metadata fidelity, and safe live-test behavior.

Review effort: Lite
Findings: 3 · 1

Open (4)

• Numeric enums incorrectly converted to UNKNOWN
• Normalize protobuf volumeCount to a number
• Converting int64 byte counts to number loses precision
• Missing volume fallback returns an invalid resource identifier

Resolved since last review (1)

• Fail live verification when retention data is missing

Previously missed (1)

In code that hasn't changed since last review

Missing snapshot fields are replaced with fabricated values

src/​tools/​handlers/​snapshot-handler.ts:39

These fallbacks turn missing API fields into valid-looking values: unknown is not the source volume and an empty string is not a creation timestamp. Clients can therefore mistake an incomplete snapshot for a real resource with a valid time. Preserve the fields as absent (with optional schema fields) or return an error rather than fabricating them.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Moderate issues remain with lockfile synchronization, fabricated source-volume identifiers, enum preservation, and unsafe int64 conversion.

Review effort: Lite
Findings: 3 · 1

Open (4)

• Numeric enums incorrectly converted to UNKNOWN
• Normalize protobuf volumeCount to a number
• Converting int64 byte counts to number loses precision
• Missing volume fallback returns an invalid resource identifier

[Copilot]

Copilot review overview

🟡 Changes recommended

Sparse backup, quota, replication, and snapshot responses can still fail MCP output validation.

Review effort: Lite
Findings: 4 · 1

Open (5)

• Preserve backupId when formatting backup list items · New
• Return schema-valid quota data for sparse responses · New
• Handle missing replication identity in list responses · New
• Handle missing snapshot identity in list responses · New
• Avoid fabricating invalid volume names for unknown locations · New

Resolved since last review (5)

• Use int64 normalization for storage pool volumeCount
• Handle undefined snapshots before early return
• Apply replication defaults before undefined return
• Apply backup vault defaults before undefined return
• Normalize undefined backups before early return

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved sparse-item and all-location fallback cases can still produce invalid or schema-incomplete output.

Review effort: Lite
Findings: 3

Open (3)

• Avoid unknown location in quota resource identifiers · New
• Avoid unknown location in sparse replication resource names · New
• Do not synthesize resource names for unknown locations · New

Resolved since last review (5)

• Handle missing snapshot identity in list responses
• Handle missing replication identity in list responses
• Return schema-valid quota data for sparse responses
• Preserve backupId when formatting backup list items
• Avoid fabricating invalid volume names for unknown locations

[Copilot]

Copilot review overview

🔵 Needs a closer look

Six moderate findings remain around sparse-item identity fields and fabricated or non-canonical resource names.

Review effort: Lite
Findings: 3

Open (3)

• Do not synthesize resource names for unknown locations
• Avoid unknown location in sparse replication resource names
• Avoid unknown location in quota resource identifiers

Previously missed (2)

In code that hasn't changed since last review

Handle sparse list items with required identity fields

src/​tools/​handlers/​backup-handler.ts:61

The list formatter still cannot produce schema-required identity fields for an undefined/sparse item: list context has no backupId, so backupId remains absent and the !result.name branch never runs. The existing listBackupsHandler test exercises exactly [undefined] but does not validate its output against listBackupsTool; use a per-item fallback (or omit such items) so name and backupId are present before MCP validation.

Validate snapshot names before preserving them

src/​tools/​handlers/​snapshot-handler.ts:64

formatSnapshotData preserves any truthy snapshot.name, so the sparse response described in this PR (projects/.../locations/us-central1/snapshots/s1) remains a non-canonical snapshot resource name even though volumeId is recovered from the request. Only retain name when it matches the /volumes/{volume}/snapshots/{id} shape; otherwise keep the ID and let ensureSnapshotRequiredFields synthesize the canonical name from the request context.

[Copilot]

Copilot review overview

🟡 Changes recommended

Missing or malformed protobuf timestamps can be silently converted to the Unix epoch.

Review effort: Lite
Findings: 1

Open (1)

• Avoid converting invalid protobuf timestamps to the Unix epoch · New

Resolved since last review (3)

• Do not synthesize resource names for unknown locations
• Avoid unknown location in sparse replication resource names
• Avoid unknown location in quota resource identifiers

[Copilot]

Copilot review overview

🟡 Changes recommended

Required-field fallbacks remain incomplete, and missing usage values are incorrectly defaulted to zero.

Review effort: Lite
Findings: 5

Open (5)

• Sparse backup responses omit required output fields · New
• Undefined backup responses omit required fields · New
• Sparse quota responses omit required identity fields · New
• Replication responses lack required identity and resource names · New
• Sparse snapshots omit identity and use placeholder volume IDs · New

Resolved since last review (1)

• Avoid converting invalid protobuf timestamps to the Unix epoch

[Copilot]

Copilot review overview

🟡 Changes recommended

Resolve the incompatible dependency override and incorrect backup usage fallback.

Review effort: Lite
Findings: 1

Open (1)

• Incompatible brace-expansion override for minimatch · New

Resolved since last review (5)

• Sparse snapshots omit identity and use placeholder volume IDs
• Replication responses lack required identity and resource names
• Sparse quota responses omit required identity fields
• Undefined backup responses omit required fields
• Sparse backup responses omit required output fields

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unknown numeric quota enum values are currently dropped and should be preserved.

Review effort: Lite
Findings: None

Resolved since last review (1)

• Incompatible brace-expansion override for minimatch