Skip to content

fix(agent-runtime): keep MCP schemas JSON-serializable#877

Open
fortissolucoescontato-bit wants to merge 1 commit into
CodebuffAI:mainfrom
fortissolucoescontato-bit:fix/mcp-json-schema-serialization
Open

fix(agent-runtime): keep MCP schemas JSON-serializable#877
fortissolucoescontato-bit wants to merge 1 commit into
CodebuffAI:mainfrom
fortissolucoescontato-bit:fix/mcp-json-schema-serialization

Conversation

@fortissolucoescontato-bit

Copy link
Copy Markdown

Summary

Keeps MCP tool input schemas as plain JSON Schema objects while they are stored
in the agent runtime.

Previously, MCP input schemas were converted to Zod schemas before storage.
Those Zod instances contain circular internal references and could reach a
JSON.stringify boundary, causing normal Freebuff prompts to fail with:

JSON.stringify cannot serialize cyclic structures

The runtime now preserves the original JSON Schema and converts through
ensureZodSchema only at the point where schema consumption or validation is
required.

Behavior

  • MCP tool definitions remain JSON-serializable
  • input schemas preserve their JSON Schema representation
  • Zod conversion still occurs when consumed (ensureZodSchema in getToolSet)
  • normal prompts work with MCP servers enabled
  • Engram tools can be listed and invoked
  • no circular serialization error is produced

Verification

  • schema handling tests: 15/15 passing
  • mcp schema serialization unit tests: 13/13 passing
  • mcp schema integration tests: 3/3 passing
  • agent-runtime tests: 475/477 (2 pre-existing missing-module failures)
  • SDK build: PASS
  • Freebuff build: PASS
  • TUI post-install: no cyclic error, no auth error

Note

This PR is independent from the read-only /mcp status command in PR #876.

Store MCP tool input schemas as plain JSON Schema objects instead of
converting them to Zod schemas before storage. Zod schemas contain
circular internal references that cause JSON.stringify to fail with
'cannot serialize cyclic structures' when the agent state is serialized.

The runtime now preserves the original JSON Schema and converts through
ensureZodSchema only at the consumption boundary (getToolSet).

Tests: 16 new tests covering schema storage, serialization roundtrip,
multi-server scenarios, circular rejection defense, and full pipeline
validation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant