improve instructions

Author: kentcdodds

epicshop/dev.js

@@ -29,6 +29,7 @@ const inspectorProcess = execa('mcp-inspector', [], {
 		SERVER_PORT: serverPort,
 		CLIENT_PORT: clientPort,
 		MCP_PROXY_TOKEN: sessionToken,
+		MCP_AUTO_OPEN_ENABLED: 'false',
 		ALLOWED_ORIGINS: [
 			`http://localhost:${clientPort}`,
 			`http://127.0.0.1:${clientPort}`,

epicshop/mcp-dev/dev.js

@@ -46,3 +46,5 @@ To support this, each tool should include an `annotations` property that describ
 📜 Please check [the table in the MCP docs](https://modelcontextprotocol.io/docs/concepts/tools#available-tool-annotations) for the default values and when each annotation is useful.
 
 The goal is to make tool behavior obvious to both users and the UI. The more clearly this is communicated, the more empowered and comfortable users will feel using the mcp server's advanced features.
+
+To test this in the MCP inspector, simply connect and click "Tools" and "List Tools," then check the annotations in the response.

exercises/01.advanced-tools/01.problem.annotations/README.mdx

@@ -68,3 +68,5 @@ Here's what a structured output response looks like:
 </callout-muted>
 
 The goal: make every journaling action in EpicMe feel seamless, safe, and delightful—so users can focus on capturing their stories, not on deciphering cryptic responses.
+
+To test this in the MCP inspector, simply connect and click "Tools" and "List Tools," then check the output schema in the response. Then you can run one of the tools and verify the output includes the structured content.

exercises/01.advanced-tools/02.problem.structured/README.mdx

@@ -49,9 +49,24 @@ if (!confirmed) {
 	provides clear feedback (no sandwiches are harmed)!
 </callout-success>
 
+Note you will also want to verify that the client has elicitation capabilities, and if they do not, then just proceed.
+
+```ts
+// the server.server is how the MCP SDK exposes the underlying server
+// instance for more advanced APIs like this one.
+const capabilities = agent.server.server.getClientCapabilities()
+if (capabilities?.elicitation) {
+	// do the elicitation
+} else {
+	// proceed without elicitation
+}
+```
+
 This approach ensures users are always in control of important actions, and the system responds with empathy and clarity.
 
 Test this one out by using the `delete_tag` tool.
 
 🐨 Kody will be there in <InlineFile file="src/tools.ts" /> to help you
 implement this.
+
+The MCP Inspector [does not support elicitation yet](https://github.com/modelcontextprotocol/inspector/issues/524), so you can check that our capabilities check is working by running the `delete_tag` tool, but to verify your elicitation is working, you'll need to run the tests.

exercises/02.elicitation/01.problem/README.mdx

@@ -294,6 +294,7 @@ export async function initializeTools(agent: EpicMeMCP) {
 			const existingTag = await agent.db.getTag(id)
 			invariant(existingTag, `Tag ID "${id}" not found`)
 
+			// 🐨 first check whether the client has the elicitInput capability, if it does then:
 			// 🐨 Use agent.server.server.elicitInput to ask the user to confirm deletion of the tag.
 			//    - The message should be: `Are you sure you want to delete tag "${existingTag.name}" (ID: ${id})?`
 			//    - The requestedSchema should be an object with a boolean property "confirmed".

exercises/02.elicitation/01.problem/src/tools.ts

@@ -294,31 +294,35 @@ export async function initializeTools(agent: EpicMeMCP) {
 			const existingTag = await agent.db.getTag(id)
 			invariant(existingTag, `Tag ID "${id}" not found`)
 
-			const result = await agent.server.server.elicitInput({
-				message: `Are you sure you want to delete tag "${existingTag.name}" (ID: ${id})?`,
-				requestedSchema: {
-					type: 'object',
-					properties: {
-						confirmed: {
-							type: 'boolean',
-							description: 'Whether to confirm the action',
+			const capabilities = agent.server.server.getClientCapabilities()
+			if (capabilities?.elicitation) {
+				const result = await agent.server.server.elicitInput({
+					message: `Are you sure you want to delete tag "${existingTag.name}" (ID: ${id})?`,
+					requestedSchema: {
+						type: 'object',
+						properties: {
+							confirmed: {
+								type: 'boolean',
+								description: 'Whether to confirm the action',
+							},
 						},
 					},
-				},
-			})
-			const confirmed =
-				result.action === 'accept' && result.content?.confirmed === true
-			if (!confirmed) {
-				const structuredContent = { success: false, tag: existingTag }
-				return {
-					structuredContent,
-					content: [
-						createTextContent(
-							`Deleting tag "${existingTag.name}" (ID: ${id}) rejected by the user.`,
-						),
-						createTagResourceLink(existingTag),
-						createTextContent(structuredContent),
-					],
+				})
+
+				const confirmed =
+					result.action === 'accept' && result.content?.confirmed === true
+				if (!confirmed) {
+					const structuredContent = { success: false, tag: existingTag }
+					return {
+						structuredContent,
+						content: [
+							createTextContent(
+								`Deleting tag "${existingTag.name}" (ID: ${id}) rejected by the user.`,
+							),
+							createTagResourceLink(existingTag),
+							createTextContent(structuredContent),
+						],
+					}
 				}
 			}
 

exercises/02.elicitation/01.solution/src/tools.ts

@@ -31,8 +31,10 @@ And don't forget to call it when the user creates a new journal entry!
 Here's an example of how to check if the client supports sampling:
 
 ```ts
-const clientCapabilities = agent.server.server.getClientCapabilities()
-if (!clientCapabilities?.sampling) {
+// the server.server is how the MCP SDK exposes the underlying server
+// instance for more advanced APIs like this one.
+const capabilities = agent.server.server.getClientCapabilities()
+if (!capabilities?.sampling) {
 	console.error('Client does not support sampling, skipping sampling request')
 	return
 }
@@ -49,3 +51,23 @@ The `maxTokens` option references the max tokens the model should return.
 This step will help you get comfortable with the basic request/response flow for
 sampling in MCP, and set the stage for more advanced prompt engineering in the
 next step.
+
+There are tests to help verify your sampling request is working.
+
+To test this in the MCP inspector:
+
+- run the `create_entry` tool
+- 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
+{
+	"model": "stub-model",
+	"stopReason": "endTurn",
+	"role": "assistant",
+	"content": {
+		"type": "text",
+		"text": "Good job!"
+	}
+}
+```

exercises/03.sampling/01.problem.simple/README.mdx

@@ -91,3 +91,23 @@ for a new journal entry.
 
 This step will help you practice prompt engineering for structured outputs, and
 show you how to use the full power of MCP's sampling API for real-world tasks.
+
+There are tests to help verify your sampling request is working.
+
+To test this in the MCP inspector:
+
+- run the `create_entry` tool
+- 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
+{
+	"model": "stub-model",
+	"stopReason": "endTurn",
+	"role": "assistant",
+	"content": {
+		"type": "text",
+		"text": "[{\"id\":2},{\"id\":4},{\"name\":\"Beach\",\"description\":\"Activities or experiences at the beach, including sand, water, and seaside fun\"}]"
+	}
+}
+```

exercises/03.sampling/02.problem.advanced/README.mdx

@@ -58,7 +58,7 @@ sequenceDiagram
 
 The goal is to make waiting feel like part of the experience, not a chore. Progress updates turn a long-running task into a journey the user can follow, one delicious layer at a time.
 
-Test this one out by using the `create_wrapped_video` tool.
+Test this one out in the MCP inspector by using the `create_wrapped_video` tool.
 
 <callout-info>
 	**NOTE**: This particular tool requires ffmpeg to be installed globally on