Merge branch 'main' into feat/spec-annotator

Author: LucaButBoring

.github/CODEOWNERS

@@ -14,3 +14,9 @@
 /docs/specification/**/authorization.mdx @modelcontextprotocol/core-maintainers @modelcontextprotocol/auth-wg
 /docs/specification/**/security_best_practices.mdx @modelcontextprotocol/core-maintainers @modelcontextprotocol/auth-wg
 /docs/docs/tutorials/security/security_best_practices.mdx @modelcontextprotocol/core-maintainers @modelcontextprotocol/auth-wg
+
+# GitHub configuration (workflows, issue templates, etc.)
+/.github/ @modelcontextprotocol/core-maintainers @modelcontextprotocol/docs-maintainers
+
+# Agent documentation
+/AGENTS.md @modelcontextprotocol/core-maintainers @modelcontextprotocol/docs-maintainers

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,75 @@
+name: Report a bug
+description: >
+  An aspect of the MCP specification doesn't work as expected, or our
+  documentation is wrong.
+labels: [bug, needs-triage]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for problems with the **MCP specification itself** or
+        with the **documentation on modelcontextprotocol.io**.
+
+        - If the bug is in a specific SDK (TypeScript, Python, etc.), file
+          it in [that SDK's repository](https://modelcontextprotocol.io/docs/sdk)
+          instead.
+        - If the bug is in how **Claude** (Claude Desktop, claude.ai) uses
+          MCP, file it at [anthropics/claude-ai-mcp](https://github.com/anthropics/claude-ai-mcp).
+        - If you want to propose a new feature or a breaking change, that's
+          a [SEP](https://modelcontextprotocol.io/community/sep-guidelines),
+          not a bug.
+
+  - type: dropdown
+    id: kind
+    attributes:
+      label: What's broken?
+      options:
+        - The spec defines behavior that doesn't work in practice
+        - The spec is ambiguous or self-contradictory
+        - The spec doesn't cover a case it clearly should
+        - The JSON schema is wrong (incorrect type, constraint, or field)
+        - The JSON schema disagrees with the spec prose
+        - The spec conflicts with an RFC or standard it references
+        - An example in the spec is wrong or won't run
+        - The documentation is wrong or misleading
+        - A docs page is missing or a link is broken
+    validations:
+      required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: Where in the spec or docs?
+      description: >
+        Link to the spec section, schema file, or docs page. Include a
+        version tag or permalink if the content might change.
+      placeholder: https://modelcontextprotocol.io/specification/2025-06-18/...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What should happen?
+      description: What you expected the spec to say, or what behavior you expected.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What actually happens?
+      description: >
+        Quote the spec text, describe the broken behavior, or paste the
+        error. If two implementations disagree, say which ones and how.
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else?
+      description: >
+        Relevant SDK versions, related issues, or workarounds you've found.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,15 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Submit a Spec Enhancement Proposal (SEP)
+    url: https://modelcontextprotocol.io/community/sep-guidelines
+    about: >
+      SEPs are the mechanism for proposing new protocol features, breaking
+      changes, or governance changes. They are submitted as pull requests
+      adding a file to the seps/ directory — not as issues. Read the SEP
+      guidelines before opening your PR.
+  - name: Report an SDK bug
+    url: https://modelcontextprotocol.io/docs/sdk
+    about: >
+      Bugs in a specific SDK (TypeScript, Python, Go, etc.) should be filed
+      in that SDK's own repository. The SDK documentation lists every
+      official SDK with a link to its issue tracker.

.github/ISSUE_TEMPLATE/work_tracking.yml

@@ -0,0 +1,38 @@
+name: Work tracking
+description: >
+  Track work that's already been discussed and agreed on — not a new
+  proposal.
+labels: [tracking]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This template is for work that's **already been discussed and
+        agreed on** — in a SEP, a working group, a maintainer sync,
+        a prior issue, wherever. It gives that work a place to be assigned,
+        linked from PRs, and closed.
+
+        If you're proposing something **new**, this is the wrong template.
+        Open a [SEP](https://modelcontextprotocol.io/community/sep-guidelines)
+        for protocol changes, or a bug report for things that are broken.
+
+  - type: input
+    id: source
+    attributes:
+      label: Where was this agreed?
+      description: >
+        Link to the discussion. If it was a synchronous conversation
+        without a link, say where and when.
+      placeholder: https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/...
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: >
+        Whatever's useful. Summary, task list, acceptance criteria, open
+        questions — structure it however fits the work.
+    validations:
+      required: false

.github/workflows/deploy-blog.yml

@@ -37,7 +37,7 @@ jobs:
         with:
           working-directory: blog
           mode: production
-          base-url: ${{ steps.pages.outputs.base_url }}/
+          base-url: https://blog.modelcontextprotocol.io/
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4

AGENTS.md

@@ -68,6 +68,19 @@ npm run check:seps       # Check SEP documents
 npm run prep             # Full prep before committing (check, generate, format)
 ```
 
+## Issue Creation
+
+Blank issues are disabled. `gh issue create` and the API bypass the template
+chooser, so when filing via CLI or API you **must** use one of the forms in
+`.github/ISSUE_TEMPLATE/` and fill in its required fields.
+
+Before filing, check `.github/ISSUE_TEMPLATE/config.yml` — some categories
+are redirected out of this repo entirely:
+
+- **SEPs** are pull requests adding a file to `seps/`, not issues
+- **SDK bugs** belong in the individual SDK repository
+- **Claude MCP behavior** belongs in `anthropics/claude-ai-mcp`
+
 ## Commit Guidelines
 
 - Do not include model names or details (e.g., "Claude", "Opus") in commit messages

CONTRIBUTING.md

@@ -9,7 +9,7 @@ Also see the [overall MCP communication guidelines in our docs](https://modelcon
 
 The following software is required to work on the spec:
 
-- Node.js 20 or above
+- Node.js 24 or above
 - TypeScript
 - TypeScript JSON Schema (for generating JSON schema)
 - [Mintlify](https://mintlify.com/) (optional, for docs)
@@ -102,21 +102,13 @@ When contributing to the documentation:
 
 ## Specification Proposal Guidelines
 
-### Principles of MCP
+Specification changes follow the [SEP process](https://modelcontextprotocol.io/community/sep-guidelines).
+Before drafting a proposal, review the [MCP design principles](https://modelcontextprotocol.io/community/design-principles)
+— proposals that align with these principles move faster through review.
 
-1. **Simple + Minimal**: It is much easier to add things to a specification than it is to
-   remove them. To maintain simplicity, we keep a high bar for adding new concepts and
-   primitives as each addition requires maintenance and compatibility consideration.
-2. **Concrete**: Specification changes need to be based on specific implementation
-   challenges and not on speculative ideas.
-
-### Stages of a specification proposal
-
-1. **Define**: Explore the problem space, validate that other MCP users face a similar
-   issue, and then clearly define the problem.
-2. **Prototype**: Build an example solution to the problem and demonstrate its practical
-   application.
-3. **Write**: Based on the prototype, write a specification proposal.
+The shortest summary: explore the problem space and validate that others share the problem,
+build a prototype that demonstrates a solution, then write the SEP based on what the
+prototype taught you.
 
 ## Submitting Changes
 

blog/archetypes/default.md

@@ -1,5 +1,22 @@
-+++
-date = '{{ .Date }}'
-draft = true
-title = '{{ replace .File.ContentBaseName "-" " " | title }}'
-+++
+---
+title: '{{ replace .File.ContentBaseName "-" " " | title }}'
+date: "{{ .Date }}"
+draft: true
+
+# One-sentence SEO summary. PaperMod emits this as BlogPosting.description
+# and <meta name="description">. Without it, both fall back to the first ~70
+# words of the post body.
+description: ""
+
+# PaperMod emits each entry as a schema.org Person in BlogPosting.author.
+author:
+  - ""
+
+tags: []
+
+# Optional per-post image for JSON-LD and OpenGraph (falls back to site
+# og-image.png). Place under static/posts/<slug>/ and reference relative to
+# static/.
+# cover:
+#   image: posts/{{ .File.ContentBaseName }}/cover.png
+---