fix(mcp): preserve $defs and definitions fields in JsonSchema conversion

[JGoP-L]

---

AgentScope-Java Version

1.0.10-SNAPSHOT

Description

Background

When MCP (Model Context Protocol) tools return JSON Schema with $ref references, the referenced type
definitions are stored in $defs (JSON Schema 2020-12) or definitions (legacy JSON Schema) fields.
These definitions are essential for resolving $ref references.

Problem

The McpTool.convertMcpSchemaToParameters() method was only copying type, properties, required, and
additionalProperties fields from the MCP JsonSchema. The $defs and definitions fields were being
dropped during conversion, causing $ref references to become invalid.

Solution

Added logic to preserve $defs and definitions fields when converting MCP schema to AgentScope
parameters:

// Preserve $defs and definitions for $ref resolution
if (inputSchema.defs() != null && !inputSchema.defs().isEmpty()) {
parameters.put("$defs", new HashMap<>(inputSchema.defs()));
}

if (inputSchema.definitions() != null && !inputSchema.definitions().isEmpty()) {
parameters.put("definitions", new HashMap<>(inputSchema.definitions()));
}

Changes

• McpTool.java: Added handling for $defs and definitions fields in convertMcpSchemaToParameters()
• McpToolTest.java: Added 3 test cases:
  • testConvertMcpSchemaToParameters_WithDefs: Tests $defs preservation
  • testConvertMcpSchemaToParameters_WithDefinitions: Tests definitions preservation
  • testConvertMcpSchemaToParameters_WithBothDefsAndDefinitions: Tests both fields together

How to Test

mvn test -pl agentscope-core -Dtest=McpToolTest

Fixes #893

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

---

[Copilot]

Pull request overview

This PR fixes MCP tool JSON Schema conversion so that referenced type definitions are not lost when converting McpSchema.JsonSchema into AgentScope tool parameters, preventing $ref resolution failures (Issue #893).

Changes:

• Preserve top-level $defs (JSON Schema 2020-12) during McpSchema.JsonSchema → parameters conversion.
• Preserve legacy definitions (pre-2020-12) during conversion.
• Add unit tests covering $defs, definitions, and both simultaneously.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpTool.java	Copies defs() → $defs and definitions() → definitions into the produced parameters schema map to keep $ref targets available.
agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpToolTest.java	Adds test cases validating $defs and/or definitions are retained in the converted schema.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!