Merge pull request #19 from push-based/feature/esm-migration

feat(angular-toolkit-mcp): prepare publishing

Author: Karnaukhov-kh

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
           node-version: 20
           cache: 'npm'
 
-      - run: npm ci --legacy-peer-deps
+      - run: npm ci
       - uses: nrwl/nx-set-shas@v4
       - run: npx nx format:check
 

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 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 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 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 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 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.mjs"
+      ]
+    }
+  }
+}
+```
+
+#### 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.mjs"
       ]
     }
   }
@@ -85,7 +130,7 @@ Copy `.cursor/mcp.json.example` to the project you're working on. Copied file sh
 | 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` |
+| `ds.deprecatedCssClassesPath` | Relative path | JavaScript file mapping deprecated CSS classes used by violation and deprecated CSS tools | `design-system/component-options.mjs` |
 
 When optional parameters are omitted:
 
@@ -94,7 +139,7 @@ When optional parameters are omitted:
 
 #### Deprecated CSS Classes File Format
 
-The `component-options.js` file should export an array of component configurations:
+The `component-options.mjs` file should export an array of component configurations:
 
 ```javascript
 const dsComponents = [
@@ -121,7 +166,7 @@ my-angular-workspace/
 │   │   ├── modal/
 │   │   └── ...
 │   └── design-system/
-│       └── component-options.js      # ds.deprecatedCssClassesPath
+│       └── component-options.mjs     # ds.deprecatedCssClassesPath
 ├── storybook/
 │   └── docs/                         # ds.storybookDocsRoot
 └── apps/
@@ -132,7 +177,7 @@ my-angular-workspace/
 
 - **Server not starting**: Ensure all paths are correct and the server is built
 - **Permission errors**: Check that the Node.js process has read access to all specified directories
-- **Component not found**: Verify that component names in `component-options.js` match your actual component class names
+- **Component not found**: Verify that component names in `component-options.mjs` match your actual component class names
 - **Path resolution issues**: Use absolute paths for `workspaceRoot` and relative paths (from workspace root) for other parameters
 
 ## Available Tools

docs/getting-started.md

@@ -44,7 +44,7 @@ Instead of the palette-based flow, copy the manual configuration from your works
         "./packages/angular-mcp/dist/main.js",
         "--workspaceRoot=/absolute/path/to/angular-toolkit-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.deprecatedCssClassesPath=packages/minimal-repo/packages/design-system/component-options.mjs",
         "--ds.uiRoot=packages/minimal-repo/packages/design-system/ui"
       ]
     }

package-lock.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",
@@ -34,6 +36,7 @@
     "eslint-config-prettier": "10.1.5",
     "eslint-plugin-functional": "^9.0.2",
     "eslint-plugin-unicorn": "^59.0.1",
+    "ignore-loader": "^0.1.2",
     "jest": "^29.7.0",
     "jest-environment-node": "^29.7.0",
     "jiti": "2.4.2",