Building GraphRAG Python MCP tools (#368)

* course structure, module 1

* add cursor rules for course content

* module 2 intro

* rework

* code review to 2c-add-neo4j-connection

* code review to 7-resources

* move core features to module 1, use context throughout examples

* update module 2, remove text to cypher challenge

* add illustration, banner, update flow

* add illustration, update summary, update flow

* restructure advanced features lesson

* Fix errors in qa tests

* update tests to enable a run for a single course

* switch to streamable-http to enable mcp inspector

* update connecting lesson

* switch order of code in 2c-add-neo4j-connection

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

* qa tests passing

Author: adam-cowley

.cursor/write-challenge-lesson.mdc

@@ -0,0 +1,131 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Write a Challenge lesson
+
+Write a practical challenge lesson that guides learners through implementing concepts they learned in previous theory lessons. The lesson should be hands-on, step-by-step, and focused on creating something functional. Use a encouraging but direct tone that assumes the learner has absorbed the theoretical concepts and is ready to apply them practically.
+
+## Constraints
+
+- Keep the lesson focused on one primary implementation goal
+- Provide specific, actionable steps with exact commands and code
+- Use simple, clear language with no motivational fluff
+- Include practical testing and verification steps
+- Ensure the challenge builds directly on previous lesson concepts
+- Make the outcome immediately testable and verifiable
+- Focus on getting something working rather than explaining theory
+- Use consistent naming and examples throughout
+- Form a checklist of instructions that users can follow step-by-step
+- All content should be written in AsciiDoc format
+- Use bullet point outlines from the lesson file to create hands-on challenges
+
+## Required Structure
+
+### 1. Challenge Introduction
+
+- Start with a short, succinct recap of the previous lesson (read the directory alphabetically to find the previous lesson content)
+- Follow with a single paragraph stating what the reader will do to complete the challenge
+- Use format: "In this challenge, you will [action] using [method/tool]"
+- Clear statement of the practical goal
+
+### 2. Challenge Goals
+
+- Numbered list (1-5 goals maximum) of specific, measurable outcomes
+- Each goal should be actionable and verifiable
+- Goals should build logically toward the final implementation
+
+### 3. Step-by-Step Instructions
+
+Break implementation into logical steps (typically 4-6 steps) forming a checklist of instructions:
+
+#### Step Structure:
+- **Step N: [Action-oriented title]** (use second-level headings like a to-do or checklist)
+- Brief explanation of what this step accomplishes
+- Exact commands to run (in code blocks)
+- Code to write (in code blocks with filenames)
+- Any important notes or explanations
+- Instructions should be concise and describe what the user should do
+
+#### Essential Steps to Include:
+- Project setup and initialization
+- Dependency installation
+- Core implementation (the main code)
+- Configuration and integration
+- Testing and verification
+
+### 4. Verification Section
+
+- Clear checklist of what should be working
+- Specific tests or examples to try
+- Expected outcomes or behaviors
+- Simple troubleshooting hints if needed
+
+### 5. Next Steps Section
+
+- Congratulatory statement acknowledging completion
+- Brief summary of what was accomplished
+- Connection to the bigger picture or learning objectives
+
+### 6. Experimentation Tips
+
+- Optional "[TIP] Experiment further" section
+- 3-4 specific suggestions for extending the implementation
+- Focus on variations or enhancements, not completely new concepts
+
+### 7. Summary Section
+
+- Use AsciiDoc format: `[.summary]` and `== Summary`
+- Provide a one-paragraph summary of the actions that the user has carried out
+- Can use bullet points with **bold key concepts** learned for more complex challenges
+- Brief description of each major accomplishment
+- Reference to the next lesson topic
+
+Example formats:
+```asciidoc
+[.summary]
+== Summary
+
+You can now install the `neo4j` library and connect to Neo4j by creating a new driver instance.
+
+In the next lesson, you will learn how to execute your first Cypher query.
+```
+
+Or for more complex challenges:
+```asciidoc
+[.summary]
+== Summary
+
+In this challenge, you demonstrated how to use the `neo4j` library to connect to Neo4j.
+```
+
+## Implementation Guidelines
+
+### Using Bullet Point Outlines:
+- If the lesson file contains bullet point outlines, use them to create hands-on challenges
+- Convert each bullet point into a concrete, actionable step
+- Maintain the logical flow and structure of the original outline
+- Transform abstract concepts into specific implementation tasks
+
+### Code and Commands:
+- Always provide exact, copy-pasteable code
+- Use consistent file names and project structure
+- Include command-line instructions with proper syntax
+- Specify which directory to run commands from
+
+### Testing:
+- Include real-world testing scenarios
+- Use actual tools and environments (VS Code, browsers, etc.)
+- Provide specific examples to test with
+- Make verification steps concrete and measurable
+
+### Tone:
+- Encouraging but matter-of-fact
+- Assume competence while providing clear guidance
+- Celebrate success without excessive enthusiasm
+- Focus on practical outcomes over learning theory
+
+## Instruction
+
+Write the final lesson content directly using AsciiDoc format. Do not include bullet points, notes, or meta-commentary. This is the learner-facing copy that guides them through the complete implementation challenge.

.cursor/write-lesson-summary.mdc

@@ -0,0 +1,40 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+Add a succinct bullet point summary of the information convered in the lesson to the summary section at the bottom of the page.
+
+Write the content in asciidoc, do not use markdown.
+
+Here is an example of a good summary:
+
+```asciidoc
+[.summary]
+== Summary 
+
+The Model Context Protocol (MCP) consists of several key elements:
+
+* **Servers** - Provide capabilities through tools, resources, and prompt templates in a client-server architecture
+* **Clients** - Manage one-to-one connections to servers and request available tools, resources, and prompt templates
+* **Hosts** - Applications (like Claude Desktop, Amazon Q, or Cursor) that maintain session state, manage clients, and decide which tools to use
+
+In the next lesson, you will learn how to install your first MCP server.
+
+```
+
+You can also provide a summary in paragraph form if many concepts aren't covered.
+
+```asciidoc
+[.summary]
+== Lesson Summary
+
+In this lesson you learned how to install the Neo4j Python Driver, create a Driver instance, verify connectivity to your database, and execute your first Cypher statement.
+
+For async applications, link:https://neo4j.com/docs/python-manual/current/concurrency/[use the `AsyncGraphDatabase` method].
+
+In the next lesson, you will take a quiz to test your knowledge of installing and creating a driver instance.
+
+```
+
+For instructions on next lesson, check the next file in the directory ordered alphabetically.  If that file exists, use the content of the file to write a short summary.  If the file is empty or you cannot find a file in the filesystem, feel free to suggest a next lesson and add a `// TODO:` comment above.  If the lesson is a challenge, use an assertive statement like "you will open a can of worms using the can of worms extraction methodology."

.cursor/write-theory-lesson.mdc

@@ -0,0 +1,53 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Write a theory lesson
+
+Write a short theory lesson that introduces one or two key concepts to a beginner. The lesson should be factual, direct, and based on consistent examples from movie recommendations. It should be written in a tone that is casual, friendly, and succinct. Avoid filler language or motivational fluff. Stick to useful, clear information.  Focus on where the content and subject will be useful for a developer or data scientist in their day to day lives.
+
+## Constraints
+
+- Keep the lesson under 5 minutes to read.
+- Only introduce 1–2 new concepts per lesson.
+- Use simple language, assume no prior knowledge.
+- All examples must relate to movie recommendation systems.
+- Use a consistent business-world analogy appropriate for developers or data scientists.
+- Do not mix metaphors or use unrelated analogies.
+- Do not include hands-on steps or exercises in this lesson.
+- Break up content by level 2 and level 3 headings.
+- You are describing something, not selling it.  Stick to facts, avoid hyperoble.  Only include information that is relevant.
+
+## Required Structure
+
+### 1. Introduction
+
+- One sentence recapping what has been learned previously where applicable.
+- One short paragraph explaining why this concept is relevant in the context of the course or previous lesson, using a business scenario from movie recommendations.
+
+### 2. Prior Knowledge
+
+- If applicable, briefly mention what was covered in the previous lesson in one sentence.
+
+### 3. Concept(s)
+
+For each concept:
+
+- Provide a clear, plain-language definition.
+- Use a consistent analogy from business, relevant to a developer or data scientist.
+- Give a concrete example from movie recommendations.
+- Include a sentence that someone might say aloud to explain the concept informally.
+- (Optional) Include a short description of a supporting visual.
+
+### 4. Practical Context
+
+- One sentence applying how the concept or concepts fit into a larger system, product, or workflow.
+
+### 5. Teaser
+
+- One sentence describing what the learner will do or build in the next lesson, phrased as a challenge.
+
+## Instruction
+
+Write the final lesson content directly. Do not include bullet points, notes, or meta-commentary. This is the learner-facing copy.

asciidoc/courses/genai-mcp-build-custom-tools-python/banner.png

@@ -1,7 +1,47 @@
 = Building GraphRAG Python MCP tools
-:categories: llms:99
+:usecase: recommendations
+:caption: Build your own GraphRAG MCP server with graph-backed tools and resources.
+:key-points: FastMCP server development, Neo4j driver lifecycle management, Context-aware tools with logging, Pagination for large datasets, Text-to-Cypher natural language queries
+:categories: llms:30, intermediate:20
+:duration: 2 hours
+:repository: neo4j-graphacademy/genai-mcp-build-custom-tools-python
+:status: active
 
-In this course, you will learn how to:
+This course follows on from the link:/courses/genai-mcp-neo4j-tools/[Developing with Neo4j MCP Tools course], which introduces the Model Context Protocol and key concepts like Servers, Clients and Tools.
 
-* Build your own MCP tools with Python.
-* Serve your MCP tools with the FastAPI MCP server.
+In this course, you will build on that knowledge to create your own MCP server using the link:https://github.com/modelcontextprotocol/python-sdk[MCP Python SDK^] and create server features that can be consumed by any MCP client.
+
+
+
+== Prerequisites
+
+This course assumes that you have are familiar with the basics of Generative AI and Large Language Models. If you are not, we recommend that you take the link:/courses/genai-fundamentals/[GenAI Fundamentals] and link:/courses/genai-mcp-neo4j-tools/[Developing with Neo4j MCP Tools] courses first.
+
+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].
+
+
+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.
+
+
+== Duration
+
+{duration}
+
+== What you will learn
+
+* How to build MCP servers with the MCP Python SDK and FastMCP
+* How to connect your server to Neo4j using lifespan management
+* 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 integrate MCP tools into development workflows
+* Advanced features: Sampling and Completions (optional)
+
+
+[.includes]
+== This course includes
+
+* [lessons]#14 lessons# across 3 modules (including setup)
+* [challenges]#7 hands-on challenges# with Neo4j
+* [quizes]#Quiz questions# to check your understanding