# Contributing to MCP-B NPM Packages

Thank you for considering contributing to MCP-B!

## Required Engineering Standards

All contributions in this repo are expected to follow these baseline standards:

- [AI Contribution Manifesto](./docs/AI_CONTRIBUTION_MANIFESTO.md)
- [MCP-B Package Philosophy](./docs/MCPB_PACKAGE_PHILOSOPHY.md)
- [Testing Philosophy](./docs/TESTING_PHILOSOPHY.md)

These docs define review expectations for safety, contract synchronization, and validation evidence.

## Code Quality Requirements

**All contributions must meet these standards before being merged:**

### Type Safety

- All code must be written in TypeScript with strict mode enabled
- No `any` types unless absolutely necessary (and documented why)
- All public APIs must have explicit type annotations
- No `@ts-ignore` or `@ts-expect-error` without explanation

### Testing

- All new features must include tests
- All bug fixes must include a regression test
- Tests must pass before submitting a PR:
  ```bash
  pnpm test:unit    # Unit tests must pass
  pnpm test:e2e     # E2E tests must pass (if applicable)
  # For runtime/browser API changes:
  pnpm --filter mcp-e2e-tests test:native-parity
  ```

### Code Quality Checks

- All code must pass linting and formatting:
  ```bash
  pnpm check        # Biome linting and formatting
  pnpm typecheck    # TypeScript type checking
  pnpm build        # Build must succeed
  ```

### Before Submitting a PR

Run the full validation suite:

```bash
pnpm build && pnpm typecheck && pnpm check && pnpm test:unit
pnpm audit:ci:high      # informational high-severity report (prod deps; excluding e2e test-app paths)
pnpm audit:ci:critical  # required pass gate (prod deps)
```

For changes touching browser runtime behavior (`@mcp-b/global`, `@mcp-b/webmcp-polyfill`,
`@mcp-b/webmcp-ts-sdk`, `@mcp-b/transports`, or e2e runtime apps), also run:

```bash
pnpm --filter mcp-e2e-tests test:native-parity
```

If any of these fail, your PR will not be merged.

Also include the exact commands you ran in the PR description.

---

## Code of Conduct

By participating in this project, you are expected to uphold our Code of Conduct:

- Use welcoming and inclusive language
- Be respectful of differing viewpoints and experiences
- Gracefully accept constructive criticism
- Focus on what is best for the community
- Show empathy towards other community members

## How Can I Contribute?

### Reporting Bugs

Before creating bug reports, please check existing issues as you might find that you don't need to create one. When you are creating a bug report, please include as many details as possible:

- **Use a clear and descriptive title**
- **Describe the exact steps to reproduce the problem**
- **Provide specific examples to demonstrate the steps**
- **Describe the behavior you observed and what behavior you expected**
- **Include screenshots if relevant**
- **Include your environment details** (OS, Node version, browser version)

### Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:

- **Use a clear and descriptive title**
- **Provide a detailed description of the suggested enhancement**
- **Provide specific examples to demonstrate the enhancement**
- **Describe the current behavior and expected behavior**
- **Explain why this enhancement would be useful**

### Pull Requests

1. Fork the repo and create your branch from `main`
2. Write your code following TypeScript strict mode
3. Add tests for all new features and bug fixes
4. Update documentation for any API changes
5. **Run the full validation suite** (see Code Quality Requirements above)
6. Create a changeset: `pnpm changeset`
7. Submit your pull request

**PRs that don't pass all checks will not be merged.**

## Development Process

### Prerequisites

- Node.js >= 22.12 (check `.nvmrc`)
- pnpm >= 10.0.0
- Git

For environment setup and workspace commands, see [Development](./README.md#development) in the root README.

### Commit Guidelines

We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification with **required package scopes** for clarity in our monorepo:

#### Commit Format

```
<type>(<scope>): <subject>
```

#### Types

- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation only changes
- `style:` Code style changes (formatting, etc)
- `refactor:` Code change that neither fixes a bug nor adds a feature
- `perf:` Performance improvement
- `test:` Adding missing tests
- `build:` Changes to build system or dependencies
- `ci:` Changes to CI configuration
- `chore:` Other changes that don't modify src or test files

#### Scopes (Required)

Package scopes (all in `packages/` directory):

- `extension-tools` - @mcp-b/extension-tools
- `global` - @mcp-b/global
- `mcp-iframe` - @mcp-b/mcp-iframe
- `react-webmcp` - @mcp-b/react-webmcp
- `smart-dom-reader` - @mcp-b/smart-dom-reader
- `transports` - @mcp-b/transports
- `usewebmcp` - usewebmcp (strict core WebMCP React hooks)
- `webmcp-local-relay` - @mcp-b/webmcp-local-relay
- `webmcp-polyfill` - @mcp-b/webmcp-polyfill
- `webmcp-ts-sdk` - @mcp-b/webmcp-ts-sdk
- `webmcp-types` - @mcp-b/webmcp-types

Repository-wide scopes:

- `root` - Changes to root config files
- `deps` - Dependency updates
- `release` - Release-related changes
- `ci` - CI/CD changes
- `docs` - Documentation changes
- `*` - Multiple packages affected (use sparingly)

#### Examples

```bash
# Package-specific changes
git commit -m "feat(transports): add postMessage timeout option to TabServerTransport"
git commit -m "fix(extension-tools): handle chrome.runtime errors gracefully"
git commit -m "docs(react-webmcp): update usage examples"
git commit -m "feat(global): add new tool registration API"

# Repository-wide changes
git commit -m "chore(deps): upgrade @modelcontextprotocol/sdk to v2.0"
git commit -m "ci(root): add npm publishing workflow"
git commit -m "docs(root): update README with installation instructions"

# Multiple packages (use sparingly)
git commit -m "refactor(*): update to new MCP SDK types"
```

**Note:** Commits without proper format will be rejected by our commit-msg hook!

### Submitting Your Pull Request

1. **Push your branch**

   ```bash
   git push origin feature/your-feature-name
   ```

2. **Create a Pull Request**
   - Go to the repository on GitHub
   - Click "New Pull Request"
   - Select your branch
   - Fill in the PR template with:
     - Clear description of changes
     - Related issue numbers
     - Testing layer coverage and exact commands run
     - Screenshots (if applicable)

3. **Address review feedback**
   - Make requested changes
   - Push new commits to your branch
   - Re-request review when ready

## Project Structure

```
npm-packages/
├── packages/                    # All NPM packages
│   ├── extension-tools/         # Chrome Extension API tools
│   ├── global/                  # Full MCP-B runtime (core + extensions)
│   ├── mcp-iframe/              # Iframe MCP element
│   ├── react-webmcp/            # React hooks for MCP-B runtime
│   ├── smart-dom-reader/        # DOM extraction for AI
│   ├── transports/              # Core transport implementations
│   ├── webmcp-polyfill/         # Strict core WebMCP runtime polyfill
│   ├── webmcp-types/            # Strict core WebMCP type definitions
│   ├── usewebmcp/               # React hooks for strict core WebMCP API
│   └── webmcp-ts-sdk/           # TypeScript SDK adapter
├── e2e/                         # E2E tests and test apps
├── docs/                        # Technical documentation
└── .changeset/                  # Changeset files
```

## Package Guidelines

When contributing to a specific package:

### @mcp-b/global

- Ensure compatibility with W3C Web Model Context API spec
- Test in multiple browser environments
- Validate tool registration and unregistration
- Handle edge cases in two-bucket system

### @mcp-b/webmcp-ts-sdk

- Minimal modifications to official SDK
- Maintain compatibility with upstream SDK updates
- Focus on dynamic tool registration support

### @mcp-b/transports

- Ensure browser compatibility
- Test in multiple browser environments
- Handle connection lifecycle properly
- Support both Tab and Extension transports

### @mcp-b/react-webmcp

- Follow React best practices
- Ensure proper cleanup in useEffect
- Add proper TypeScript types for hooks
- Support both provider and client use cases
- Test with React StrictMode

### @mcp-b/extension-tools

- Test in Chrome extension context
- Document required permissions
- Handle chrome.runtime errors gracefully
- Auto-generate tools from Chrome API types

### @mcp-b/smart-dom-reader

- Optimize for token efficiency
- Test in various DOM structures
- Handle shadow DOM and iframes
- Maintain stateless architecture

### @mcp-b/mcp-iframe

- Test cross-origin scenarios
- Handle postMessage security properly
- Support tool prefixing for namespacing
- Test connection lifecycle

## Testing

```bash
pnpm test:unit      # Unit tests (required for all PRs)
pnpm test:e2e       # E2E tests (if applicable)
```

- [Testing Philosophy](./docs/TESTING_PHILOSOPHY.md) - Test-layer strategy, mocking policy, coverage expectations
- [E2E Testing Infrastructure](./docs/TESTING.md) - Playwright setup, test apps, debugging

## Documentation

- Update README files for any API changes
- Add JSDoc comments for public APIs
- Include usage examples for new features
- Update TypeScript types and interfaces

## Release Process

Releases are handled automatically by our CI/CD pipeline:

1. Contributors create changesets with their PRs
2. A bot creates a "Version Packages" PR
3. Maintainers review and merge the version PR
4. Packages are automatically published to npm

## Getting Help

- **Discord**: Join our [Discord community](https://discord.gg/a9fBR6Bw)
- **GitHub Issues**: Open an issue for bugs or features
- **Discussions**: Use GitHub Discussions for questions

## Recognition

Contributors will be recognized in:

- The project README
- Release notes
- Our Discord community

Thank you for contributing to MCP-B! 🚀