Merge pull request modelcontextprotocol#41 from modelcontextprotocol/davidsp/missing-docs

feat: Add protocol details for error codes, pagination, and templates

Author: dsp-ant

docs/spec/_index.md

@@ -50,6 +50,36 @@ In addition to basic primitives, MCP offers a set of control flow messages.
 * **Logging:** Anything related to how the server processes logs.
 * **Completion**: Supports completion of server arguments on the client side. See
 
+## Error Codes
+
+MCP uses standard JSON-RPC error codes as well as protocol-specific codes:
+
+Standard JSON-RPC error codes:
+- `-32700`: Parse error
+- `-32600`: Invalid request
+- `-32601`: Method not found
+- `-32602`: Invalid params
+- `-32603`: Internal error
+
+All error responses MUST include:
+- A numeric error code
+- A human-readable message
+- Optional additional error data
+
+Example error response:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32602,
+    "message": "Required parameter missing",
+    "data": {
+      "parameter": "uri"
+    }
+  }
+}
+```
 # Use cases
 Most use cases are around enabling people to build their own specific workflows and integrations. MCP enables engineers and teams to **tailor AI to their needs.**
 

docs/spec/jsonrpc.md

@@ -26,6 +26,71 @@ HTTP with Server-Sent Events (SSE)
 
 ### Message Format
 
+### Progress Notifications
+
+MCP supports progress tracking for long-running operations through out-of-band notifications. Progress notifications allow the sender of a request to provide updates about the operation's progress.
+
+To request progress notifications, include a `progressToken` in the request metadata:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "some_method",
+  "params": {
+    "_meta": {
+      "progressToken": "abc123"
+    }
+  }
+}
+```
+
+The receiver MAY then send progress notifications using the same token:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/progress",
+  "params": {
+    "progressToken": "abc123",
+    "progress": 50,
+    "total": 100
+  }
+}
+```
+
+### Pagination
+
+Many list operations in MCP support pagination using cursors. The server response will include a `nextCursor` if more results are available:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "resources": [...],
+    "nextCursor": "next_page_token"
+  }
+}
+```
+
+Clients can include a `cursor` parameter containing the opaque token from the server,
+to obtain the next page starting from the cursor:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "resources/list",
+  "params": {
+    "cursor": "some_opaque_token"
+  }
+}
+```
+
+
+Clients should continue making requests with the provided cursor until no `nextCursor` is returned.
+
 All messages in MCP **MUST** follow the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines three types of messages:
 
 1. Requests
@@ -73,6 +138,30 @@ Authentication mechanisms are not part of the core MCP specification. Implementa
 
 The MCP version is declared in the `initialize` request and response. Clients and servers **MUST** agree on a compatible protocol version to proceed with communication.
 
+### Ping Messages
+
+Either party can send ping messages to check if the other is still alive and responsive:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "ping"
+}
+```
+
+The receiver MUST respond promptly with an empty result:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {}
+}
+```
+
+If the receiver fails to respond in a timely manner, the sender MAY disconnect.
+
 ## Specification
 
 The conical specification can be found at [Model Context Protocol](http://github.com/modelcontextprotocol/spec/tree/main/spec/schema.ts). The specification of the data format

docs/spec/resources.md

@@ -43,6 +43,36 @@ In this example, the server supports basic resource operations, subscriptions, a
 A Resource in the Model Context Protocol (MCP) represents a discrete unit of data that a server can provide to clients. Each Resource is uniquely identified by a URI and may have associated metadata such as a name and MIME type. Resources can represent various types of data, including files, database records, or application-specific information.
 
 ### Resource Templates
+To retrieve available resource templates from the server, the client MUST send a `resources/templates/list` request:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "resources/templates/list"
+}
+```
+
+The server MUST respond with a list of resource templates:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "resourceTemplates": [
+      {
+        "uriTemplate": "file:///{path}",
+        "name": "Local File",
+        "description": "Access local files",
+        "mimeType": "application/octet-stream"
+      }
+    ]
+  }
+}
+```
+
+Resource templates use URI templates as defined in [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) to specify parameterized resource URIs.
 
 Resource Templates are URI patterns that describe a class of resources that can be dynamically generated or accessed. They use URI templates as defined in [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) to specify how clients can construct valid resource URIs. Templates allow servers to expose a potentially large or dynamic set of resources without explicitly listing each one. Clients can use these templates to generate specific resource URIs as needed.
 
@@ -159,7 +189,7 @@ Example:
   "result": {
     "resourceTemplates": [
       {
-        "uriTemplate": "file://{path}",
+        "uriTemplate": "file:///{path}",
         "name": "Local File",
         "description": "Access local files",
         "mimeType": "application/octet-stream"