Merge branch 'main' into fix/tool-resource-guidance

Author: evalstate

.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

@@ -19,8 +19,8 @@ The following software is required to work on the spec:
 2. Clone your fork:
 
 ```bash
-git clone https://github.com/YOUR-USERNAME/specification.git
-cd specification
+git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
+cd modelcontextprotocol
 ```
 
 3. Install dependencies:
@@ -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,12 +77,31 @@ 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
+
+#### Principles of MCP
+
+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.
+
 ## Submitting Changes
 
 1. Push your changes to your fork

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"
             ]
@@ -188,6 +187,7 @@
                   "specification/draft/basic/lifecycle",
                   "specification/draft/basic/transports",
                   "specification/draft/basic/authorization",
+                  "specification/draft/basic/security_best_practices",
                   {
                     "group": "Utilities",
                     "pages": [
@@ -202,7 +202,8 @@
                 "group": "Client Features",
                 "pages": [
                   "specification/draft/client/roots",
-                  "specification/draft/client/sampling"
+                  "specification/draft/client/sampling",
+                  "specification/draft/client/elicitation"
                 ]
               },
               {
@@ -226,25 +227,17 @@
           },
           {
             "group": "Resources",
-            "pages": [
-              "specification/versioning",
-              "specification/contributing"
-            ]
+            "pages": ["specification/versioning", "specification/contributing"]
           }
         ]
       }
     ],
     "global": {
       "anchors": [
         {
-          "anchor": "Python SDK",
-          "href": "https://github.com/modelcontextprotocol/python-sdk",
-          "icon": "python"
-        },
-        {
-          "anchor": "TypeScript SDK",
-          "href": "https://github.com/modelcontextprotocol/typescript-sdk",
-          "icon": "square-js"
+          "anchor": "C# SDK",
+          "href": "https://github.com/modelcontextprotocol/csharp-sdk",
+          "icon": "square-c"
         },
         {
           "anchor": "Java SDK",
@@ -257,9 +250,24 @@
           "icon": "square-k"
         },
         {
-          "anchor": "C# SDK",
-          "href": "https://github.com/modelcontextprotocol/csharp-sdk",
-          "icon": "square-c"
+          "anchor": "Python SDK",
+          "href": "https://github.com/modelcontextprotocol/python-sdk",
+          "icon": "python"
+        },
+        {
+          "anchor": "Ruby SDK",
+          "href": "https://github.com/modelcontextprotocol/ruby-sdk",
+          "icon": "gem"
+        },
+        {
+          "anchor": "Swift SDK",
+          "href": "https://github.com/modelcontextprotocol/swift-sdk",
+          "icon": "swift"
+        },
+        {
+          "anchor": "TypeScript SDK",
+          "href": "https://github.com/modelcontextprotocol/typescript-sdk",
+          "icon": "square-js"
         }
       ]
     }
@@ -303,9 +311,6 @@
     }
   ],
   "contextual": {
-    "options": [
-      "copy",
-      "view"
-    ]
+    "options": ["copy", "view"]
   }
 }