|
| 1 | +<!-- Autogenerated by weave; DO NOT EDIT --> |
| 2 | +# Contributing to the Go MCP SDK |
| 3 | + |
| 4 | +Thank you for your interest in contributing! The Go SDK needs active |
| 5 | +contributions to keep up with changes in the MCP spec, fix bugs, and accommodate |
| 6 | +new and emerging use-cases. We welcome all forms of contribution, from filing |
| 7 | +and reviewing issues, to contributing fixes, to proposing and implementing new |
| 8 | +features. |
| 9 | + |
| 10 | +As described in the [design document](https://github.com/modelcontextprotocol/go-sdk/blob/main/design/design.md), it is important for |
| 11 | +the MCP SDK to remain idiomatic, future-proof, and extensible. The process |
| 12 | +described here is intended to ensure that the SDK evolves safely and |
| 13 | +transparently, while adhering to these goals. |
| 14 | + |
| 15 | +1. [Development setup](#development-setup) |
| 16 | + 1. [Conformance tests](#conformance-tests) |
| 17 | +1. [Filing issues](#filing-issues) |
| 18 | + 1. [Bugs](#bugs) |
| 19 | + 1. [Proposals](#proposals) |
| 20 | + 1. [Design discussion](#design-discussion) |
| 21 | +1. [Contributing code](#contributing-code) |
| 22 | + 1. [Adding and updating dependencies](#adding-and-updating-dependencies) |
| 23 | + 1. [Updating the README](#updating-the-readme) |
| 24 | +1. [Timeouts](#timeouts) |
| 25 | +1. [Code of conduct](#code-of-conduct) |
| 26 | +1. [Governance](#governance) |
| 27 | + 1. [Working Group meetings](#working-group-meetings) |
| 28 | + 1. [Discord](#discord) |
| 29 | + 1. [Antitrust considerations](#antitrust-considerations) |
| 30 | + |
| 31 | + |
| 32 | +## Development setup |
| 33 | + |
| 34 | +This module can be built and tested using the standard Go toolchain. Run `go |
| 35 | +test ./...` to run all its tests. |
| 36 | + |
| 37 | +To test changes to this module against another module that uses the SDK, we |
| 38 | +recommend using a [`go.work` file](https://go.dev/doc/tutorial/workspaces) to |
| 39 | +define a multi-module workspace. For example, if your directory contains a |
| 40 | +`project` directory containing your project, and a `go-sdk` directory |
| 41 | +containing the SDK, run: |
| 42 | + |
| 43 | +```sh |
| 44 | +go work init ./project ./go-sdk |
| 45 | +``` |
| 46 | + |
| 47 | +### Conformance tests |
| 48 | + |
| 49 | +The SDK includes a script to run the official MCP conformance tests against the |
| 50 | +SDK's conformance server: |
| 51 | + |
| 52 | +```sh |
| 53 | +./scripts/conformance.sh |
| 54 | +``` |
| 55 | + |
| 56 | +By default, results are cleaned up after the script runs. To save results to a |
| 57 | +specific directory: |
| 58 | + |
| 59 | +```sh |
| 60 | +./scripts/conformance.sh --result_dir ./conformance-results |
| 61 | +``` |
| 62 | + |
| 63 | +To run against a local checkout of the |
| 64 | +[conformance repo](https://github.com/modelcontextprotocol/conformance) instead |
| 65 | +of the latest npm release: |
| 66 | + |
| 67 | +```sh |
| 68 | +./scripts/conformance.sh --conformance_repo ~/src/conformance |
| 69 | +``` |
| 70 | + |
| 71 | +Note: you must run `npm install` in the conformance repo first. |
| 72 | + |
| 73 | +Run `./scripts/conformance.sh --help` for more options. |
| 74 | + |
| 75 | +## Filing issues |
| 76 | + |
| 77 | +This project uses the [GitHub issue |
| 78 | +tracker](https://github.com/modelcontextprotocol/go-sdk/issues) for issues. The |
| 79 | +process for filing bugs and proposals is described below. |
| 80 | + |
| 81 | +TODO(rfindley): describe a process for asking general questions in the public |
| 82 | +MCP discord server. |
| 83 | + |
| 84 | +### Bugs |
| 85 | + |
| 86 | +Please [report |
| 87 | +bugs](https://github.com/modelcontextprotocol/go-sdk/issues/new). If the SDK is |
| 88 | +not working as you expected, it is likely due to a bug or inadequate |
| 89 | +documentation, and reporting an issue will help us address this shortcoming. |
| 90 | + |
| 91 | +When reporting a bug, make sure to answer these five questions: |
| 92 | + |
| 93 | +1. What did you do? |
| 94 | +2. What did you see? |
| 95 | +3. What did you expect to see? |
| 96 | +4. What version of the Go MCP SDK are you using? |
| 97 | +5. What version of Go are you using (`go version`)? |
| 98 | + |
| 99 | +### Proposals |
| 100 | + |
| 101 | +A proposal is an issue that proposes a new API for the SDK, or a change to the |
| 102 | +signature or behavior of an existing API. Proposals should be labeled with the |
| 103 | +'proposal' label, and require an explicit approval from a maintainer before |
| 104 | +being accepted (indicated by the 'proposal-accepted' label). Proposals must |
| 105 | +remain open for at least a week to allow discussion before being accepted or |
| 106 | +declined by a maintainer. |
| 107 | + |
| 108 | +Proposals that are straightforward and uncontroversial may be approved based on |
| 109 | +discussion on the issue tracker or in a GitHub Discussion. However, proposals |
| 110 | +that are deemed to be sufficiently unclear or complicated may be deferred to a |
| 111 | +regular Working Group meeting (see 'Governance' below). |
| 112 | + |
| 113 | +This process is similar to the [Go proposal |
| 114 | +process](https://github.com/golang/proposal), but is necessarily lighter weight |
| 115 | +to accommodate the greater rate of change expected for the SDK. |
| 116 | + |
| 117 | +### Design discussion |
| 118 | + |
| 119 | +For open ended design discussion (anything that doesn't fall into the issue |
| 120 | +categories above), use [GitHub |
| 121 | +Discussions](https://github.com/modelcontextprotocol/go-sdk/discussions). |
| 122 | +Ideally, each discussion should be focused on one aspect of the design. For |
| 123 | +example: Tool Binding and Session APIs would be two separate discussions. |
| 124 | +When discussions reach a consensus, they should be promoted into proposals. |
| 125 | + |
| 126 | +## Contributing code |
| 127 | + |
| 128 | +The project uses GitHub pull requests (PRs) to review changes. |
| 129 | + |
| 130 | +Any significant change should be associated with a GitHub issue. Issues that |
| 131 | +are deemed to be good opportunities for contribution are be labeled ['Help |
| 132 | +Wanted'](https://github.com/modelcontextprotocol/go-sdk/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22). |
| 133 | +If you want to work on such an issue, please first comment on the issue to say |
| 134 | +that you're interested in contributing. For issues _not_ labeled 'Help Wanted', |
| 135 | +it is recommended that you ask (and wait for confirmation) on the issue before |
| 136 | +contributing, to avoid duplication of effort or wasted work. For nontrivial |
| 137 | +changes that _don't_ relate to an existing issue, please file an issue first. |
| 138 | + |
| 139 | +Changes should be high quality and well tested, and should generally follow the |
| 140 | +[Google Go style guide](https://google.github.io/styleguide/go/). Commit |
| 141 | +messages should follow the [format used by the Go |
| 142 | +project](https://go.dev/wiki/CommitMessage). |
| 143 | + |
| 144 | +Unless otherwise noted, the Go source files are distributed under the license |
| 145 | +found in the LICENSE file. New contributions are licensed under Apache 2.0. All |
| 146 | +Go files in the SDK should have a copyright header following the format below: |
| 147 | + |
| 148 | +```go |
| 149 | +// Copyright 2025 The Go MCP SDK Authors. All rights reserved. |
| 150 | +// Use of this source code is governed by the license |
| 151 | +// that can be found in the LICENSE file. |
| 152 | +``` |
| 153 | + |
| 154 | +### Adding and updating dependencies |
| 155 | + |
| 156 | +In general, the SDK tries to use as few dependencies as possible. Each new |
| 157 | +dependency is a potential source for bugs, churn, and conflicts for our users. |
| 158 | +Therefore, we require a [proposal](#proposals) for any new module dependency, |
| 159 | +including upgrading an existing module to a new major version. New dependencies |
| 160 | +should be evaluated for their stability and security, and should be |
| 161 | +well-established in the Go ecosystem. |
| 162 | + |
| 163 | +In general, dependencies should be for internal use by the SDK implementation, |
| 164 | +or for testing. Do not include types from dependencies in the SDK API. |
| 165 | + |
| 166 | +On the other hand, updating existing dependencies can be done at any time |
| 167 | +without a proposal, as long as their major version does not change. Prefer to |
| 168 | +update dependencies immediately following a release of the SDK, to allow as |
| 169 | +much time as possible to find issues with the new version. |
| 170 | + |
| 171 | +After any change to dependencies, run govulncheck to check them for |
| 172 | +vulnerabilities. |
| 173 | + |
| 174 | +``` |
| 175 | +go run golang.org/x/vuln/cmd/govulncheck@latest |
| 176 | +``` |
| 177 | + |
| 178 | +### Updating the README |
| 179 | + |
| 180 | +The top-level `README.md` file is generated from `internal/readme/README.src.md` |
| 181 | +and should not be edited directly. To update the README: |
| 182 | + |
| 183 | +1. Make your changes to `internal/readme/README.src.md` |
| 184 | +2. Run `go generate ./internal/readme` from the repository root to regenerate `README.md` |
| 185 | +3. Commit both files together |
| 186 | + |
| 187 | +The CI system will automatically check that the README is up-to-date by running |
| 188 | +`go generate ./internal/readme` and verifying no changes result. If you see a CI failure about the |
| 189 | +README being out of sync, follow the steps above to regenerate it. |
| 190 | + |
| 191 | +## Timeouts |
| 192 | + |
| 193 | +If a contributor hasn't responded to issue questions or PR comments in two weeks, |
| 194 | +the issue or PR may be closed. It can be reopened when the contributor can resume |
| 195 | +work. |
| 196 | + |
| 197 | +## Code of conduct |
| 198 | + |
| 199 | +This project follows the [Go Community Code of Conduct](https://go.dev/conduct). |
| 200 | +If you encounter a conduct-related issue, please mail conduct@golang.org. |
| 201 | + |
| 202 | +## Governance |
| 203 | + |
| 204 | +Initially, the Go SDK repository will be administered by the Go team and |
| 205 | +Anthropic, and they will be the approvers (the set of people able to merge PRs |
| 206 | +to the SDK), also referred to as the 'Working Group'. The policies here are |
| 207 | +also intended to satisfy necessary constraints of the Go team's participation |
| 208 | +in the project. This may change in the future: see 'Ongoing Evaluation' below. |
| 209 | + |
| 210 | +### Working Group meetings |
| 211 | + |
| 212 | +On a regular basis, the Working Group will host a virtual meeting to discuss |
| 213 | +outstanding proposals and other changes to the SDK. These meetings and their |
| 214 | +agendas will be announced in advance, and open to all. The meetings will be |
| 215 | +recorded, and recordings and meeting notes will be made available afterward. |
| 216 | +(TODO: decide on a mechanism for tracking these meetings--likely a GitHub |
| 217 | +issue.) |
| 218 | + |
| 219 | +This process is similar to the [Go Tools |
| 220 | +call](https://go.dev/wiki/golang-tools), though it is expected that meetings |
| 221 | +will at least initially occur on a more frequent basis. |
| 222 | + |
| 223 | +### Discord |
| 224 | + |
| 225 | +Discord (either the public or private Anthropic discord servers) should only be |
| 226 | +used for logistical coordination or answering questions. For transparency and |
| 227 | +durability, design discussion and decisions should occur in GitHub issues, |
| 228 | +GitHub discussions, or public steering meetings. |
| 229 | + |
| 230 | +### Antitrust considerations |
| 231 | + |
| 232 | +The goal of this repository is to provide a robust and complete Go |
| 233 | +implementation of the model context protocol, in an open and transparent |
| 234 | +manner, without bias toward specific integration paths or providers. To that |
| 235 | +end, the model context protocol organization's [antitrust |
| 236 | +policy](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/ANTITRUST.md) |
| 237 | +applies to all participation in this project. |
0 commit comments