solutions to 10c

Author: adam-cowley

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

@@ -29,7 +29,7 @@ The SDK includes two main approaches for building servers:
 * **FastMCP**: A high-level, decorator-based approach that makes it simple to create servers quickly
 * **Low-level server**: A more flexible approach that gives you full control over the MCP protocol
 
-In this course, we will focus on the FastMCP approach.
+In this course, you will focus on the FastMCP approach.
 
 
 == Installing the MCP Python SDK
@@ -48,16 +48,16 @@ This package includes both the core MCP functionality and the FastMCP high-level
 
 == Introducing FastMCP
 
-FastMCP is the high-level interface in the MCP Python SDK designed to make server development as simple as possible.  FastMCP is built on top of the FastAPI framework, and uses a decorator approach to defining MCP features.
+link:https://gofastmcp.com/[FastMCP^] is the high-level interface in the MCP Python SDK designed to make server development as simple as possible.  It is built on top of the FastAPI framework, and uses a decorator approach to defining MCP features.
 
 
 == Core MCP Features
 
-MCP servers expose three types of features to clients. Let's take a look at each one and when to use them.
+MCP servers expose three types of features to clients.
 
 === 1. Tools
 
-**Tools** are functions that LLMs can call to perform actions or retrieve data. They are perfect for tasks that LLMs struggle with, like counting or complex calculations.
+**Tools** are functions that LLMs can call to perform actions or retrieve data. Tools are perfect for tasks that LLMs struggle with, like counting or complex calculations.
 
 **Characteristics:**
 
@@ -204,7 +204,7 @@ Reflection is then used to infer metadata about the tool.
 2. The output of the tool is an `int`
 3. The string in the opening line is used to  describe what the tool does and and when it should be used.
 
-The `@mcp.tool()` decorator accepts a number of optional arguments, which we will cover later in the course.
+The `@mcp.tool()` decorator accepts a number of optional arguments, which you will learn about later in the course.
 
 
 == Running the server 
@@ -240,13 +240,16 @@ link:https://github.com/jlowin/fastmcp[Learn more about `fastmcp`].
 
 === Transport methods 
 
-In the previous course, we also covered the different transport methods that can be used to connect to an MCP server; Standard Input/Output (`stdio`), and Streamable HTTP (`http`).
-As we will develop a local MCP server in this course, we will focus on the `stdio` transport method.  You can change the transport method by passing the `transport` parameter to the `run` method.
+In the link:https://graphacademy.neo4j.com/courses/genai-mcp-neo4j-tools/[Developing with Neo4j MCP Tools course^], we also covered the different transport methods that can be used to connect to an MCP server; Standard Input/Output (`stdio`), and Streamable HTTP (`http`).
+
+This course will focus on the **Streamable HTTP** transport method.  
+The Streamable HTTP transport method exposes the tools through a HTTP server, with results streamed back to the client using link:https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events[Server-Sent Events (SSE)^].
+
 
 [source,python]
 ----
 mcp.run(
-    transport="http", 
+    transport="streamable-http", 
     host="127.0.0.1", 
     port=8000, 
     path="/mcp"
@@ -258,13 +261,20 @@ Streaming HTTP is recommended for web deployments.
 [TIP]
 .The `fastmcp` command line tool
 ====
-You can also provide the `--transport`, `--host`, `--port`, and `--path` flags to the `fastmcp` command.
+You can change the transport method by providing the `--transport`, `--host`, `--port`, and `--path` flags to the `fastmcp` command.
+The command doesn't execute the `__main__` block of the server, instead preferring the parameters passed to the command.
+
+[source,bash]
+----
+fastmcp run server.py --transport http --host 127.0.0.1 --port 8000
+----
+
+link:https://gofastmcp.com/patterns/cli/[Learn more about the `fastmcp` command line tool^].
 ====
 
 read::Mark as Completed[]
 
 
-
 [.summary]
 == Summary
 

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

@@ -2,7 +2,6 @@
 :type: challenge
 :order: 10
 
-
 In the previous lesson, you learned about pagination and how to use Neo4j's `SKIP` and `LIMIT` clauses to fetch data in manageable chunks.
 
 In this challenge, you will implement a paginated tool that allows users to browse through movies in a specific genre, page by page.
@@ -41,111 +40,42 @@ First, define the tool function with its parameters:
 [source,python]
 .server/main.py
 ----
-@mcp.tool()
-async def browse_movies_by_genre(
-    genre: str,
-    cursor: str = "0",
-    page_size: int = 10,
-    ctx: Context = None
-) -> dict:
-    """
-    Browse movies in a genre with pagination support.
-    
-    Args:
-        genre: Genre name (e.g., "Action", "Comedy", "Drama")
-        cursor: Pagination cursor - position in the result set (default "0")
-        page_size: Number of movies to return per page (default 10)
-    
-    Returns:
-        Dictionary containing:
-        - movies: List of movie objects with title, released, and rating
-        - next_cursor: Cursor for the next page (null if no more pages)
-        - page: Current page number (1-indexed)
-        - has_more: Boolean indicating if more pages are available
-    """
+include::{repository-raw}/main/solutions/10c-paginated-tool/main.py[tag=list_movies_by_genre_def]
 ----
 
-The function takes a required `genre` parameter and optional `cursor` and `page_size` parameters. The cursor defaults to "0" (start of the list), and page_size defaults to 10 items per page.
+The function takes a required `genre` parameter and optional `cursor` and `page_size` parameters. The cursor defaults to `0` (start of the list), and page_size defaults to 10 items per page.
 
 Next, handle cursor validation and setup:
 
 [source,python]
 ----
-    # Parse cursor to get skip value
-    try:
-        skip = int(cursor)
-    except ValueError:
-        await ctx.error(f"Invalid cursor: {cursor}")
-        skip = 0
-    
-    # Access driver from lifespan context
-    driver = ctx.request_context.lifespan_context.driver
-    
-    # Log the request
-    page_num = (skip // page_size) + 1
-    await ctx.info(f"Fetching {genre} movies, page {page_num} (showing {page_size} per page)...")
+include::{repository-raw}/main/solutions/10c-paginated-tool/main.py[tag=list_movies_by_genre_cursor]
 ----
 
-This section converts the cursor string to a number and calculates the current page number. If the cursor is invalid, it defaults to the start (skip = 0).
+This section uses the cursor number to calculate the skip value. 
 
-The query execution uses Neo4j's SKIP and LIMIT for pagination:
+Next, using the driver instance from the lifespan context, execute the query to fetch the movies using the SKIP and LIMIT clauses, and coerce the results into a list of dictionaries.
 
 [source,python]
 ----
-    try:
-        # Execute paginated query
-        records, summary, keys = await driver.execute_query(
-            """
-            MATCH (m:Movie)-[:IN_GENRE]->(g:Genre {name: $genre})
-            RETURN m.title AS title,
-                   m.released AS released,
-                   m.imdbRating AS rating
-            ORDER BY m.imdbRating DESC, m.title ASC
-            SKIP $skip
-            LIMIT $limit
-            """,
-            genre=genre,
-            skip=skip,
-            limit=page_size
-        )
+include::{repository-raw}/main/solutions/10c-paginated-tool/main.py[tag=list_movies_by_genre_execute]
 ----
 
-The Cypher query finds movies in the specified genre, ordered by rating (highest first) and title. SKIP and LIMIT handle the pagination.
-
-Finally, process the results and return the paginated response:
+Finally, calculate the next cursor and return the structured output.
 
 [source,python]
 ----
-        # Convert to list of dictionaries
-        movies = [record.data() for record in records]
-        
-        # Calculate next cursor
-        next_cursor = None
-        if len(movies) == page_size:
-            next_cursor = str(skip + page_size)
-        
-        # Log results
-        await ctx.info(f"Returned {len(movies)} movies from page {page_num}")
-        if next_cursor is None:
-            await ctx.info("This is the last page")
-        
-        # Return structured response
-        return {
-            "genre": genre,
-            "movies": movies,
-            "next_cursor": next_cursor,
-            "page": page_num,
-            "page_size": page_size,
-            "has_more": next_cursor is not None,
-            "count": len(movies)
-        }
-        
-    except Exception as e:
-        await ctx.error(f"Query failed: {str(e)}")
-        raise
+include::{repository-raw}/main/solutions/10c-paginated-tool/main.py[tag=list_movies_by_genre_return]
 ----
 
-The response includes the movies list and pagination metadata. The `next_cursor` is only set if a full page was returned, indicating more results are available.
+The structured output consists of a dictionary with the following keys:
+
+* `genre` - The genre passed to the tool by the client
+* `movies` - A list of movies returned from the query
+* `next_cursor` - The cursor for the next page
+* `page` - The current page number
+* `page_size` - The number of movies per page
+* `has_more` - A boolean indicating if more pages are available
 
 
 == Step 2: Test with the Interactive Client
@@ -177,21 +107,41 @@ genre (required)
   Type: string
   Enter value: Action
 
-cursor (optional, default: 0)
+page_size (optional)
+  Type: integer
+  Enter value: 2
+
+cursor (optional)
   Type: string
-  Enter value: 0
+  Enter value: 1=9
 
-page_size (optional, default: 10)
-  Type: integer
-  Enter value: 10
 ----
 
-The response should contain:
+You should receive a structured response similar to the following, with information about the current page and the next cursor.
 
-* 10 Action movies
-* A `next_cursor` value (e.g., `"10"`)
-* `page: 1`
-* `has_more: true`
+[source,json]
+.Structured Response
+----
+{
+  "genre": "Action",
+  "movies": [
+    {
+      "title": "'Hellboy': The Seeds of Creation",
+      "released": "2004-07-27",
+      "rating": 6.9
+    },
+    {
+      "title": "13 Assassins (Jûsan-nin no shikaku)",
+      "released": "2010-09-25",
+      "rating": 7.6
+    }
+  ],
+  "next_cursor": 2,
+  "page": 1,
+  "page_size": 2,
+  "has_more": true
+}
+----
 
 
 === Fetch the Second Page
@@ -204,45 +154,49 @@ genre (required)
   Type: string
   Enter value: Action
 
-cursor (optional, default: 0)
-  Type: string
-  Enter value: 10
-
 page_size (optional, default: 10)
   Type: integer
-  Enter value: 10
-----
-
-The response should contain:
-
-* The next 10 Action movies
-* A new `next_cursor` value (e.g., `"20"`)
-* `page: 2`
-* `has_more: true` (if more pages exist)
-
-
-=== Continue to the Last Page
+  Enter value: 2
 
-Keep using the `next_cursor` until you reach a response where:
-
-* `next_cursor` is `null` or not present
-* `has_more` is `false`
-* Fewer than `page_size` movies are returned
+cursor (optional, default: 0)
+  Type: string
+  Enter value: 2
 
+----
 
-== Step 3: Test with Different Genres
+The response should contain a different page number, next cursor and list of movies.
 
-Try different genres to see how pagination behaves:
+[source,json]
+.Paginated Response
+----
+{
+  "genre": "Action",
+  "movies": [
+    {
+      "title": "2 Fast 2 Furious (Fast and the Furious 2, The)",
+      "released": "2003-06-06",
+      "rating": 5.8
+    },
+    {
+      "title": "2 Guns",
+      "released": "2013-08-02",
+      "rating": 6.7
+    }
+  ],
+  "next_cursor": 6,
+  "page": 3,
+  "page_size": 2,
+  "has_more": true
+}
+----
 
-* `"Comedy"` - Might have many pages
-* `"Sci-Fi"` - Moderate number of pages
-* `"Documentary"` - Might fit in a single page
 
-Notice how some genres have more movies than others!
+Experiment with different genres, for example [copy]#Comedy#, [copy]#Sci-Fi#, or [copy]#Documentary#, and change the [copy]#page_size# to see how it affects the results.
 
 
 read::I have pagination![]
 
+// TODO: Update this to add a COUNT {} subquery for the total?  Nice use of degree counts...
 
 [.summary]
 == Summary

asciidoc/courses/genai-mcp-build-custom-tools-python/modules/2-database-features/lessons/10c-paginated-tool/lesson.adoc

@@ -120,7 +120,7 @@ Create a `graph_statistics` tool function that uses `ctx.request_context.lifespa
 [source,python]
 .server/main.py
 ----
-include::{repository-raw}/main/solutions/2c-add-neo4j-connection/main.py[tag=tool]
+include::{repository-raw}/main/solutions/2c-add-neo4j-connection/main.py[tag=graph_statistics]
 ----
 
 [TIP]
@@ -129,7 +129,7 @@ include::{repository-raw}/main/solutions/2c-add-neo4j-connection/main.py[tag=too
 The `database_` parameter is used to specify the database to execute the query on.
 Any named arguments that do not end with an underscore will be passed as parameters to the Cypher query.
 
-You can link:/courses/drivers-python/[learn more about the Driverin the Using Neo4j with Python course^].
+You can link:/courses/drivers-python/[learn more about the Driver in the Using Neo4j with Python course^].
 ====