Merge pull request #60 from chrisreddington/instruction-updates

Instruction updates

Author: chrisreddington

.github/copilot-instructions.md

@@ -13,9 +13,9 @@ This is a crowdfunding platform for games with a developer theme. The applicatio
 - When adding new functionality, make sure you update the README
 - Make sure all guidance in the Copilot Instructions file is updated with any relevant changes, including to project structure and scripts, and programming guidance
 
-### Global language guidance
+### Code formatting requirements
 
-- Use type hints for function parameters and return values for all languages which support them
+- When writing Python, you must use type hints for return values and function parameters.
 
 ### Python and Flask Patterns
 

.github/instructions/flask-endpoint.instructions.md

@@ -7,15 +7,15 @@
 - All endpoints require tests
     - Use the `unittest` module for testing
     - All tests must pass
-    - A script is provided to run tests at `scripts/run-server-tests.sh`
+    - [A script is provided to run tests](../../scripts/run-server-tests.sh)
 
 ## Project notes
 
 - The Python virtual environment is located in the root of the project in a **venv** folder
-- Register all blueprints in `server/app.py`
-- Use the [test instructions](.github/instructions/python-tests.instructions.md) when creating tests
+- Register all blueprints in [the app entrypoint](../../server/app.py)
+- Use the [test instructions](./python-tests.instructions.md) when creating tests
 
 ## Prototype files
 
-- [Endpoint prototype](server/routes/games.py)
-- [Tests prototype](server/tests/test_games.py)
+- [Endpoint prototype](../../server/routes/games.py)
+- [Tests prototype](../../server/tests/test_games.py)

.gitignore

@@ -66,3 +66,6 @@ bld/
 msbuild.log
 msbuild.err
 msbuild.wrn
+
+# SQLite
+*.db

.vscode/mcp.json

@@ -1,26 +1,8 @@
 {
-    "inputs": [
-        {
-            "type": "promptString",
-            "id": "github_token",
-            "description": "GitHub Personal Access Token",
-            "password": true
-        }
-    ],
-    "servers": {
-        "github": {
-            "command": "docker",
-            "args": [
-                "run",
-                "-i",
-                "--rm",
-                "-e",
-                "GITHUB_PERSONAL_ACCESS_TOKEN",
-                "ghcr.io/github/github-mcp-server"
-            ],
-            "env": {
-                "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
-            }
-        }
+  "servers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/"
     }
+  }
 }

docs/0-prereqs.md

@@ -14,11 +14,11 @@ To create a copy of the repository for the code you'll create an instance from t
 > [!IMPORTANT]
 > If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors for naming the repository.
 
-3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to either GitHub Copilot Pro+ or GitHub Copilot Enterprise.
+3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to Copilot coding agent and can assign issues to Copilot.
 
     ![Input the repository template settings](images/repository-template-settings.png)
 
-4. Make a note of the repository path you created (`organization-or-user-name/repository-name`), as you will be referring to this later in the lab.
+4. Make a note of the repository path you created (**organization-or-user-name/repository-name**), as you will be referring to this later in the lab.
 
 ## Creating a codespace
 

docs/1-copilot-coding-agent.md

@@ -34,7 +34,7 @@ As a result, we want to [be mindful about how we approach assigning tasks to Cop
 
 Creating code, regardless of who's involved, typically requires a specific environment and some setup scripts to be run to ensure everything is in a good state. This holds true when assigning tasks to Copilot, which is performing tasks in a similar fashion to a SWE.
 
-[Copilot coding agent supports a special workflow][setup-workflow], set in the `.github/workflows/copilot-setup-steps.yml` file, to run before it gets to work. This enables it to have access to the required development tools and dependencies. We pre-configured this ahead of the lab to help the lab flow and allow this learning opportunity. It makes sure that Copilot had access to Python, Node.JS, and the required dependencies for the client and server:
+[Copilot coding agent supports a special workflow][setup-workflow], set in the **.github/workflows/copilot-setup-steps.yml** file, to run before it gets to work. This enables it to have access to the required development tools and dependencies. We pre-configured this ahead of the lab to help the lab flow and allow this learning opportunity. It makes sure that Copilot had access to Python, Node.JS, and the required dependencies for the client and server:
 
 ```yaml
 name: "Copilot Setup Steps"
@@ -79,8 +79,8 @@ jobs:
 
 It looks like any other GitHub workflow file, but it has a few key points:
 
-- It contains a single job called `copilot-setup-steps`. This job is executed in GitHub Actions before Copilot starts working on the pull request.
-- We've also added a `workflow_dispatch` trigger, which allows you to run the workflow manually from the Actions tab of your repository. This is useful for testing that the workflow runs successfully instead of waiting for Copilot to run it.
+- It contains a single job called **copilot-setup-steps**. This job is executed in GitHub Actions before Copilot starts working on the pull request.
+- We've also added a **workflow_dispatch** trigger, which allows you to run the workflow manually from the Actions tab of your repository. This is useful for testing that the workflow runs successfully instead of waiting for Copilot to run it.
 
 ## Improving code documentation
 
@@ -109,13 +109,17 @@ While every developer and organization understands the importance of documentati
 
 11. Select the **Pull Requests** tab.
 12. Open the newly generated issue, which will be titled something similar to **[WIP]: Code lacks documentation**.
-13. Notice how Copilot has created a todo list.
+13. After a few minutes, you should see that Copilot has created a todo list.
 14. Review the list and the tasks it's going to complete.
 15.  Scroll down the pull request timeline, and you should see an update that Copilot has started working on the issue.
 16.  Select the **View session** button.
 
   ![Copilot session view](images/ex4-view-session.png)
 
+
+> [!IMPORTANT]
+> You may need to refresh the window to see the updated indicator.
+
 17. Notice that you can scroll through the live session, and how Copilot is solving the problem. That includes exploring the code and understanding the state, how Copilot pauses to think and decide on the appropriate plan and also creating code.
 
 This will likely take several minutes. One of the primary goals of Copilot coding agent is to allow it to perform tasks asynchronously, freeing us to focus on other tasks. We're going to take advantage of that very feature by both assigning another task to Copilot coding agent, then turning our attention to writing some code to add features to our application.
@@ -180,7 +184,7 @@ You explored the these concepts:
 - the importance of clearly scoped issues.
 - assigning issues to Copilot.
 
-With coding agent working diligently in the background, we can now turn our attention to our next lesson, [using MCP servers to interact with external services][next-lesson].
+With coding agent working diligently in the background, we can now turn our attention to our next lesson, [using MCP servers to interact with external services][next-lesson]. [Copilot coding agent can also use MCP servers][coding-agent-mcp], but we're going to switch back to our Codespace and try use MCP with Copilot agent mode.
 
 ## Resources
 
@@ -194,6 +198,7 @@ With coding agent working diligently in the background, we can now turn our atte
 |:--|--:|
 
 [coding-agent-overview]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot#overview-of-copilot-coding-agent
+[coding-agent-mcp]: https://docs.github.com/en/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp
 [assign-issue]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/using-copilot-to-work-on-an-issue
 [setup-workflow]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#pre-installing-dependencies-in-github-copilots-environment
 [copilot-agents]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot

docs/2-mcp.md

@@ -83,7 +83,7 @@ Once you have the extension installed, you may need to authenticate with your Gi
     ![Example of selecting the Claude 3.5 Sonnet model](images/copilot-agent-mode-model.png)
 
 > [!IMPORTANT]
-> The authors of this lab are not indicating a preference towards one model or another. When building this lab, we used Claude 3.5, and as such are including that in the instructions. The hope is the code suggestions you receive will be relatively consistent to ensure a good experience. However, because LLMs are probabilistic, you may notice the suggestions received differ from what is indicated in the lab. This is perfectly normal and expected.
+> The authors of this lab are not indicating a preference towards one model or another. When building this lab, we used Claude 3.5 Sonnet, and as such are including that in the instructions. The hope is the code suggestions you receive will be relatively consistent to ensure a good experience. However, because LLMs are probabilistic, you may notice the suggestions received differ from what is indicated in the lab. This is perfectly normal and expected.
 
 8. The chat pane should update to indicate that you are now in agent mode. You should see a tools icon, showing that we can configure tools for GitHub Copilot to use.
 
@@ -100,74 +100,50 @@ The **.vscode/mcp.json** file is used to configure the MCP servers that are avai
 
     ```json
     {
-        "inputs": [
-            {
-                "type": "promptString",
-                "id": "github_token",
-                "description": "GitHub Personal Access Token",
-                "password": true
-            }
-        ],
         "servers": {
             "github": {
-                "command": "docker",
-                "args": [
-                    "run",
-                    "-i",
-                    "--rm",
-                    "-e",
-                    "GITHUB_PERSONAL_ACCESS_TOKEN",
-                    "ghcr.io/github/github-mcp-server"
-                ],
-                "env": {
-                    "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
-                }
+            "type": "http",
+            "url": "https://api.githubcopilot.com/mcp/"
             }
         }
     }
     ```
 
-The `inputs` section defines the inputs that the MCP server will require. In this case, we are asking for a GitHub Personal Access Token, which is required to authenticate with the GitHub API. The `password` field is set to `true`, which means that the input will be masked when you enter it.
-
-> [!IMPORTANT]
-> Make sure that you do not share your GitHub Personal Access Token with anyone, as it provides access to your GitHub account and repositories. Treat it like a password and keep it secure. That means you should not check it into source control or share it with anyone else.
->
-> Because it is a sensitive password, **DO NOT** paste it into the **mcp.json** file, is an artifact of the source code. Published tokens is the leading cause of security breaches. Instead, you'll securely add it to your codespace in a later step.
+This configuration provides GitHub Copilot access to several additional tools so that it can interact with GitHub repositories, issues, pull requests, and more. This particular configuration uses the [remote GitHub MCP server][remote-github-mcp-server]. By using this approach, we don't need to worry about running the MCP server locally (and the associated management, like keeping it up to date), and we can authenticate to the remote server using OAuth 2.0 instead of a personal access token (PAT).
 
-The `servers` section defines the MCP server that you want to use. In this case, we are using the GitHub MCP server, which is run in a Docker container. The `command` field specifies the command to run the MCP server, and the `args` field specifies the arguments to pass to the command. The `env` field specifies the environment variables to set when running the MCP server. The `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable is set to the value of the `github_token` input, which is provided by the user when prompted.
+The MCP server configuration is defined in the **servers** section of the **mcp.json** file. Each MCP server is defined by a unique name (in this case, github) and its type (in this case, **http**). When using local MCP servers, the type may be **stdio** and have a **command** and **args** field to specify how to start the MCP server. You can find out more about the configuration format in the [VS Code documentation][vscode-mcp-config]. In some configurations (not for the remote GitHub MCP server with OAuth), you may also see an **inputs** section. This defines any inputs (like sensitive tokens) that the MCP server may require. You can read more about the configuration properties in the [VS Code documentation][vscode-mcp-config]
 
-## Obtain the token
+To utilize an MCP server it needs to be "started". This will allow GitHub Copilot to communicate with the server and perform the tasks you request.
 
-In order to interact with GitHub via the MCP server you'll need to have a token. This can either be done by [creating a personal access token (PAT)][github-pat-docs], or (as in our case) using the GitHub token from the codespace. Let's obtain the GitHub token.
+1. Inside VS Code, open **.vscode/mcp.json**.
+2. To start the GitHub MCP server, select **Start** above the GitHub server.
 
-1. Open the terminal in your Codespace by selecting <kbd>Ctl</kbd>+<kbd>\`</kbd>.
-2. Run the following command to print the value of the GITHUB_TOKEN environment variable:
+    ![The start button above the GitHub MCP server entry](images/ex2-start-mcp.png)
 
-    ```bash
-    echo $GITHUB_TOKEN
-    ```
+3. You should see a popup asking you to authenticate to GitHub.
 
-3. Highlight the token and copy it to the clipboard.
+    ![A popup showing that the GitHub MCP server wants to authenticate to GitHub](images/ex2-mcp-auth-popup.png)
 
-## Start the MCP server
+4. Select **Continue** on the user account that you're using for this lab.
 
-To utilize an MCP server it needs to be "started". This will allow GitHub Copilot to communicate with the server and perform the tasks you request.
+    ![A popup showing the user account selection for GitHub authentication](images/ex2-mcp-select-account.png)
 
-1. Inside VS Code, open **.vscode/mcp.json**.
-2. To start the GitHub MCP server, select **Start** above the GitHub server.
-3. You should see a prompt asking for the GitHub personal access token.
-4. Paste the token you copied previously.
+5. If the page appears, select **Authorize visual-studio-code** to allow the GitHub MCP server to login as your selected user account. Once complete, the page should say "You can now close the window.".
 
-    ![Example of the start button and the prompt asking for the GitHub personal access token](images/copilot-github-mcp-token-prompt.png)
+    ![A popup showing the authorization for visual-studio-code app](images/ex2-mcp-auth-vscode.png)
 
-> [!IMPORTANT]
-> Do not share your PAT with anyone, as it provides access to your GitHub account and repositories. Treat it like a password and keep it secure. That includes not checking it into source control. **Do not paste it directly into the .vscode/mcp.json file.**
+6. After navigating back to the GitHub Codespace, you should see that the GitHub MCP server has started. You can check this in two places:
+    - The line in **.vscode/mcp.json** which previously said start. It should now present several options, and show a number of tools available. 
+    - Select the tools icon in the Copilot Chat pane to see the tools available. Scroll down the list that appears at the top of the screen, and you should see a list of tools from the GitHub MCP server.
 
-5. The GitHub MCP server should start up, and you should now see the number of tools available in the Copilot Chat window increase from 0. This indicates that the AI agent is now able to access the GitHub MCP server and perform actions on your behalf.
+    ![Example of the MCP server started with tools available](images/ex2-mcp-server-started.png)
 
-    ![Example of the Copilot Chat Pane showing tools available](images/copilot-agent-mode-mcp-tools.png)
+That's it! You can now use Copilot Chat in agent mode to create issues, manage pull requests, and more.
 
-6. You can select the tools icon to see the list of available tools that the GitHub MCP server provides. This includes tools for creating and managing repositories, issues, pull requests, and more.
+> [!IMPORTANT]
+> If you have any issues with this MCP server configuration, there are alternate configuration options in the  [GitHub MCP server][github-mcp-server] repository using local or remote MCP. If you opt for a configuration that requires authentication via a GitHub Personal Access Token (PAT), make sure that you do not share it with anyone. Treat it like a password and keep it secure. That means you should not check it into source control or share it with anyone else.
+>
+> Because it is a sensitive password, **DO NOT** paste it into the **mcp.json** file. Instead use the **inputs** property to pass the token as an input variable. Published tokens is one of the leading causes of security breaches.
 
 ## Creating a backlog of tasks
 
@@ -267,3 +243,5 @@ Notice that the setup process is similar to the GitHub MCP server, but you do no
 [vscode-extensions]: https://code.visualstudio.com/docs/configure/extensions/extension-marketplace
 [copilot-chat-extension]: https://marketplace.visualstudio.com/items?itemName=GitHub.copilot
 [github-pat-docs]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token
+[remote-github-mcp-server]: https://github.blog/changelog/2025-06-12-remote-github-mcp-server-is-now-available-in-public-preview/
+[vscode-mcp-config]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_configuration-format