feat: move transports into a subfolder for better organization

docs/specification/draft/basic/transports/_index.md

@@ -0,0 +1,77 @@
+---
+title: Transports
+type: docs
+weight: 10
+---
+
+{{< callout type="info" >}}
+**Protocol Revision**: draft
+{{< /callout >}}
+
+MCP currently defines two standard transport mechanisms for client-server communication:
+
+1. [stdio](#stdio), communication over standard in and standard out
+2. [HTTP with Server-Sent Events](#http-with-sse) (SSE)
+
+Clients **SHOULD** support stdio whenever possible.
+
+It is also possible for clients and servers to implement [custom transports](#custom-transports) in a pluggable fashion.
+
+## stdio
+
+In the **stdio** transport:
+
+- The client launches the MCP server as a subprocess.
+- The server receives JSON-RPC messages on its standard input (`stdin`) and writes responses to its standard output (`stdout`).
+- Messages are delimited by newlines, and **MUST NOT** contain embedded newlines.
+- The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging purposes. Clients **MAY** capture, forward, or ignore this logging.
+- The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message.
+- The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP message.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server Process
+
+    Client->>+Server Process: Launch subprocess
+    loop Message Exchange
+        Client->>Server Process: Write to stdin
+        Server Process->>Client: Write to stdout
+        Server Process--)Client: Optional logs on stderr
+    end
+    Client->>Server Process: Close stdin, terminate subprocess
+    deactivate Server Process
+```
+
+## HTTP with SSE
+
+In the **SSE** transport, the server operates as an independent process that can handle multiple client connections.
+
+The server **MUST** provide two endpoints:
+
+1. An SSE endpoint, for clients to establish a connection and receive messages from the server
+2. A regular HTTP POST endpoint for clients to send messages to the server
+
+When a client connects, the server **MUST** send an `endpoint` event containing a URI for the client to use for sending messages. All subsequent client messages **MUST** be sent as HTTP POST requests to this endpoint.
+
+Server messages are sent as SSE `message` events, with the message content encoded as JSON in the event data.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+
+    Client->>Server: Open SSE connection
+    Server->>Client: endpoint event
+    loop Message Exchange
+        Client->>Server: HTTP POST messages
+        Server->>Client: SSE message events
+    end
+    Client->>Server: Close SSE connection
+```
+
+## Custom Transports
+
+Clients and servers **MAY** implement additional custom transport mechanisms to suit their specific needs. The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange.
+
+Implementers who choose to support custom transports **MUST** ensure they preserve the JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports **SHOULD** document their specific connection establishment and message exchange patterns to aid interoperability.

docs/specification/draft/basic/transports/upgrade.md

@@ -0,0 +1,81 @@
+# Transport Protocol Upgrade Mechanism
+
+## 1. Introduction
+
+This specification defines a protocol upgrade mechanism that enables MCP servers to transition clients from one transport protocol to another during session initialization. The primary use case is upgrading from transports with limited capabilities (like STDIO) to more feature-rich transports that support additional functionality like authentication.
+
+## 2. Upgrade Process
+
+### 2.1 Available Transports
+
+The `transport` field **MUST** specify one of the following standardized values:
+
+- `stdio` - Standard input/output transport
+- `http+sse` - HTTP with Server-Sent Events transport
+
+Servers **SHOULD NOT** request upgrades from HTTP+SSE to STDIO as this would reduce protocol capabilities. While the transport field supports custom values for extensibility, any custom transport **MUST** provide at least the same capabilities as the transport being upgraded from.
+
+Example custom transport upgrade:
+
+```json
+{
+  "upgrade": {
+    "endpoint": "grpc://new-server.example.com:50051",
+    "transport": "grpc" // Custom transport implementation
+  }
+}
+```
+
+### 2.2 Initialization
+
+When a client connects using a transport that lacks required capabilities, the server **MUST** include an `upgrade` field in its initialize response to indicate that a transport upgrade is necessary.
+
+### 2.3 Upgrade Fields
+
+The `upgrade` object contains the following required fields:
+
+| Field     | Type   | Description                         |
+| --------- | ------ | ----------------------------------- |
+| endpoint  | string | The URL of the new server endpoint  |
+| transport | string | The protocol identifier for the new |
+|           |        | transport                           |
+
+### 2.4 Example Upgrade Flow
+
+During initialization with STDIO transport:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2024-11-05",
+    "upgrade": {
+      "endpoint": "http://new-server.example.com:8080",
+      "transport": "http+sse"
+    },
+    "serverInfo": {
+      "name": "ExampleServer",
+      "version": "1.0.0"
+    }
+  }
+}
+```
+
+### 2.5 Client Requirements
+
+Upon receiving an upgrade response, clients **MUST**:
+
+1. Terminate the existing connection
+2. Establish a new connection using the specified transport protocol
+3. Reinitialize the session with the new endpoint
+
+### 2.6 Authentication Flow
+
+The most common upgrade scenario is transitioning from STDIO to HTTP+SSE transport to support authentication:
+
+1. Client connects via STDIO
+2. Server requires authentication
+3. Server responds with upgrade to HTTP+SSE
+4. Client reconnects using HTTP+SSE
+5. Authentication proceeds on new transport