Skip to content

Conversation

Jahteo
Copy link

@Jahteo Jahteo commented Oct 8, 2025

Initial recommended changes, including minor discussion comments that should be implemented or removed.
Big changes are:

  • Reorganizes steps so learner can simply go from top to bottom, instead of back and forth. Plus 2 of the 3 Common Setup Steps were only used in Local Setup which was confusing.
    • Exception: troubleshooting steps are still at the bottom
  • adds Docker troubleshooting steps discussed in slack\

- ✅ Isolated from your host system

## Local Setup
### Local Setup
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did you look at this rendered? H2s being underlined have a nice visual distinction isolating their content. These core "setup" sections should be h2s to make their content very clear where it is.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's more important to be explicit that the ### DevContainer Setup and ### Local Setup are both options under the ## Setup Dev Environment versus both being steps that need to be followed. If they're H3's, a learner can look at the outline and understand the high level page structure as:

  • Setup Visual Studio Code
  • Setup Dev Environment
  • Verifying Setup
  • Troubleshooting
  • Next Steps
    Since we haven't decided if this will be in the academy, read from github, or cloned locally, it feels weird to break semantic html patterns just for styling.

That said, I do agree the raw file and preview both needed visual distinction, and personally kept wanting to have AI add an emoji to each H2 & H3. So I get it if you decide to make them H2, we'd just want an inline way to be explicit that they're not both required steps.
It could be by making the headers something like "## Recommended DevContainer Setup" & "## Alternative Local Setup" and removing the "## Setup Dev Environment"

Comment on lines 73 to 75
- Make server files executable
- Configure VS Code extensions
- Set up port forwarding for MCP servers
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to add instructions or solution notes on how a learner can verify they setup correctly?

Comment on lines 187 to 197
#### **Steps:**

**Download and install:**

- Go to [code.visualstudio.com](https://code.visualstudio.com/)
- Download the installer for your operating system
- Follow the installation instructions
1. **Clone the repository**:
<!-- todo: minor discussion: these "clone" instructions should match the "clone" instructions in the DevContainer setup. There, it clones from inside VSCode terminal with different commands, this assumes use of a generic terminal. Maybe use the instructions for inside vscode, so there's no one fighting with `code .` not working? Those these are simpler and what most devs would do 🤷 -->

**Required VS Code Extension for DevContainer Setup:**
```bash
git clone https://github.com/bitovi/mcp-training.git
cd mcp-training
```

- **Dev Containers** - [marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
Then open the folder in VS Code: `code .`
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[minor discussion]
These "clone" instructions don't match the "clone" instructions in the DevContainer setup. There, it clones from inside VSCode terminal with different commands, here it assumes use of a generic terminal.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants