remove mcp instructor, added solutions to repo up to 2c-add-neo4j-connection

Author: adam-cowley

asciidoc/courses/genai-mcp-build-custom-tools-python/course.adoc

@@ -20,7 +20,6 @@ This course assumes that you have are familiar with the basics of Generative AI
 We also assume a basic understanding of Python and command line tools.  We assume that you have Python installed along with the `uv` package manager.
 If you are not familiar with uv, you should also link:https://docs.astral.sh/uv/[review the uv documentation].
 
-We also use the link:https://github.com/modelcontextprotocol/inspector[MCP Inspector^] to test and debug your MCP servers and tools.  This tool is run through link:https://docs.npmjs.com/cli/v8/commands/npx[the `npx` command]^, so you will need Node.js to be installed.  You can link:https://nodejs.org/en/download[download Node.js from the official website^].
 
 The course features hands-on challenges using link:https://github.com/settings/copilot[GitHub CoPilot^], you will need to enable either the free or Pro version.
 
@@ -36,14 +35,13 @@ The course features hands-on challenges using link:https://github.com/settings/c
 * How to create tools with context, logging, and structured outputs
 * How to expose resources and prompts through your server
 * How to implement pagination for large Neo4j datasets
-* How to use the MCP Inspector to test and debug
 * How to integrate MCP tools into development workflows
 * Advanced features: Sampling and Completions (optional)
 
 
 [.includes]
 == This course includes
 
-* [lessons]#16 lessons# across 3 modules (including setup)
+* [lessons]#14 lessons# across 3 modules (including setup)
 * [challenges]#7 hands-on challenges# with Neo4j
 * [quizes]#Quiz questions# to check your understanding

asciidoc/courses/genai-mcp-build-custom-tools-python/modules/1-getting-started/lessons/1-mcp-python-sdk/lesson.adoc

@@ -6,7 +6,7 @@ In the link:/courses/genai-mcp-neo4j-tools/[Developing with Neo4j MCP Tools cour
 
 In this course, you will learn how to build your own MCP servers with graph-backed tools and resources, creating a complete GraphRAG application.
 
-You will  learn to build these tools with the MCP Python SDK, and you will use the MCP Inspector to test your servers.
+You will learn to build these tools with the MCP Python SDK, and you will use an interactive Python client to test your servers.
 
 [TIP]
 .Emerging standards
@@ -279,4 +279,4 @@ In this lesson, you learned the foundational concepts for building MCP servers w
 * **Decorators** - Use `@mcp.tool()`, `@mcp.resource()`, and `@mcp.prompt()` to register features
 * **Transport methods** - Run servers using `stdio` (default) or `http` for web deployments
 
-In the next lesson, you will create your first MCP server using FastMCP and test it with the MCP Inspector.
+In the next lesson, you will create your first MCP server using FastMCP.

asciidoc/courses/genai-mcp-build-custom-tools-python/modules/1-getting-started/lessons/2-setup/lesson.adoc

@@ -48,7 +48,8 @@ The repository contains a `server/` directory where you will build your MCP serv
 Here are the important directories:
 
 * `server/` - Your MCP server code will go here
-* `examples/` - Example code demonstrating MCP concepts
+* `client/` - An interactive Python client for testing your MCP server
+* `solutions/` - Complete solutions for each of the challenges
 * `.github/` - GitHub configuration including Codespace setup
 
 
@@ -61,10 +62,9 @@ We have created a Neo4j Sandbox instance for you to use during this course, load
 To define the connection details as environment variables, create a `.env` file in the `server/` directory with the following values:
 
 
-[source,env]
+[source,env,subs="attributes+"]
 .server/.env
 ----
-# Neo4j Connection Details
 NEO4J_URI={instance-scheme}://{instance-ip}:{instance-boltPort}
 NEO4J_USERNAME={instance-username}
 NEO4J_PASSWORD={instance-password}
@@ -88,9 +88,8 @@ NEO4J_USERNAME:: [copy]#{instance-username}#
 NEO4J_PASSWORD:: [copy]#{instance-password}#
 
 [TIP]
+.Have your own Neo4j Aura database?
 ====
-**Using your own Neo4j Aura database?**
-
 If you have a link:https://neo4j.com/cloud/aura/[Neo4j Aura^] database with the Recommendations dataset, you can use those credentials instead in your `.env` file.
 ====
 
@@ -101,13 +100,18 @@ To verify your setup, run the `test_environment.py` script.
 
 [source,bash]
 ----
-python server/test_environment.py
+uv --directory client run test_environment.py
 ----
 
 
 You should see an `OK` message if you have set up your environment correctly. If any tests fail, check the contents of the `.env` file.
 
-
+[source,role=nocopy]
+----
+...
+----------------------------------------------------------------------
+Ran 3 tests in 0.366s
+----
 
 [TIP]
 .Accessing Environment Variables in Python

asciidoc/courses/genai-mcp-build-custom-tools-python/modules/1-getting-started/lessons/3c-create-first-server/lesson.adoc

@@ -22,10 +22,25 @@ You can open your existing codespaces at link:https://github.com/codespaces[gith
 
 To complete this challenge, you will need to:
 
-1. Create a new MCP server using the MCP Python SDK.
-2. Create a tool that counts the number of times a letter appears in a word.
-3. Configure VS Code to use the MCP server with stdio.
-4. Test the server using the Chat window in Agent mode.
+1. Create a new MCP server using the MCP Python SDK
+2. Create a tool that counts the number of times a letter appears in a word
+3. Run your MCP server with HTTP transport
+4. Test the server using the interactive client
+
+
+[TIP]
+.Solution Available
+====
+If you get stuck, you can review the complete solution in the repository at `solutions/3c-create-first-server/main.py`.
+
+To see the solution in action, run:
+
+[source,bash]
+----
+uv --directory solutions/3c-create-first-server run main.py
+----
+====
+
 
 == Step-by-Step Instructions
 
@@ -34,6 +49,7 @@ To complete this challenge, you will need to:
 First, create a new directory for your MCP server:
 
 [source,bash]
+.Create a new directory
 ----
 mkdir strawberry
 cd strawberry
@@ -44,6 +60,7 @@ cd strawberry
 Initialize a new Python project using `uv`:
 
 [source,bash]
+.Initialize a new UV project
 ----
 uv init
 ----
@@ -55,6 +72,7 @@ This will create a basic project structure with a `pyproject.toml` file and a `m
 Add the MCP Python SDK to your project:
 
 [source,bash]
+.Add the MCP Python SDK to your project
 ----
 uv add "mcp[cli]"
 ----
@@ -70,7 +88,7 @@ Open `main.py` in your editor and add the following code to create a simple MCP
 from mcp.server.fastmcp import FastMCP
 
 # Create an MCP server
-mcp = FastMCP("Strawbrerry")
+mcp = FastMCP("Strawberry")
 
 @mcp.tool()
 def count_letters(text: str, search: str) -> int:
@@ -88,24 +106,23 @@ if __name__ == "__main__":
 This example uses the `streaming-http` transport method to run the server.
 This differs from `stdio` in that the client uses HTTP to communicate with the server.
 
-We have made this choice to make it easier to test the server in GitHub Codespaces with the MCP Inspector.
+We have made this choice to make it easier to test the server in GitHub Codespaces with the interactive Python client.
 For local development, using `stdio` is also a valid option.
 
 link:https://modelcontextprotocol.io/specification/2025-06-18/basic/transports[Learn more about transports^]
 ====
 
-=== Step 5: Configure your server in VS Code and test with Agent mode
+=== Step 5: Run Your Server
 
-Now let's configure your server to work with VS Code's Agent mode. This will allow you to interact with your MCP server through a conversational interface.
-
-First, let's run the server to make sure it works:
+Start your MCP server:
 
 [source,bash]
+.Run your MCP server
 ----
 uv run main.py
 ----
 
-If the server is running, you will see the following output in the terminal:
+If the server is running successfully, you will see output similar to:
 
 [source,role=nocopy]
 .Console Output
@@ -118,58 +135,99 @@ INFO:     Application startup complete.
 INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
 ----
 
+Your server is now running on port 8000 and ready to accept connections from MCP clients.
 
-Once the server is running, modify the `.vscode/mcp.json` file to configure VS Code to use the server.
 
-[source,json]
+== Test with the Interactive Client
+
+Now let's test your server. The course repository includes an interactive Python client in the `client/` folder that you can use to test your MCP server.
+
+
+Open a **new terminal** (keep the server running in the first one) and run the following command:
+
+[source,bash]
+.Run the interactive client
 ----
-{
-    "servers": {
-        "strawberry": {
-            "type": "http",
-            "url": "http://localhost:8000/mcp"
-        }
-    }
-}
+uv --directory client run main.py
 ----
 
-This configuration tells VS Code to connect to the server at `http://localhost:8000/mcp` using a HTTP connection.
+The client will connect to your server and display an interactive menu showing available tools:
 
+[source,output,role=nocopy]
+.Console Output
+----
+============================================================
+🔧 Available Tools:
+============================================================
+
+1. count_letters
+   Count occurrences of a letter in the text
 
-=== Step 6: Verify your implementation
+0. Exit
+============================================================
 
+Select a tool, resource, or template (enter number): 
+----
 
-To test your server, open up the Chat window in **Agent** mode:
+Enter `1` to select the `count_letters` tool.
 
-1. Open the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
-2. Execute the "Chat: Open Chat (Agent)" command
+The client will prompt you for the required parameters with type information:
 
-Now try asking the following question:
+[source,output,role=nocopy]
+.Console Output
+----
+text (required)
+  Type: string
+  Enter value: strawberry
 
-[copy]#How many times does the letter 'r' appear in the word 'strawberry'?#
+search (required)
+  Type: string
+  Enter value: r
+----
+
+After entering the parameters, you'll see the result returned by the tool:
+
+[source,output,role=nocopy]
+.Console Output
+----
+✨ Result:
+------------------------------------------------------------
+3
+------------------------------------------------------------
+----
 
-The agent should discover the `count_letters` tool and prompt you to confirm the tool call.
-It should respond with the answer `3`.
+Try testing with different inputs to verify the tool works correctly. Press Enter to return to the menu, or `q` to quit.
 
 
 [TIP]
-.The agent didn't call the tool?
+.Other Testing Options
 ====
-This is the joy of LLMs and tool calling.
-Depending on the underlying model, the agent may not behave as you expect.  
-In this case, the model may feel confident in its own answer and not call the tool.
+**VS Code Agent Mode**: You can also test your MCP server directly in VS Code by configuring it in `.vscode/mcp.json` and using the Chat window in Agent mode. This allows you to interact with your tools conversationally.
 
-Try switching to a different model, rephrasing the question, or explicitly mentioning the tool you want to use.
-====
+[%collapsible]
+.Configuring the server for VS Code Agent mode
+=====
+[source,json]
+.vscode/mcp.json
+----
+{
+  "servers": {
+    "strawberry": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+----
+=====
 
+**MCP Inspector**: For visual debugging, the link:https://github.com/modelcontextprotocol/inspector[MCP Inspector^] provides a web-based UI for exploring tools, resources, and prompts. Run it with `npx @modelcontextprotocol/inspector`.
+====
 
 
 == That's it!
 
-You have just created your first MCP server! 
-
-The Chat window in VS Code is a useful way to test your server, but it isn't the most efficient way to test your MCP server.
-In the next lesson, you will learn about the MCP Inspector, which is a tool that allows you to inspect the MCP server and its tools.
+You have just created and tested your first MCP server!
 
 
 read::Mark as Completed[]
@@ -180,8 +238,9 @@ read::Mark as Completed[]
 In this challenge, you successfully built your first MCP server from scratch:
 
 * **FastMCP setup** - Created a new MCP server using the FastMCP class with the MCP Python SDK
-* **Tool implementation** - Added a `count_letters` tool using the `@mcp.tool()` decorator to solve LLM counting limitations.
-* **Server installation** - Configured the server for VS Code using `uv run mcp install main.py`
-* **Agent mode testing** - Tested the server functionality through VS Code Agent mode with conversational queries
+* **Tool implementation** - Added a `count_letters` tool using the `@mcp.tool()` decorator to solve LLM counting limitations
+* **HTTP transport** - Configured the server to use streaming-HTTP transport for easy testing
+* **Interactive testing** - Tested the server with the Python client for immediate feedback
+
 
-In the next lesson, you will learn about context management for handling server lifecycle and resource management.
+In the next module, you will learn about context management for handling server lifecycle and resource management, and you'll start building tools that connect to Neo4j.