Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
390 lines (301 loc) · 17.1 KB

CONTRIBUTING.md

File metadata and controls

390 lines (301 loc) · 17.1 KB
Raw

Contributing to the Go MCP SDK

Thank you for your interest in contributing! The Go SDK needs active contributions to keep up with changes in the MCP spec, fix bugs, and accommodate new and emerging use-cases. We welcome all forms of contribution, from filing and reviewing issues, to contributing fixes, to proposing and implementing new features.

As described in the design document, it is important for the MCP SDK to remain idiomatic, future-proof, and extensible. The process described here is intended to ensure that the SDK evolves safely and transparently, while adhering to these goals.

  1. Before you start
    1. Why issues rather than pull requests
    2. How issues get in
    3. How pull requests get in
    4. AI-assisted contributions
  2. Development setup
    1. Conformance tests
  3. Filing issues
    1. Bugs
    2. Proposals
    3. Design discussion
  4. Contributing code
    1. Adding and updating dependencies
    2. Updating the README
  5. Versioning
    1. What counts as a breaking change
    2. Deprecation
  6. Timeouts
  7. Code of conduct
  8. Governance
    1. Working Group meetings
    2. Discord
    3. Antitrust considerations

Before you start

Important

The most useful contribution is a good issue. Pull requests from outside the maintainer team are closed automatically unless they link an issue assigned to their author, and issues should meet the checklist below.

Why issues rather than pull requests

Coding agents can now turn any open issue into a plausible-looking pull request within hours, and generate speculative bug reports from a scan of the code, so we receive far more issues and PRs than we can read carefully. Reviewing a PR properly still takes as long as it always did. When an issue is well described, it is usually quicker for a maintainer to write a fix that fits the codebase than to review and reshape someone else's.

What we can't produce ourselves is your context: what you were doing, what you expected, a minimal reproduction, and the system where it broke. That is what a good issue carries, so that is what we ask for first.

How issues get in

Bugs and enhancement requests are filed with the issue forms; blank issues are disabled. Each form starts with a checklist, and an issue with every box ticked is much more likely to be accepted. By ticking them, you confirm that:

  • you searched the existing issues, and this one is not a duplicate;
  • the problem is real, and you ran into it yourself with the latest release;
  • you ran into it in a production system, not in a toy example, a benchmark, or an automated or AI-driven scan of the code;
  • you, a human, examined the relevant SDK code, and wrote or reviewed the whole report;
  • the report is brief and concise.

Only tick a box if it's true. If one doesn't apply, the report may belong somewhere else: questions and open-ended ideas go to GitHub Discussions, and security vulnerabilities must be reported privately as described in SECURITY.md.

How pull requests get in

A PR from someone outside the maintainer team stays open when both of these hold:

  1. Its description links an open issue in this repository with Fixes #123 (or Closes, Resolves), or with Updates #123 for a partial fix.
  2. A maintainer has assigned that issue to you, or the issue carries the help wanted label, which means we'd welcome a PR for it from anyone.

Otherwise a bot labels the PR missing-issue-link, leaves a comment explaining this, and closes it. Drafts are treated the same way. If that happens to yours, there's no need to open a new one: it reopens automatically as soon as a maintainer assigns you the issue, or when you edit the description to link one that qualifies. While it's closed, push updates as new commits rather than force-pushing, since GitHub can't reopen a PR whose branch has been rewritten. This applies to small fixes like typos too; for those, an issue pointing at the problem is all we need.

Whether to assign an issue, and to whom, is a maintainer call, and it depends on our capacity at the time as much as on the change itself. Comments that only ask to be assigned don't factor into it, so please skip those (and don't have an agent post them). What does help is engaging with the issue itself: confirming the reproduction, asking about the intended behavior, or briefly describing the approach you'd take. If you reported the issue and would like to fix it yourself, say so in the issue.

Maintainers can override the check by reopening the PR, by removing its missing-issue-link label, or by adding bypass-issue-check.

AI-assisted contributions

You are welcome to use AI tools. What matters is that a person is accountable for the result:

  • Disclose it. One line in the PR description, issue, or comment.
  • Own it. You can explain the change and the reasoning in your own words, and when a maintainer asks a question, the answer comes from you rather than from a chat window.
  • Keep a human in the loop. Issues, PRs, and comments generated by an agent without a person who has actually hit the problem and read the output may be closed without warning. If you have an agent filing issues or PRs against this repository autonomously, please turn it off.
  • Keep issues short and factual. What happened, what you expected, and how to reproduce it.

Undisclosed AI contributions may be closed, and repeated cases can lead to a block from the modelcontextprotocol org. The org-wide AI contribution policy also applies.

Development setup

This module can be built and tested using the standard Go toolchain. Run go test ./... to run all its tests.

To test changes to this module against another module that uses the SDK, we recommend using a go.work file to define a multi-module workspace. For example, if your directory contains a project directory containing your project, and a go-sdk directory containing the SDK, run:

go work init ./project ./go-sdk

Conformance tests

The SDK includes scripts to run the official MCP conformance tests against the SDK's conformance server and client:

./scripts/server-conformance.sh
./scripts/client-conformance.sh

By default, results are cleaned up after the script runs. To save results to a specific directory:

./scripts/server-conformance.sh --result_dir ./conformance-results
./scripts/client-conformance.sh --result_dir ./conformance-results

To run against a local checkout of the conformance repo instead of the latest npm release:

./scripts/server-conformance.sh --conformance_repo ~/src/conformance
./scripts/client-conformance.sh --conformance_repo ~/src/conformance

Note: you must run npm install in the conformance repo first.

Run either script with --help for more options.

Filing issues

This project uses the GitHub issue tracker for issues. The process for filing bugs and proposals is described below.

For general questions, see the Discord section below. Prefer GitHub issues or discussions for anything that should stay durable and searchable.

Bugs

Please report bugs with the bug report form. If the SDK is not working as you expected, it is likely due to a bug or inadequate documentation, and reporting an issue will help us address this shortcoming.

The form asks what you did, what you saw, what you expected to see, how to reproduce it, where you hit it, and which versions of the Go MCP SDK and Go you are using. It also carries the checklist described in How issues get in.

Proposals

A proposal is an issue that proposes a new API for the SDK, or a change to the signature or behavior of an existing API. Proposals should be labeled with the 'proposal' label, and require an explicit approval from a maintainer before being accepted (indicated by the 'proposal-accepted' label). Proposals must remain open for at least a week to allow discussion before being accepted or declined by a maintainer.

Proposals that are straightforward and uncontroversial may be approved based on discussion on the issue tracker or in a GitHub Discussion. However, proposals that are deemed to be sufficiently unclear or complicated may be deferred to a regular Working Group meeting (see 'Governance' below).

This process is similar to the Go proposal process, but is necessarily lighter weight to accommodate the greater rate of change expected for the SDK.

Design discussion

For open ended design discussion (anything that doesn't fall into the issue categories above), use GitHub Discussions. Ideally, each discussion should be focused on one aspect of the design. For example: Tool Binding and Session APIs would be two separate discussions. When discussions reach a consensus, they should be promoted into proposals.

Contributing code

The project uses GitHub pull requests (PRs) to review changes.

Every PR from outside the maintainer team must link an issue that a maintainer has assigned to you, as described in How pull requests get in. Issues that are deemed to be good opportunities for contribution are labeled 'Help Wanted', and don't need assignment. For changes that don't relate to an existing issue, file an issue first, and wait for it to be assigned before opening a PR.

Changes should be high quality and well tested, and should generally follow the Google Go style guide. Commit messages should follow the format used by the Go project.

Unless otherwise noted, the Go source files are distributed under the license found in the LICENSE file. New contributions are licensed under Apache 2.0. All Go files in the SDK should have a copyright header following the format below:

// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
// Use of this source code is governed by the license
// that can be found in the LICENSE file.

Adding and updating dependencies

In general, the SDK tries to use as few dependencies as possible. Each new dependency is a potential source for bugs, churn, and conflicts for our users. Therefore, we require a proposal for any new module dependency, including upgrading an existing module to a new major version. New dependencies should be evaluated for their stability and security, and should be well-established in the Go ecosystem.

In general, dependencies should be for internal use by the SDK implementation, or for testing. Do not include types from dependencies in the SDK API.

On the other hand, updating existing dependencies can be done at any time without a proposal, as long as their major version does not change. Prefer to update dependencies immediately following a release of the SDK, to allow as much time as possible to find issues with the new version.

After any change to dependencies, run govulncheck to check them for vulnerabilities.

go run golang.org/x/vuln/cmd/govulncheck@latest

Updating the README

The top-level README.md file is generated from internal/readme/README.src.md and should not be edited directly. To update the README:

  1. Make your changes to internal/readme/README.src.md
  2. Run go generate ./internal/readme from the repository root to regenerate README.md
  3. Commit both files together

The CI system will automatically check that the README is up-to-date by running go generate ./internal/readme and verifying no changes result. If you see a CI failure about the README being out of sync, follow the steps above to regenerate it.

Versioning

The SDK follows semantic versioning, as the Go module system requires: the major version is part of the module path, so a breaking release would import as github.com/modelcontextprotocol/go-sdk/v2. A breaking change therefore cannot reach existing users by accident; they have to change their import path to receive one.

This policy covers the exported API of the SDK's importable packages — mcp, jsonrpc, auth, auth/extauth and oauthex. Everything under internal/ is not importable outside the module and may change in any release.

Which MCP spec revisions each SDK version speaks is documented in the README. Support for a new revision arrives in a minor release; dropping a revision the SDK previously negotiated is a breaking change.

What counts as a breaking change

  • Removing or renaming an exported identifier.
  • Changing the signature of an exported function or method.
  • Removing or renaming a field of an exported struct, or changing its type.
  • Adding a method to an exported interface that users are meant to implement.
  • Changing documented behavior that callers could reasonably rely on.
  • Dropping support for an MCP spec revision.

The following are not breaking, and may land in a minor or patch release:

  • Adding an exported identifier, or a field to an exported struct.
  • Fixing behavior that contradicted its documentation.
  • Refactoring that leaves the exported API unchanged.
  • Adding support for a new MCP spec revision.
  • Raising the minimum Go version to one still supported upstream, per the README.

Deprecation

An API on its way out is marked with a // Deprecated: comment naming its replacement, which gopls and staticcheck surface at call sites. It keeps working until the next major version, since removing it would itself be a breaking change.

Protocol features that the specification deprecates are a separate matter and follow the spec's timeline rather than this policy. The features deprecated by SEP-2577 — roots, sampling and logging — remain supported for at least twelve months, as noted in the README.

Any change to the exported API, breaking or not, goes through the proposal process.

Timeouts

If a contributor hasn't responded to issue questions or PR comments in two weeks, the issue or PR may be closed. It can be reopened when the contributor can resume work.

Code of conduct

This project follows the Go Community Code of Conduct. If you encounter a conduct-related issue, please mail conduct@golang.org.

Governance

Initially, the Go SDK repository will be administered by the Go team and Anthropic, and they will be the approvers (the set of people able to merge PRs to the SDK), also referred to as the 'Working Group'. The policies here are also intended to satisfy necessary constraints of the Go team's participation in the project. This may change in the future: see 'Ongoing Evaluation' below.

Working Group meetings

On a regular basis, the Working Group will host a virtual meeting to discuss outstanding proposals and other changes to the SDK. These meetings and their agendas will be announced in advance, and open to all. The meetings will be recorded, and recordings and meeting notes will be made available afterward. (TODO: decide on a mechanism for tracking these meetings--likely a GitHub issue.)

This process is similar to the Go Tools call, though it is expected that meetings will at least initially occur on a more frequent basis.

Discord

Discord (either the public or private Anthropic discord servers) should only be used for logistical coordination or answering questions. For transparency and durability, design discussion and decisions should occur in GitHub issues, GitHub discussions, or public steering meetings.

Antitrust considerations

The goal of this repository is to provide a robust and complete Go implementation of the model context protocol, in an open and transparent manner, without bias toward specific integration paths or providers. To that end, the model context protocol organization's antitrust policy applies to all participation in this project.