diff --git a/docs/community/communication.mdx b/docs/community/communication.mdx index 2a9846ab2..46ec39108 100644 --- a/docs/community/communication.mdx +++ b/docs/community/communication.mdx @@ -71,12 +71,13 @@ For bug reports, feature tracking, and actionable development tasks. When to use: -- Submit SEP proposals (following the [SEP guidelines](./sep-guidelines)) - Bug reports with reproducible steps - Documentation improvements with specific scope - CI/CD problems and infrastructure issues - Release tasks and milestone tracking +**Note**: SEP proposals are submitted as pull requests to the [`seps/` directory](https://github.com/modelcontextprotocol/specification/tree/main/seps), not as GitHub Issues. See the [SEP guidelines](./sep-guidelines) for details. + ### Security Issues **Do not post security issues publicly.** Instead: @@ -89,10 +90,10 @@ When to use: All MCP decisions are documented and captured in public channels. -- **Technical decisions**: [GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues) and SEPs. +- **Technical decisions**: [GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues) and [SEPs](https://github.com/modelcontextprotocol/specification/tree/main/seps). - **Specification changes**: [On the Model Context Protocol website](https://modelcontextprotocol.io/specification/draft/changelog). - **Process changes**: [Community documentation](https://modelcontextprotocol.io/community/governance). -- **Governance decisions and updates**: [GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues) and SEPs. +- **Governance decisions and updates**: [GitHub Issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues) and [SEPs](https://github.com/modelcontextprotocol/specification/tree/main/seps). When documenting decisions, we will retain as much context as possible: diff --git a/docs/community/governance.mdx b/docs/community/governance.mdx index aaf7b6397..974ce1889 100644 --- a/docs/community/governance.mdx +++ b/docs/community/governance.mdx @@ -104,11 +104,11 @@ Core maintainers and maintainers are encouraged to improve any part of the MCP p #### Specification Enhancement Proposal (SEP) -Proposed changes to the specification must come in the form of a written version, starting with a summary of the proposal, outlining the **problem** it tries to solve, propose **solution**, **alternatives**, **considerations, outcomes** and **risks**. The [SEP Guidelines](/community/sep-guidelines) outline information on the expected structure of SEPs. SEP's should be created as issues in the [specification repository](https://github.com/modelcontextprotocol/specification) and tagged with the labels `proposal, sep`. +Proposed changes to the specification must come in the form of a written version, starting with a summary of the proposal, outlining the **problem** it tries to solve, propose **solution**, **alternatives**, **considerations, outcomes** and **risks**. The [SEP Guidelines](/community/sep-guidelines) outline information on the expected structure of SEPs. SEPs are submitted as pull requests to the [`seps/` directory](https://github.com/modelcontextprotocol/specification/tree/main/seps) in the specification repository. -All proposals must have a **sponsor** from the MCP steering group (maintainer, core maintainer or lead core maintainer). The sponsor is responsible for ensuring that the proposal is actively developed, meets the quality standard for proposals and is responsible for presenting and discussing it in meetings of core maintainers. Maintainer and Core Maintainer groups should review open proposals without sponsors in regular intervals. Proposals that do not find a sponsor within six months are automatically rejected. +All proposals must have a **sponsor** from the MCP steering group (maintainer, core maintainer or lead core maintainer). The sponsor is responsible for ensuring that the proposal is actively developed, meets the quality standard for proposals, **updating the SEP status** in the markdown file, and presenting and discussing it in meetings of core maintainers. Maintainer and Core Maintainer groups should review open proposals without sponsors at regular intervals. Proposals that do not find a sponsor within six months are automatically rejected. -Once proposals have a sponsor, they are assigned to the sponsor and are tagged `draft`. +Once proposals have a sponsor, the sponsor assigns themselves to the PR and updates the SEP status to `draft`. ## Communication diff --git a/docs/community/sep-guidelines.mdx b/docs/community/sep-guidelines.mdx index 1cdc5169d..739539fc4 100644 --- a/docs/community/sep-guidelines.mdx +++ b/docs/community/sep-guidelines.mdx @@ -9,11 +9,11 @@ SEP stands for Specification Enhancement Proposal. A SEP is a design document pr We intend SEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into MCP. The SEP author is responsible for building consensus within the community and documenting dissenting opinions. -Because the SEPs are maintained as text files in a versioned repository (GitHub Issues), their revision history is the historical record of the feature proposal. +SEPs are maintained as markdown files in the [`seps/` directory](https://github.com/modelcontextprotocol/specification/tree/main/seps) of the specification repository. Their revision history serves as the historical record of the feature proposal. -## What qualifies a SEP? +## What qualifies as a SEP? -The goal is to reserve the SEP process for changes that are substantial enough to require broad community discussion, a formal design document, and a historical record of the decision-making process. A regular GitHub issue or pull request is often more appropriate for smaller, more direct changes. +The goal is to reserve the SEP process for changes that are substantial enough to require broad community discussion, a formal design document, and a historical record of the decision-making process. A regular GitHub pull request is often more appropriate for smaller, more direct changes. Consider proposing a SEP if your change involves any of the following: @@ -42,41 +42,66 @@ Each SEP must have an **SEP author** -- someone who writes the SEP using the sty ### SEP Workflow -SEPs should be submitted as a GitHub Issue in the [specification repository](https://github.com/modelcontextprotocol/modelcontextprotocol). The standard SEP workflow is: +SEPs are submitted as pull requests to the [`seps/` directory](https://github.com/modelcontextprotocol/specification/tree/main/seps) in the specification repository. The standard SEP workflow is: -1. You, the SEP author, create a [well-formatted](#sep-format) GitHub Issue with the `SEP` and `proposal` tags. The SEP number is the same as the GitHub Issue number, the two can be used interchangeably. -2. Find a Core Maintainer or Maintainer to sponsor your proposal. Core Maintainers and Maintainers will regularly go over the list of open proposals to determine which proposals to sponsor. You can tag relevant maintainers from [the maintainer list](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md) in your proposal. -3. Once a sponsor is found, the GitHub Issue is assigned to the sponsor. The sponsor will add the `draft` tag, ensure the SEP number is in the title, and assign a milestone. -4. The sponsor will informally review the proposal and may request changes based on community feedback. When ready for formal review, the sponsor will add the `in-review` tag. -5. After the `in-review` tag is added, the SEP enters formal review by the Core Maintainers team. The SEP may be accepted, rejected, or returned for revision. -6. If the SEP has not found a sponsor within three months, Core Maintainers may close the SEP as `dormant`. +1. **Draft your SEP** as a markdown file named `0000-your-feature-title.md`, using `0000` as a placeholder for the SEP number. Follow the [SEP format](#sep-format) described below. + +2. **Create a pull request** adding your SEP file to the `seps/` directory in the [specification repository](https://github.com/modelcontextprotocol/specification). + +3. **Update the SEP number**: Once your PR is created, amend your commit to rename the file using the PR number (e.g., PR #1850 becomes `1850-your-feature-title.md`) and update the SEP header to reference the correct number. + +4. **Find a Sponsor**: Tag a Core Maintainer or Maintainer from [the maintainer list](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md) in your PR to request sponsorship. Maintainers regularly review open proposals to determine which to sponsor. + +5. **Sponsor assigns themselves**: Once a sponsor agrees, they will assign themselves to the PR and update the SEP status to `draft` in the markdown file. + +6. **Informal review**: The sponsor reviews the proposal and may request changes based on community feedback. Discussion happens in the PR comments. + +7. **Formal review**: When the SEP is ready, the sponsor updates the status to `in-review`. The SEP enters formal review by the Core Maintainers team. + +8. **Resolution**: The SEP may be `accepted`, `rejected`, or returned for revision. The sponsor updates the status accordingly. + +9. **Finalization**: Once accepted, the reference implementation must be completed. When complete and incorporated into the specification, the sponsor updates the status to `final`. + +If a SEP has not found a sponsor within six months, Core Maintainers may close the PR and mark the SEP as `dormant`. ### SEP Format Each SEP should have the following parts: -1. **Preamble** -- A short descriptive title, the names and contact info for each author, the current status. +1. **Preamble** -- A short descriptive title, the names and contact info for each author, the current status, SEP type, and PR number. 2. **Abstract** -- A short (~200 word) description of the technical issue being addressed. 3. **Motivation** -- The motivation should clearly explain why the existing protocol specification is inadequate to address the problem that the SEP solves. The motivation is critical for SEPs that want to change the Model Context Protocol. SEP submissions without sufficient motivation may be rejected outright. -4. **Specification** -- The technical specification should describe the syntax and semantics of any new protocol feature. The specification should be detailed enough to allow competing, interoperable implementations. A PR with the changes to the specification should be provided. +4. **Specification** -- The technical specification should describe the syntax and semantics of any new protocol feature. The specification should be detailed enough to allow competing, interoperable implementations. 5. **Rationale** -- The rationale explains why particular design decisions were made. It should describe alternate designs that were considered and related work. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion. 6. **Backward Compatibility** -- All SEPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The SEP must explain how the author proposes to deal with these incompatibilities. 7. **Reference Implementation** -- The reference implementation must be completed before any SEP is given status "Final", but it need not be completed before the SEP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of protocol details. 8. **Security Implications** -- If there are security concerns in relation to the SEP, those concerns should be explicitly written out to make sure reviewers of the SEP are aware of them. +See the [SEP template](https://github.com/modelcontextprotocol/specification/blob/main/seps/README.md#sep-file-structure) for the complete file structure. + ### SEP States -SEPs can be one one of the following states +SEPs can be in one of the following states: -- `proposal`: SEP proposal without a sponsor. -- `draft`: SEP proposal with a sponsor. -- `in-review`: SEP proposal ready for review. +- `draft`: SEP proposal with a sponsor, undergoing informal review. +- `in-review`: SEP proposal ready for formal review by Core Maintainers. - `accepted`: SEP accepted by Core Maintainers, but still requires final wording and reference implementation. - `rejected`: SEP rejected by Core Maintainers. -- `withdrawn`: SEP withdrawn. -- `final`: SEP finalized. +- `withdrawn`: SEP withdrawn by the author. +- `final`: SEP finalized with reference implementation complete. - `superseded`: SEP has been replaced by a newer SEP. -- `dormant`: SEP that has not found sponsors and was subsequently closed. +- `dormant`: SEP that has not found a sponsor and was subsequently closed. + +### Status Management + +**The Sponsor is responsible for updating the SEP status.** This ensures that status transitions are made by someone with the authority and context to do so appropriately. The sponsor: + +1. Updates the `Status` field directly in the SEP markdown file +2. Applies matching labels to the pull request (e.g., `draft`, `in-review`, `accepted`) + +Both the markdown status field and PR labels should be kept in sync. The markdown file serves as the canonical record (versioned with the proposal), while PR labels make it easy to filter and search for SEPs by status. + +Authors should request status changes through their sponsor rather than modifying the status field or labels themselves. ### SEP Review & Resolution @@ -92,9 +117,20 @@ Once a SEP has been accepted, the reference implementation must be completed. Wh A SEP can also be "Rejected" or "Withdrawn". A SEP that is "Withdrawn" may be re-submitted at a later date. +## The Sponsor Role + +A Sponsor is a Core Maintainer or Maintainer who champions the SEP through the review process. The sponsor's responsibilities include: + +- Reviewing the proposal and providing constructive feedback +- Requesting changes based on community input +- **Updating the SEP status** as the proposal progresses through the workflow +- Initiating formal review when the SEP is ready +- Presenting and discussing the proposal at Core Maintainer meetings +- Ensuring the proposal meets quality standards + ## Reporting SEP Bugs, or Submitting SEP Updates -How you report a bug, or submit a SEP update depends on several factors, such as the maturity of the SEP, the preferences of the SEP author, and the nature of your comments. For SEPs not yet reaching `final` state, it's probably best to send your comments and changes directly to the SEP author. Once SEP is finalized, you may want to submit corrections as a GitHub comment on the issue or pull request to the reference implementation. +How you report a bug, or submit a SEP update depends on several factors, such as the maturity of the SEP, the preferences of the SEP author, and the nature of your comments. For SEPs not yet reaching `final` state, it's probably best to comment directly on the SEP's pull request. Once a SEP is finalized and merged, you may submit updates by creating a new pull request that modifies the SEP file. ## Transferring SEP Ownership diff --git a/docs/specification/draft/changelog.mdx b/docs/specification/draft/changelog.mdx index fa9164271..cf8e87ec7 100644 --- a/docs/specification/draft/changelog.mdx +++ b/docs/specification/draft/changelog.mdx @@ -31,6 +31,10 @@ the previous revision, [2025-06-18](/specification/2025-06-18). 1. Decouple request payloads from RPC method definitions into standalone parameter schemas. ([SEP-1319](https://github.com/modelcontextprotocol/specification/issues/1319), PR [#1284](https://github.com/modelcontextprotocol/specification/pull/1284)) +## Process changes + +1. Formalize PR-based SEP workflow with markdown files in `seps/` directory, PR-derived numbering, sponsor responsibilities, and status management via PR labels ([SEP-1850](https://github.com/modelcontextprotocol/specification/pull/1850)). + ## Full changelog For a complete list of all changes that have been made since the last protocol revision, diff --git a/seps/1850-pr-based-sep-workflow.md b/seps/1850-pr-based-sep-workflow.md new file mode 100644 index 000000000..c01be3009 --- /dev/null +++ b/seps/1850-pr-based-sep-workflow.md @@ -0,0 +1,179 @@ +# SEP-1850: PR-Based SEP Workflow + +- **Status**: Draft +- **Type**: Process +- **Created**: 2025-11-20 +- **Author(s)**: Nick Cooper (@nickcoai), David Soria Parra (@davidsp) +- **Sponsor**: David Soria Parra (@davidsp) +- **PR**: https://github.com/modelcontextprotocol/specification/pull/1850 + +## Abstract + +This SEP formalizes the pull request-based SEP workflow that stores proposals as markdown files in the `seps/` directory of the Model Context Protocol specification repository. The workflow assigns SEP numbers from pull request numbers, maintains version history in Git, and replaces the previous GitHub Issues-based process. This establishes a file-based approach as the canonical way to author, review, and accept SEPs. + +## Motivation + +The issue-based SEP process introduced several challenges: + +- **Dispersed content**: Proposal content was scattered across GitHub issues, linked documents, and pull requests, making review and archival difficult. +- **Difficult collaboration**: Maintaining long-form specifications in issue bodies made iterative edits and multi-contributor collaboration harder. +- **Limited version control**: GitHub issues don't provide the same version control capabilities as Git-managed files. +- **Unclear status management**: The process lacked clear mechanisms for tracking status transitions and ensuring consistency between different sources of truth. + +A file-based workflow addresses these issues by: + +- Keeping every SEP in version control alongside the specification itself +- Providing Git's built-in review tooling, history, and searchability +- Linking SEP numbers to pull requests to eliminate manual bookkeeping +- Surfacing all discussion in the pull request thread +- Using PR labels in conjunction with file status for better discoverability + +## Specification + +### 1. Canonical Location + +- Every SEP lives in `seps/{NUMBER}-{slug}.md` in the specification repository +- The SEP number is always the pull request number that introduces the SEP file +- The `seps/` directory serves as the single source of truth for all SEPs + +### 2. Author Workflow + +1. **Draft the proposal** in `seps/0000-{slug}.md` using `0000` as a placeholder number +2. **Open a pull request** containing the draft SEP and any supporting materials +3. **Request a sponsor** from the Maintainers list; tag potential sponsors from [MAINTAINERS.md](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md) +4. **After the PR number is known**, amend the commit to rename the file to `{PR-number}-{slug}.md` and update the header (`SEP-{PR-number}` and `PR: #{PR-number}`) +5. **Wait for sponsor assignment**: Once a sponsor agrees, they will assign themselves and update the status to `Draft` + +### 3. Sponsor Responsibilities + +A Sponsor is a Core Maintainer or Maintainer who champions the SEP through the review process. The sponsor's responsibilities include: + +- **Reviewing the proposal** and providing constructive feedback +- **Requesting changes** based on community input +- **Managing status transitions** by: + - Ensuring that the `Status` field in the SEP markdown file is accurate + - Applying matching PR labels to keep them in sync with the file status + - Communicating status changes via PR comments +- **Initiating formal review** when the SEP is ready (moving from `Draft` to `In-Review`) +- **Raising to Core-Maintainers** ensuring the SEP is presented at the Core Maintainer meeting and that author and sponsor present. +- **Ensuring quality standards** are met before advancing the proposal +- **Tracking implementation** progress and ensuring reference implementations are complete before `Final` status + +### 4. Review Flow + +Status progression follows: `Draft → In-Review → Accepted → Final` + +Additional terminal states: `Rejected`, `Withdrawn`, `Superseded`, `Dormant` + +**Dormant status**: If a SEP does not find a sponsor within six months, Core Maintainers may close the PR and mark the SEP as `dormant`. + +Reference implementations must be tracked via linked pull requests or issues and must be complete before marking a SEP as `Final`. + +### 5. Documentation + +- `docs/community/sep-guidelines.mdx` serves as the contributor-facing instructions +- `seps/README.md` provides the concise reference for formatting, naming, sponsor responsibilities, and acceptance criteria +- Both documents must reflect this workflow and be kept in sync + +### 6. SEP File Structure + +Each SEP must include: + +```markdown +# SEP-{NUMBER}: {Title} + +- **Status**: Draft | In-Review | Accepted | Rejected | Withdrawn | Final | Superseded | Dormant +- **Type**: Standards Track | Informational | Process +- **Created**: YYYY-MM-DD +- **Author(s)**: Name (@github-username) +- **Sponsor**: @github-username (or "None" if seeking sponsor) +- **PR**: https://github.com/modelcontextprotocol/specification/pull/{NUMBER} + +## Abstract + +## Motivation + +## Specification + +## Rationale + +## Backward Compatibility + +## Security Implications + +## Reference Implementation +``` + +### 7. Status Management via PR Labels + +To improve discoverability and filtering: + +- Sponsors must apply PR labels that match the SEP status (`draft`, `in-review`, `accepted`, `final`, etc.) +- Both the markdown `Status` field and PR labels should be kept in sync +- The markdown file serves as the canonical record (versioned with the proposal) +- PR labels enable easy filtering and searching for SEPs by status +- Only sponsors should modify status fields and labels; authors should request changes through their sponsor + +### 8. Legacy Considerations + +- Contributors may optionally open a GitHub Issue for early discussion, but the authoritative SEP text lives in `seps/` +- Issues should link to the relevant file once a pull request exists +- SEP numbers are derived from PR numbers, not issue numbers + +## Rationale + +### Why File-Based? + +Storing SEPs as files keeps authoritative specs versioned with the code, mirroring successful processes used by PEPs (Python Enhancement Proposals) and other standards bodies. This approach: + +- Provides built-in version control via Git +- Enables standard code review workflows +- Maintains clear history of all changes +- Supports multi-contributor collaboration +- Integrates naturally with the specification repository + +### Why PR Numbers? + +Using pull request numbers: + +- Eliminates race conditions around manual numbering +- Creates natural traceability between proposal and discussion +- Prevents number conflicts +- Simplifies the contribution process +- Maintains a single discussion thread for review + +### Why PR Labels? + +Adding PR labels alongside the file status: + +- Enables quick filtering of SEPs by status without opening files +- Provides immediate visibility of SEP states in PR lists +- Supports GitHub's search and filter capabilities +- Complements the canonical markdown status field +- Reduces friction for maintainers managing multiple SEPs + +### Making This the Primary Process + +Maintaining two overlapping canonical processes risked divergence and created confusion for contributors. Establishing the file-based approach as the primary method: + +- Reduces cognitive overhead for new contributors +- Ensures consistency in the SEP corpus +- Simplifies maintenance for sponsors +- Aligns with industry best practices + +## Backward Compatibility + +- Existing issue-based SEPs remain valid and require no migration +- Historical GitHub Issue links continue to work +- Future SEPs should reference the new file locations in `seps/` +- Maintainers may optionally backfill historical SEPs into `seps/` for archival purposes + +## Security Implications + +No new security considerations beyond the standard code review process for pull requests. + +## Reference Implementation + +- This pull request (#1850) implements the canonical instructions in both `seps/README.md` and `docs/community/sep-guidelines.mdx` +- The process has been updated to reflect the PR-based workflow with status management via labels +- This SEP document itself serves as an example of the new format diff --git a/seps/README.md b/seps/README.md index b50c9fd05..50842449c 100644 --- a/seps/README.md +++ b/seps/README.md @@ -1,124 +1,3 @@ # Specification Enhancement Proposals (SEPs) -> **Experimental**: This is an experimental alternative method for creating SEPs. The default method remains using GitHub issues as described at https://modelcontextprotocol.io/community/sep-guidelines. - -## Overview - -This directory contains SEPs in markdown file format, similar to Python's PEP system. Each SEP is a standalone markdown document that describes a proposed enhancement to the MCP specification. - -## File Naming Convention - -SEP files use the format: `{NUMBER}-{TITLE}.md` - -Where: - -- **NUMBER**: The pull request number that introduces this SEP -- **TITLE**: A short, lowercase, hyphenated title - -Examples: - -- `1234-resource-templates.md` -- `1567-sampling-improvements.md` - -## Creating a New SEP - -1. **Draft your SEP** as a markdown file with a temporary name (e.g., `DRAFT-your-feature.md`) - -2. **Create a pull request** adding your SEP file to the `seps/` directory - -3. **Rename your file** to use the PR number as the SEP number (e.g., PR #1850 → `1850-your-feature.md`) - -4. **Update the SEP header** to reference the correct number - -5. **Find a Sponsor** - A Core Maintainer or Maintainer who will shepherd your proposal through review - -## SEP File Structure - -```markdown -# SEP-{NUMBER}: {Title} - -- **Status**: Draft | In-Review | Accepted | Rejected | Withdrawn | Final -- **Type**: Standards Track | Informational | Process -- **Created**: YYYY-MM-DD -- **Author(s)**: Name (@github-username) -- **Sponsor**: @github-username -- **PR**: #{NUMBER} - -## Abstract - -Brief (~200 word) technical summary of the proposal. - -## Motivation - -Why is this change needed? Why is the current protocol inadequate? - -## Specification - -Detailed technical specification of the proposed changes. - -## Rationale - -Design decisions made and alternatives that were considered. - -## Backward Compatibility - -How does this affect existing implementations? (Required for incompatible changes) - -## Security Implications - -Any security concerns related to this proposal. - -## Reference Implementation - -Link to or description of a reference implementation (required before Final status). -``` - -## SEP Types - -- **Standards Track**: New protocol features or changes affecting interoperability -- **Informational**: Design issues, guidelines, or information without new features -- **Process**: Changes to MCP processes or governance - -## Status Workflow - -`Draft` → `In-Review` → `Accepted` → `Final` - -Alternative outcomes: `Rejected`, `Withdrawn`, or `Superseded` - -- **Draft**: Initial proposal, sponsor assigned, informal review -- **In-Review**: Open for formal community and maintainer review -- **Accepted**: Approved, pending reference implementation -- **Final**: Implemented and merged into the specification -- **Rejected**: Not accepted after review -- **Withdrawn**: Author withdrew the proposal -- **Superseded**: Replaced by a newer SEP - -## The Sponsor Role - -A Sponsor is a Core Maintainer or Maintainer who: - -- Reviews the proposal and provides feedback -- Requests changes based on community input -- Initiates formal review when the SEP is ready -- Shepherds the proposal through the acceptance process - -You can find potential sponsors in the maintainers list. Tag them in your PR to request sponsorship. - -## Why PR Numbers? - -Using the PR number as the SEP number: - -- Eliminates need for maintainer number assignment -- Creates natural traceability between proposal and discussion -- Prevents number conflicts -- Simplifies the contribution process - -## Acceptance Criteria - -- Prototype/reference implementation -- Clear benefit to the MCP ecosystem -- Community consensus - -## Relationship to Issue-Based SEPs - -This file-based approach complements the existing issue-based SEP process. Contributors may choose either method based on preference. The canonical SEP guidelines remain at https://modelcontextprotocol.io/community/sep-guidelines +See https://modelcontextprotocol.io/community/sep-guidelines diff --git a/seps/TEMPLATE.md b/seps/TEMPLATE.md new file mode 100644 index 000000000..f37a02e23 --- /dev/null +++ b/seps/TEMPLATE.md @@ -0,0 +1,109 @@ +# SEP-{NUMBER}: {Title} + +> **Note**: This template provides a standard structure for SEPs. You may adapt sections based on the specific needs of your proposal. For example, Process SEPs may not need a "Backward Compatibility" section, while Standards Track SEPs should include detailed technical specifications. + +- **Status**: Draft | In-Review | Accepted | Rejected | Withdrawn | Final | Superseded | Dormant +- **Type**: Standards Track | Informational | Process +- **Created**: YYYY-MM-DD +- **Author(s)**: Name (@github-username) +- **Sponsor**: @github-username (or "None" if seeking sponsor) +- **PR**: https://github.com/modelcontextprotocol/specification/pull/{NUMBER} + +## Abstract + +Brief (~200 word) technical summary of the proposal. This should be a concise overview that allows readers to quickly understand what this SEP proposes. + +## Motivation + +Why is this change needed? Why is the current protocol specification inadequate to address the problem that this SEP solves? + +The motivation is critical for SEPs that want to change the Model Context Protocol. SEP submissions without sufficient motivation may be rejected outright. + +## Specification + +Detailed technical specification of the proposed changes. The specification should describe the syntax and semantics of any new protocol feature in sufficient detail to allow competing, interoperable implementations. + +For Protocol changes, include: + +- New message formats or data structures +- Endpoints or methods +- Behavioral requirements +- Error handling + +For Process changes, include: + +- Step-by-step procedures +- Roles and responsibilities +- Timelines or milestones + +## Rationale + +Explain why particular design decisions were made. This section should: + +- Describe alternate designs that were considered +- Explain why the proposed approach was chosen +- Reference related work or prior art +- Document important objections or concerns raised during discussion +- Provide evidence of consensus within the community + +## Backward Compatibility + +**Required for SEPs that introduce backward incompatibilities.** + +Describe: + +- What existing functionality will break or change +- The severity and scope of incompatibilities +- How the author proposes to handle the transition +- Migration paths for existing implementations + +If there are no backward compatibility concerns, state that explicitly. + +## Security Implications + +Describe any security concerns related to this proposal, including: + +- New attack surfaces +- Privacy considerations +- Authentication or authorization changes +- Data validation requirements + +If there are no security implications, state that explicitly. + +## Reference Implementation + +Link to or describe a reference implementation. A reference implementation is required before any SEP can be given "Final" status. + +The principle of "rough consensus and running code" is useful when resolving discussions of protocol details. + +Include: + +- Links to prototype code or pull requests +- Pointers to example usage +- Test results or validation + +--- + +## Additional Optional Sections + +Depending on your SEP, you may want to include: + +### Performance Implications + +How does this change affect performance, scalability, or resource usage? + +### Testing Plan + +How will this proposal be tested? What test cases should implementations cover? + +### Alternatives Considered + +Detailed discussion of alternative approaches that were rejected and why. + +### Open Questions + +Unresolved issues that need community input or further discussion. + +### Acknowledgments + +Credit to people who contributed ideas, feedback, or reviews.