From e46e7409ee469e312f52cf40e4567f4324787927 Mon Sep 17 00:00:00 2001 From: "Szymon.Poltorak" Date: Thu, 4 Sep 2025 10:18:35 +0200 Subject: [PATCH 1/5] Remove .cursor/mcp.json from tracking (now in .gitignore) --- .cursor/mcp.json | 22 ---------------------- 1 file changed, 22 deletions(-) delete mode 100644 .cursor/mcp.json diff --git a/.cursor/mcp.json b/.cursor/mcp.json deleted file mode 100644 index dc83135..0000000 --- a/.cursor/mcp.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "mcpServers": { - "nx-mcp": { - "url": "http://localhost:9665/sse" - }, - "angular-toolkit-mcp": { - "command": "node", - "args": [ - "./packages/angular-mcp/dist/main.js", - "--workspaceRoot=/home/spoltorak/projects/x-mcp", - "--ds.storybookDocsRoot=packages/minimal-repo/packages/design-system/storybook-host-app/src/components", - "--ds.deprecatedCssClassesPath=packages/minimal-repo/packages/design-system/component-options.js", - "--ds.uiRoot=packages/minimal-repo/packages/design-system/ui" - ] - }, - "ESLint": { - "type": "stdio", - "command": "npx", - "args": ["@eslint/mcp@latest"] - } - } -} From ebcb397f12e4e06ce829b339842ac3a96c7917e0 Mon Sep 17 00:00:00 2001 From: "Szymon.Poltorak" Date: Wed, 10 Sep 2025 12:11:02 +0200 Subject: [PATCH 2/5] refactor: make storybookDocsRoot and deprecatedCssClassesPath optional in MCP config --- .../01-find-violations.mdc | 10 ++++- .../01b-find-all-violations.mdc | 10 ++++- README.md | 39 ++++++++++++++++++- .../src/lib/angular-mcp-server.ts | 18 ++++++--- .../get-deprecated-css-classes.tool.ts | 5 +++ .../component/get-ds-component-data.tool.ts | 4 +- .../ds/component/list-ds-components.tool.ts | 7 ++-- .../ds/project/report-deprecated-css.tool.ts | 6 +++ .../report-all-violations.tool.ts | 5 +++ .../tools/ds/shared/utils/handler-helpers.ts | 8 ++-- .../violation-analysis/base-analyzer.ts | 6 +++ .../angular-mcp-server-options.schema.ts | 22 +++++++---- .../ds-components-file.validation.ts | 7 +++- .../src/lib/validation/file-existence.ts | 17 +++++--- packages/angular-mcp/src/main.ts | 4 +- 15 files changed, 131 insertions(+), 37 deletions(-) diff --git a/.cursor/flows/ds-refactoring-flow/01-find-violations.mdc b/.cursor/flows/ds-refactoring-flow/01-find-violations.mdc index 9cee81b..70a0d9d 100644 --- a/.cursor/flows/ds-refactoring-flow/01-find-violations.mdc +++ b/.cursor/flows/ds-refactoring-flow/01-find-violations.mdc @@ -19,7 +19,10 @@ Step 1: Find violations Store the result in a variable called scanResult. 2. Perform first-level error handling: - - If the function call returns an error, respond with: + - If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with: + ⚠️ *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. + Then stop execution. + - If the function call returns any other error, respond with: 🚨 *Tool execution failed* – [error message] Then stop execution. - If scanResult.totalViolations is 0, respond with: @@ -57,7 +60,10 @@ Once the user provides a subfolder choice, proceed as follows: - Store the result in a variable called fileScan. 3. Perform error handling and validation: - - If the function call returns an error, respond with: + - If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with: + ⚠️ *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. + Then stop execution. + - If the function call returns any other error, respond with: 🚨 *Tool execution failed* – [error message] Then stop execution. - If fileScan.rows.length is 0, respond with: diff --git a/.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc b/.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc index 714da1b..5a86f6b 100644 --- a/.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc +++ b/.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc @@ -17,7 +17,10 @@ Step 1: Find violations Store the result in a variable called scanResult. 2. Perform first-level error handling: - - If the function call returns an error, respond with: + - If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with: + ⚠️ *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. + Then stop execution. + - If the function call returns any other error, respond with: 🚨 *Tool execution failed* – [error message] Then stop execution. - If no violations are found, respond with: @@ -54,7 +57,10 @@ Once the user provides a subfolder choice, proceed as follows: - Store the result in a variable called fileScan. 3. Perform error handling and validation: - - If the function call returns an error, respond with: + - If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with: + ⚠️ *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. + Then stop execution. + - If the function call returns any other error, respond with: 🚨 *Tool execution failed* – [error message] Then stop execution. - If fileScan.rows.length is 0, respond with: diff --git a/README.md b/README.md index 11e3a4b..8e943fc 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,8 @@ Copy `.cursor/mcp.json.example` to the project you're working on. Copied file sh } ``` +> 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. + > **Note**: The example file contains configuration for `ESLint` official MCP which is required for the toolkit to work properly. ### Configuration Parameters @@ -76,10 +78,20 @@ Copy `.cursor/mcp.json.example` to the project you're working on. Copied file sh | Parameter | Type | Description | Example | |-----------|------|-------------|---------| | `workspaceRoot` | Absolute path | Root directory of your Angular workspace | `/Users/dev/my-angular-app` | -| `ds.storybookDocsRoot` | Relative path | Root directory containing Storybook documentation | `storybook/docs` | -| `ds.deprecatedCssClassesPath` | Relative path | JavaScript file mapping deprecated CSS classes | `design-system/component-options.js` | | `ds.uiRoot` | Relative path | Directory containing UI components | `packages/ui` | +#### Optional Parameters + +| Parameter | Type | Description | Example | +|-----------|------|-------------|---------| +| `ds.storybookDocsRoot` | Relative path | Root directory containing Storybook documentation used by documentation-related tools | `storybook/docs` | +| `ds.deprecatedCssClassesPath` | Relative path | JavaScript file mapping deprecated CSS classes used by violation and deprecated CSS tools | `design-system/component-options.js` | + +When optional parameters are omitted: + +- `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). +- `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`. + #### Deprecated CSS Classes File Format The `component-options.js` file should export an array of component configurations: @@ -141,6 +153,29 @@ my-angular-workspace/ - **`build-component-usage-graph`**: Maps where given Angular components are imported (modules, specs, templates, styles) so refactors touch every file +### Tool behavior with optional parameters + +The following tools work without optional params: + +- `get-project-dependencies` +- `build-component-usage-graph` +- `get-ds-component-data` (documentation section is empty if `ds.storybookDocsRoot` is not set) +- Component contract tools: + - `build_component_contract` + - `diff_component_contract` + - `list_component_contracts` + +The following tools require optional params to work: + +- Requires `ds.deprecatedCssClassesPath`: + - `get-deprecated-css-classes` + - `report-deprecated-css` + - `report-all-violations` + - `report-violations` + +- Requires `ds.storybookDocsRoot` for docs lookup (skipped otherwise): + - `get-ds-component-data` (docs files discovery only) + ### Component Contracts - **`build_component_contract`**: Generate a static surface contract for a component's template and SCSS diff --git a/packages/angular-mcp-server/src/lib/angular-mcp-server.ts b/packages/angular-mcp-server/src/lib/angular-mcp-server.ts index 8b7857f..11146f8 100644 --- a/packages/angular-mcp-server/src/lib/angular-mcp-server.ts +++ b/packages/angular-mcp-server/src/lib/angular-mcp-server.ts @@ -25,8 +25,8 @@ import { validateDeprecatedCssClassesFile } from './validation/ds-components-fil export class AngularMcpServerWrapper { private readonly mcpServer: McpServer; private readonly workspaceRoot: string; - private readonly storybookDocsRoot: string; - private readonly deprecatedCssClassesPath: string; + private readonly storybookDocsRoot?: string; + private readonly deprecatedCssClassesPath?: string; private readonly uiRoot: string; /** @@ -71,11 +71,13 @@ export class AngularMcpServerWrapper { // Validate config using the Zod schema - only once here const validatedConfig = AngularMcpServerOptionsSchema.parse(config); - // Validate file existence + // Validate file existence (optional keys are checked only when provided) validateAngularMcpServerFilesExist(validatedConfig); - // Load and validate deprecatedCssClassesPath content - await validateDeprecatedCssClassesFile(validatedConfig); + // Load and validate deprecatedCssClassesPath content only if provided + if (validatedConfig.ds.deprecatedCssClassesPath) { + await validateDeprecatedCssClassesFile(validatedConfig); + } return new AngularMcpServerWrapper(validatedConfig); } @@ -140,6 +142,12 @@ export class AngularMcpServerWrapper { // Scan available design system components to add them as discoverable resources try { + if (!this.storybookDocsRoot) { + return { + resources, + }; + } + const dsUiPath = path.resolve( process.cwd(), this.storybookDocsRoot, diff --git a/packages/angular-mcp-server/src/lib/tools/ds/component/get-deprecated-css-classes.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/component/get-deprecated-css-classes.tool.ts index 1fb33a1..f8d35b7 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/component/get-deprecated-css-classes.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/component/get-deprecated-css-classes.tool.ts @@ -28,6 +28,11 @@ export const getDeprecatedCssClassesHandler = createHandler< >( getDeprecatedCssClassesSchema.name, async ({ componentName }, { cwd, deprecatedCssClassesPath }) => { + if (!deprecatedCssClassesPath) { + throw new Error( + 'Missing ds.deprecatedCssClassesPath. Provide it when starting the server to use this tool.', + ); + } return getDeprecatedCssClasses( componentName, deprecatedCssClassesPath, diff --git a/packages/angular-mcp-server/src/lib/tools/ds/component/get-ds-component-data.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/component/get-ds-component-data.tool.ts index 43e3049..cae45dd 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/component/get-ds-component-data.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/component/get-ds-component-data.tool.ts @@ -137,7 +137,7 @@ export const getDsComponentDataHandler = createHandler< } const documentationFiles: string[] = []; - if (includeDocumentation) { + if (includeDocumentation && storybookDocsRoot) { const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); const docPaths = getComponentDocPathsForName( docsBasePath, @@ -153,7 +153,7 @@ export const getDsComponentDataHandler = createHandler< } let storiesFilePaths: string[] = []; - if (includeStories) { + if (includeStories && storybookDocsRoot) { const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); const componentFolderName = componentNameToKebabCase(componentName); const storiesComponentFolderPath = path.join( diff --git a/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts index d657a35..31704e5 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts @@ -150,7 +150,6 @@ export const listDsComponentsHandler = createHandler< }); const components: DsComponentInfo[] = []; - const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); const includeAll = sections.includes('all'); const includeImplementation = @@ -172,7 +171,8 @@ export const listDsComponentsHandler = createHandler< } const documentationFiles: string[] = []; - if (includeDocumentation) { + if (includeDocumentation && storybookDocsRoot) { + const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); const docPaths = getComponentDocPathsForName( docsBasePath, componentName, @@ -187,7 +187,8 @@ export const listDsComponentsHandler = createHandler< } let storiesFilePaths: string[] = []; - if (includeStories) { + if (includeStories && storybookDocsRoot) { + const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); const storiesComponentFolderPath = path.join( docsBasePath, folderName, diff --git a/packages/angular-mcp-server/src/lib/tools/ds/project/report-deprecated-css.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/project/report-deprecated-css.tool.ts index 5c2e4d1..b2a2ab3 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/project/report-deprecated-css.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/project/report-deprecated-css.tool.ts @@ -42,6 +42,12 @@ export const reportDeprecatedCssHandler = createHandler< async (params, { cwd, deprecatedCssClassesPath }) => { const { directory, componentName } = params; + if (!deprecatedCssClassesPath) { + throw new Error( + 'Missing ds.deprecatedCssClassesPath. Provide it when starting the server to use this tool.', + ); + } + const deprecated = getDeprecatedCssClasses( componentName, deprecatedCssClassesPath, diff --git a/packages/angular-mcp-server/src/lib/tools/ds/report-violations/report-all-violations.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/report-violations/report-all-violations.tool.ts index a624d56..3ee8434 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/report-violations/report-all-violations.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/report-violations/report-all-violations.tool.ts @@ -47,6 +47,11 @@ export const reportAllViolationsHandler = createHandler< >( reportAllViolationsSchema.name, async (params, { cwd, deprecatedCssClassesPath }) => { + if (!deprecatedCssClassesPath) { + throw new Error( + 'Missing ds.deprecatedCssClassesPath. Provide it when starting the server to use this tool.', + ); + } const groupBy = params.groupBy || 'file'; const dsComponents = await loadAndValidateDsComponentsFile( cwd, diff --git a/packages/angular-mcp-server/src/lib/tools/ds/shared/utils/handler-helpers.ts b/packages/angular-mcp-server/src/lib/tools/ds/shared/utils/handler-helpers.ts index 76a6e44..a446a17 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/shared/utils/handler-helpers.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/shared/utils/handler-helpers.ts @@ -26,8 +26,8 @@ export interface BaseHandlerOptions { export interface HandlerContext { cwd: string; workspaceRoot: string; - storybookDocsRoot: string; - deprecatedCssClassesPath: string; + storybookDocsRoot?: string; + deprecatedCssClassesPath?: string; uiRoot: string; } @@ -60,8 +60,8 @@ export function setupHandlerEnvironment( return { cwd, workspaceRoot: params.workspaceRoot || cwd, - storybookDocsRoot: params.storybookDocsRoot || '', - deprecatedCssClassesPath: params.deprecatedCssClassesPath || '', + storybookDocsRoot: params.storybookDocsRoot, + deprecatedCssClassesPath: params.deprecatedCssClassesPath, uiRoot: params.uiRoot || '', }; } diff --git a/packages/angular-mcp-server/src/lib/tools/ds/shared/violation-analysis/base-analyzer.ts b/packages/angular-mcp-server/src/lib/tools/ds/shared/violation-analysis/base-analyzer.ts index 302021b..f6ad047 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/shared/violation-analysis/base-analyzer.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/shared/violation-analysis/base-analyzer.ts @@ -29,6 +29,12 @@ export async function analyzeViolationsBase( process.chdir(cwd); + if (!deprecatedCssClassesPath) { + throw new Error( + 'Missing ds.deprecatedCssClassesPath. Provide it when starting the server to use this tool.', + ); + } + const deprecatedCssClasses = getDeprecatedCssClasses( componentName, deprecatedCssClassesPath || '', diff --git a/packages/angular-mcp-server/src/lib/validation/angular-mcp-server-options.schema.ts b/packages/angular-mcp-server/src/lib/validation/angular-mcp-server-options.schema.ts index 4237a03..acbfd04 100644 --- a/packages/angular-mcp-server/src/lib/validation/angular-mcp-server-options.schema.ts +++ b/packages/angular-mcp-server/src/lib/validation/angular-mcp-server-options.schema.ts @@ -10,14 +10,20 @@ export const AngularMcpServerOptionsSchema = z.object({ 'workspaceRoot must be an absolute path to the repository root where MCP server is working (e.g., /path/to/workspace-root)', }), ds: z.object({ - storybookDocsRoot: z.string().refine(isRelativePath, { - message: - 'ds.storybookDocsRoot must be a relative path from workspace root to the storybook project root (e.g., path/to/storybook/components)', - }), - deprecatedCssClassesPath: z.string().refine(isRelativePath, { - message: - 'ds.deprecatedCssClassesPath must be a relative path from workspace root to the file component to deprecated css classes mapping (e.g., path/to/components-config.js)', - }), + storybookDocsRoot: z + .string() + .optional() + .refine((val) => val === undefined || isRelativePath(val), { + message: + 'ds.storybookDocsRoot must be a relative path from workspace root to the storybook project root (e.g., path/to/storybook/components)', + }), + deprecatedCssClassesPath: z + .string() + .optional() + .refine((val) => val === undefined || isRelativePath(val), { + message: + 'ds.deprecatedCssClassesPath must be a relative path from workspace root to the file component to deprecated css classes mapping (e.g., path/to/components-config.js)', + }), uiRoot: z.string().refine(isRelativePath, { message: 'ds.uiRoot must be a relative path from workspace root to the components folder (e.g., path/to/components)', diff --git a/packages/angular-mcp-server/src/lib/validation/ds-components-file.validation.ts b/packages/angular-mcp-server/src/lib/validation/ds-components-file.validation.ts index c8012e3..45bd857 100644 --- a/packages/angular-mcp-server/src/lib/validation/ds-components-file.validation.ts +++ b/packages/angular-mcp-server/src/lib/validation/ds-components-file.validation.ts @@ -6,9 +6,14 @@ import { DsComponentsArraySchema } from './ds-components.schema'; export async function validateDeprecatedCssClassesFile( config: AngularMcpServerOptions, ): Promise { + const relPath = config.ds.deprecatedCssClassesPath; + if (!relPath) { + // Optional parameter not provided; nothing to validate + return; + } const deprecatedCssClassesAbsPath = path.resolve( config.workspaceRoot, - config.ds.deprecatedCssClassesPath, + relPath, ); let dsComponents; diff --git a/packages/angular-mcp-server/src/lib/validation/file-existence.ts b/packages/angular-mcp-server/src/lib/validation/file-existence.ts index f2ecdf6..6ad8253 100644 --- a/packages/angular-mcp-server/src/lib/validation/file-existence.ts +++ b/packages/angular-mcp-server/src/lib/validation/file-existence.ts @@ -13,14 +13,19 @@ export function validateAngularMcpServerFilesExist( const missingFiles: string[] = []; + // Always require uiRoot, optional: storybookDocsRoot, deprecatedCssClassesPath const dsPaths = [ - { label: 'ds.storybookDocsRoot', relPath: config.ds.storybookDocsRoot }, - { - label: 'ds.deprecatedCssClassesPath', - relPath: config.ds.deprecatedCssClassesPath, - }, + config.ds.storybookDocsRoot + ? { label: 'ds.storybookDocsRoot', relPath: config.ds.storybookDocsRoot } + : null, + config.ds.deprecatedCssClassesPath + ? { + label: 'ds.deprecatedCssClassesPath', + relPath: config.ds.deprecatedCssClassesPath, + } + : null, { label: 'ds.uiRoot', relPath: config.ds.uiRoot }, - ]; + ].filter(Boolean) as { label: string; relPath: string }[]; for (const { label, relPath } of dsPaths) { const absPath = path.resolve(root, relPath); diff --git a/packages/angular-mcp/src/main.ts b/packages/angular-mcp/src/main.ts index aeef3f1..07a9065 100644 --- a/packages/angular-mcp/src/main.ts +++ b/packages/angular-mcp/src/main.ts @@ -60,8 +60,8 @@ const argv = yargs(hideBin(process.argv)) const { workspaceRoot, ds } = argv as unknown as { workspaceRoot: string; ds: { - storybookDocsRoot: string; - deprecatedCssClassesPath: string; + storybookDocsRoot?: string; + deprecatedCssClassesPath?: string; uiRoot: string; }; }; From 5cd18e0947aec12d960ee5582240f7617e5482c7 Mon Sep 17 00:00:00 2001 From: "Szymon.Poltorak" Date: Wed, 10 Sep 2025 13:30:33 +0200 Subject: [PATCH 3/5] fix(): update prompts to fully respect missing param --- .cursor/flows/ds-refactoring-flow/01-find-violations.mdc | 2 +- .cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.cursor/flows/ds-refactoring-flow/01-find-violations.mdc b/.cursor/flows/ds-refactoring-flow/01-find-violations.mdc index 70a0d9d..255899c 100644 --- a/.cursor/flows/ds-refactoring-flow/01-find-violations.mdc +++ b/.cursor/flows/ds-refactoring-flow/01-find-violations.mdc @@ -19,7 +19,7 @@ Step 1: Find violations Store the result in a variable called scanResult. 2. Perform first-level error handling: - - If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with: + - If the function call returns an error or result containing "Missing ds.deprecatedCssClassesPath", respond with: ⚠️ *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. Then stop execution. - If the function call returns any other error, respond with: diff --git a/.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc b/.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc index 5a86f6b..0ee4864 100644 --- a/.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc +++ b/.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc @@ -17,7 +17,7 @@ Step 1: Find violations Store the result in a variable called scanResult. 2. Perform first-level error handling: - - If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with: + - If the function call returns an error or result containing "Missing ds.deprecatedCssClassesPath", respond with: ⚠️ *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. Then stop execution. - If the function call returns any other error, respond with: From 06e8fbd66bd9fef024227433cd0638df3310f91e Mon Sep 17 00:00:00 2001 From: "Szymon.Poltorak" Date: Wed, 10 Sep 2025 13:32:02 +0200 Subject: [PATCH 4/5] chore: formatting --- .../lib/tools/ds/component/list-ds-components.tool.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts index 31704e5..3ba4328 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts @@ -172,7 +172,10 @@ export const listDsComponentsHandler = createHandler< const documentationFiles: string[] = []; if (includeDocumentation && storybookDocsRoot) { - const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); + const docsBasePath = resolveCrossPlatformPath( + cwd, + storybookDocsRoot, + ); const docPaths = getComponentDocPathsForName( docsBasePath, componentName, @@ -188,7 +191,10 @@ export const listDsComponentsHandler = createHandler< let storiesFilePaths: string[] = []; if (includeStories && storybookDocsRoot) { - const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); + const docsBasePath = resolveCrossPlatformPath( + cwd, + storybookDocsRoot, + ); const storiesComponentFolderPath = path.join( docsBasePath, folderName, From 0eddc82b258e6f1c539f801191b227d271ec989c Mon Sep 17 00:00:00 2001 From: "Szymon.Poltorak" Date: Thu, 11 Sep 2025 09:30:21 +0200 Subject: [PATCH 5/5] fix: error message about missing param, unify if condition --- .../get-deprecated-css-classes.tool.ts | 2 +- .../component/get-ds-component-data.tool.ts | 45 +++++++++--------- .../ds/component/list-ds-components.tool.ts | 46 +++++++++---------- .../ds/project/report-deprecated-css.tool.ts | 2 +- .../report-all-violations.tool.ts | 2 +- .../violation-analysis/base-analyzer.ts | 2 +- 6 files changed, 51 insertions(+), 48 deletions(-) diff --git a/packages/angular-mcp-server/src/lib/tools/ds/component/get-deprecated-css-classes.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/component/get-deprecated-css-classes.tool.ts index f8d35b7..ceacbf4 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/component/get-deprecated-css-classes.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/component/get-deprecated-css-classes.tool.ts @@ -30,7 +30,7 @@ export const getDeprecatedCssClassesHandler = createHandler< async ({ componentName }, { cwd, deprecatedCssClassesPath }) => { if (!deprecatedCssClassesPath) { throw new Error( - 'Missing ds.deprecatedCssClassesPath. Provide it when starting the server to use this tool.', + 'Missing ds.deprecatedCssClassesPath. Provide --ds.deprecatedCssClassesPath in mcp.json file.', ); } return getDeprecatedCssClasses( diff --git a/packages/angular-mcp-server/src/lib/tools/ds/component/get-ds-component-data.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/component/get-ds-component-data.tool.ts index cae45dd..4ae1c44 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/component/get-ds-component-data.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/component/get-ds-component-data.tool.ts @@ -137,31 +137,34 @@ export const getDsComponentDataHandler = createHandler< } const documentationFiles: string[] = []; - if (includeDocumentation && storybookDocsRoot) { + + let storiesFilePaths: string[] = []; + if (storybookDocsRoot) { const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); - const docPaths = getComponentDocPathsForName( - docsBasePath, - componentName, - ); - if (fs.existsSync(docPaths.paths.api)) { - documentationFiles.push(`file://${docPaths.paths.api}`); + if (includeDocumentation) { + const docPaths = getComponentDocPathsForName( + docsBasePath, + componentName, + ); + + if (fs.existsSync(docPaths.paths.api)) { + documentationFiles.push(`file://${docPaths.paths.api}`); + } + if (fs.existsSync(docPaths.paths.overview)) { + documentationFiles.push(`file://${docPaths.paths.overview}`); + } } - if (fs.existsSync(docPaths.paths.overview)) { - documentationFiles.push(`file://${docPaths.paths.overview}`); - } - } - let storiesFilePaths: string[] = []; - if (includeStories && storybookDocsRoot) { - const docsBasePath = resolveCrossPlatformPath(cwd, storybookDocsRoot); - const componentFolderName = componentNameToKebabCase(componentName); - const storiesComponentFolderPath = path.join( - docsBasePath, - componentFolderName, - ); - const storiesFiles = findStoriesFiles(storiesComponentFolderPath); - storiesFilePaths = storiesFiles.map((file) => `file://${file}`); + if (includeStories) { + const componentFolderName = componentNameToKebabCase(componentName); + const storiesComponentFolderPath = path.join( + docsBasePath, + componentFolderName, + ); + const storiesFiles = findStoriesFiles(storiesComponentFolderPath); + storiesFilePaths = storiesFiles.map((file) => `file://${file}`); + } } return { diff --git a/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts index 3ba4328..0169511 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/component/list-ds-components.tool.ts @@ -171,36 +171,36 @@ export const listDsComponentsHandler = createHandler< } const documentationFiles: string[] = []; - if (includeDocumentation && storybookDocsRoot) { + + let storiesFilePaths: string[] = []; + if (storybookDocsRoot) { const docsBasePath = resolveCrossPlatformPath( cwd, storybookDocsRoot, ); - const docPaths = getComponentDocPathsForName( - docsBasePath, - componentName, - ); - if (fs.existsSync(docPaths.paths.api)) { - documentationFiles.push(`file://${docPaths.paths.api}`); + if (includeDocumentation) { + const docPaths = getComponentDocPathsForName( + docsBasePath, + componentName, + ); + + if (fs.existsSync(docPaths.paths.api)) { + documentationFiles.push(`file://${docPaths.paths.api}`); + } + if (fs.existsSync(docPaths.paths.overview)) { + documentationFiles.push(`file://${docPaths.paths.overview}`); + } } - if (fs.existsSync(docPaths.paths.overview)) { - documentationFiles.push(`file://${docPaths.paths.overview}`); - } - } - let storiesFilePaths: string[] = []; - if (includeStories && storybookDocsRoot) { - const docsBasePath = resolveCrossPlatformPath( - cwd, - storybookDocsRoot, - ); - const storiesComponentFolderPath = path.join( - docsBasePath, - folderName, - ); - const storiesFiles = findStoriesFiles(storiesComponentFolderPath); - storiesFilePaths = storiesFiles.map((file) => `file://${file}`); + if (includeStories) { + const storiesComponentFolderPath = path.join( + docsBasePath, + folderName, + ); + const storiesFiles = findStoriesFiles(storiesComponentFolderPath); + storiesFilePaths = storiesFiles.map((file) => `file://${file}`); + } } components.push({ diff --git a/packages/angular-mcp-server/src/lib/tools/ds/project/report-deprecated-css.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/project/report-deprecated-css.tool.ts index b2a2ab3..5af3b82 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/project/report-deprecated-css.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/project/report-deprecated-css.tool.ts @@ -44,7 +44,7 @@ export const reportDeprecatedCssHandler = createHandler< if (!deprecatedCssClassesPath) { throw new Error( - 'Missing ds.deprecatedCssClassesPath. Provide it when starting the server to use this tool.', + 'Missing ds.deprecatedCssClassesPath. Provide --ds.deprecatedCssClassesPath in mcp.json file.', ); } diff --git a/packages/angular-mcp-server/src/lib/tools/ds/report-violations/report-all-violations.tool.ts b/packages/angular-mcp-server/src/lib/tools/ds/report-violations/report-all-violations.tool.ts index 3ee8434..b57a622 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/report-violations/report-all-violations.tool.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/report-violations/report-all-violations.tool.ts @@ -49,7 +49,7 @@ export const reportAllViolationsHandler = createHandler< async (params, { cwd, deprecatedCssClassesPath }) => { if (!deprecatedCssClassesPath) { throw new Error( - 'Missing ds.deprecatedCssClassesPath. Provide it when starting the server to use this tool.', + 'Missing ds.deprecatedCssClassesPath. Provide --ds.deprecatedCssClassesPath in mcp.json file.', ); } const groupBy = params.groupBy || 'file'; diff --git a/packages/angular-mcp-server/src/lib/tools/ds/shared/violation-analysis/base-analyzer.ts b/packages/angular-mcp-server/src/lib/tools/ds/shared/violation-analysis/base-analyzer.ts index f6ad047..11df2fa 100644 --- a/packages/angular-mcp-server/src/lib/tools/ds/shared/violation-analysis/base-analyzer.ts +++ b/packages/angular-mcp-server/src/lib/tools/ds/shared/violation-analysis/base-analyzer.ts @@ -31,7 +31,7 @@ export async function analyzeViolationsBase( if (!deprecatedCssClassesPath) { throw new Error( - 'Missing ds.deprecatedCssClassesPath. Provide it when starting the server to use this tool.', + 'Missing ds.deprecatedCssClassesPath. Provide --ds.deprecatedCssClassesPath in mcp.json file.', ); }