You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .cursor/flows/ds-refactoring-flow/01-find-violations.mdc
+8-2Lines changed: 8 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,10 @@ Step 1: Find violations
19
19
Store the result in a variable called scanResult.
20
20
21
21
2. Perform first-level error handling:
22
-
- If the function call returns an error, respond with:
22
+
- If the function call returns an error or result containing "Missing ds.deprecatedCssClassesPath", respond with:
23
+
<commentary>⚠️ *Cannot proceed: Missing required configuration parameter* – The `ds.deprecatedCssClassesPath` parameter must be provided when starting the MCP server to use violation detection tools. Please restart the server with this parameter configured.</commentary>
24
+
Then stop execution.
25
+
- If the function call returns any other error, respond with:
- If scanResult.totalViolations is 0, respond with:
@@ -57,7 +60,10 @@ Once the user provides a subfolder choice, proceed as follows:
57
60
- Store the result in a variable called fileScan.
58
61
59
62
3. Perform error handling and validation:
60
-
- If the function call returns an error, respond with:
63
+
- If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with:
64
+
<commentary>⚠️ *Cannot proceed: Missing required configuration parameter* – The `ds.deprecatedCssClassesPath` parameter must be provided when starting the MCP server to use violation detection tools. Please restart the server with this parameter configured.</commentary>
65
+
Then stop execution.
66
+
- If the function call returns any other error, respond with:
Copy file name to clipboardExpand all lines: .cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc
+8-2Lines changed: 8 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,10 @@ Step 1: Find violations
17
17
Store the result in a variable called scanResult.
18
18
19
19
2. Perform first-level error handling:
20
-
- If the function call returns an error, respond with:
20
+
- If the function call returns an error or result containing "Missing ds.deprecatedCssClassesPath", respond with:
21
+
<commentary>⚠️ *Cannot proceed: Missing required configuration parameter* – The `ds.deprecatedCssClassesPath` parameter must be provided when starting the MCP server to use violation detection tools. Please restart the server with this parameter configured.</commentary>
22
+
Then stop execution.
23
+
- If the function call returns any other error, respond with:
@@ -54,7 +57,10 @@ Once the user provides a subfolder choice, proceed as follows:
54
57
- Store the result in a variable called fileScan.
55
58
56
59
3. Perform error handling and validation:
57
-
- If the function call returns an error, respond with:
60
+
- If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with:
61
+
<commentary>⚠️ *Cannot proceed: Missing required configuration parameter* – The `ds.deprecatedCssClassesPath` parameter must be provided when starting the MCP server to use violation detection tools. Please restart the server with this parameter configured.</commentary>
62
+
Then stop execution.
63
+
- If the function call returns any other error, respond with:
Copy file name to clipboardExpand all lines: README.md
+40-3Lines changed: 40 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ A Model Context Protocol (MCP) server that provides Angular project analysis and
9
9
-**Dependency Mapping**: Map component dependencies across modules, templates, and styles
10
10
-**ESLint Integration**: Lint Angular files with automatic ESLint configuration discovery
11
11
-**Project Analysis**: Analyze buildable/publishable libraries and validate import paths
12
-
-**Component Documentation**: Retrieve component data and documentation
12
+
-**Component Documentation**: Retrieve component data and documentation, list available components
13
13
14
14
## Use Cases
15
15
@@ -67,6 +67,8 @@ Copy `.cursor/mcp.json.example` to the project you're working on. Copied file sh
67
67
}
68
68
```
69
69
70
+
> Note: `ds.storybookDocsRoot` and `ds.deprecatedCssClassesPath` are optional. The server will start without them. Tools that require these paths will return a clear error prompting you to provide the missing parameter.
71
+
70
72
> **Note**: The example file contains configuration for `ESLint` official MCP which is required for the toolkit to work properly.
71
73
72
74
### Configuration Parameters
@@ -76,10 +78,20 @@ Copy `.cursor/mcp.json.example` to the project you're working on. Copied file sh
76
78
| Parameter | Type | Description | Example |
77
79
|-----------|------|-------------|---------|
78
80
|`workspaceRoot`| Absolute path | Root directory of your Angular workspace |`/Users/dev/my-angular-app`|
|`ds.storybookDocsRoot`| Relative path | Root directory containing Storybook documentation used by documentation-related tools |`storybook/docs`|
88
+
|`ds.deprecatedCssClassesPath`| Relative path | JavaScript file mapping deprecated CSS classes used by violation and deprecated CSS tools |`design-system/component-options.js`|
89
+
90
+
When optional parameters are omitted:
91
+
92
+
-`ds.storybookDocsRoot`: Tools will skip Storybook documentation lookups (e.g., `get-ds-component-data` will still return implementation/import data but may have no docs files).
93
+
-`ds.deprecatedCssClassesPath`: Tools that require the mapping will fail fast with a clear error. Affected tools include: `get-deprecated-css-classes`, `report-deprecated-css`, `report-all-violations`, and `report-violations`.
94
+
83
95
#### Deprecated CSS Classes File Format
84
96
85
97
The `component-options.js` file should export an array of component configurations:
@@ -135,10 +147,35 @@ my-angular-workspace/
135
147
136
148
### Component Analysis
137
149
150
+
-**`list-ds-components`**: List all available Design System components in the project with their file paths and metadata
151
+
138
152
-**`get-ds-component-data`**: Return data for a component including implementation files, documentation files, and import path
139
153
140
154
-**`build-component-usage-graph`**: Maps where given Angular components are imported (modules, specs, templates, styles) so refactors touch every file
141
155
156
+
### Tool behavior with optional parameters
157
+
158
+
The following tools work without optional params:
159
+
160
+
-`get-project-dependencies`
161
+
-`build-component-usage-graph`
162
+
-`get-ds-component-data` (documentation section is empty if `ds.storybookDocsRoot` is not set)
163
+
- Component contract tools:
164
+
-`build_component_contract`
165
+
-`diff_component_contract`
166
+
-`list_component_contracts`
167
+
168
+
The following tools require optional params to work:
169
+
170
+
- Requires `ds.deprecatedCssClassesPath`:
171
+
-`get-deprecated-css-classes`
172
+
-`report-deprecated-css`
173
+
-`report-all-violations`
174
+
-`report-violations`
175
+
176
+
- Requires `ds.storybookDocsRoot` for docs lookup (skipped otherwise):
Copy file name to clipboardExpand all lines: docs/component-refactoring-flow.md
+11-4Lines changed: 11 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ This document describes a 3-step AI-assisted component refactoring process for i
9
9
2.**Refactor Component** → Execute approved checklist items and implement changes
10
10
3.**Validate Component** → Verify improvements through contract comparison and scoring
11
11
12
-
The process includes two quality gates where human review and approval are required.
12
+
The process includes two quality gates where human review and approval are required. When refactoring involves Design System components, the process can leverage selective data retrieval to access only the specific component information needed (implementation, documentation, or stories).
13
13
14
14
## Prerequisites
15
15
@@ -155,9 +155,15 @@ At this point, all checklist items have been processed. You must review the refa
155
155
### Tools used
156
156
157
157
-`build_component_contract` - Creates component contracts for safe refactoring
158
-
- Parameters: `componentFile`, `dsComponentName` (set to "AUTO")
158
+
- Parameters: `saveLocation`, `typescriptFile` (required), `templateFile` (optional), `styleFile` (optional), `dsComponentName` (optional, set to "AUTO")
159
159
- Returns: contract path with component's public API, DOM structure, and styles
160
160
- Purpose: Establish baseline for validation comparison
161
+
- Note: Template and style files are optional for components with inline templates/styles
162
+
163
+
-`get-ds-component-data` - Retrieves Design System component information when needed
164
+
- Parameters: `componentName`, `sections` (optional) - Array of sections to include: "implementation", "documentation", "stories", "all"
165
+
- Returns: Selective component data based on refactoring needs
166
+
- Purpose: Access DS component documentation and examples for proper implementation patterns
161
167
162
168
### Flow
163
169
@@ -229,12 +235,13 @@ The rule implements a comprehensive validation process:
> Replace `<component-file.ts>` with the path to your component and set `dsComponentName` to the design-system component (e.g., `DsBadge`). The tool analyses the template, TypeScript, and styles, then saves a timestamped `*.contract.json` to
72
-
> `.cursor/tmp/contracts/<ds-component-kebab>/`.
71
+
> Replace the parameters with:
72
+
> -`saveLocation`: Path where to save the contract file (supports absolute and relative paths)
73
+
> -`typescriptFile`: Path to the TypeScript component file (.ts) — **Required**
74
+
> -`templateFile`: *(Optional)* Path to the component template file (.html). Omit for inline templates
75
+
> -`styleFile`: *(Optional)* Path to the component style file (.scss, .css, etc.). Omit for inline styles or components without styles
76
+
> -`dsComponentName`: *(Optional)* Design system component name (e.g., `DsBadge`)
77
+
>
78
+
> The tool analyses the template, TypeScript, and styles, then saves the contract to your specified location.
79
+
>
80
+
> **Note**: Angular components can have inline templates and styles. If `templateFile` or `styleFile` are not provided, the tool will extract inline template/styles from the TypeScript file.
73
81
74
82
## When to Build a Contract
75
83
@@ -160,10 +168,13 @@ What happens when QA finds a bug or a reviewer requests changes **after** the in
160
168
3.**Locate the original baseline contract** – this is the contract that was captured for the initial state (usually the very first timestamp in the folder).
161
169
4.**Generate a diff** between the baseline and the latest contract:
0 commit comments