Fix serverName references

Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>

Author: rdimitrov

docs/guides/consuming/use-rest-api.md

@@ -9,9 +9,9 @@ Integration patterns and best practices for building applications that consume M
 **Authentication**: Not required for read-only access
 
 - **`GET /v0/servers`** - List all servers with pagination
-- **`GET /v0/servers/{server_id}`** - Get latest version of server by server ID
-- **`GET /v0/servers/{server_id}?version=X.X.X`** - Get specific version of server
-- **`GET /v0/servers/{server_id}/versions`** - List all versions of a server
+- **`GET /v0/servers/{serverName}`** - Get latest version of server by server name (URL-encoded)
+- **`GET /v0/servers/{serverName}/versions/{version}`** - Get specific version of server
+- **`GET /v0/servers/{serverName}/versions`** - List all versions of a server
 
 See the [interactive API documentation](https://registry.modelcontextprotocol.io/docs) for complete request/response schemas.
 
@@ -22,6 +22,32 @@ See the [interactive API documentation](https://registry.modelcontextprotocol.io
 
 For now we recommend scraping the `GET /v0/servers` endpoint on some regular basis. In the future we might provide a filter for updatedAt ([#291](https://github.com/modelcontextprotocol/registry/issues/291)) to get only recently changed servers.
 
+### Pagination Example
+
+The API uses cursor-based pagination. Here's how to fetch all servers:
+
+```bash
+# Initial request
+curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100"
+```
+
+```json
+{
+  "servers": [...],
+  "metadata": {
+    "count": 100,
+    "nextCursor": "com.example/my-server:1.0.0"
+  }
+}
+```
+
+```bash
+# Next page using cursor
+curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100&cursor=com.example%2Fmy-server%3A1.0.0"
+```
+
+**Important**: Always URL-encode cursor values when using them in query parameters.
+
 Servers are generally immutable, except for the `status` field which can be updated to `deleted` (among other states). For these packages, we recommend you also update the status field to `deleted` or remove the package from your registry quickly. This is because this status generally indicates it has violated our permissive [moderation guidelines](../administration/moderation-guidelines.md), suggesting it is illegal, malware or spam.
 
 ### Filtering & Enhancement

docs/reference/api/CHANGELOG.md

@@ -11,12 +11,12 @@ Changes to the REST API endpoints and responses.
 API endpoints updated to use server names instead of server IDs for better usability.
 
 **Changed endpoints:**
-- `GET /v0/servers/{server_id}` → `GET /v0/servers/{server_name}`
-- `GET /v0/servers/{server_id}/versions` → `GET /v0/servers/{server_name}/versions`
+- `GET /v0/servers/{server_id}` → `GET /v0/servers/{serverName}`
+- `GET /v0/servers/{server_id}/versions` → `GET /v0/servers/{serverName}/versions`
 
 **New endpoints:**
-- `GET /v0/servers/{server_name}/versions/{version}` - Get specific server version
-- `PUT /v0/servers/{server_name}/versions/{version}` - Edit server version (admin only)
+- `GET /v0/servers/{serverName}/versions/{version}` - Get specific server version
+- `PUT /v0/servers/{serverName}/versions/{version}` - Edit server version (admin only)
 
 **Response format changes:**
 - Introduced `ServerResponse` schema separating server data from registry metadata

docs/reference/api/generic-registry-api.md

@@ -15,9 +15,9 @@ The official registry has some more endpoints and restrictions on top of this. S
 
 ### Core Endpoints
 - **`GET /v0/servers`** - List all servers with pagination
-- **`GET /v0/servers/{server_name}`** - Get latest version of server by server name (URL-encoded)
-- **`GET /v0/servers/{server_name}/versions/{version}`** - Get specific version of server (both parameters should be URL-encoded)
-- **`GET /v0/servers/{server_name}/versions`** - List all versions of a server
+- **`GET /v0/servers/{serverName}`** - Get latest version of server by server name (URL-encoded)
+- **`GET /v0/servers/{serverName}/versions/{version}`** - Get specific version of server (both parameters should be URL-encoded)
+- **`GET /v0/servers/{serverName}/versions`** - List all versions of a server
 - **`POST /v0/publish`** - Publish new server (optional, registry-specific authentication)
 
 ### Authentication
@@ -27,6 +27,21 @@ The official registry has some more endpoints and restrictions on top of this. S
 ### Content Type
 All requests and responses use `application/json`
 
+### Pagination
+List endpoints use cursor-based pagination for efficient, stable results.
+
+#### Cursor Format
+Pagination cursors use the format: `{serverName}:{version}`
+
+**Example cursor**: `"com.example/my-server:1.0.0"`
+
+#### Usage
+1. **Initial request**: Omit the `cursor` parameter
+2. **Subsequent requests**: Use the `nextCursor` value from the previous response
+3. **End of results**: When `nextCursor` is null or empty, there are no more results
+
+**Important**: Always treat cursors as opaque strings. Never manually construct or modify cursor values.
+
 ### Basic Example: List Servers
 
 ```bash
@@ -53,7 +68,7 @@ curl https://registry.example.com/v0/servers?limit=10
   ],
   "metadata": {
     "count": 10,
-    "next_cursor": "eyJ..."
+    "nextCursor": "com.example/my-server:1.0.0"
   }
 }
 ```

docs/reference/api/official-registry-api.md

@@ -58,4 +58,4 @@ Example: `GET /v0/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&v
 #### Admin endpoints
 - GET `/metrics` - Prometheus metrics endpoint
 - GET `/v0/health` - Basic health check endpoint
-- PUT `/v0/servers/{server_name}/versions/{version}` - Edit specific server version
+- PUT `/v0/servers/{serverName}/versions/{version}` - Edit specific server version

docs/reference/api/openapi.yaml

@@ -19,10 +19,18 @@ paths:
       parameters:
         - name: cursor
           in: query
-          description: Pagination cursor for retrieving next set of results
+          description: |
+            Pagination cursor for retrieving next set of results.
+
+            **Cursor Format**: `{serverName}:{version}`
+
+            Example: `"com.example/my-server:1.0.0"`
+
+            Cursors are opaque strings returned in the `metadata.nextCursor` field of paginated responses. Always use the exact cursor value returned by the API.
           required: false
           schema:
             type: string
+            example: "com.example/my-server:1.0.0"
         - name: limit
           in: query
           description: Maximum number of items to return
@@ -306,7 +314,13 @@ components:
           properties:
             nextCursor:
               type: string
-              description: Cursor for next page of results
+              description: |
+                Pagination cursor for retrieving the next page of results.
+
+                **Format**: `{serverName}:{version}` (e.g., "com.example/my-server:1.0.0")
+
+                Use this exact value in the `cursor` query parameter of your next request. If null or empty, there are no more results.
+              example: "com.example/my-server:1.0.0"
             count:
               type: integer
               description: Number of items in current page

internal/database/postgres.go

@@ -133,9 +133,9 @@ func (db *PostgreSQL) ListServers(
 		}
 	}
 
-	// Add cursor pagination using compound server_name:version cursor
+	// Add cursor pagination using compound serverName:version cursor
 	if cursor != "" {
-		// Parse cursor format: "server_name:version"
+		// Parse cursor format: "serverName:version"
 		parts := strings.SplitN(cursor, ":", 2)
 		if len(parts) == 2 {
 			cursorServerName := parts[0]
@@ -213,7 +213,7 @@ func (db *PostgreSQL) ListServers(
 		return nil, "", fmt.Errorf("error iterating rows: %w", err)
 	}
 
-	// Determine next cursor using compound server_name:version format
+	// Determine next cursor using compound serverName:version format
 	nextCursor := ""
 	if len(results) > 0 && len(results) >= limit {
 		lastResult := results[len(results)-1]