refactor: standardize JSON code block filenames across multiple exercises

kentcdodds · kentcdodds · commit d542f9a6c843 · 2025-07-30T14:24:22.000-06:00
diff --git a/exercises/01.advanced-tools/02.problem.structured/README.mdx b/exercises/01.advanced-tools/02.problem.structured/README.mdx
@@ -27,7 +27,7 @@ async (input) => {
 
 Here's what a structured output response looks like:
 
-```json filename="server-response.json" nocopy
+```json filename=server-response.json nocopy
 {
 	"content": [
 		{
diff --git a/exercises/01.advanced-tools/README.mdx b/exercises/01.advanced-tools/README.mdx
@@ -158,7 +158,7 @@ Suppose we have a tool that generates a random fantasy character profile:
 
 #### Request
 
-```json filename="client-request.json" nocopy
+```json filename=client-request.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 99,
@@ -174,7 +174,7 @@ Suppose we have a tool that generates a random fantasy character profile:
 
 #### Response
 
-```json filename="server-response.json" nocopy
+```json filename=server-response.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 99,
diff --git a/exercises/02.elicitation/README.mdx b/exercises/02.elicitation/README.mdx
@@ -51,7 +51,7 @@ Imagine an online pizza ordering system. After a user selects their pizza and to
 1. The user submits their pizza order.
 2. The server sends an `elicitation/create` request:
 
-```json filename="server-request.json" nocopy
+```json filename=server-request.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 1,
@@ -83,7 +83,7 @@ The client presents this to the user, who can:
 
 Here's what the response from the client might look like:
 
-```json filename="client-response.json" nocopy
+```json filename=client-response.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 1,
diff --git a/exercises/03.sampling/01.problem.simple/README.mdx b/exercises/03.sampling/01.problem.simple/README.mdx
@@ -80,7 +80,7 @@ To test this in the MCP inspector:
 - check the "Sampling" navigation tab and you should have a sampling request
 - at this point, YOU are the LLM. You can copy paste this into your response:
 
-```json filename="example-sampling-client-response.json"
+```json filename=example-sampling-client-response.json
 {
 	"model": "stub-model",
 	"stopReason": "endTurn",
diff --git a/exercises/03.sampling/02.problem.advanced/README.mdx b/exercises/03.sampling/02.problem.advanced/README.mdx
@@ -30,7 +30,7 @@ for a new journal entry.
 4. Evaluate the response (make sure it's in the right format)
 5. Repeat in new chats until you're happy with the prompt/response
 
-```json filename="example-user-message.json"
+```json filename=example-user-message.json
 {
 	"entry": {
 		"id": 6,
@@ -100,7 +100,7 @@ To test this in the MCP inspector:
 - check the "Sampling" navigation tab and you should have a sampling request
 - at this point, YOU are the LLM. You can copy paste this into your response:
 
-```json filename="example-sampling-client-response.json"
+```json filename=example-sampling-client-response.json
 {
 	"model": "stub-model",
 	"stopReason": "endTurn",
diff --git a/exercises/03.sampling/README.mdx b/exercises/03.sampling/README.mdx
@@ -48,7 +48,7 @@ sequenceDiagram
 
 Here's a simple example of a sampling request and response using MCP:
 
-```json filename="server-request.json" nocopy
+```json filename=server-request.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 1,
@@ -69,7 +69,7 @@ Here's a simple example of a sampling request and response using MCP:
 }
 ```
 
-```json filename="client-response.json" nocopy
+```json filename=client-response.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 1,
diff --git a/exercises/04.long-running-tasks/README.mdx b/exercises/04.long-running-tasks/README.mdx
@@ -37,7 +37,7 @@ sequenceDiagram
 
 **Client Request with Progress Token:**
 
-```json filename="client-request.json" nocopy
+```json filename=client-request.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 5,
@@ -54,7 +54,7 @@ sequenceDiagram
 
 **Server Progress Notification:**
 
-```json filename="server-progress-notification-request.json" nocopy
+```json filename=server-progress-notification-request.json nocopy
 {
 	"jsonrpc": "2.0",
 	"method": "notifications/progress",
@@ -69,7 +69,7 @@ sequenceDiagram
 
 **Server Final Response:**
 
-```json filename="server-response.json" nocopy
+```json filename=server-response.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 5,
@@ -115,7 +115,7 @@ sequenceDiagram
 
 **Client Cancellation Notification:**
 
-```json filename="client-cancelled-notification-request.json" nocopy
+```json filename=client-cancelled-notification-request.json nocopy
 {
 	"jsonrpc": "2.0",
 	"method": "notifications/cancelled",
diff --git a/exercises/05.changes/README.mdx b/exercises/05.changes/README.mdx
@@ -46,11 +46,18 @@ if (freeDockingPorts.length > 0 && !dockModuleTool.enabled) {
 
 The TypeScript SDK automatically sends `list_changed` notifications when tools are enabled or disabled. To avoid over-sending notifications, you should check whether the tool is already enabled or disabled before enabling or disabling it.
 
-<callout-info>
-	[In the
-	future](https://github.com/modelcontextprotocol/typescript-sdk/pull/746),
-	`list_changed` will be batched to avoid sending too many notifications.
-</callout-info>
+#### Example: Resource List Change Notification
+
+When new experiment logs become available in the space station's research database:
+
+```json filename=server-notification.json nocopy
+{
+	"jsonrpc": "2.0",
+	"method": "notifications/resources/list_changed"
+}
+```
+
+This tells the client that the available resources have changed, prompting it to refresh its resource list and discover new experiment logs.
 
 ## 2. Resource List Change (Templates and Expansions)
 
@@ -81,7 +88,7 @@ ingredientsResource.enable() // or disable()
 
 Resources in MCP can be either static (a single file, a database record) or dynamic via **resource templates** (e.g., a directory of files, a database table, or even a set of modules on a space station 🚀). Resource templates allow the server to expose a pattern or collection of resources that can change over time.
 
-A `notifications/resources/list_changed` notification is sent when:
+A `notifications/resources/list_changed` notification (like the one in the example above) is sent when:
 
 - A new resource template is enabled/disabled
 - The set of expansions for a template changes (e.g., a new module docks, a new experiment log appears, or a file is added to a directory)
@@ -98,7 +105,7 @@ While `list_changed` tells clients about changes in what resources are available
 
 A client wants to stay updated on a specific space station module:
 
-```json filename="client-request.json" nocopy
+```json filename=client-request.json nocopy
 {
 	"jsonrpc": "2.0",
 	"id": 1,
@@ -109,7 +116,7 @@ A client wants to stay updated on a specific space station module:
 
 When the module's status changes (e.g., a new experiment starts, or the module is undocked), the server sends:
 
-```json filename="server-response.json" nocopy
+```json filename=server-notification-request.json nocopy
 {
 	"jsonrpc": "2.0",
 	"method": "notifications/resources/updated",
@@ -135,36 +142,40 @@ This all might work a little bit like this:
 ```mermaid
 sequenceDiagram
   participant User
-  participant HostApp
+  participant App
   participant Client
   participant Server
 
-  User->>HostApp: Start application
-  HostApp->>Client: Initialize client
+  User->>App: Start application
+  App->>Client: Initialize client
   Client->>Server: Initialization request
   Server-->>Client: Capabilities response
   %% ---
   Note over User,Server: (Later, when things change...)
   Server-->>Client: notifications/tools/list_changed
   Server-->>Client: notifications/resources/list_changed
   Server-->>Client: notifications/prompts/list_changed
-  Client-->>HostApp: Forward list_changed notification
-  HostApp->>Client: Fetch updated definitions
+  Client-->>App: Forward list_changed notification
+  App->>Client: Fetch updated definitions
   Client->>Server: Fetch updated definitions
   Server-->>Client: Updated definitions
-  Client-->>HostApp: Forward updated definitions
-  HostApp->>User: Update UI
+  Client-->>App: Forward updated definitions
+  App->>User: Update UI
   %% ---
   Note over User,Server: (Subscription flow)
-  HostApp->>Client: Subscribe to resource
+  App->>Client: Subscribe to resource
   Client->>Server: Subscribe to resource
   Server-->>Client: Subscription confirmed
-  Client-->>HostApp: Subscription confirmed
+  Client-->>App: Subscription confirmed
   %% ---
   Note over User,Server: (Later, when resource changes...)
   Server-->>Client: notifications/resources/updated
-  Client-->>HostApp: Forward resource update
-  HostApp->>User: Update UI
+  Client-->>App: Forward resource update
+  App->>Client: Request updated resource
+  Client->>Server: resources/read
+  Server-->>Client: Return updated resource
+  Client-->>App: Forward resource data
+  App->>User: Update UI with resource data
 ```
 
 ## References

Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@ async (input) => {`
`27`	`27`
`28`	`28`	`Here's what a structured output response looks like:`
`29`	`29`
`30`		-```json filename="server-response.json" nocopy
	`30`	+```json filename=server-response.json nocopy
`31`	`31`	`{`
`32`	`32`	`"content": [`
`33`	`33`	`{`
Original file line number	Diff line number	Diff line change
`@@ -158,7 +158,7 @@ Suppose we have a tool that generates a random fantasy character profile:`
`158`	`158`
`159`	`159`	`#### Request`
`160`	`160`
`161`		-```json filename="client-request.json" nocopy
	`161`	+```json filename=client-request.json nocopy
`162`	`162`	`{`
`163`	`163`	`"jsonrpc": "2.0",`
`164`	`164`	`"id": 99,`
`@@ -174,7 +174,7 @@ Suppose we have a tool that generates a random fantasy character profile:`
`174`	`174`
`175`	`175`	`#### Response`
`176`	`176`
`177`		-```json filename="server-response.json" nocopy
	`177`	+```json filename=server-response.json nocopy
`178`	`178`	`{`
`179`	`179`	`"jsonrpc": "2.0",`
`180`	`180`	`"id": 99,`
Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,7 @@ Imagine an online pizza ordering system. After a user selects their pizza and to`
`51`	`51`	`1. The user submits their pizza order.`
`52`	`52`	2. The server sends an `elicitation/create` request:
`53`	`53`
`54`		-```json filename="server-request.json" nocopy
	`54`	+```json filename=server-request.json nocopy
`55`	`55`	`{`
`56`	`56`	`"jsonrpc": "2.0",`
`57`	`57`	`"id": 1,`
`@@ -83,7 +83,7 @@ The client presents this to the user, who can:`
`83`	`83`
`84`	`84`	`Here's what the response from the client might look like:`
`85`	`85`
`86`		-```json filename="client-response.json" nocopy
	`86`	+```json filename=client-response.json nocopy
`87`	`87`	`{`
`88`	`88`	`"jsonrpc": "2.0",`
`89`	`89`	`"id": 1,`
Original file line number	Diff line number	Diff line change
`@@ -80,7 +80,7 @@ To test this in the MCP inspector:`
`80`	`80`	`- check the "Sampling" navigation tab and you should have a sampling request`
`81`	`81`	`- at this point, YOU are the LLM. You can copy paste this into your response:`
`82`	`82`
`83`		-```json filename="example-sampling-client-response.json"
	`83`	+```json filename=example-sampling-client-response.json
`84`	`84`	`{`
`85`	`85`	`"model": "stub-model",`
`86`	`86`	`"stopReason": "endTurn",`
Original file line number	Diff line number	Diff line change
`@@ -48,7 +48,7 @@ sequenceDiagram`
`48`	`48`
`49`	`49`	`Here's a simple example of a sampling request and response using MCP:`
`50`	`50`
`51`		-```json filename="server-request.json" nocopy
	`51`	+```json filename=server-request.json nocopy
`52`	`52`	`{`
`53`	`53`	`"jsonrpc": "2.0",`
`54`	`54`	`"id": 1,`
`@@ -69,7 +69,7 @@ Here's a simple example of a sampling request and response using MCP:`
`69`	`69`	`}`
`70`	`70`	```
`71`	`71`
`72`		-```json filename="client-response.json" nocopy
	`72`	+```json filename=client-response.json nocopy
`73`	`73`	`{`
`74`	`74`	`"jsonrpc": "2.0",`
`75`	`75`	`"id": 1,`