Skip to content

CONTRIBUTING.MD

Latest commit

 

History

History
300 lines (217 loc) · 6.92 KB

CONTRIBUTING.MD

File metadata and controls

300 lines (217 loc) · 6.92 KB

Contributing to Angular Toolkit MCP

Thank you for your interest in contributing to the Angular Toolkit MCP! This document provides guidelines and information for contributors.

📋 Table of Contents

🚀 Getting Started

Prerequisites

  • Node.js (version 18 or higher)
  • npm (comes with Node.js)
  • Git for version control

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork locally

🛠️ Development Setup

Initial Setup

  1. Install dependencies:

    npm install

  2. Build the project:

    npx nx build angular-toolkit-mcp

Nx Workspace Commands

This project uses Nx for monorepo management. Key commands:

# Build all projects
npx nx run-many --target=build --all

# Build specific project
npx nx build angular-mcp-server

# Run tests for all projects
npx nx run-many --target=test --all

# Lint all projects
npx nx run-many --target=lint --all

# Check project graph
npx nx graph

🏗️ Project Structure

This is an Nx monorepo with the following structure:

├── packages/
│   ├── angular-mcp/           # Main MCP client application
│   ├── angular-mcp-server/    # Core MCP server library
│   ├── minimal-repo/          # Test fixtures and examples
│   └── shared/                # Shared libraries
│       ├── angular-ast-utils/     # Angular AST parsing
│       ├── ds-component-coverage/ # Design system analysis
│       ├── models/               # Core types and schemas
│       ├── styles-ast-utils/     # CSS/SCSS AST parsing
│       ├── typescript-ast-utils/ # TypeScript AST utilities
│       └── utils/               # General utilities
├── testing/                   # Testing utilities and setup
├── docs/                      # Documentation
└── tools/                     # Build and development tools

Key Projects

  • angular-mcp: Main executable MCP client
  • angular-mcp-server: Core server logic and MCP tools
  • Shared libraries: Reusable utilities for AST parsing, file operations, and Angular analysis

🔄 Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name

2. Make Changes

  • Follow the existing code style and patterns
  • Add tests for new functionality
  • Update documentation as needed

3. Build and Test

# Build affected projects
npx nx affected --target=build

# Run tests
npx nx affected --target=test

# Lint code
npx nx affected --target=lint

4. Commit Changes

Follow conventional commit format:

git commit -m "feat: add new MCP tool for component analysis"
git commit -m "fix: resolve dependency resolution issue"
git commit -m "docs: update API documentation"

🧪 Testing

Running Tests

# Run all tests
npx nx run-many --target=test --all

# Run tests for specific project
npx nx test angular-mcp-server

# Run tests with coverage
npx nx test angular-mcp-server --coverage

Writing Tests

  • Use Vitest for unit testing
  • Follow the existing test patterns
  • Mock external dependencies appropriately
  • Test both success and error scenarios

📏 Code Quality

ESLint Configuration

The project uses ESLint with TypeScript and Nx-specific rules:

# Lint all files
npx nx run-many --target=lint --all

# Lint specific project
npx nx lint angular-mcp-server

# Auto-fix linting issues
npx nx lint angular-mcp-server --fix

Code Style Guidelines

  • Use TypeScript strict mode
  • Follow functional programming patterns where possible
  • Use descriptive variable and function names
  • Add JSDoc comments for public APIs
  • Prefer composition over inheritance

Pre-commit Checks

Before committing, ensure:

  • All tests pass
  • No linting errors
  • Code builds successfully
  • Documentation is updated

📝 Submitting Changes

Pull Request Process

  1. Push your branch:

    git push origin feature/your-feature-name

  2. Create a Pull Request:

    • Use a descriptive title
    • Include a detailed description of changes
    • Reference any related issues
    • Add screenshots for UI changes

  3. PR Requirements:

    • All CI checks must pass
    • Code review approval required
    • Documentation updates included
    • Tests added for new functionality

🐛 Debugging

Debug Server

Start the MCP server in debug mode:

npx nx run angular-toolkit-mcp:debug

This starts the server with the MCP Inspector for debugging.

Debugging Tips

  • Use the MCP Inspector for real-time debugging
  • Check server logs for detailed error information
  • 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

    npx nx build angular-toolkit-mcp

  3. Test the Package

    cd packages/angular-mcp/dist
npm pack
# Test the generated .tgz file
node main.js --help

  4. Authenticate with npm

    npm login

    Ensure you have access to the @push-based scope.

  5. Publish to npm

    npm run publish:mcp

    Or manually:

    npx nx build angular-toolkit-mcp
cd packages/angular-mcp/dist
npm publish

  6. Verify Publication

    npm view @push-based/angular-toolkit-mcp
npx @push-based/angular-toolkit-mcp@latest --help

  7. Tag the Release

    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.