docs: add contribution guidelines for issues and PRs

Author: felixweinberger

CONTRIBUTING.md

@@ -2,49 +2,110 @@
 
 We welcome contributions to the Model Context Protocol TypeScript SDK! This document outlines the process for contributing to the project.
 
-## Getting Started
+## Issues
+
+### Issue First, Code Second
+
+**Open an issue before starting work on new features or significant changes.** This means having an actual discussion and getting alignment—not just opening an issue moments before submitting a PR.
+
+We will close pull requests for features that weren't previously discussed, regardless of the effort invested. Code is cheap to produce but expensive to maintain, and every merged feature creates long-term maintenance burden.
+
+Bug fixes for straightforward bugs can skip this step. For complex bugs requiring significant changes, consider opening an issue first to discuss the approach.
+
+### What Counts as "Significant"?
+
+- New public APIs or classes
+- Architectural changes or refactoring
+- Changes that touch multiple modules
+- Features that might require spec changes (these need a [SEP](https://github.com/modelcontextprotocol/modelcontextprotocol) first)
+
+### Writing Good Issues
+
+Good issues are clear and concise:
+
+- State the problem directly
+- Include a minimal reproducible example when applicable
+- Skip unnecessary background—get to the point
+
+Issues that transfer burden to maintainers without effort to validate the problem will be closed. LLM-generated issues that are clearly low-effort will be closed immediately.
+
+### Finding Issues to Work On
+
+| Label | For | Description |
+|-------|-----|-------------|
+| [`good first issue`](https://github.com/modelcontextprotocol/typescript-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | Newcomers | Can tackle without deep codebase knowledge |
+| [`help wanted`](https://github.com/modelcontextprotocol/typescript-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Experienced contributors | Maintainers probably won't get to this |
+| [`ready for work`](https://github.com/modelcontextprotocol/typescript-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) | Maintainers | Triaged and ready for a maintainer to pick up |
+
+Issues labeled `needs confirmation`, `needs repro`, or `needs design` are **not** ready for work—wait for maintainer input before starting.
+
+## Pull Requests
+
+PRs are not the place to iterate on ideas; that's what issues are for. Only open a PR for work that's already been discussed and aligned.
+
+### Scope
+
+Keep PRs focused and small. A PR that changes 50 lines across 3 files can be reviewed in minutes. A PR that changes 500 lines across 20 files requires hours of careful analysis, creates review bottlenecks, and often hides issues.
+
+If your change is large, break it into smaller, incremental PRs.
+
+### What Gets Rejected
+
+PRs may be rejected for:
+
+- **Lack of prior discussion** — Features or significant changes without an approved issue
+- **Scope creep** — Changes that go beyond what was discussed or add unrequested features
+- **Misalignment with SDK direction** — Even well-implemented features may be rejected if they don't fit the SDK's goals
+- **Insufficient quality** — Code that doesn't meet clarity, maintainability, or style standards
+- **Overengineering** — Unnecessary complexity or abstraction for simple problems
+
+### Submitting Your PR
+
+1. Follow the existing code style
+2. Include tests for new functionality
+3. Update documentation as needed
+4. Keep changes focused and atomic
+5. Provide a clear description of changes
+
+## Development
+
+### Getting Started
 
 1. Fork the repository
 2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/typescript-sdk.git`
 3. Install dependencies: `npm install`
 4. Build the project: `npm run build`
 5. Run tests: `npm test`
 
-## Development Process
+### Workflow
 
 1. Create a new branch for your changes
 2. Make your changes
 3. Run `npm run lint` to ensure code style compliance
 4. Run `npm test` to verify all tests pass
 5. Submit a pull request
 
-## Pull Request Guidelines
-
-- Follow the existing code style
-- Include tests for new functionality
-- Update documentation as needed
-- Keep changes focused and atomic
-- Provide a clear description of changes
-
-## Running Examples
+### Running Examples
 
 - Start the server: `npm run server`
 - Run the client: `npm run client`
 
-## Code of Conduct
+## Policies
+
+### Code of Conduct
 
 This project follows our [Code of Conduct](CODE_OF_CONDUCT.md). Please review it before contributing.
 
-## Reporting Issues
+### Reporting Issues
 
 - Use the [GitHub issue tracker](https://github.com/modelcontextprotocol/typescript-sdk/issues)
 - Search existing issues before creating a new one
 - Provide clear reproduction steps
 
-## Security Issues
+### Security Issues
 
 Please review our [Security Policy](SECURITY.md) for reporting security vulnerabilities.
 
-## License
+### License
 
 By contributing, you agree that your contributions will be licensed under the MIT License.