Welcome, and thanks for your interest in contributing! We're glad you're here.
This document outlines how to contribute effectively to the TypeScript SDK.
Issues
Discuss Before You Code
Please open an issue before starting work on new features or significant changes. This gives us a chance to align on approach and save you time if we see potential issues.
We'll close PRs for undiscussed features—not because we don't appreciate the effort, but because every merged feature becomes an ongoing maintenance burden for our small team of maintainers. Talking first helps us figure out together whether something belongs in the SDK.
Straightforward bug fixes (a few lines of code with tests demonstrating the fix) can skip this step. For complex bugs that need significant changes, consider opening 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 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 focused—a clear problem statement goes a long way
We're a small team, so issues that include some upfront debugging help us move faster. Low-effort or obviously AI-generated issues will be closed.
Finding Issues to Work On
| Label | For | Description | | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------- | | `good first issue` | Newcomers | Can tackle without deep codebase knowledge | | `help wanted` | Experienced contributors | Maintainers probably won't get to this | | `ready for work` | 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.
Before starting work, comment on the issue so we can assign it to you. This lets others know and avoids duplicate effort.
Pull Requests
By the time you open a PR, the "what" and "why" should already be settled in an issue. This keeps PR reviews focused on implementation rather than revisiting whether we should do it at all.
Branches
This repository has two main branches:
- `main` – v2 of the SDK (the stable release line). This is a monorepo with split packages.
- `v1.x` – stable v1 release. Bug fixes and patches for v1 should target this branch.
Which branch should I use as a base?
- For new features or v2-related work: base your PR on
main - For v1 bug fixes or patches: base your PR on
v1.x
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 or get clear alignment from a maintainer on your approach in an issue before submitting a large PR.
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
- 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
Development
Getting Started
This project uses pnpm as its package manager. If you don't have pnpm installed, enable it via corepack (included with Node.js 16.9+):
corepack enable
Then:
- Fork the repository
- Clone your fork:
git clone https://github.com/YOUR-USERNAME/typescript-sdk.git - Install dependencies:
pnpm install - Build the project:
pnpm build:all - Run tests:
pnpm test:all
Workflow
- Create a new branch for your changes (based on
main or v1.x as appropriate) - Make your changes
- Run
pnpm lint:all to ensure code style compliance - Run
pnpm test:all to verify all tests pass - Submit a pull request
Good to know
Details about this repository that neither the code nor the tools will tell you.
- Spec — The full spec text is at
https://modelcontextprotocol.io/llms-full.txt, and the schema for a protocol revision is schema//schema.ts in modelcontextprotocol/modelcontextprotocol. - Tests — Tests live under each package's
test/ directory; a test file next to its source never runs. - Adapters — The packages under
packages/middleware/ are thin adapters, versioned separately from client and server, so a user can run a new server with an older adapter. - Package roots — A package's root entry stays runtime-neutral so browser and Workers bundlers can use it; Node-only code lives at a subpath export such as
./stdio. - Migration guide —
docs/migration/upgrade-to-v2.md covers the upgrade from v1 only. Its text lives in the agent skill skills/mcp-typescript-sdk-upgrade-to-v2/ (one references/ file per subsystem), which the page includes, so edit it there; mechanical renames go in packages/codemod/src/migrations/v1-to-v2/mappings/.
Running Examples
See `examples/README.md` for the full list of runnable examples — one self-verifying client/server pair per directory.
Quick start:
## Run any story's server
pnpm --filter @mcp-examples/tools server -- --http --port 3000
## Run its client (in another terminal)
pnpm --filter @mcp-examples/tools client -- --http http://127.0.0.1:3000/
## Run every story over every transport × era leg
pnpm run:examples
Releasing v1.x Patches
The v1.x branch contains the stable v1 release. To release a patch:
Latest v1.x (e.g., v1.25.3)
git checkout v1.x
git pull origin v1.x
## Apply your fix or cherry-pick commits
npm version patch # Bumps version and creates tag (e.g., v1.25.3)
git push origin v1.x --tags
The tag push automatically triggers the release workflow.
Older minor versions (e.g., v1.23.2)
For patching older minor versions that aren't on the v1.x branch:
## 1. Create a release branch from the last release tag
git checkout -b release/1.23 v1.23.1
## 2. Apply your fixes (cherry-pick or manual)
git cherry-pick
## 3. Bump version and push
npm version patch # Creates v1.23.2 tag
git push origin release/1.23 --tags
Then manually trigger the "Publish v1.x" workflow from GitHub Actions, specifying the tag (e.g., v1.23.2).
npm Tags
v1.x releases are published with release-X.Y npm tags (e.g., release-1.25), not latest. To install a specific minor version:
npm install @modelcontextprotocol/sdk@release-1.25
Policies
Code of Conduct
This project follows our Code of Conduct. Please review it before contributing.
Reporting Issues
- Use the GitHub issue tracker
- Search existing issues before creating a new one
- Provide clear reproduction steps
Security Issues
Please review our Security Policy for reporting security vulnerabilities.
License
By contributing, you agree that your code contributions will be licensed under the Apache License 2.0. Documentation contributions (excluding specifications) are licensed under CC-BY 4.0. See the LICENSE file for details.