bitovi · Jahteo · Oct 9, 2025 · Oct 9, 2025 · Oct 9, 2025 · Oct 9, 2025
diff --git a/training/1-what-is-mcp.md b/training/1-what-is-mcp.md
@@ -12,23 +12,30 @@ Learn about the Model Context Protocol (MCP) and understand how it enables AI ag
   - [stdio](#stdio)
   - [Streamable HTTP](#streamable-http)
 - [How Agents Use MCP](#how-agents-use-mcp)
-- [MCP Architecture](#mcp-architecture)
-- [Key Benefits](#key-benefits)
 - [Terminology Note](#terminology-note)
+- [Next Steps](#next-steps)
 
 ## What is MCP?
 
 MCP (Model Context Protocol) is a **protocol** based on JSON‑RPC that runs over various transports. It allows "clients" (agent applications, IDEs, chat UIs) to call capabilities hosted by **servers**.
 
 Think of MCP as a bridge between AI agents and external services. Instead of each agent needing custom integrations for every service, MCP provides a standardized way for agents to discover and use capabilities from different providers.
 
+## Terminology Note
+
+Throughout this training, we'll use "server" and "tool provider" consistently with the MCP SDK terminology. Remember:
+
+- **Client**: The AI agent, IDE, or chat application
+- **Server**: The MCP service that provides tools, resources, and prompts
+- **Transport**: The communication layer for client and server (stdio or Streamable HTTP)
+
 ## Core MCP Capabilities
 
 MCP servers can expose four main types of capabilities:
 
 ### Tools
 
-[Tools](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/tools) are RPC‑like functions that clients can call to perform actions or retrieve data. Examples:
+[Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) are RPC‑like functions that clients can call to perform actions or retrieve data. Examples:
 
 - Search Jira issues
 - Create a GitHub issue
@@ -37,7 +44,7 @@ MCP servers can expose four main types of capabilities:
 
 ### Resources
 
-[Resources](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/resources) are readable URIs that return content, similar to files or dynamic lookups. Resources represent **data that exists** rather than **actions to perform**.
+[Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) are readable URIs that return content, similar to files or dynamic lookups. Resources represent **data that exists** rather than **actions to perform**.
 
 **Key differences from tools:**
 
@@ -84,15 +91,15 @@ MCP servers can expose four main types of capabilities:
 
 ### Prompts
 
-[Prompts](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/prompts) are pre‑defined prompt templates exposed by the server that clients can use. Examples:
+[Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts) are pre‑defined prompt templates exposed by the server that clients can use. Examples:
 
 - Code review templates
 - Meeting summary formats
 - Bug report templates
 
 ### Sampling Hooks
 
-[Sampling hooks](https://spec.modelcontextprotocol.io/specification/2025-06-18/client/sampling) allow servers to **use the client's AI capabilities** for text/data generation within tool workflows. Sampling hooks enable servers to leverage the client's AI model without needing their own.
+[Sampling hooks](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling) allow servers to **use the client's AI capabilities** for text/data generation within tool workflows. Sampling hooks enable servers to leverage the client's AI model without needing their own.
 
 **How it works:**
 
@@ -122,7 +129,7 @@ MCP servers can expose four main types of capabilities:
 
 ## MCP Transports (2025)
 
-In 2025, MCP supports two primary transports:
+In 2025, MCP supports two primary transport mechanisms for client-server communication, called [transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports):
 
 ### stdio
 
@@ -151,14 +158,6 @@ The typical flow of an agent using MCP services:
 5. **Streaming Results**: Agent receives real-time updates through optional SSE
 6. **Context Updates**: Agent incorporates results into its working context
 
-## Terminology Note
-
-Throughout this training, we'll use "server" and "tool provider" consistently with the MCP SDK terminology. Remember:
-
-- **Client**: The AI agent, IDE, or chat application
-- **Server**: The MCP service that provides tools, resources, and prompts
-- **Transport**: The communication layer (stdio or Streamable HTTP)
-
 ## Next Steps
 
 Now that you understand what MCP is and its core capabilities, let's see it in action!

diff --git a/training/2-using-mcp.md b/training/2-using-mcp.md
@@ -16,13 +16,11 @@ Learn how to connect to and use a real production MCP server by configuring VS C
 
 ## Problem
 
-Before building your own MCP server, you need to understand how MCP works in practice. You want to use GitHub Copilot to help manage GitHub issues by connecting to GitHub's MCP server, creating a new issue in the `bitovi/mcp-training` repository, and then closing it.
-
-This hands-on experience will show you how agents discover tools, handle authentication, and make tool calls in a real-world scenario.
+Before building an MCP server, your first task is to use GitHub Copilot to help manage GitHub issues by connecting to GitHub's MCP server, creating a new issue in the `bitovi/mcp-training` repository, and then closing it. This hands-on experience will help you understand how MCP works in practice - showing how agents discover tools, handle authentication, and make tool calls in a real-world scenario.
 
 ## What you need to know
 
-📝 **Reference**: [MCP Specification](https://spec.modelcontextprotocol.io/)
+📝 **Reference**: [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18)
 
 ### MCP Client Configuration in VS Code
 
@@ -144,7 +142,7 @@ When working with AI agents that have access to MCP tools, effective prompting i
 
 **Example Effective Prompts:**
 
-- ✅ "Create a new issue in bitovi/mcp-training with title 'Test MCP Integration' and describe it as a training exercise"
+- ✅ "Create a new issue in microsoft/vscode with title 'Feature Request: Better Terminal Integration' and describe the need for improved terminal features"
 - ❌ "Make an issue about testing"
 - ✅ "Close issue #42 in the mcp-training repository"
 - ❌ "Close that issue"
@@ -162,7 +160,7 @@ Using Github Copilot Chat, you should be able to:
 <details>
 <summary>Click to see the complete solution</summary>
 
-### 1. Create `.vscode/mcp.json`
+### 1. Verify `.vscode/mcp.json` has already been provided
 
 ```json
 {

diff --git a/training/3-mcp-with-stdio.md b/training/3-mcp-with-stdio.md
@@ -215,25 +215,24 @@ The server should:
 
 🔍 Test your server in VS Code:
 
-1. **Add your server to VS Code's MCP configuration**:
+1. **Ensure your server is in VS Code's MCP configuration**:
 
-   Create or edit `.vscode/mcp.json` in your workspace root:
+   `.vscode/mcp.json` is already provided in your workspace root. Ensure it includes this server:
 
    ```json
    {
      "servers": {
-       "mcp-training": {
+       "mcp-training-stdio": {
          "type": "stdio",
-         "command": "./src/stdio-server.ts",
-         "cwd": "${workspaceFolder}"
+         "command": "./src/stdio-server.ts"
        }
      }
    }
    ```
 
    💡 **Note**: This works because the `stdio-server.ts` file has a shebang line that tells the system how to execute it with the TypeScript loader.
 
-2. **Start your MCP server**: In VS Code's MCP panel, find your "mcp-training" server and click the start button to launch it
+2. **Start your MCP server**: In VS Code's MCP panel, find your "mcp-training-stdio" server and click the start button to launch it
 
 3. **Test the server in VS Code**:
    - Open any file in VS Code
@@ -259,7 +258,8 @@ The server should:
 
 ## Solution
 
-Here's the complete implementation:
+<details>
+<summary>Click to see the complete solution</summary>
 
 **Install the required dependencies**:
 
@@ -289,25 +289,16 @@ function createSlug(text: string): string {
   return slug;
 }
 
--// Factory function to create a new MCP server instance
+// Factory function to create a new MCP server instance
 -export function createMcpServer()/*: McpServer*/ {
--  // TODO: Create and configure the MCP server
--
--
--  // Register tools
--
--
--  // Return the configured server
--  //return server;
--}
-+// Factory function to create a new MCP server instance
 +export function createMcpServer(): McpServer {
+  // TODO: Create and configure the MCP server
 +  const server = new McpServer({
 +    name: "demo-server",
 +    version: "1.0.0"
 +  });
 +
-+  // Register tools
+ // Register tools
 +  server.registerTool(
 +    "slugify",
 +    {
@@ -326,6 +317,8 @@ function createSlug(text: string): string {
 +    }
 +  );
 +
+// Return the configured server
+-  //return server;
 +  return server;
 +}
 ```
@@ -334,11 +327,9 @@ function createSlug(text: string): string {
 
 1. **Lines 1-2**: Uncomment imports for `McpServer` and `z` (Zod) to enable MCP functionality
 2. **Line 15**: Add proper TypeScript return type annotation for the factory function
-3. **Line 16**: Remove "TODO:" from comment and implement server creation
-4. **Lines 16-19**: Create new `McpServer` instance with server metadata (name and version)
-5. **Line 21**: Remove "TODO:" from comment and implement tool registration
-6. **Lines 21-35**: Register the "slugify" tool with Zod schema validation and implementation
-7. **Line 37**: Remove "TODO:" and implement server return instead of commented placeholder
+3. **Lines 16-19**: Create new `McpServer` instance with server metadata (name and version)
+4. **Lines 21-35**: Register the "slugify" tool with Zod schema validation and implementation
+5. **Line 37**: Implement server return instead of commented placeholder
 
 📁 **Reference Implementation**: [training/3-mcp-with-stdio/src/mcp-server.ts](./3-mcp-with-stdio/src/mcp-server.ts#L1-L2,L15,L16-L19,L21-L35,L37)
 
@@ -354,15 +345,12 @@ import {createMcpServer} from "./mcp-server.js";
 
 try {
   // Create stdio transport
--
 +  const transport = new StdioServerTransport();
 
   // Connect server to transport
--
 +  await createMcpServer().connect(transport);
 
   // Log to stderr so it doesn't interfere with MCP protocol
--
 +  console.error("Demo MCP server running on stdio");
 +
 } catch (error) {
@@ -374,15 +362,15 @@ try {
 **Key Changes:**
 
 1. **Line 2**: Uncomment `StdioServerTransport` import to enable stdio communication
-2. **Line 7**: Replace empty line with stdio transport creation
-3. **Line 10**: Replace empty line with server connection to transport
-4. **Line 13**: Replace empty line with stderr logging to avoid interfering with MCP protocol
+2. **Line 7**: Add stdio transport creation
+3. **Line 10**: Add server connection to transport
+4. **Line 13**: Add stderr logging to avoid interfering with MCP protocol
 
 📁 **Reference Implementation**: [training/3-mcp-with-stdio/src/stdio-server.ts](./3-mcp-with-stdio/src/stdio-server.ts#L2,L7,L10,L13)
 
 ### 3. Configure VS Code MCP Integration (`.vscode/mcp.json`)
 
-Add your server to VS Code's MCP configuration:
+Verify your server is in VS Code's MCP configuration:
 
 ```diff
 {
@@ -401,11 +389,12 @@ Add your server to VS Code's MCP configuration:
 
 **Key Changes:**
 
-1. **Lines 6-9**: Add new "mcp-training" server configuration using stdio transport
-2. **Command property**: Point to the executable stdio server file with proper shebang
+1. **Lines 6-9**: Add new "mcp-training-stdio" server configuration using stdio transport
 
 📁 **Reference Implementation**: [training/3-mcp-with-stdio/.vscode/mcp.json](./3-mcp-with-stdio/.vscode/mcp.json#L6-L9)
 
+</details>
+
 ## Next Steps
 
 You now have a working MCP server!

diff --git a/training/4-mcp-inspector.md b/training/4-mcp-inspector.md
@@ -50,6 +50,8 @@ When you run the inspector, it will:
 2. Open a web interface (default port 6274)
 3. Connect to your specified server (if provided)
 
+> Tip to simplify auth: look in your terminal for the url to `🔗 Open inspector with token pre-filled:`
+
 ### Connecting to Local stdio Servers
 
 For local development, you can directly specify your server script:
@@ -261,7 +263,8 @@ return {
 
 ## Solution
 
-Here's the complete solution for debugging with MCP Inspector:
+<details>
+<summary>Click to see the complete solution for debugging with MCP Inspector</summary>
 
 **Connect to your local server**:
 
@@ -302,23 +305,24 @@ server.registerTool(
   "slugify",
   {
     title: "Slugify",
-      description: "Convert text to a URL-friendly slug",
-      inputSchema: {
-        text: z.string().describe("The text to convert into a URL-friendly slug")
-      }
+    description: "Convert text to a URL-friendly slug",
+    inputSchema: {
+      text: z.string().describe("The text to convert into a URL-friendly slug"),
     },
-    async ({ text }) => {
-      const slug = createSlug(text);
+  },
+  async ({ text }) => {
+    const slug = createSlug(text);
 
-      // FIXED: Using correct 'content' field
-      return {
-        content: [{ type: "text", text: slug }]
-      };
-    }
-  );
-}
+    // FIXED: Using correct 'content' field
+    return {
+      content: [{ type: "text", text: slug }],
+    };
+  }
+);
 ```
 
+</details>
+
 ## Next Steps
 
 Now that you've mastered debugging with MCP Inspector, you're ready to build production-ready MCP services!