feat(angular-toolkit-mcp): prepare publishing

Author: Karnaukhov-kh

CONTRIBUTING.MD

@@ -13,6 +13,7 @@ Thank you for your interest in contributing to the Angular Toolkit MCP! This doc
 - [Submitting Changes](#submitting-changes)
 - [Documentation](#documentation)
 - [Debugging](#debugging)
+- [Release Process](#release-process)
 
 ## 🚀 Getting Started
 
@@ -38,7 +39,7 @@ Thank you for your interest in contributing to the Angular Toolkit MCP! This doc
 
 2. **Build the project:**
    ```bash
-   npx nx build angular-mcp
+   npx nx build @push-based/angular-toolkit-mcp
    ```
 
 ### Nx Workspace Commands
@@ -209,7 +210,7 @@ Before committing, ensure:
 Start the MCP server in debug mode:
 
 ```bash
-npx nx run angular-mcp:debug
+npx nx run @push-based/angular-toolkit-mcp:debug
 ```
 
 This starts the server with the MCP Inspector for debugging.
@@ -222,6 +223,78 @@ This starts the server with the MCP Inspector for debugging.
 - Use `console.log` or debugger statements in development
 - Test with the minimal-repo examples
 
+## 📦 Release Process
+
+### Publishing to npm
+
+The Angular Toolkit MCP is published to npm as `@push-based/angular-toolkit-mcp`. Only maintainers with appropriate permissions can publish new versions.
+
+### Release Steps
+
+1. **Update Version**
+   
+   Update the version in `packages/angular-mcp/package.json` following semantic versioning:
+   - **Patch** (0.1.0 → 0.1.1): Bug fixes
+   - **Minor** (0.1.0 → 0.2.0): New features (backwards compatible)
+   - **Major** (0.1.0 → 1.0.0): Breaking changes
+
+2. **Build the Package**
+   ```bash
+   npx nx build @push-based/angular-toolkit-mcp
+   ```
+
+3. **Test the Package**
+   ```bash
+   cd packages/angular-mcp/dist
+   npm pack
+   # Test the generated .tgz file
+   node main.js --help
+   ```
+
+4. **Authenticate with npm**
+   ```bash
+   npm login
+   ```
+   Ensure you have access to the `@push-based` scope.
+
+5. **Publish to npm**
+   ```bash
+   npm run publish:mcp
+   ```
+   Or manually:
+   ```bash
+   npx nx build @push-based/angular-toolkit-mcp
+   cd packages/angular-mcp/dist
+   npm publish
+   ```
+
+6. **Verify Publication**
+   ```bash
+   npm view @push-based/angular-toolkit-mcp
+   npx @push-based/angular-toolkit-mcp@latest --help
+   ```
+
+7. **Tag the Release**
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+8. **Update Documentation**
+   - Update CHANGELOG.md with release notes
+   - Update any version references in documentation
+
+### Pre-release Checklist
+
+Before publishing a new version:
+- [ ] All tests pass (`npx nx run-many --target=test --all`)
+- [ ] No linting errors (`npx nx run-many --target=lint --all`)
+- [ ] Build succeeds (`npx nx build @push-based/angular-toolkit-mcp`)
+- [ ] Version number updated in package.json
+- [ ] CHANGELOG.md updated with changes
+- [ ] Documentation updated as needed
+- [ ] Local npm pack test successful
+
 ## 📄 License
 
 By contributing, you agree that your contributions will be licensed under the MIT License.

README.md

@@ -20,6 +20,27 @@ A Model Context Protocol (MCP) server that provides Angular project analysis and
 - Breaking change detection during component updates
 - Code quality analysis and improvement
 
+## Quick Start
+
+Install and run via npx (no manual build required):
+
+```json
+{
+  "mcpServers": {
+    "angular-toolkit": {
+      "command": "npx",
+      "args": [
+        "@push-based/angular-toolkit-mcp@latest",
+        "--workspaceRoot=/absolute/path/to/your/angular/workspace",
+        "--ds.uiRoot=packages/ui"
+      ]
+    }
+  }
+}
+```
+
+**Required Node.js version:** 18 or higher
+
 ## Configuration
 
 ### Prerequisites
@@ -28,39 +49,63 @@ A Model Context Protocol (MCP) server that provides Angular project analysis and
 
 ### Installation & Setup
 
+#### For Users
+
+Simply use npx as shown in the Quick Start section above. No installation or build required.
+
+#### For Contributors (Local Development)
+
 1. Clone the repository
 
-2. Build the MCP
+2. Install dependencies and build the MCP
 
-  ```bash
+   ```bash
    npm install
    npx nx build angular-mcp
-  ```
+   ```
 
-2. Locate the built server
+3. Locate the built server
 
    After building, the server will be available at `packages/angular-mcp/dist/main.js`
 
 ### MCP Configuration
 
 Add the server to your MCP client configuration (e.g., Claude Desktop, Cursor, Copilot, Windsurf or other MCP-compatible clients):
 
-#### For Cursor (`.cursor/mcp.json` or MCP settings):
+#### For Users (npx - Recommended)
+
+```json
+{
+  "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.js"
+      ]
+    }
+  }
+}
+```
+
+#### For Contributors (Local Development)
 
-Copy `.cursor/mcp.json.example` to the project you're working on. Copied file should be: `.cursor/mcp.json` and update `angular-toolkit-mcp` values accordingly:
+When developing locally, point to the built server:
 
 ```json
 {
   "mcpServers": {
-     ...(other servers)...
     "angular-toolkit-mcp": {
       "command": "node",
       "args": [
-        "/absolute/path/to/angular-mcp-server/packages/angular-mcp-server/dist/index.js",
+        "/absolute/path/to/angular-toolkit-mcp/packages/angular-mcp/dist/main.js",
         "--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.js",
-        "--ds.uiRoot=relative/path/to/ui/components"
+        "--ds.deprecatedCssClassesPath=relative/path/to/component-options.js"
       ]
     }
   }

package.json

@@ -3,7 +3,9 @@
   "version": "0.0.0",
   "type": "module",
   "license": "MIT",
-  "scripts": {},
+  "scripts": {
+    "publish:mcp": "nx build @push-based/angular-toolkit-mcp && cd packages/angular-mcp/dist && npm publish"
+  },
   "private": true,
   "devDependencies": {
     "@eslint/js": "^9.28.0",

packages/angular-mcp/README.md

@@ -1,7 +1,94 @@
-# angular-mcp
+# Angular Toolkit MCP
 
-This library was generated with [Nx](https://nx.dev).
+A Model Context Protocol (MCP) server that provides Angular project analysis and refactoring capabilities. This server enables LLMs to analyze Angular projects for component usage patterns, dependency analysis, code quality issues, and provides automated refactoring assistance.
 
-## Building
+## Installation
 
-Run `nx build angular-mcp-server` to build the library.
+No installation required! Run directly with npx:
+
+```bash
+npx @push-based/angular-toolkit-mcp@latest --workspaceRoot=/path/to/workspace --ds.uiRoot=packages/ui
+```
+
+## Configuration
+
+Add the server to your MCP client configuration (e.g., Claude Desktop, Cursor, Copilot, Windsurf):
+
+```json
+{
+  "mcpServers": {
+    "angular-toolkit": {
+      "command": "npx",
+      "args": [
+        "@push-based/angular-toolkit-mcp@latest",
+        "--workspaceRoot=/absolute/path/to/your/angular/workspace",
+        "--ds.uiRoot=packages/ui",
+        "--ds.storybookDocsRoot=storybook/docs",
+        "--ds.deprecatedCssClassesPath=design-system/component-options.js"
+      ]
+    }
+  }
+}
+```
+
+### Configuration Parameters
+
+#### Required Parameters
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `workspaceRoot` | Absolute path | Root directory of your Angular workspace | `/Users/dev/my-angular-app` |
+| `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 | `storybook/docs` |
+| `ds.deprecatedCssClassesPath` | Relative path | JavaScript file mapping deprecated CSS classes | `design-system/component-options.js` |
+
+## Key Features
+
+- **Component Analysis**: Detect deprecated CSS classes and component usage violations
+- **Safe Refactoring**: Generate contracts for safe component refactoring with breaking change detection
+- **Dependency Mapping**: Map component dependencies across modules, templates, and styles
+- **ESLint Integration**: Lint Angular files with automatic ESLint configuration discovery
+- **Project Analysis**: Analyze buildable/publishable libraries and validate import paths
+- **Component Documentation**: Retrieve component data and documentation, list available components
+
+## Available Tools
+
+### Component Analysis
+- `report-violations` - Report deprecated CSS usage in a directory
+- `report-deprecated-css` - Report deprecated CSS classes found in styling files
+- `get-deprecated-css-classes` - List deprecated CSS classes for a component
+- `list-ds-components` - List all available Design System components
+- `get-ds-component-data` - Get component data including implementation and documentation
+- `build-component-usage-graph` - Map component imports across the project
+
+### Component Contracts
+- `build_component_contract` - Generate a static surface contract for a component
+- `diff_component_contract` - Compare before/after contracts for breaking changes
+- `list_component_contracts` - List all available component contracts
+
+### Project Analysis
+- `get-project-dependencies` - Analyze project dependencies and library configuration
+- `lint-changes` - Lint changed Angular files using ESLint rules
+
+## Requirements
+
+- Node.js version 18 or higher
+
+## Documentation
+
+For comprehensive documentation, guides, and workflows, see the [full documentation](https://github.com/push-based/angular-toolkit-mcp).
+
+## License
+
+MIT License - see the [LICENSE](https://github.com/push-based/angular-toolkit-mcp/blob/main/LICENSE) file for details.
+
+---
+
+<div align="center">
+  <p><strong>Sponsored by Entain</strong></p>
+</div>

packages/angular-mcp/package.json

@@ -1,8 +1,31 @@
 {
-  "name": "@push-based/angular-mcp",
-  "version": "0.0.1",
-  "private": true,
-  "bin": "main.js",
+  "name": "@push-based/angular-toolkit-mcp",
+  "version": "0.1.0",
+  "description": "A Model Context Protocol server for Angular project analysis and refactoring",
+  "keywords": [
+    "mcp",
+    "angular",
+    "refactoring",
+    "analysis",
+    "model-context-protocol"
+  ],
+  "author": "Push-Based",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/push-based/angular-toolkit-mcp.git"
+  },
+  "homepage": "https://github.com/push-based/angular-toolkit-mcp",
+  "bugs": "https://github.com/push-based/angular-toolkit-mcp/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "angular-toolkit-mcp": "main.js"
+  },
   "files": [
     "main.js",
     "README.md"

packages/angular-mcp/src/main.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import express from 'express';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

packages/angular-mcp/webpack.config.cjs

@@ -1,5 +1,6 @@
 const { NxAppWebpackPlugin } = require('@nx/webpack/app-plugin');
 const { join } = require('path');
+const webpack = require('webpack');
 
 module.exports = {
   output: {
@@ -11,10 +12,22 @@ module.exports = {
       compiler: 'tsc',
       main: './src/main.ts',
       tsConfig: './tsconfig.app.json',
-      assets: ['./src/assets'],
+      assets: [
+        './src/assets',
+        {
+          input: '.',
+          glob: 'README.md',
+          output: '.',
+        },
+      ],
       optimization: false,
       outputHashing: 'none',
       generatePackageJson: true,
     }),
+    new webpack.BannerPlugin({
+      banner: '#!/usr/bin/env node',
+      raw: true,
+      entryOnly: true,
+    }),
   ],
 };