feat(mcp-server): expose polymorphic relations in describeCollection

[Scra3]

Summary

• Detect polymorphic-referenced-models from forest-rails schema in describeCollection
• Expose isPolymorphic: true and polymorphicTargets: ['Post', 'Video'] in the relation output
• Set targetCollection: null for polymorphic relations (since the reference name isn't a real collection)
• Add LLM guidance in the tool description about polymorphic _id and _type fields

Why

When a Ruby agent has polymorphic relations (e.g. commentable on comments), the MCP server didn't expose this info. LLMs couldn't know they need to pass both commentable_id AND commentable_type for create/update, or that listRelated won't work on polymorphic BelongsTo relations.

Example output

{
  "relations": [
    {
      "name": "commentable",
      "type": "many-to-one",
      "targetCollection": null,
      "isPolymorphic": true,
      "polymorphicTargets": ["Post", "Video"]
    }
  ]
}

Test plan

• Polymorphic BelongsTo relation detected and exposed with targets
• Non-polymorphic relations unchanged (no extra fields)
• Build passes, lint clean

🤖 Generated with Claude Code

Note

Expose polymorphic relations in describeCollection MCP tool output

• Relation entries in describeCollection now include isPolymorphic: true and polymorphicTargets when polymorphicReferencedModels is present on a field; targetCollection is set to null for these relations.
• Actions without a configured endpoint are excluded from the actions array and surfaced in _meta.skippedActions with reason 'no endpoint configured'; getActionEndpoints also skips endpoint-less actions.
• Fixes a runtime error in FieldFormStates when a change-hook response omits layout, by treating missing layout as an empty array.
• Documentation strings in the list tool are updated to explain the : separator for relation fields and limitations for polymorphic relations.

^{Macroscope summarized 9c21c01.}

[qltysh]

4 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 16): declareDescribeCollectionTool	3
qlty	Structure	Deeply nested control flow (level = 4)	1

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (3)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-client/src/action-fields/field-form-states.ts	100.0%
	packages/mcp-server/src/utils/schema-fetcher.ts	100.0%
	packages/mcp-server/src/tools/describe-collection.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[Scra3]

in v1 it can be undefined

[nbouliol]

LGTM