[davidallada]

Important

1. Make sure you have read our contribution guidelines
2. Ensure there is an associated issue
3. Use the correct syntax to link this PR: Fixes #<issue number>.

Summary

Fixes #44181

An MCP tool parameter that accepts more than one JSON type has its list values turned into strings before they reach the MCP server.

Reproduction. Home Assistant's built-in MCP server declares GetLiveContext.domain as vol.Any(cv.string, [cv.string]), which Dify receives as {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}. When the model calls the tool with {"domain": ["light"]}, a value the schema allows, Dify sends "['light']". Home Assistant then answers No exposed entities found in domain(s): ['light']. Sending "light" or ["light"] straight to /api/mcp works.

Root cause.

1. convert_mcp_schema_to_parameter (api/services/tools/tools_transform_service.py) gives a union the type of its first non-null branch (string here). It keeps the raw schema only for array/object, so the LLM is told the parameter is a plain string.
2. Tool._transform_tool_parameters_type (api/core/tools/__base/tool.py) then calls cast_parameter_value. For string, that does str(value), so ["light"] becomes "['light']". For a [number, string] union, a valid string value raises instead.

Fix.

• New helper schema_accepts_multiple_types (api/core/tools/mcp_tool/tool.py): returns true when a property's type list or anyOf/oneOf branches name more than one non-null JSON type. integer/float count as number, so [integer, number] is not a union.
• convert_mcp_schema_to_parameter also keeps the raw schema as input_schema for these properties. The LLM then sees the real union. The parameter's Dify type does not change, so the UI is unaffected.
• MCPTool._transform_tool_parameters_type forwards the values of these parameters unchanged. All other parameters still go through the base cast. The MCP server owns the schema and validates the value.

MCP tool parameters are rebuilt from the stored inputSchema each time the provider loads (MCPToolProviderController.from_entity), so existing providers get the fix without a re-sync.

Alternatives considered.

• Stop str()-ing lists/dicts in cast_parameter_value. This is shared by builtin, plugin, API and datasource tools, so it would also change what genuinely string-only parameters receive. json.dumps would not help either, because Home Assistant would still get a string.
• Resolve string-or-array unions to array. The array cast wraps a plain "light" into ["light"]. Applying the same idea to object would be worse: the object cast turns a non-JSON string into {} and drops the value.
• Skip casting for all MCP parameters. This would remove the useful coercions for single-type parameters (e.g. "5" → 5).
• Map unions to the any parameter type. any is a Dify-internal type with its own frontend handling (variable selectors).

Screenshots

N/A. Backend-only change.

Tests

• test_mcp_tool.py::test_mcp_tool_invoke_preserves_values_of_mixed_type_union_parameters: builds the parameters from a string-or-string-list schema, calls MCPTool.invoke, and checks the arguments passed to invoke_remote_mcp_tool. It is parametrized over anyOf, oneOf and type-list unions, each in both branch orders ([string, array] and [array, string]), with the values "light" and ["light", "cover"]. A single-type string parameter is still cast. Before the fix it fails with assert "['light']" == ['light'].
• test_tools_transform_service.py: input_schema is attached for the same six union forms and for [string, array, null]. It is not attached for [string, null], anyOf[string, null], oneOf[null, string] and oneOf[integer, number].

Results:

• uv run --project api --dev pytest api/tests/unit_tests/core/tools/ api/tests/unit_tests/services/tools/ api/tests/unit_tests/core/plugin: 968 passed before the change, 991 passed after (23 new test cases), 0 failed.
• ruff format --check ./api and ruff check ./api pass.
• lint-imports: 68 contracts kept.
• make api-contract-lint, dotenv-linter, scripts/check_no_spec_mock.py and scripts/check_no_new_base_model.py pass.
• ./dev/pyrefly-check-local on both changed source files: clean.

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've verified the change and added or updated tests where meaningful regression risk justifies coverage.
• I've updated the documentation accordingly.
• I ran make lint && make type-check (backend) and vp staged (frontend) to appease the lint gods

[Stream29]

Accepting this as a scoped fix for the directly declared mixed-type MCP parameters. Independent component checks confirmed schema preservation and unchanged string/list arguments across anyOf, oneOf and type-list unions in both branch orders, while single-type coercion remains intact. Broader nested-union and null/empty-value handling can be addressed separately. This approval does not imply full end-to-end or Python 3.13 CI validation; merge remains subject to resolving the branch conflict and satisfying repository checks.

[Stream29]

Re-approving the scoped MCP fix after merging current main and resolving the schema-conversion naming conflict. The resolution retains main’s lowercase local names and the PR’s union-schema preservation condition. The two targeted test files passed (66 tests), Ruff check/format passed, and all 56 independent probe observations match the previously reviewed head. Local validation used Python 3.12 with a warnings.deprecated compatibility shim, not the required Python 3.13 CI environment. Known nested-union and null/empty-value limitations remain outside this scoped fix.

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-10-17 17:19:05.877435580 +0000
+++ /tmp/pyrefly_pr.txt	2026-10-17 17:18:57.321451156 +0000
@@ -3863,11 +3863,11 @@
 ERROR Object of type `ToolInvokeMessage.BlobChunkMessage | ToolInvokeMessage.BlobMessage | ToolInvokeMessage.FileMessage | ToolInvokeMessage.JsonMessage | ToolInvokeMessage.LogMessage | ToolInvokeMessage.RetrieverResourceMessage | ToolInvokeMessage.TextMessage | ToolInvokeMessage.VariableMessage | None` has no attribute `text` [missing-attribute]
    --> tests/unit_tests/core/tools/test_dataset_retriever_tool.py:176:12
 ERROR Object of type `ToolInvokeMessage.BlobChunkMessage | ToolInvokeMessage.BlobMessage | ToolInvokeMessage.FileMessage | ToolInvokeMessage.JsonMessage | ToolInvokeMessage.LogMessage | ToolInvokeMessage.RetrieverResourceMessage | ToolInvokeMessage.TextMessage | ToolInvokeMessage.VariableMessage | None` has no attribute `text` [missing-attribute]
-  --> tests/unit_tests/core/tools/test_mcp_tool.py:69:12
+  --> tests/unit_tests/core/tools/test_mcp_tool.py:70:12
 ERROR Object of type `ToolInvokeMessage.BlobChunkMessage | ToolInvokeMessage.BlobMessage | ToolInvokeMessage.FileMessage | ToolInvokeMessage.JsonMessage | ToolInvokeMessage.LogMessage | ToolInvokeMessage.RetrieverResourceMessage | ToolInvokeMessage.TextMessage | ToolInvokeMessage.VariableMessage | None` has no attribute `text` [missing-attribute]
-  --> tests/unit_tests/core/tools/test_mcp_tool.py:79:12
+  --> tests/unit_tests/core/tools/test_mcp_tool.py:80:12
 ERROR Argument `str` is not assignable to parameter `identity_mode` with type `IdentityMode` in function `core.tools.mcp_tool.tool.MCPTool.__init__` [bad-argument-type]
-   --> tests/unit_tests/core/tools/test_mcp_tool.py:182:23
+   --> tests/unit_tests/core/tools/test_mcp_tool.py:218:23
 ERROR Object of type `ToolInvokeMessage.BlobChunkMessage | ToolInvokeMessage.BlobMessage | ToolInvokeMessage.FileMessage | ToolInvokeMessage.JsonMessage | ToolInvokeMessage.LogMessage | ToolInvokeMessage.RetrieverResourceMessage | ToolInvokeMessage.TextMessage | ToolInvokeMessage.VariableMessage | None` has no attribute `text` [missing-attribute]
   --> tests/unit_tests/core/tools/test_plugin_tool.py:68:13
 ERROR Object of class `ToolInvokeMeta` has no attribute `type` [missing-attribute]
@@ -5613,7 +5613,7 @@
 ERROR Object of class `MCPToolProvider` has no attribute `decrypted_headers` [missing-attribute]
   --> tests/unit_tests/services/tools/test_mcp_tools_transform.py:74:5
 ERROR Object of class `Mapping` has no attribute `startswith` [missing-attribute]
-   --> tests/unit_tests/services/tools/test_tools_transform_service.py:341:16
+   --> tests/unit_tests/services/tools/test_tools_transform_service.py:343:16
 ERROR Argument `Literal['opendal']` is not assignable to parameter `storage_type` with type `StorageType` in function `models.model.UploadFile.__init__` [bad-argument-type]
   --> tests/unit_tests/services/workflow/test_draft_var_loader_simple.py:82:26
 ERROR Argument `Literal['account']` is not assignable to parameter `created_by_role` with type `CreatorUserRole` in function `models.model.UploadFile.__init__` [bad-argument-type]

[github-actions]

Pyrefly Type Coverage

Metric	Base	PR	Delta
Type coverage	75.08%	75.07%	-0.01%
Strict coverage	74.75%	74.74%	-0.01%
Typed symbols	62,158	62,161	+3
Untyped symbols	20,725	20,733	+8
Modules	3802	3802	0

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.61%. Comparing base (5dff246) to head (f389eb3).

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #44182   +/-   ##
=======================================
  Coverage   82.61%   82.61%           
=======================================
  Files        5510     5510           
  Lines      328544   328565   +21     
  Branches    65224    65229    +5     
=======================================
+ Hits       271416   271437   +21     
- Misses      51932    51933    +1     
+ Partials     5196     5195    -1     

Flag	Coverage Δ
api	88.59% <100.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.