Contributing to MCP

community/contributing First recorded · 573 lines, first recorded

# Contributing to MCP ## Before You Begin ### Prerequisites ### Repository Structure ### Project Roles ## Your First Contribution ### Step 1: Set Up Your Environment ### Step 2: Find Something to Work On ### Step 3: Make Your Change ### Step 4: Submit a Pull Request ### What Makes a Good Contribution ## Types of Contributions ### Small Changes (Direct PR) ### Major Changes (SEP Required) ## Working with the Specification Repository ### Schema Changes ### Documentation Changes ### Major Protocol Changes ## Working with the SDK Repositories ### Before Contributing to an SDK ### SDK Repositories ## Getting Help ### Communication Channels ### Finding a Sponsor for SEPs ## Troubleshooting ### `npm run check` fails ### My PR has been sitting unnoticed for weeks ### I can't find a sponsor for my SEP ### My SEP was rejected ## Out of Scope ## AI Contributions ## Code of Conduct ## License

The first capture of this source. The page was already there, and this is what it said.

# Contributing to MCP

> How to contribute to the Model Context Protocol project

The Model Context Protocol (MCP) is an open source project that welcomes contributions from the
community. This guide walks you through everything you need to get started.

## Before You Begin

### Prerequisites

Before contributing, ensure you have the following installed and ready:

* **[Git](https://git-scm.com/downloads)** - For cloning repositories and submitting changes
* **[Node.js 24+](https://nodejs.org/)** - Required for building and testing our projects
* **npm** - Comes with Node.js, used for dependency management
* **[GitHub account](https://github.com/signup)** - For submitting pull requests and issues
* **Language-specific tooling** - If contributing to an SDK, you'll need the appropriate
  development environment for that language (e.g., Python, Rust, Go)

Verify your setup:

```bash theme={null}
node --version  # Should be 24.x or higher
npm --version   # Should be 11.x or higher
git --version   # Any recent version
```

<Note>
  These commands work the same on macOS, Linux, and Windows, so you're good to
  go on any platform.
</Note>

### Repository Structure

MCP spans multiple repositories in the
[`modelcontextprotocol`](https://github.com/modelcontextprotocol) organization on GitHub. Here are
a few notable sub-projects worth checking out:

| Repository                                                                                                  | Contents                  |
| ----------------------------------------------------------------------------------------------------------- | ------------------------- |
| [`modelcontextprotocol/modelcontextprotocol`](https://github.com/modelcontextprotocol/modelcontextprotocol) | Specification, docs, SEPs |
| [`modelcontextprotocol/typescript-sdk`](https://github.com/modelcontextprotocol/typescript-sdk)             | TypeScript/JavaScript SDK |
| [`modelcontextprotocol/python-sdk`](https://github.com/modelcontextprotocol/python-sdk)                     | Python SDK                |
| [`modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk)                             | Go SDK                    |
| [`modelcontextprotocol/java-sdk`](https://github.com/modelcontextprotocol/java-sdk)                         | Java SDK                  |
| [`modelcontextprotocol/kotlin-sdk`](https://github.com/modelcontextprotocol/kotlin-sdk)                     | Kotlin SDK                |
| [`modelcontextprotocol/csharp-sdk`](https://github.com/modelcontextprotocol/csharp-sdk)                     | C# SDK                    |
| [`modelcontextprotocol/swift-sdk`](https://github.com/modelcontextprotocol/swift-sdk)                       | Swift SDK                 |
| [`modelcontextprotocol/rust-sdk`](https://github.com/modelcontextprotocol/rust-sdk)                         | Rust SDK                  |
| [`modelcontextprotocol/ruby-sdk`](https://github.com/modelcontextprotocol/ruby-sdk)                         | Ruby SDK                  |
| [`modelcontextprotocol/php-sdk`](https://github.com/modelcontextprotocol/php-sdk)                           | PHP SDK                   |

Throughout this guide, **specification repository** refers to
`modelcontextprotocol/modelcontextprotocol`, which contains the protocol spec, this documentation
site, and [Spec Enhancement Proposals (SEPs)](/community/sep-guidelines).

### Project Roles

MCP follows a [governance model](/community/governance) with different levels of responsibility:

* **Contributors** - Anyone who files issues, submits PRs, or participates in discussions (that's
  you!)
* **Maintainers** - Steward specific areas like SDKs, documentation, or
  [Working Groups](/community/working-interest-groups)
* **Core Maintainers** - Guide overall project direction, review SEPs, and oversee the specification

You can find the current list of maintainers in the
[`MAINTAINERS.md`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md)
file.

Maintainers are here to help you succeed! Don't hesitate to reach out if you have questions or
need guidance on your contribution.

## Your First Contribution

Start here if you are new to MCP and contributing to its ecosystem.

<Note>
  While we use the specification repository as an example, the key patterns are
  applicable to other MCP repos as well.
</Note>

### Step 1: Set Up Your Environment

Set up your local environment so you can test and validate changes before submitting them.

<Steps>
  <Step title="Fork the repository">
    Click the **Fork** button on the [repository page](https://github.com/modelcontextprotocol/modelcontextprotocol) to create your own copy. This gives you a personal workspace where you can make changes without affecting the main project.
  </Step>

  <Step title="Clone your fork">
    ```bash theme={null}
    git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
    cd modelcontextprotocol
    ```

    Replace `YOUR-USERNAME` with your GitHub username.
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```

    This installs the tools needed for schema generation, documentation building, and validation.
  </Step>

  <Step title="Verify everything works">
    ```bash theme={null}
    npm run check
    ```

    This runs TypeScript compilation, schema validation, example validation, documentation link checks, and formatting checks. If everything passes, your environment is good and you're ready to contribute.
  </Step>
</Steps>

If `npm run check` fails, see [Troubleshooting](#troubleshooting) below.

### Step 2: Find Something to Work On

While a lot of the items you might see tracked in the repository can feel intimidating, especially
for newcomers, there are plenty of places where you can start with your first improvements:

1. **Documentation improvements** - Help us fix typos, unclear explanations, broken links, or
   incomplete examples
2. **Issues labeled `good first issue`** - Tackle issues tagged in the
   [specification repo](https://github.com/modelcontextprotocol/modelcontextprotocol/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
   as well as our SDK repos
3. **Schema examples** - Add examples to `schema/draft/examples/` to make it easier for developers
   to understand protocol primitives

### Step 3: Make Your Change

Create your changes in a dedicated branch.

<Steps>
  <Step title="Create a branch">
    ```bash theme={null}
    git checkout -b fix/your-description
    ```

    Use a descriptive branch name that reflects your change, like `fix/typo-in-tools-doc` or `feat/add-example-for-resources`.
  </Step>

  <Step title="Make your changes">
    Edit the relevant files in your local copy. If you're editing schema files, remember to run `npm run generate:schema` to regenerate the JSON schema and documentation.
  </Step>

  <Step title="Run checks">
    ```bash theme={null}
    npm run check
    ```

    Fix any issues before committing. If you have formatting errors, `npm run format` can auto-fix most of them.
  </Step>

  <Step title="Commit with a clear message">
    ```bash theme={null}
    git commit -m "Fix typo in tools documentation"
    ```

    Write a concise message that describes what you changed and why. Reference issue numbers if applicable (e.g., `Fix typo in tools documentation (#123)`).
  </Step>
</Steps>

### Step 4: Submit a Pull Request

When you're ready, push your branch and open a pull request.

<Steps>
  <Step title="Push your branch">
    ```bash theme={null}
    git push origin fix/your-description
    ```
  </Step>

  <Step title="Open a PR on GitHub">
    You can use the [GitHub CLI](https://cli.github.com/) to make this process easier:

    ```bash theme={null}
    gh pr create --fill
    ```

    Alternatively, navigate to your fork on GitHub and click **Compare & pull request**.
  </Step>

  <Step title="Fill in the PR template">
    Provide a clear description of your changes and link any related issues.
  </Step>

  <Step title="Wait for review">
    Maintainers typically respond within 1-5 business days.
  </Step>
</Steps>

<Tip>
  That's it, **congratulations on your first contribution**! Every improvement,
  no matter how small, helps make MCP better for everyone.
</Tip>

### What Makes a Good Contribution

Help us review your contribution quickly by following these patterns:

| Harder to Review                             | Thoughtful and Impactful                         |
| -------------------------------------------- | ------------------------------------------------ |
| Large PR with unrelated changes              | Focused PR addressing one issue                  |
| Reformatting code without functional changes | Fixing a bug with a clear explanation            |
| Vague commit messages ("fixed stuff")        | Descriptive commits linking to issues            |
| Submitting with failing CI checks            | All CI tests pass before requesting review       |
| Duplicating existing documentation           | Documenting an undocumented feature or edge case |

## Types of Contributions

Different contributions follow different processes depending on their scope.

<Tip>
  Not sure which category your change falls into? Ask in the [MCP Contributor
  Discord](/community/communication#discord) before starting any significant
  work.
</Tip>

### Small Changes (Direct PR)

Simply submit a pull request directly to the repo for:

* Bug fixes and typo corrections
* Documentation improvements, such as bringing clarity to an ambiguous or unclear section
* Adding examples to existing features
* Minor schema fixes that don't materially change the specification or SDK behavior
* Test improvements

### Major Changes (SEP Required)

Anything that changes the MCP specification requires following the
[Specification Enhancement Proposal (SEP)](/community/sep-guidelines) process. This includes, but
is not limited to:

* New protocol features or API methods
* Breaking changes to existing behavior
* Changes to the message format or schema structure
* New interoperability standards
* Governance or process changes

Here are a few concrete examples of what would require following the SEP steps:

* Adding a new RPC method like `tools/execute`
* Changing how authentication and authorization works
* Adding a new capability negotiation field
* Modifying the transport layer specification

## Working with the Specification Repository

Once you've determined [what type of contribution](#types-of-contributions) you're making, here's
how to work with the specification repository.

### Schema Changes

The TypeScript schema (`schema/draft/schema.ts`) is the **source of truth** for the protocol. It
defines every message type, request/response structure, and primitive (tools, resources, prompts)
that clients and servers exchange. SDK implementers across all languages rely on this schema to
build conformant implementations.

When you run `npm run generate:schema`, it generates:

* The JSON schema (`schema/draft/schema.json`) for validation
* The Schema Reference documentation (`docs/specification/draft/schema.mdx`)

To modify the schema:

<Steps>
  <Step title="Edit the TypeScript schema">
    Make your changes in `schema/draft/schema.ts`.
  </Step>

  <Step title="Add examples (optional)">
    Add JSON examples in `schema/draft/examples/[TypeName]/` (e.g., `Tool/my-example.json`). Reference them in the schema using `@example` + `@includeCode` JSDoc tags.
  </Step>

  <Step title="Generate JSON schema and docs">
    ```bash theme={null}
    npm run generate:schema
    ```
  </Step>

  <Step title="Validate your changes">
    ```bash theme={null}
    npm run check
    ```
  </Step>
</Steps>

### Documentation Changes

Docs are written in [MDX format](https://mdxjs.com/) (Markdown with JSX components) and powered by
[Mintlify](https://mintlify.com/). The `docs/` directory contains:

* `docs/docs/` - Guides and tutorials for getting started and building with MCP

Cut at 300 lines.