Skip to content

tools.md

Latest commit

 

History

History
255 lines (219 loc) · 14.2 KB

tools.md

File metadata and controls

255 lines (219 loc) · 14.2 KB

Angular MCP Tools for AI Agents

This document provides comprehensive guidance for AI agents working with Angular migration and analysis tools. Each tool is designed to support automated refactoring, validation, and analysis workflows.

Tool Categories

🔍 Project Analysis Tools

report-violations

Purpose: Identifies deprecated CSS usage patterns for a specific component in Angular projects AI Usage: Use when you need to analyze violations for a specific component before planning refactoring Key Parameters:

  • directory: Target analysis directory (use relative paths like ./src/app)
  • componentName: Component class name (e.g., DsButton)
  • groupBy: "file" or "folder" for result organization
  • excludePatterns: Optional glob pattern(s) to exclude files/directories from scanning. Supports standard glob syntax (*, **, ?). Can be a single string or array of strings (e.g., "node_modules/**", ["**/dist/**", "**/*.spec.ts"])
  • saveAsFile: Optional boolean - if true, saves report to tmp/.angular-toolkit-mcp/violations-report/<componentName>/<directory>-violations.json Output:
  • Default: Structured violation reports grouped by file or folder
  • With saveAsFile: true: File path and statistics (components, files, lines) Best Practice: Use saveAsFile: true when you need to persist results for later processing or grouping workflows

report-all-violations

Purpose: Reports all deprecated CSS usage for every component within a directory AI Usage: Use for a fast, global inventory of violations across the codebase before narrowing to specific components Key Parameters:

  • directory: Target analysis directory (use relative paths like ./src/app)
  • groupBy: "component" or "file" for result organization (default: "component")
  • excludePatterns: Optional glob pattern(s) to exclude files/directories from scanning. Supports standard glob syntax (*, **, ?). Can be a single string or array of strings (e.g., "node_modules/**", ["**/dist/**", "**/*.spec.ts"])
  • saveAsFile: Optional boolean - if true, saves report to tmp/.angular-toolkit-mcp/violations-report/<directory>-violations.json Output:
  • Default: Structured violation reports grouped by component or file covering all components
  • With saveAsFile: true: File path and statistics (components, files, lines) Best Practice: Use saveAsFile: true to persist results for grouping workflows or large-scale migration planning. The saved file can be used as input for work distribution grouping tools.

get-project-dependencies

Purpose: Analyzes project structure, dependencies, and buildability AI Usage: Validate project architecture before suggesting refactoring strategies Key Parameters:

  • directory: Project directory to analyze
  • componentName: Optional DS component for import path validation Output: Dependency analysis, buildable/publishable status, peer dependencies Best Practice: Use to understand project constraints before recommending changes

group-violations

Purpose: Creates balanced work distribution groups from violations reports for parallel development AI Usage: Use after report-all-violations to organize violations into balanced work groups for team distribution Key Parameters:

  • fileName: Name of violations JSON file in tmp/.angular-toolkit-mcp/violations-report/ (e.g., "packages-poker-core-lib-violations.json")
  • minGroups: Minimum number of groups (default: 3)
  • maxGroups: Maximum number of groups (default: 5)
  • variance: Acceptable variance percentage for balance (default: 20) Output:
  • Work groups with balanced violation counts
  • Individual JSON and Markdown files per group
  • Metadata with validation results
  • Saved to tmp/.angular-toolkit-mcp/violation-groups/<reportName>/ Best Practice: Use after saving violations with saveAsFile: true. The tool accepts both component-grouped and file-grouped reports. Groups maintain path exclusivity (each file in exactly one group) and preserve directory boundaries to enable parallel development without merge conflicts.

report-deprecated-css

Purpose: Scans styling files for deprecated CSS classes AI Usage: Complement violation reports with style-specific analysis Key Parameters:

  • directory: Directory containing style files
  • componentName: Target DS component Output: List of deprecated CSS classes found in stylesheets Best Practice: Run after report-violations for comprehensive CSS analysis

📚 Component Information Tools

list-ds-components

Purpose: Lists all available Design System components in the project with their file paths and metadata AI Usage: Discover available DS components before starting migration or analysis workflows Key Parameters:

  • sections: Array of sections to include - "implementation", "documentation", "stories", or "all" (default: ["all"]) Output: Complete inventory of DS components with their implementation files, documentation files, stories files, and import paths Best Practice: Use as the first step to understand the DS component landscape before targeted analysis

get-ds-component-data

Purpose: Returns comprehensive data for a specific DS component including implementation files, documentation files, stories files, and import path AI Usage: Get detailed information about a specific component for analysis or migration planning Key Parameters:

  • componentName: DS component class name (e.g., DsBadge)
  • sections: Array of sections to include - "implementation", "documentation", "stories", or "all" (default: ["all"]) Output: Structured data with file paths for implementation, documentation, stories, and import information Best Practice: Use selective sections to optimize performance when you only need specific types of files

get-component-docs

Purpose: Retrieves MDX documentation for DS components AI Usage: Access official component documentation to understand proper usage patterns Key Parameters:

  • componentName: DS component class name (e.g., DsButton) Output: API documentation and usage examples in MDX format Best Practice: Always consult docs before suggesting component usage changes

get-component-paths

Purpose: Provides filesystem and NPM import paths for DS components AI Usage: Verify correct import paths when suggesting code changes Key Parameters:

  • componentName: DS component class name Output: Source directory path and NPM import path Best Practice: Use to ensure accurate import statements in generated code

get-deprecated-css-classes

Purpose: Lists deprecated CSS classes for specific DS components AI Usage: Understand what CSS classes to avoid or replace during migration Key Parameters:

  • componentName: DS component class name Output: Array of deprecated CSS class names Best Practice: Cross-reference with violation reports to prioritize fixes

get-ds-story-data

Purpose: Parses Storybook .stories.ts files for a DS component and returns a compact summary of its API surface, usage patterns, and story templates AI Usage: Use to understand selector style, input API, slots, form integration, and real-world template examples before generating or migrating component code. Defaults to markdown output with docs-template stories filtered out for minimal token cost. Key Parameters:

  • componentName: DS component class name (e.g., DsButton, DsBadge)
  • format: "markdown" (default) or "json" for structured data
  • descriptionLength: "short" (default, first sentence only) or "full"
  • excludeTags: Story tags to filter out — defaults to ["docs-template"] to skip showcase stories. Pass [] to include all. Output: Contains:
  • selector: Selector style (element or attribute) with CSS selector and usage note
  • imports: Filtered @frontend/ and @design-system/ scoped imports
  • argTypes: Input definitions with type, default, and description
  • slots: Named content projection slots
  • formIntegration: Detected Angular forms bindings (ngModel, formControlName, formControl)
  • stories: Story entries with name, single-line cleaned template, tags, args overrides, and story-level inputs. Templates have inline styles and HTML comments stripped. [all-meta-args-bound] indicates argsToTemplate() usage. Best Practice: Use alongside get-ds-component-data for a complete picture before planning migrations. For components with many stories, the default excludeTags: ["docs-template"] filter reduces output by 40-50%.

🔗 Analysis & Mapping Tools

build-component-usage-graph

Purpose: Maps component usage across modules, specs, templates, and styles AI Usage: Understand component dependencies before refactoring to avoid breaking changes Key Parameters:

  • directory: Root directory for analysis
  • violationFiles: Array of files with violations (from report-violations) Output: Component usage graph showing all import relationships Best Practice: Essential for large refactoring projects to map impact scope

lint-changes

Purpose: Runs ESLint validation on changed Angular files AI Usage: Validate code quality after making automated changes Key Parameters:

  • directory: Root directory containing components
  • files: Optional list of changed files
  • configPath: Optional ESLint config path Output: ESLint results and violations Best Practice: Always run after code modifications to ensure quality

📋 Component Contract Tools

build_component_contract

Purpose: Creates static surface contracts for component templates and styles AI Usage: Generate contracts before refactoring to track breaking changes Key Parameters:

  • saveLocation: Path where to save the contract file (supports absolute and relative paths)
  • typescriptFile: Required TypeScript component file (.ts)
  • templateFile: Optional Template file name (.html). Omit for inline templates
  • styleFile: Optional Style file name (.scss, .css, etc.). Omit for inline styles or no styles
  • dsComponentName: Optional design system component name Output: Component contract file with API surface Best Practice: Create contracts before major refactoring for comparison. Template and style files are optional—the tool will extract inline templates/styles from the TypeScript file when not provided

diff_component_contract

Purpose: Compares before/after contracts to identify breaking changes AI Usage: Validate that refactoring doesn't introduce breaking changes Key Parameters:

  • saveLocation: Path where to save the diff result file (supports absolute and relative paths)
  • contractBeforePath: Path to pre-refactoring contract
  • contractAfterPath: Path to post-refactoring contract
  • dsComponentName: Optional design system component name Output: Diff analysis showing breaking changes Best Practice: Essential validation step after component modifications

list_component_contracts

Purpose: Lists all available component contracts AI Usage: Discover existing contracts for comparison operations Key Parameters:

  • directory: Directory to search for contracts Output: List of available contract files Best Practice: Use to manage contract lifecycle during refactoring

⚙️ Configuration Tools

AI Agent Workflow Patterns

1. Discovery & Analysis Workflow

1. list-ds-components → Discover available DS components
2. report-all-violations (saveAsFile: true) → Identify all violations and save to file
3. group-violations → Create balanced work distribution groups
4. get-project-dependencies → Analyze project structure

2. Planning & Preparation Workflow

1. get-ds-component-data → Get comprehensive component information
2. get-ds-story-data → Extract usage patterns and templates from stories
3. build-component-usage-graph → Map component relationships
4. get-component-docs → Review proper usage patterns
5. get-component-paths → Verify import paths
6. build_component_contract → Create baseline contracts

3. Refactoring & Validation Workflow

1. [Apply code changes]
2. build_component_contract → Create post-change contracts
3. diff_component_contract → Validate no breaking changes
4. lint-changes → Ensure code quality

4. Non-Viable Cases Handling (Alternative to Steps 3-5)

1. report-deprecated-css → Identify CSS usage in global styles
2. report-deprecated-css → Identify CSS usage in component overrides
3. [Replace HTML classes with after-migration- prefix]
4. [Duplicate CSS selectors with prefixed versions]
5. report-deprecated-css → Validate CSS count consistency
6. report-violations → Validate violation reduction

Purpose: Used during the main DS refactoring workflow when components are identified as non-viable during planning step Trigger: Requires developer review and approval after AI identifies non-viable cases in step 2 Key Pattern: Use after-migration-[ORIGINAL_CLASS] prefix to exclude components from future analysis Replaces: Normal fix violations → validate changes → prepare report sequence

Error Handling for AI Agents

  • Path Resolution: Always use relative paths starting with ./
  • Component Names: Use PascalCase with Ds prefix (e.g., DsButton)
  • File Arrays: Ensure violation file arrays are properly formatted
  • Directory Validation: Verify directories exist before analysis
  • Contract Management: Clean up temporary contracts after analysis

Performance Considerations

  • Use groupBy: "folder" for large codebases to reduce output size
  • Limit violationFiles arrays to relevant files only
  • Use selective sections parameter in get-ds-component-data and list-ds-components to retrieve only needed data types
  • Cache component documentation between related operations
  • Run validation tools in parallel when possible

Integration Points

These tools integrate with:

  • Storybook: For component documentation
  • PostCSS: For style analysis

Output Formats

All tools return structured data suitable for:

  • JSON parsing for programmatic analysis
  • Markdown formatting for human-readable reports
  • File path arrays for batch operations
  • Contract objects for API comparison