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
+
+### Discuss Before You Code
+
+**Open an issue before starting work on new features or significant changes.** We mean a real conversation where we align on approach—not an issue opened five minutes before your PR.
+
+We'll close PRs for undiscussed features regardless of effort invested. Every merged feature becomes ongoing maintenance, so we're selective about what we take on.
+
+Straightforward bug fixes can skip this step. For complex bugs that need significant changes, open an issue first.
+
+### 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
+
+Help us help you:
+
+- Lead with what's broken or what you need
+- Include code we can run to see the problem
+- Keep it short—if it takes a paragraph to explain, it might be too vague
+
+We'll close issues that expect maintainers to do the debugging for you. Obviously AI-generated issues with walls of text and no real content will be closed on sight.
+
+### 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
+
+By the time you open a PR, the "what" and "why" should already be settled in an issue. PRs are for reviewing implementation, not debating whether we should do it.
+
+### Scope
+
+Small PRs get reviewed fast. Large PRs sit in the queue.
+
+We can review a few dozen lines in a few minutes. But a PR touching hundreds of lines across many files takes real effort to verify—and things inevitably slip through. If your change is big, break it into a stack of smaller 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.