Merge branch 'main' into patch-1

Author: xyc

.gitattributes

@@ -1 +1,2 @@
 package-lock.json linguist-generated=true
+schema/*/schema.json linguist-generated=true

.github/workflows/markdown-format.yml

@@ -4,23 +4,25 @@ on:
   push:
     paths:
       - '**/*.md'
+      - '**/*.mdx'
   pull_request:
     paths:
       - '**/*.md'
+      - '**/*.mdx'
 
 jobs:
   format:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20'
-          
+
       - name: Install dependencies
         run: npm ci
-        
+
       - name: Check markdown formatting
-        run: npm run format:check
+        run: npm run format:check

CONTRIBUTING.md

@@ -32,8 +32,9 @@ npm install  # install dependencies
 
 ## Making Changes
 
-Note that schema changes are made to `schema.ts`. `schema.json` is generated from
-`schema.ts` using `npm run validate:schema`.
+Note that schema changes are made to `schema.ts`, and `schema.json` is generated from
+`schema.ts`. You should validate your `schema.ts` changes first and then generate the
+`schema.json`.
 
 1. Create a new branch:
 
@@ -46,15 +47,27 @@ git checkout -b feature/your-feature-name
 
 ```bash
 npm run validate:schema    # validate schema
-npm run generate:json     # generate JSON schema
 ```
 
-4. Run docs locally (optional):
+4. Generate the `schema.json`:
+
+```bash
+npm run generate:json      # generate JSON schema
+```
+
+5. Run docs locally (optional):
 
 ```bash
 npm run serve:docs
 ```
 
+6. Format/lint your changes:
+
+```bash
+npm run format:check   # check formatting
+npm run format         # apply formatting
+```
+
 ### Documentation Guidelines
 
 When contributing to the documentation:
@@ -64,10 +77,11 @@ When contributing to the documentation:
 - Include code examples where appropriate
 - Use proper MDX formatting and components
 - Test all links and code samples
+  - You may run `npm run check-links` to look for broken internal links.
 - Use appropriate headings: "When to use", "Steps", and "Tips" for tutorials
 - Place new pages in appropriate sections (concepts, tutorials, etc.)
-- Update docs.json when adding new pages
-- Follow existing file naming conventions (kebab-case.mdx)
+- Update `docs.json` when adding new pages
+- Follow existing file naming conventions (`kebab-case.mdx`)
 - Include proper frontmatter in MDX files
 
 ### Specification Proposal Guidelines

docs/clients.mdx

@@ -7,7 +7,11 @@ description: Our plans for evolving Model Context Protocol
 
 The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and direction for approximately **the next six months**, though these may change significantly as the project develops. To see what's changed recently, check out the **[specification changelog](/specification/2025-03-26/changelog/)**.
 
-<Note>The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an _exhaustive_ list; we may incorporate work that isn't mentioned here.</Note>
+<Note>
+
+The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an _exhaustive_ list; we may incorporate work that isn't mentioned here.
+
+</Note>
 
 We value community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts.
 

docs/development/roadmap.mdx

@@ -53,7 +53,6 @@
           {
             "group": "Development",
             "pages": [
-              "development/updates",
               "development/roadmap",
               "development/contributing"
             ]
@@ -258,7 +257,7 @@
         {
           "anchor": "Ruby SDK",
           "href": "https://github.com/modelcontextprotocol/ruby-sdk",
-          "icon": "ruby"
+          "icon": "gem"
         },
         {
           "anchor": "Swift SDK",