Angular Toolkit

You can analyze Angular projects, identify deprecated patterns, map dependencies, and perform safe refactoring with this MCP server. It provides automated tooling to inspect components, validate imports, and generate contracts that help you implement breaking changes safely while improving code quality across your Angular workspace.

How to use

To use this MCP server, connect it to an MCP client (such as Claude Desktop, Cursor, Copilot, Windsurf, or other compatible clients) and start querying it for component analysis, dependency mapping, and refactoring guidance. You can request reports on deprecated CSS classes, fetch component data and documentation, and generate contracts to validate refactor changes before applying them.

How to install

Prerequisites: ensure you have Node.js version 18 or higher installed on your system.

{
  "mcpServers": {
    "angular-toolkit": {
      "command": "npx",
      "args": [
        "@push-based/angular-toolkit-mcp@latest",
        "--workspaceRoot=/absolute/path/to/your/angular/workspace",
        "--ds.uiRoot=relative/path/to/ui/components",
        "--ds.storybookDocsRoot=relative/path/to/storybook/docs",
        "--ds.deprecatedCssClassesPath=relative/path/to/component-options.mjs"
      ]
    }
  }
}

Configuration

Prerequisites include Node.js version 18 or higher with ESM support. You can run the MCP server via npx to avoid manual builds.

Configuration details and setup notes

For users, the recommended setup uses npx to run the MCP server directly from the registry with a workspace root and optional documentation and deprecated CSS mapping paths. The following configuration shows all of the options you may provide.

{
  "mcpServers": {
    "angular-toolkit": {
      "command": "npx",
      "args": [
        "@push-based/angular-toolkit-mcp@latest",
        "--workspaceRoot=/absolute/path/to/your/angular/workspace",
        "--ds.uiRoot=relative/path/to/ui/components",
        "--ds.storybookDocsRoot=relative/path/to/storybook/docs",
        "--ds.deprecatedCssClassesPath=relative/path/to/component-options.mjs"
      ]
    }
  }
}

Troubleshooting

If the server does not start, verify all paths are correct and that the server was built if necessary. Check file permissions to ensure the Node.js process can read the configured directories. If a component cannot be found, confirm that the component names in your mapping file match your actual component class names. For path resolution issues, use absolute paths for workspaceRoot and relative paths from the workspace root for other parameters.

Component analysis and workflow

The MCP server provides a range of tools to help you analyze Angular projects and manage refactoring safely. You can generate initial contracts before refactoring, perform changes, generate new contracts after the changes, and compare contracts to detect breaking changes.

Angular project integration

This MCP server is designed to assist with migration planning, refactoring safety, access to component documentation and examples, and overall code quality improvements across your Angular project.

Notes

Optional documentation and CSS mapping parameters may be omitted. If omitted, their related tools will skip lookups or fail gracefully with clear prompts to provide the missing information when required.

Contributing

If you contribute, follow the standard contribution guidelines for setting up a local development environment, building the MCP, and running the server for testing.

License

This project is licensed under the MIT License.

Available tools

report-violations

Reports deprecated CSS usage for a specific component in a directory and can output statistics to a file.

report-all-violations

Reports all deprecated CSS usage across all components in a directory and can output statistics.

group-violations

Creates balanced work distribution groups from violations reports while preserving directory boundaries.

report-deprecated-css

Reports deprecated CSS classes found in styling files.

get-deprecated-css-classes

Lists deprecated CSS classes for a component.

list-ds-components

Lists all available Design System components with their file paths and metadata.

get-ds-component-data

Returns data for a component, including implementation files, documentation files, and import paths.

build-component-usage-graph

Maps where given Angular components are imported across modules, specs, templates, and styles.

build_component_contract

Generates a static surface contract for a component's template and SCSS.

diff_component_contract

Compares before/after contracts to detect breaking changes.

list_component_contracts

Lists all available component contracts in the contracts directory.

get-project-dependencies

Analyzes project dependencies and validates import paths for components, including buildability/publishability checks.

lint-changes

Lints changed Angular files using ESLint with automatic config resolution.