Skip to content

feat(rules): add component resolution rules to webflow_guide_tool#111

Draft
kiratchhina wants to merge 1 commit intomainfrom
kiratchhina/component-resolution-rules
Draft

feat(rules): add component resolution rules to webflow_guide_tool#111
kiratchhina wants to merge 1 commit intomainfrom
kiratchhina/component-resolution-rules

Conversation

@kiratchhina
Copy link
Copy Markdown
Collaborator

Summary

When a Webflow site consumes components from a shared library, list_components returns two entries for the same component name — one with readonly: true (shared library) and one site-level. component_builder previously resolved by name and silently picked the site-level version, which disconnects placed instances from upstream design system updates.

This PR encodes the correct resolution behaviour directly into the webflow_guide_tool runtime instructions so that any agent using this MCP server follows safe defaults automatically.

What's different

  • Removed the instruction telling agents to "pass the component name (not the ID)" — this was actively unsafe for sites with shared library components
  • Added a required list_components call before every component_builder insertion
  • Added a resolution priority order: explicit ID → unambiguous readonly match → ambiguous (warn + confirm) → no readonly match (warn + ask)
  • Added a standard warning format for name collisions so users always know which version is being used before anything is inserted
  • Added pre/post session audit rules to detect and surface any implicit site-level component creation

How it works

All rules live in webflow_guide_tool (src/tools/rules.ts), which agents are already instructed to call first before all other tools. No schema or API changes — this is purely behavioural guidance.

QA Spec

  • Agent calls list_components before component_builder on a site with shared library components
  • Agent picks the readonly: true entry when a name collision exists
  • Agent surfaces the disambiguation warning and waits for confirmation rather than proceeding silently
  • Agent performs post-session audit and flags any increase in total component count
  • No regression on sites with no shared library components (unambiguous name resolves normally)

Made with Cursor

When a site consumes shared library components, list_components returns
duplicate names — one readonly (shared library) and one site-level.
component_builder historically resolved by name and silently picked the
site-level version, disconnecting instances from upstream design system updates.

This adds explicit resolution rules to the webflow_guide_tool:
- Require list_components before every component_builder call
- Prefer readonly: true entries; use explicit IDs where possible
- Warn and require confirmation on any name collision
- Mandate a pre/post session audit to detect implicit component creation

Also removes the old "Pass the component name (not the ID)" instruction
which was actively contradicting safe resolution behaviour.

Made-with: Cursor
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