Merge branch 'main' into spec/sampling-includecontext

Author: LucaButBoring

.gitattributes

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

.github/workflows/main.yml

@@ -18,8 +18,8 @@ jobs:
 
       - run: npm ci
 
-      - run: npm run validate:schema
+      - name: Check TypeScript definitions
+        run: npm run check:schema:ts
 
-      - run: npm run generate:json
       - name: Verify that `npm run generate:json` did not change outputs (if it did, please re-run it and re-commit!)
-        run: git diff --exit-code
+        run: npm run check:schema:json

.github/workflows/markdown-format.yml

@@ -4,23 +4,28 @@ 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 check:docs:format
+
+      - name: Check markdown links
+        run: npm run check:docs:links

CONTRIBUTING.md

@@ -32,24 +32,32 @@ 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`.
 
 1. Create a new branch:
 
 ```bash
 git checkout -b feature/your-feature-name
 ```
 
-2. Make your changes
-3. Validate your changes:
+2. Make your changes.
+
+3. Validate schema changes and generate `schema.json`:
+
+```bash
+npm run check:schema:ts
+npm run generate:json
+```
+
+4. Validate documentation changes and apply formatting:
 
 ```bash
-npm run validate:schema    # validate schema
-npm run generate:json     # generate JSON schema
+npm run check:docs
+npm run format
 ```
 
-4. Run docs locally (optional):
+5. Preview documentation locally (optional):
 
 ```bash
 npm run serve:docs
@@ -64,10 +72,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:docs: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

@@ -38,6 +38,7 @@ The protocol layer handles message framing, request/response linking, and high-l
 
 <Tabs>
   <Tab title="TypeScript">
+
     ```typescript
     class Protocol<Request, Notification, Result> {
         // Handle incoming requests
@@ -53,8 +54,10 @@ The protocol layer handles message framing, request/response linking, and high-l
         notification(notification: Notification): Promise<void>
     }
     ```
+
   </Tab>
   <Tab title="Python">
+
     ```python
     class Session(BaseSession[RequestT, NotificationT, ResultT]):
         async def send_request(
@@ -86,25 +89,27 @@ The protocol layer handles message framing, request/response linking, and high-l
             """Handle incoming notification from other side."""
             # Notification handling implementation
     ```
+
   </Tab>
 </Tabs>
 
 Key classes include:
 
-* `Protocol`
-* `Client`
-* `Server`
+- `Protocol`
+- `Client`
+- `Server`
 
 ### Transport layer
 
 The transport layer handles the actual communication between clients and servers. MCP supports multiple transport mechanisms:
 
 1. **Stdio transport**
+
    - Uses standard input/output for communication
    - Ideal for local processes
 
-2. **HTTP with SSE transport**
-   - Uses Server-Sent Events for server-to-client messages
+2. **Streamable HTTP transport**
+   - Uses HTTP with optional Server-Sent Events for streaming
    - HTTP POST for client-to-server messages
 
 All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](/specification/) for detailed information about the Model Context Protocol message format.
@@ -114,36 +119,39 @@ All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages
 MCP has these main types of messages:
 
 1. **Requests** expect a response from the other side:
-    ```typescript
-    interface Request {
-      method: string;
-      params?: { ... };
-    }
-    ```
+
+   ```typescript
+   interface Request {
+     method: string;
+     params?: { ... };
+   }
+   ```
 
 2. **Results** are successful responses to requests:
-    ```typescript
-    interface Result {
-      [key: string]: unknown;
-    }
-    ```
+
+   ```typescript
+   interface Result {
+     [key: string]: unknown;
+   }
+   ```
 
 3. **Errors** indicate that a request failed:
-    ```typescript
-    interface Error {
-      code: number;
-      message: string;
-      data?: unknown;
-    }
-    ```
+
+   ```typescript
+   interface Error {
+     code: number;
+     message: string;
+     data?: unknown;
+   }
+   ```
 
 4. **Notifications** are one-way messages that don't expect a response:
-    ```typescript
-    interface Notification {
-      method: string;
-      params?: { ... };
-    }
-    ```
+   ```typescript
+   interface Notification {
+     method: string;
+     params?: { ... };
+   }
+   ```
 
 ## Connection lifecycle
 
@@ -176,6 +184,7 @@ After initialization, the following patterns are supported:
 ### 3. Termination
 
 Either party can terminate the connection:
+
 - Clean shutdown via `close()`
 - Transport disconnection
 - Error conditions
@@ -191,13 +200,14 @@ enum ErrorCode {
   InvalidRequest = -32600,
   MethodNotFound = -32601,
   InvalidParams = -32602,
-  InternalError = -32603
+  InternalError = -32603,
 }
 ```
 
 SDKs and applications can define their own error codes above -32000.
 
 Errors are propagated through:
+
 - Error responses to requests
 - Error events on transports
 - Protocol-level error handlers
@@ -208,6 +218,7 @@ Here's a basic example of implementing an MCP server:
 
 <Tabs>
   <Tab title="TypeScript">
+
     ```typescript
     import { Server } from "@modelcontextprotocol/sdk/server/index.js";
     import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -237,8 +248,10 @@ Here's a basic example of implementing an MCP server:
     const transport = new StdioServerTransport();
     await server.connect(transport);
     ```
+
   </Tab>
   <Tab title="Python">
+
     ```python
     import asyncio
     import mcp.types as types
@@ -267,6 +280,7 @@ Here's a basic example of implementing an MCP server:
     if __name__ == "__main__":
         asyncio.run(main())
     ```
+
   </Tab>
 </Tabs>
 
@@ -275,23 +289,26 @@ Here's a basic example of implementing an MCP server:
 ### Transport selection
 
 1. **Local communication**
+
    - Use stdio transport for local processes
    - Efficient for same-machine communication
    - Simple process management
 
 2. **Remote communication**
-   - Use SSE for scenarios requiring HTTP compatibility
+   - Use Streamable HTTP for scenarios requiring HTTP compatibility
    - Consider security implications including authentication and authorization
 
 ### Message handling
 
 1. **Request processing**
+
    - Validate inputs thoroughly
    - Use type-safe schemas
    - Handle errors gracefully
    - Implement timeouts
 
 2. **Progress reporting**
+
    - Use progress tokens for long operations
    - Report progress incrementally
    - Include total progress when known
@@ -304,17 +321,20 @@ Here's a basic example of implementing an MCP server:
 ## Security considerations
 
 1. **Transport security**
+
    - Use TLS for remote connections
    - Validate connection origins
    - Implement authentication when needed
 
 2. **Message validation**
+
    - Validate all incoming messages
    - Sanitize inputs
    - Check message size limits
    - Verify JSON-RPC format
 
 3. **Resource protection**
+
    - Implement access controls
    - Validate resource paths
    - Monitor resource usage
@@ -329,12 +349,14 @@ Here's a basic example of implementing an MCP server:
 ## Debugging and monitoring
 
 1. **Logging**
+
    - Log protocol events
    - Track message flow
    - Monitor performance
    - Record errors
 
 2. **Diagnostics**
+
    - Implement health checks
    - Monitor connection state
    - Track resource usage