[PR #4087] [CLOSED] fix(mcp): normalize advertised boolean literals for Gemini compatibility (#4025) #6047

New issue

Closed

opened 2026-10-31 01:11:27 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:11:27 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4087
Author: @HarsH-1877
Created: 10/15/2026
Status: ❌ Closed

Base: main ← Head: fix/mcp-schema-gemini-const-4025

📝 Commits (4)

3c554f7 test(mcp): add failing tests for advertised boolean const normalization (#4025)
1cf2b96 fix(mcp): normalize advertised boolean literals for Gemini compatibility (#4025)
9eae43d test(mcp): verify Gemini dialect constraints across advertised tool catalog (#4025)
14faf5c fix(mcp): merge mixed union boolean alternatives and drop negated literals (#4025)

📊 Changes

6 files changed (+352 additions, -21 deletions)

View changed files

📝 docs/mcp-contracts.md (+11 -7)
📝 src/contracts/inputSchemaPresentation.ts (+152 -9)
📝 src/contracts/toolInputReferences.test.ts (+125 -0)
📝 tests/boundary/mcp/compactInputSchemaMcp.test.ts (+13 -2)
📝 tests/boundary/mcp/toolSchemaValidity.test.ts (+16 -3)
📝 tests/fixtures/mcpClientSchemaConstraints.ts (+35 -0)

📄 Description

Summary

Fixes #4025. Advertised MCP tool input schemas emitted non-string const values (booleans) on 5 tools (38 occurrences). When clients like OpenCode/LibreChat render declarations through the Vercel AI SDK, those are serialized as enum: [false] / enum: [true]. Google Gemini's function declaration parameters API requires all enum values to be strings (TYPE_STRING), causing the Gemini API to reject the entire tool catalog with HTTP 400.

This change normalizes non-string literals into their declared primitive types (preserving default and description) and collapses redundant boolean anyOf/oneOf variants into single boolean property definitions in the advertised projection, while keeping canonical runtime Zod validation strict.

Problem and expected behavior

Trigger: Calling tools/list on REA over MCP stdio from a client backed by Google Gemini.
Observed: Gemini API returns HTTP 400: Invalid value at 'tools[0].function_declarations[...].enum[0]' (TYPE_STRING), false. The entire tool catalog fails to load.
Expected: Advertised tool input schemas project boolean literals as { "type": "boolean" } (with defaults where present) and omit non-string const/enum attributes, allowing Gemini-backed clients to connect seamlessly.

Change and scope

Added normalizeAdvertisedLiterals in src/contracts/inputSchemaPresentation.ts to normalize non-string const and enum values across schema maps ($defs, properties), schema arrays, and children.
Added collapseBooleanCombinator in flattenRootObjectUnion and normalizeAdvertisedLiterals to merge boolean variants from discriminated unions into single boolean properties instead of redundant anyOf branches.
Added nonStringConstOrEnumSchemaError in tests/fixtures/mcpClientSchemaConstraints.ts.
Integrated boundary checks in tests/boundary/mcp/toolSchemaValidity.test.ts and tests/boundary/mcp/compactInputSchemaMcp.test.ts ensuring all 207 advertised tools comply with Gemini dialect constraints in both full and compact profiles.
Updated docs/mcp-contracts.md explaining the TYPE_STRING enum compatibility requirement.
Contribution scope fit: Routine contract/schema projection compatibility fix; ordinary fix within existing boundaries.

Contract and boundary impact

Semantic owner and earliest changed stage: src/contracts/inputSchemaPresentation.ts (advertised MCP schema projection).
Contribution scope fit and linked maintainer decision: Not applicable (ordinary schema compatibility fix within existing boundaries).
CLI and MCP/tool-catalog contract: Advertised tool input schemas are free of non-string const and enum keywords. Server-side runtime Zod validation is unchanged.
Provider, bridge, target-format, or platform compatibility: Restores compatibility with Google Gemini and Vercel AI SDK function calling.
Evidence, artifact, provenance, or reconstruction contract: Not applicable.
Target selection, authority, upstream behavior, and cleanup details: Not applicable.
Generated metadata: Not applicable (no catalog metadata drift).

Expected effects:

Documentation or usability only; no target interaction.

Evidence and regression coverage

Tests added or updated:
- src/contracts/toolInputReferences.test.ts: Added unit tests verifying boolean const normalization, nested definition normalization, boolean discriminated union collapsing, and preservation of string const.
- tests/boundary/mcp/toolSchemaValidity.test.ts: Added nonStringConstOrEnumSchemaError check to schemaErrors(tools) across all 207 tools.
- tests/boundary/mcp/compactInputSchemaMcp.test.ts: Added assertion verifying neither full nor compact catalog profiles advertise non-string const or enum.
Base reproduction: 38 non-string const occurrences across 5 tools (inspect_web_page, analyze_web_bundle, compare_web_captures, inspect_electron_page, evaluate_reconstruction_coverage) on base commit 47b4628ba. After fix: 0 occurrences.
Proof: 47/47 tests passing across the 3 affected test suites.

Validation performed

npm run test:focused -- tests/boundary/mcp/toolSchemaValidity.test.ts tests/boundary/mcp/compactInputSchemaMcp.test.ts src/contracts/toolInputReferences.test.ts — 47 passed (0 failures).
npm run check:fast — 0 errors (typecheck and lint passed).
npm run docs:check — 0 errors (licenses, package metadata, product catalog, and doc facts passed).

Compatibility, safety, and release

Breaking changes or migration steps: None.
Package or release metadata impact: None.
Security, privacy, process, or containment review: Not applicable.

Author readiness

Human owner: @HarsH-1877

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4087 **Author:** [@HarsH-1877](https://github.com/HarsH-1877) **Created:** 10/15/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/mcp-schema-gemini-const-4025` --- ### 📝 Commits (4) - [`3c554f7`](https://github.com/morluto/rea/commit/3c554f77bf1b1da1393caf7ec3b88318a4533beb) test(mcp): add failing tests for advertised boolean const normalization (#4025) - [`1cf2b96`](https://github.com/morluto/rea/commit/1cf2b965acda6a49dbf8ce19bd8c4f4756192a0f) fix(mcp): normalize advertised boolean literals for Gemini compatibility (#4025) - [`9eae43d`](https://github.com/morluto/rea/commit/9eae43d780a9718eab678a2a49592a6b5ceece20) test(mcp): verify Gemini dialect constraints across advertised tool catalog (#4025) - [`14faf5c`](https://github.com/morluto/rea/commit/14faf5c2be58ca79441383d5fed3676c0fe100dd) fix(mcp): merge mixed union boolean alternatives and drop negated literals (#4025) ### 📊 Changes **6 files changed** (+352 additions, -21 deletions) <details> <summary>View changed files</summary> 📝 `docs/mcp-contracts.md` (+11 -7) 📝 `src/contracts/inputSchemaPresentation.ts` (+152 -9) 📝 `src/contracts/toolInputReferences.test.ts` (+125 -0) 📝 `tests/boundary/mcp/compactInputSchemaMcp.test.ts` (+13 -2) 📝 `tests/boundary/mcp/toolSchemaValidity.test.ts` (+16 -3) 📝 `tests/fixtures/mcpClientSchemaConstraints.ts` (+35 -0) </details> ### 📄 Description ## Summary Fixes #4025. Advertised MCP tool input schemas emitted non-string `const` values (booleans) on 5 tools (38 occurrences). When clients like OpenCode/LibreChat render declarations through the Vercel AI SDK, those are serialized as `enum: [false]` / `enum: [true]`. Google Gemini's function declaration parameters API requires all enum values to be strings (`TYPE_STRING`), causing the Gemini API to reject the entire tool catalog with HTTP 400. This change normalizes non-string literals into their declared primitive types (preserving `default` and `description`) and collapses redundant boolean `anyOf`/`oneOf` variants into single boolean property definitions in the advertised projection, while keeping canonical runtime Zod validation strict. ## Problem and expected behavior - **Trigger:** Calling `tools/list` on REA over MCP stdio from a client backed by Google Gemini. - **Observed:** Gemini API returns HTTP 400: `Invalid value at 'tools[0].function_declarations[...].enum[0]' (TYPE_STRING), false`. The entire tool catalog fails to load. - **Expected:** Advertised tool input schemas project boolean literals as `{ "type": "boolean" }` (with defaults where present) and omit non-string `const`/`enum` attributes, allowing Gemini-backed clients to connect seamlessly. ## Change and scope - Added `normalizeAdvertisedLiterals` in `src/contracts/inputSchemaPresentation.ts` to normalize non-string `const` and `enum` values across schema maps (`$defs`, `properties`), schema arrays, and children. - Added `collapseBooleanCombinator` in `flattenRootObjectUnion` and `normalizeAdvertisedLiterals` to merge boolean variants from discriminated unions into single boolean properties instead of redundant `anyOf` branches. - Added `nonStringConstOrEnumSchemaError` in `tests/fixtures/mcpClientSchemaConstraints.ts`. - Integrated boundary checks in `tests/boundary/mcp/toolSchemaValidity.test.ts` and `tests/boundary/mcp/compactInputSchemaMcp.test.ts` ensuring all 207 advertised tools comply with Gemini dialect constraints in both full and compact profiles. - Updated `docs/mcp-contracts.md` explaining the `TYPE_STRING` enum compatibility requirement. - Contribution scope fit: Routine contract/schema projection compatibility fix; ordinary fix within existing boundaries. ## Contract and boundary impact - Semantic owner and earliest changed stage: `src/contracts/inputSchemaPresentation.ts` (advertised MCP schema projection). - Contribution scope fit and linked maintainer decision: Not applicable (ordinary schema compatibility fix within existing boundaries). - CLI and MCP/tool-catalog contract: Advertised tool input schemas are free of non-string `const` and `enum` keywords. Server-side runtime Zod validation is unchanged. - Provider, bridge, target-format, or platform compatibility: Restores compatibility with Google Gemini and Vercel AI SDK function calling. - Evidence, artifact, provenance, or reconstruction contract: Not applicable. - Target selection, authority, upstream behavior, and cleanup details: Not applicable. - Generated metadata: Not applicable (no catalog metadata drift). Expected effects: - [x] Documentation or usability only; no target interaction. ## Evidence and regression coverage - Tests added or updated: - `src/contracts/toolInputReferences.test.ts`: Added unit tests verifying boolean `const` normalization, nested definition normalization, boolean discriminated union collapsing, and preservation of string `const`. - `tests/boundary/mcp/toolSchemaValidity.test.ts`: Added `nonStringConstOrEnumSchemaError` check to `schemaErrors(tools)` across all 207 tools. - `tests/boundary/mcp/compactInputSchemaMcp.test.ts`: Added assertion verifying neither full nor compact catalog profiles advertise non-string `const` or `enum`. - Base reproduction: 38 non-string `const` occurrences across 5 tools (`inspect_web_page`, `analyze_web_bundle`, `compare_web_captures`, `inspect_electron_page`, `evaluate_reconstruction_coverage`) on base commit `47b4628ba`. After fix: 0 occurrences. - Proof: 47/47 tests passing across the 3 affected test suites. ## Validation performed - `npm run test:focused -- tests/boundary/mcp/toolSchemaValidity.test.ts tests/boundary/mcp/compactInputSchemaMcp.test.ts src/contracts/toolInputReferences.test.ts` — 47 passed (0 failures). - `npm run check:fast` — 0 errors (typecheck and lint passed). - `npm run docs:check` — 0 errors (licenses, package metadata, product catalog, and doc facts passed). ## Compatibility, safety, and release - Breaking changes or migration steps: None. - Package or release metadata impact: None. - Security, privacy, process, or containment review: Not applicable. ## Author readiness Human owner: @HarsH-1877 - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:11:27 +00:00