refactor: make storybookDocsRoot and deprecatedCssClassesPath optional in MCP config

Author: Szymon.Poltorak

.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:
+     <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>
+     Then stop execution.
+   - If the function call returns any other error, respond with:
      <commentary>🚨 *Tool execution failed* – [error message]</commentary>
      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:
+     <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>
+     Then stop execution.
+   - If the function call returns any other error, respond with:
      <commentary>🚨 *Tool execution failed* – [error message]</commentary>
      Then stop execution.
    - If fileScan.rows.length is 0, respond with:

.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:
+     <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>
+     Then stop execution.
+   - If the function call returns any other error, respond with:
      <commentary>🚨 *Tool execution failed* – [error message]</commentary>
      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:
+     <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>
+     Then stop execution.
+   - If the function call returns any other error, respond with:
      <commentary>🚨 *Tool execution failed* – [error message]</commentary>
      Then stop execution.
    - If fileScan.rows.length is 0, respond with:

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

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,

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,

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(

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,

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,

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,

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 || '',
   };
 }