docs(community): restructure community docs (rebase of #3363) by sarahnovotny · Pull Request #3441 · modelcontextprotocol/modelcontextprotocol

sarahnovotny · 2026-10-17T07:01:35Z

Supersedes #3363. That PR should be closed once this one is open.

This is @dsp-ant's #3363 rebased onto current main, with the merge conflicts resolved and the drift since 2026-09-15 repaired. His two commits keep his authorship; the two on top are mine.

Why a new pull request instead of a rebase in place

#3363 has been a draft since 2026-09-15 and is 196 commits behind main. Four files conflict on rebase (contributing.mdx, sep-guidelines.mdx, working-interest-groups.mdx, docs.json), and three rules that #3336 added after that branch was cut are silently removed by the restructure. Repairing that takes commits on top rather than a force-push to someone else's branch, so the work lives here and #3363 closes as superseded.

Commits

Commit	Author	What
`da1f3cb`	@dsp-ant	restructure community docs (unchanged, rebased)
`58b39c0`	@dsp-ant	address review of community docs restructure (rebased)
`f14dfaf`	@sarahnovotny	reconcile the restructure with merged upstream changes
`ae43efd`	@sarahnovotny	state the pull request creation policy accurately

`f14dfaf` — reconcile with upstream

Re-lands the three rules from #3336 that the restructure dropped:

prior discussion is required, and the pull request description must link to it; a SEP without a linked discussion is not accepted
the specification repository accepts pull requests from collaborators only
the sponsor confirms the discussion happened and is linked before setting in-review

It also repoints CONTRIBUTING.md at #workflow, since the restructure deletes the #step-by-step-process anchor it linked to, and brings both hand-maintained group lists back in sync — the docs.json nav and the "Current groups" table in working-interest-groups.mdx. That adds filesystems, governance, infrastructure, progressive-disclosure and scientific-computing, replaces the deleted primitive-grouping, and keeps the apps entry @dsp-ant added, which is still missing from the nav on main.

`ae43efd` — pull request creation policy

contributing.mdx claimed "No invitation or role is needed to attend or speak at a meeting, to comment on a pull request, or to open one." The repository's pull_request_creation_policy is collaborators_only, so that sentence is false as written. It now uses the wording adopted in the Governance Working Group charter (#3423): creation is limited to maintainers, with the fork / working-group-repository drafting route spelled out so an outside contributor knows what to do instead.

contributor-ladder.mdx said Contributors "may open pull requests in restricted repositories"; it now points at Contributing rather than restating the same rule in two places.

Open questions for reviewers

docs/community/contributing.mdx (−628 lines) may belong in a separate pull request. Discussion MCP Maintainer Day - September 16, 2026 (Amsterdam) #3403 assigns a contributing rewrite to another maintainer with a specific brief. The other 13 files here stand on their own, so this file can be dropped from this pull request if that work is in flight.
Three sections have no home in the restructured SEP guidelines and are deleted rather than moved: "Final SEPs are historical records / are not updated", "Transferring SEP Ownership", and "Copyright".
@dsp-ant's four open questions on docs(community): restructure community docs #3363: Q3 is confirmed — private vulnerability reporting is enabled on all seven repositories checked. Q1's substance already exists on main as a <Note>. Q2 and Q4 need a Core Maintainer decision.

Verification

prettier --check clean on every touched md / mdx
check:docs:js-comments OK across 359 MDX files
docs.json parses; 119 redirects, 85 of them under /seps/
navigation ↔ files reconcile for docs/community/: 0 broken links or anchors, 0 orphaned pages
check:seps fails, but it fails on main too — 43 SEPs against **Final**: 42 in docs/seps/index.mdx. This pull request touches neither file.
npx mint broken-links was not run; mint is not installed locally

🤖 Generated with Claude Code

Rewrite the community pages as prescriptive reference docs with less duplication between them. Merge the security page into a new Project Policies page, trim Contributing to an entry point, regroup the Community nav, and add the missing Apps WG charter to the nav.

Give the Code of Conduct reporting address, require group agendas to link Project Policies, drop the SEP dormancy automation claim, and remove a redirect for a URL that never existed.

Rebase of modelcontextprotocol#3363 onto main, restoring three rules the rewrite dropped. All three were merged after the branch point. - SEP guidelines: prior discussion is required and the pull request description must link to it, and the sponsor confirms that link before setting in-review (modelcontextprotocol#3336) - SEP guidelines: the repository accepts pull requests from collaborators only, which matches the repo's pull request creation policy - CONTRIBUTING.md: point the SEP guidelines link at #workflow; the Step-by-Step Process section it referenced was renamed by this restructure Both copies of the group lists are also brought up to date, in the docs.json nav and in the Current groups section: adding the Filesystems, Governance, Infrastructure and Progressive Disclosure working groups and the Scientific Computing interest group, and replacing the Primitive Grouping interest group, which upstream renamed to Progressive Disclosure. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The contributing page said that no role is needed to open a pull request and that group membership is not required to open one or submit a SEP. Pull request creation on the specification repository is limited to maintainers, as recorded in the Maintainer Day notes of 2026-09-16 and in the Governance Working Group charter. Replace the claim with the policy and the route the decision specified: draft from a fork or a working group repository and ask a maintainer to open the pull request and name the author. The contributor ladder listed pull requests in restricted repositories as a Member privilege, which the policy does not grant. It now points at the contributing page instead of restating a competing rule. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

localden

First review batch - thank you for looking through this! It's a bit hard to review this by hand because there are a lot of changes here, and for future changes would recommend splitting this into more scoped PRs.

localden · 2026-10-18T01:43:55Z


-Sections marked **(WG only)** are required for Working Groups and optional for Interest Groups.
+- The group must already be sponsored under [Forming a group](/community/working-interest-groups#forming-a-group).
+- Copy the template below into the charter file and replace the placeholders. Delete the `{/* */}` guidance comments or leave them as written: HTML comments break the MDX build, and `npm run format` corrupts a `{/* */}` comment that spans lines.


Can we instead have a skill or a more agent-based suggestion here? I'd love to reduce the manual copy/paste efforts.

localden · 2026-10-18T01:44:53Z

 ---

-Every MCP Working Group and Interest Group must maintain a charter document following this structure. Charters are stored at `docs/community/working-groups/<group-name>.mdx` or `docs/community/interest-groups/<group-name>.mdx` in the [modelcontextprotocol repository](https://github.com/modelcontextprotocol/modelcontextprotocol) and added to `docs/docs.json`.
+This page gives the charter template that every working group and interest group must follow and explains how to submit a charter. The template was adopted by [SEP-2149](/seps/2149-working-group-charter-template), a Specification Enhancement Proposal (SEP), and is changed, together with the rules in [Working Groups and Interest Groups](/community/working-interest-groups), by a Process SEP. Each charter lives at `docs/community/working-groups/<name>.mdx` or `docs/community/interest-groups/<name>.mdx` in the [modelcontextprotocol repository](https://github.com/modelcontextprotocol/modelcontextprotocol), records only the group's mission, scope, leadership, membership and operations, and does not restate those rules, which apply to every group. Sections marked **(WG only)** are required for working groups and optional for interest groups. To start a group, see [Forming a group](/community/working-interest-groups#forming-a-group).


The SEP URLs can also be simplified, and we can use /seps/2149

localden · 2026-10-18T01:45:25Z

+- The group must already be sponsored under [Forming a group](/community/working-interest-groups#forming-a-group).
+- Copy the template below into the charter file and replace the placeholders. Delete the `{/* */}` guidance comments or leave them as written: HTML comments break the MDX build, and `npm run format` corrupts a `{/* */}` comment that spans lines.
+- Open a pull request that adds the charter file, a navigation entry under Working Groups or Interest Groups in `docs/docs.json`, and a line under [Current groups](/community/working-interest-groups#current-groups).
+- Run `npm run prep` before pushing.


Can we reorder this if this is something that we need to do before pushing?

localden · 2026-10-18T01:46:12Z

+- Copy the template below into the charter file and replace the placeholders. Delete the `{/* */}` guidance comments or leave them as written: HTML comments break the MDX build, and `npm run format` corrupts a `{/* */}` comment that spans lines.
+- Open a pull request that adds the charter file, a navigation entry under Working Groups or Interest Groups in `docs/docs.json`, and a line under [Current groups](/community/working-interest-groups#current-groups).
+- Run `npm run prep` before pushing.
+- Both charter directories are CODEOWNERS-gated to Core Maintainers. A Core Maintainer's approving review on the pull request is the Core Maintainer approval that [Amending or retiring a group](/community/working-interest-groups#amending-or-retiring-a-group) requires.


Suggested change

- Both charter directories are CODEOWNERS-gated to Core Maintainers. A Core Maintainer's approving review on the pull request is the Core Maintainer approval that [Amending or retiring a group](/community/working-interest-groups#amending-or-retiring-a-group) requires.

- A Core Maintainer will review the pull request, as outlined in the [Amending or retiring a group](/community/working-interest-groups#amending-or-retiring-a-group) requirements.

localden · 2026-10-18T01:46:43Z

+- Open a pull request that adds the charter file, a navigation entry under Working Groups or Interest Groups in `docs/docs.json`, and a line under [Current groups](/community/working-interest-groups#current-groups).
+- Run `npm run prep` before pushing.
+- Both charter directories are CODEOWNERS-gated to Core Maintainers. A Core Maintainer's approving review on the pull request is the Core Maintainer approval that [Amending or retiring a group](/community/working-interest-groups#amending-or-retiring-a-group) requires.
+- Use [Transports](/community/working-groups/transports) (working group) or [Security](/community/interest-groups/security) (interest group) as a filled-in example.


This probably can be rendered as a note rather than a bulletpoint item, otherwise it reads like a step/requirement.

localden · 2026-10-18T01:49:54Z

+The [MCP Contributor Discord](https://discord.gg/6CSzBmMkjX) is for people working on the protocol and its projects. It is not a support channel: MCP users should read the documentation and ask in GitHub Discussions. Do not market products or services on the server, and mention vendors only as examples relevant to the specification.

-### Public Channels (Default)
+Channels are named `#general` for project-wide discussion, `#<name>-wg` and `#<name>-ig` for each working group and interest group, and `#<lang>-sdk-dev` for each SDK. Other projects have a channel such as `#inspector-dev`. Propose a new group in `#wg-ig-group-creation`. Responses are best-effort.


We should move away from ig - I will put a new SEP for transitioning IGs into more regular forums, so we might remove that here.

localden · 2026-10-18T01:50:41Z

- Community onboarding and contribution guidance
- Community feedback and collaborative brainstorming
- Public office hours and maintainer availability
+Discord is not the record. A Discord discussion heading toward a technical or governance decision must move to a GitHub Discussion or Issue. Every technical or governance decision, including a Core Maintainer outcome on a SEP, is written up in a Discussion or Issue with the `notes` label, or on the SEP's pull request. Specification changes are also recorded in the [changelog](/specification/draft/changelog), and process changes in these community pages.


up in a Discussion or Issue with the notes label

Just a discussion. We're no longer using issues for this.

localden · 2026-10-18T01:52:06Z

+## Join the work in progress

-### Join the Community
+Protocol work is organized in [working groups and interest groups](/community/working-interest-groups). Their meetings are open to anyone and are listed on [meet.modelcontextprotocol.io](https://meet.modelcontextprotocol.io/). [Meetings and channels](/community/working-interest-groups#meetings-and-channels) sets out how a meeting is announced and minuted. No invitation or role is needed to attend or speak at a meeting, to comment on a pull request, or to open an issue or a discussion. Pull request creation on the specification repository is limited to maintainers: share your change as a branch on a fork or in a working group repository and ask in the group's Discord channel for a maintainer to open the pull request and name you as the author. Belonging to a group is not required, though a SEP needs [prior discussion](/community/sep-guidelines#before-you-write) with the relevant group. Every meeting runs under the [Antitrust Policy](/community/antitrust). Read it before attending, especially if you participate on behalf of an employer.


Let's also not really allude to interest groups - they would be discussion forums. Or we can frame it that way, but the focus is on working groups.

Also we should scan this - let's not direct people to discussions but rather Discord for contribution/architectural discussions around the protocol, issues for reporting bugs or problems with the protocol or SDK.

localden · 2026-10-18T01:54:52Z

+## Fix docs or spec text

-Verify your setup:
+Open a pull request against the specification repository. For a typo or a single paragraph the GitHub web editor is enough, and CI runs the checks. Clone the repository for larger edits and run `npm run prep` before pushing. Setup and troubleshooting are in [CONTRIBUTING.md](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CONTRIBUTING.md).


We have restricted who can contribute to the spec/open PRs because of AI spam, so this would no longer work. We should suggest opening an issue first to report it.

localden · 2026-10-18T01:56:09Z

@@ -1,67 +0,0 @@
---


Is there a reason we're removing this document?

localden · 2026-10-18T06:20:49Z

Stacking a little contribution doc PR: sarahnovotny#2

dsp-ant and others added 4 commits October 16, 2026 03:51

docs(community): address review of community docs restructure

58b39c0

Give the Code of Conduct reporting address, require group agendas to link Project Policies, drop the SEP dormancy automation claim, and remove a redirect for a URL that never existed.

sarahnovotny requested review from a team as code owners October 17, 2026 07:01

localden requested changes Oct 18, 2026

View reviewed changes

localden mentioned this pull request Oct 18, 2026

docs(community): rewrite contributing page as concise steps sarahnovotny/modelcontextprotocol#2

Open

	- Both charter directories are CODEOWNERS-gated to Core Maintainers. A Core Maintainer's approving review on the pull request is the Core Maintainer approval that [Amending or retiring a group](/community/working-interest-groups#amending-or-retiring-a-group) requires.
	- A Core Maintainer will review the pull request, as outlined in the [Amending or retiring a group](/community/working-interest-groups#amending-or-retiring-a-group) requirements.

Conversation

sarahnovotny commented Oct 17, 2026

Why a new pull request instead of a rebase in place

Commits

f14dfaf — reconcile with upstream

ae43efd — pull request creation policy

Open questions for reviewers

Verification

Uh oh!

localden left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

localden commented Oct 18, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`f14dfaf` — reconcile with upstream

`ae43efd` — pull request creation policy