Midwest Component Library v0.24.0

Previews

No matching results.

🧠 v0.22.1 — MCP Guidance & Component Docs

What's New

MCP Guidance System

The MCP server now ships a guidance layer that warns AI agents about common composition mistakes before they happen. Guidance is stored in lib/midwest/mcp/data/component_guidance.yml and surfaced automatically through MCP tools.

Two data sources feed into guidance:

  • Auto-detected — Template scanning discovers which components internally render other components (e.g., StatComponent renders a CardComponent). This powers redundant nesting warnings.
  • Curated — Anti-patterns and best practices captured from real agent mistakes observed in the field.

A new bin/guidance CLI manages the guidance data:

bin/guidance              # List components with guidance
bin/guidance show stat    # Show full guidance for a component
bin/guidance add          # Describe a pattern; Claude formats and appends it
bin/guidance scan         # Display the internally-renders graph
bin/guidance check        # Validate YAML keys against the component index

Component Descriptions

Every component now has a class-level doc comment describing its purpose and key capabilities. These descriptions are surfaced through list_components, get_component_api, get_helper_methods, and search results — giving AI agents richer context without needing to read source files.

What Changed

MCP Tool Enhancements

All eight MCP tools received intelligence upgrades in this release:

  • get_component_api — Now returns customization points (allowed/discouraged patterns, constrained option values) and guidance (anti-patterns and best practices) when available.
  • get_component_examples — Now includes template_examples with ready-to-use snippets in ERB, HAML, and Ruby for every component.
  • get_component_relationships — Now returns internally_renders (which components a template uses) and nesting_warnings when redundant wrapping is detected.
  • get_form_builder_info — Now includes validation_patterns (server-side, client-side, match, errors summary, implicit options) and utility_methods (errorssummary, errorfor, fieldgroup, livesummary, showif, passwordrequirements).
  • get_helper_methods — Helper listings now include the component's description for at-a-glance context.
  • validate_component_usage — New parent_component: parameter checks for redundant nesting (e.g., wrapping a StatComponent in a midwest_card when it already renders one internally).
  • search_components — Guidance text is now included in search scoring, so queries like "nesting" or "anti-pattern" surface relevant components.

ComponentIndex — Template scanning

ComponentIndex now scans component templates to build an internal-renders graph. New methods internal_renders_for and redundant_containers_for power the nesting warnings across tools.

SearchIndex — Weighted scoring

Search scoring was refactored from inline arithmetic to a FIELD_WEIGHTS hash, adding a guidance field weighted at 2.

Test fixes

  • DatePickerComponentTest — Updated selectors to match refactored date picker markup.
  • RepeatableComponentPreviewSystemTest — Adjusted for uppercased label text and removed brittle "Remove" text assertion.
  • ShowIfComponentSystemTest — Corrected hidden section count from 3 to 2 to match negate-section behavior.

What Was Removed

Nothing removed.

Dev Process

GuidanceIndex

New Midwest::MCP::Index::GuidanceIndex loads curated anti-patterns and best practices from YAML with class-name normalization (supports "stat", "stat_component", and "Midwest::StatComponent" lookups).

README — MCP section

The README now documents MCP server setup (.mcp.json config) and the guidance system with bin/guidance usage examples.

New and updated tests

  • GuidanceIndexTest — YAML loading, normalization, has_guidance?, required field validation.
  • ComponentIndexTest — Template scanning, internal renders detection, redundant container detection, self-reference exclusion, form helper mapping.
  • ComponentParserTest — Description extraction from class comments.
  • ToolsTest — Expanded for customization points, guidance, template examples, validation patterns, utility methods, redundant nesting, helper descriptions, and fuzzy suggestion coverage.