github-featured/modelcontextprotocol--python-sdk

Files

T

Max Isbey 5150037733 Add machine-translated docs sites for zh-CN, ja, ko and pt-BR

Ship preview translations of the docs in Simplified Chinese, Japanese,
Korean and Brazilian Portuguese, served at /zh-CN/, /ja/, /ko/ and /pt-BR/
next to the English site (three pages each to start). English stays the
single source of truth; everything else is generated and never hand-edited.

scripts/docs/translations.py drives it (status / translate / stage /
languages). `translate` re-translates only the `##` sections whose English
changed and carries the rest of the page over byte-for-byte from the previous
translation, then gates the result: heading anchors and code blocks are
re-imposed from the English, the structure (sections, headings, fences, links,
inline code, admonitions, glossary rules) is checked with the findings fed
back for another attempt, and a stronger model reviews the meaning against the
English. Per-language inputs — instructions.md (register, voice, typography)
and glossary.json (termbase, keep-in-English list, banned renderings) — are the
human-edited part; the pages and state.json under i18n/<code>/ are generated,
so a correction goes into the inputs and holds across every future run.

The build stages each language over the English tree (translations overlaid,
notices stamped in — machine-translated, may be behind English, not translated
— and links into the API reference pointed at the English one) and builds it
strictly into site/<code>/. Heading ids are pinned into the translations from
the ids the English site renders, so #fragment links resolve on every language
site without touching the English pages. An outdated translation is served
with a warning unless the English page's links or anchors moved under it, so an
English edit can never break a language build. Every config carries the same
language switcher.

2026-07-31 21:11:06 +00:00

6.8 KiB

Raw Permalink Blame History

Contributing

Thank you for your interest in contributing to the MCP Python SDK! This document provides guidelines and instructions for contributing.

Before You Start

We welcome contributions! These guidelines exist to save everyone time, yours included. Following them means your work is more likely to be accepted.

All pull requests require a corresponding issue. Unless your change is trivial (typo, docs tweak, broken link), create an issue first. Every merged feature becomes ongoing maintenance, so we need to agree something is worth doing before reviewing code. PRs without a linked issue will be closed.

Having an issue doesn't guarantee acceptance. Wait for maintainer feedback or a ready for work label before starting. PRs for issues without buy-in may also be closed.

Use issues to validate your idea before investing time in code. PRs are for execution, not exploration.

AI-Assisted Contributions

Important

If you used AI assistance for a contribution, disclose it in the PR or issue.

We use AI tooling constantly and have no problem with you using it too. But somewhere in the loop there has to be a human who actually understands the change. We have a large backlog and limited reviewer time—we're not spending it on code nobody has read. Not disclosing is also just rude to the people on the other end.

Disclose it. One line in the PR or issue description. That's it.
Own it. You can explain the change in your own words. When a maintainer asks a question, the answer comes from you, not pasted from a chat window.
No drive-by agents. PRs, issues, or comments produced by an autonomous agent with no human review get closed on sight. If your agent is auto-filing PRs against our open issues, stop.

Undisclosed AI contributions get closed. Repeat offenders get banned from the modelcontextprotocol org.

The SDK is Opinionated

Not every contribution will be accepted, even with a working implementation. We prioritize maintainability and consistency over adding capabilities. This is at maintainers' discretion.

What Needs Discussion

These always require an issue first:

New public APIs or decorators
Architectural changes or refactoring
Changes that touch multiple modules
Features that might require spec changes (these need a SEP first)

Bug fixes for clear, reproducible issues are welcome—but still create an issue to track the fix.

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 or needs maintainer action are not ready for work—wait for maintainer input first.

Before starting, comment on the issue so we can assign it to you. This prevents duplicate effort.

Development Setup

Make sure you have Python 3.10+ installed
Install uv
Fork the repository
Clone your fork: git clone https://github.com/YOUR-USERNAME/python-sdk.git
Install dependencies:

uv sync --frozen --all-extras --dev

Set up pre-commit hooks:

uv tool install pre-commit --with pre-commit-uv --force-reinstall

Development Workflow

Choose the correct branch for your changes:

Change Type	Target Branch	Example
New features and fixes for v2	`main`	New APIs, refactors
Security fixes for v1	`v1.x`	Critical patches
Critical bug fixes for v1	`v1.x`	Backports of severe bugs

Note: main is the current stable line (v2). The v1.x branch is the previous major's maintenance line and receives only security and critical bug fixes.

Create a new branch from your chosen base branch
Make your changes
Ensure tests pass:

uv run pytest

Run type checking:

uv run pyright

Run linting:

uv run ruff check .
uv run ruff format .

Update README snippets if you modified docs_src/ code embedded in the README:

uv run scripts/update_readme_snippets.py

(Optional) Run pre-commit hooks on all files:

pre-commit run --all-files

Submit a pull request to the same branch you branched from

Code Style

We use ruff for linting and formatting
Follow PEP 8 style guidelines
Add type hints to all functions
Include docstrings for public APIs

Documentation and Translations

Documentation contributions are English only: the pages under docs/ are the source of truth, and the translated documentation sites are generated from them, guided by the per-language style guides and glossaries under i18n/<lang>/. Never edit the generated pages under i18n/<lang>/pages/—the next translation run overwrites them. To fix a translation, change that language's instructions.md or glossary.json (or the English page, if that's where the problem is), and the fix carries into every future run. See i18n/README.md for the details.

Pull Requests

By the time you open a PR, the "what" and "why" should already be settled in an issue. This keeps reviews focused on implementation.

Scope

Small PRs get reviewed fast. Large PRs sit in the queue.

A few dozen lines can be reviewed in minutes. Hundreds of lines across many files takes real effort and things slip through. If your change is big, break it into smaller PRs or get alignment from a maintainer first.

What Gets Rejected

No prior discussion: Features or significant changes without an approved issue
Scope creep: Changes that go beyond what was discussed
Misalignment: Even well-implemented features may be rejected if they don't fit the SDK's direction
Overengineering: Unnecessary complexity for simple problems
Undisclosed or unreviewed AI output: See AI-Assisted Contributions

Checklist

Update documentation as needed
Add tests for new functionality
Ensure CI passes
Address review feedback

Code of Conduct

Please note that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

License

By contributing, you agree that your contributions will be licensed under the MIT License.

6.8 KiB Raw Permalink Blame History