diff --git a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/1-overview.md b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/1-overview.md index c3a7539f8f..8d70d6472a 100644 --- a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/1-overview.md +++ b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/1-overview.md @@ -1,5 +1,5 @@ --- -title: Simplify Arm migration with the Docker MCP ToolKit and Arm MCP Server +title: Simplify Arm migration with the Docker MCP Toolkit and Arm MCP Server weight: 2 ### FIXED, DO NOT MODIFY @@ -28,8 +28,8 @@ When architecture-specific optimizations are present, migration may involve: - Identifying x86-specific intrinsics or assembly - Updating compiler flags and build configurations - Mapping AVX2 operations to appropriate NEON equivalents -- Rewriting vectorized code and adjusting loop structures. -- Updating Dockerfiles, base images, and compiler flags. +- Rewriting vectorized code and adjusting loop structures +- Updating Dockerfiles, base images, and compiler flags - Validating correctness and performance on Arm systems These steps are well understood, but they can require careful review across code, build scripts, and container configurations. @@ -38,42 +38,51 @@ These steps are well understood, but they can require careful review across code The Docker MCP Toolkit is a management interface in Docker Desktop that lets you discover, configure, and run containerized MCP (Model Context Protocol) servers. It connects these servers to AI coding assistants through a unified gateway. -For Arm migration, three MCP servers work together: +## MCP servers for Arm migration + +Three MCP servers work together to support the migration workflow: + +**Arm MCP Server** + +Provides migration-focused tools: +- `migrate_ease_scan` detects x86-specific code and compiler flags +- `check_image` and `skopeo` verify container architecture support +- `knowledge_base_search` accesses learning resources, Arm intrinsics, and software version compatibility +- `mca` performs microarchitectural performance analysis + +**GitHub MCP Server** + +Enables Git repository operations including creating pull requests, managing branches, and committing changes. + +**Sequential Thinking MCP Server** + +Helps the AI assistant break down complex migration decisions into logical steps. -- **Arm MCP Server**: - Provides migration-focused tools, including: - - `migrate_ease_scan` for detecting x86-specific code and compiler flags - - `check_image` and `skopeo` for verifying container architecture support - - `knowledge_base_search` for a knowledge base of learning resources, Arm intrinsics, and software version compatibility - - `mca` for microarchitectural performance analysis - -- **GitHub MCP Server**: Enables Git repository operations including creating pull requests, managing branches, and committing changes. -- -- **Sequential Thinking MCP Server**: Helps the AI assistant break down complex migration decisions into logical steps. ## How AI-assisted migration works When connected to the Docker MCP Toolkit, an AI coding assistant like GitHub Copilot can coordinate a structured migration workflow: -1. Verify whether container base images support `linux/arm64` using `check_image` or `skopeo`. -2. Scan the codebase with `migrate_ease_scan` to identify AVX2 intrinsics, x86-specific flags, and other portability considerations. -3. Use `knowledge_base_search` to find appropriate Arm SIMD equivalents for every x86 intrinsic. -4. Refactor the code with architecture-specific accuracy. -5. Update Dockerfiles and build configurations for Arm comptibility. -6. Create a pull request with the proposed changes using the GitHub MCP Server. +- Verify whether container base images support `linux/arm64` using `check_image` or `skopeo` +- Scan the codebase with `migrate_ease_scan` to identify AVX2 intrinsics, x86-specific flags, and other portability considerations +- Use `knowledge_base_search` to find appropriate Arm SIMD equivalents for every x86 intrinsic +- Refactor the code with architecture-specific accuracy +- Update Dockerfiles and build configurations for Arm compatibility +- Create a pull request with the proposed changes using the GitHub MCP Server -## What you will build in this Learning Path +## The demo application -In this Learning Path, you will migrate a real-world legacy application - a matrix multiplication benchmark written with AVX2 intrinsics for x86 - to Arm64 using GitHub Copilot and Docker MCP Toolkit. +This Learning Path uses a real-world example: a matrix multiplication benchmark written in C++ with AVX2 intrinsics for x86. You'll migrate it to Arm64 using the AI-assisted workflow described above. The demo repository is available at [github.com/JoeStech/docker-blog-arm-migration](https://github.com/JoeStech/docker-blog-arm-migration). -You will: +By the end of this Learning Path, you'll have a working Arm64 container with NEON-optimized code and an automated pull request containing all migration changes. + +## What you've learned and what's next -1. Set up Docker MCP Toolkit with the Arm, GitHub, and Sequential Thinking MCP servers. -2. Connect VS Code with GitHub Copilot to the MCP Gateway. -3. Analyze the x86-specific portions of the codebase. -4. Use AI-assisted MCP workflows to update intrinsics and container configuration. -5. Review and validate the pull request generated by the AI agent. +You now understand: +- Why Arm migration requires more than rebuilding containers when architecture-specific code is present +- How the Docker MCP Toolkit connects AI assistants to specialized migration tools +- The structured workflow that GitHub Copilot uses to automate migration tasks -In the next section, you will install and configure the Docker MCP Toolkit. +Next, you'll install and configure the Docker MCP Toolkit with the three required MCP servers. diff --git a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/2-setup.md b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/2-setup.md index 995777b873..a05acdbaa7 100644 --- a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/2-setup.md +++ b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/2-setup.md @@ -10,23 +10,23 @@ layout: learningpathall Make sure the following tools are installed: -- Docker Desktop 4.59 or later. -- VS Code with the GitHub Copilot extension. -- A GitHub account with a Personal Access Token(PAT) that allows repository access. -- A machine with at least 8 GB RAM (16 GB recommended). +- Docker Desktop 4.59 or later +- VS Code with the GitHub Copilot extension +- A GitHub account with a Personal Access Token (PAT) that allows repository access +- A machine with at least 8 GB RAM (16 GB recommended) -You will use Docker Desktop to host MCP servers locally, and VS Code with GitHub Copilot to invoke those servers through the MCP Gateway. +You'll use Docker Desktop to host MCP servers locally, and VS Code with GitHub Copilot to invoke those servers through the MCP Gateway. ## Enable the Docker MCP Toolkit The MCP Toolkit allows Docker Desktop to run and manage MCP (Model Context Protocol) servers, which expose structured tools that AI assistants can call. -1. Open Docker Desktop. -2. Go to **Settings** > **Beta features**. -3. Toggle **Enable Docker MCP Toolkit** on. -4. Click **Apply**. +- Open Docker Desktop +- Go to **Settings** > **Beta features** +- Toggle **Enable Docker MCP Toolkit** on +- Select **Apply** -After a few seconds, the **MCP Toolkit** tab appears in the left sidebar. +The **MCP Toolkit** tab appears in the left sidebar. ## Add the required MCP servers @@ -55,9 +55,9 @@ Search for **GitHub Official** in the catalog and add the [GitHub MCP Server](ht Configure authentication: -1. Select the GitHub Official server. -2. Choose **Personal Access Token** as the authentication method. -3. Enter your GitHub token from **GitHub Settings** > **Developer Settings** > **Personal access tokens**. +- Select the GitHub Official server +- Choose **Personal Access Token** as the authentication method +- Enter your GitHub token from **GitHub Settings** > **Developer Settings** > **Personal access tokens** This server lets GitHub Copilot create pull requests, manage issues, and commit changes directly to your repositories. @@ -69,10 +69,10 @@ No configuration is needed. This server helps GitHub Copilot break down complex ## Connect VS Code to the MCP Gateway -1. In Docker Desktop, go to **MCP Toolkit** > **Clients** tab. -2. Scroll to **Visual Studio Code** and click **Connect**. -3. Open VS Code and click the **Extensions** icon in the left toolbar. -4. Find **MCP_DOCKER**, click the gear icon, and click **Start Server**. +- In Docker Desktop, go to **MCP Toolkit** > **Clients** tab +- Scroll to **Visual Studio Code** and select **Connect** +- Open VS Code and select the **Extensions** icon in the left toolbar +- Find **MCP_DOCKER**, select the gear icon, and select **Start Server** ## Verify the connection @@ -82,7 +82,7 @@ Open GitHub Copilot Chat in VS Code and ask: What Arm migration tools do you have access to? ``` -If the setup is correct, Copilot will list tools from: +If the setup is correct, Copilot lists tools from: - Arm MCP Server - GitHub MCP Server @@ -90,6 +90,12 @@ If the setup is correct, Copilot will list tools from: This confirms that tool invocation through the MCP Gateway is working. -Your environment is now ready for AI-assisted migration. +## What you've learned and what's next -In the next section, you will examine the demo application and identify the architecture-specific elements that require adaptation for Arm64. +You have: +- Enabled the Docker MCP Toolkit in Docker Desktop +- Configured three MCP servers: Arm MCP Server, GitHub MCP Server, and Sequential Thinking MCP Server +- Connected VS Code with GitHub Copilot to the MCP Gateway +- Verified that Copilot can access migration tools + +Next, you'll examine the demo application to identify x86-specific code that needs adaptation for Arm64. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/3-understand-the-demo.md b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/3-understand-the-demo.md index 403ac49869..7e18d7c2f3 100644 --- a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/3-understand-the-demo.md +++ b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/3-understand-the-demo.md @@ -1,5 +1,5 @@ --- -title: Understand the legacy x86 demo application +title: Examine x86 AVX2 intrinsics in the demo application weight: 4 ### FIXED, DO NOT MODIFY @@ -77,15 +77,15 @@ To run this code on Arm, several adjustments are required: 2. **Intrinsic mapping**: Each AVX2 intrinsic must be mapped to an Arm equivalent. For example: - - `_mm256_setzero_pd()` creates a 256-bit zero vector of four doubles(Arm NEON is 128-bit). + - `_mm256_setzero_pd()` creates a 256-bit zero vector of four doubles. Arm NEON uses 128-bit registers. - `_mm256_loadu_pd()` loads 4 doubles at once (NEON loads 2 with `vld1q_f64`). - `_mm256_add_pd()` and `_mm256_mul_pd()` are 256-bit operations (NEON uses 128-bit equivalents). - `_mm256_extractf128_pd()` extracts the high 128 bits (not needed on NEON). -4. **Vector width differences**: AVX2 operates on 256-bit registers (four double-precision values). NEON operates on 128-bit registers (two double-precision values). This affects: - - Loop stride - - Accumulation logic - - Horizontal reduction patterns +3. **Vector width differences**: AVX2 operates on 256-bit registers (four double-precision values). NEON operates on 128-bit registers (two double-precision values). This affects: + - Loop stride + - Accumulation logic + - Horizontal reduction patterns 4. **Horizontal reduction logic**: The AVX2 pattern: @@ -99,5 +99,11 @@ is specific to x86 register structure. On Arm, reduction is implemented using NE On newer Arm platforms supporting SVE or SVE2 (for example Neoverse V1/V2 based platforms), wider vector lengths may be available. SVE uses a vector-length-agnostic (VLA) model, which differs from fixed-width AVX2 and NEON programming. The Arm MCP Server knowledge base can help determine the appropriate approach for your target platform. {{% /notice %}} -In the next section, you will use GitHub Copilot together with the Docker MCP Toolkit to analyze these elements automatically and generate Arm-compatible updates. -In the next section, you will use GitHub Copilot with the Docker MCP Toolkit to automate the entire migration. +## What you've learned and what's next + +You have: +- Examined a legacy x86 application with AVX2 intrinsics +- Identified the architecture-specific elements: base image, compiler flags, SIMD headers, and intrinsic functions +- Understood how vector width differences between AVX2 (256-bit) and NEON (128-bit) affect the migration approach + +Next, you'll use GitHub Copilot with the Docker MCP Toolkit to automate the migration process. diff --git a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/4-run-migration.md b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/4-run-migration.md index ec88e8439a..1c77d14169 100644 --- a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/4-run-migration.md +++ b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/4-run-migration.md @@ -1,5 +1,5 @@ --- -title: Run the AI-driven Arm migration +title: Automate x86 to Arm migration with GitHub Copilot weight: 5 ### FIXED, DO NOT MODIFY @@ -15,7 +15,7 @@ cd docker-blog-arm-migration code . ``` -Make sure the MCP_DOCKER server is running in VS Code ( Use **Extensions** > **MCP_DOCKER** > **Start Server** if needed). +Make sure the MCP_DOCKER server is running in VS Code (use **Extensions** > **MCP_DOCKER** > **Start Server** if needed). This allows GitHub Copilot to invoke the configured MCP servers through the MCP Gateway. @@ -136,14 +136,22 @@ You can see an example PR at [github.com/JoeStech/docker-blog-arm-migration/pull After migration, you should see: **Dockerfile updates**: -- Replaced `centos:6` with `ubuntu:22.04`. -- Added `TARGETARCH` for multi-architecture builds. -- Changed `-mavx2` to `-march=armv8-a+simd` for Arm builds. +- Replaced `centos:6` with `ubuntu:22.04` +- Added `TARGETARCH` for multi-architecture builds +- Changed `-mavx2` to `-march=armv8-a+simd` for Arm builds **Source code updates**: -- Added `#ifdef __aarch64__` architecture guards. -- Replaced all `_mm256_*` AVX2 intrinsics with NEON equivalents (`vld1q_f64`, `vaddq_f64`, `vmulq_f64`). -- Adjusted loop strides from 4 (AVX2) to 2 (NEON). -- Rewrote horizontal reduction using NEON pair-wise addition. +- Added `#ifdef __aarch64__` architecture guards +- Replaced all `_mm256_*` AVX2 intrinsics with NEON equivalents (`vld1q_f64`, `vaddq_f64`, `vmulq_f64`) +- Adjusted loop strides from 4 (AVX2) to 2 (NEON) +- Rewrote horizontal reduction using NEON pair-wise addition -In the next section, you will build, test, and validate the migrated application on Arm. +## What you've learned and what's next + +You have: +- Provided migration instructions to GitHub Copilot +- Observed the AI-driven workflow using MCP server tools +- Reviewed the automated changes: container image updates, intrinsic mapping, and compiler flag adjustments +- Seen how the GitHub MCP Server creates a pull request with all migration changes + +Next, you'll build and validate the migrated application on Arm64 hardware. diff --git a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/5-validate-and-next-steps.md b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/5-validate-and-next-steps.md index ad5aec5c23..52dbb54c99 100644 --- a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/5-validate-and-next-steps.md +++ b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/5-validate-and-next-steps.md @@ -1,5 +1,5 @@ --- -title: Validate the migration and explore further +title: Validate the Arm64 migration and test containers weight: 6 ### FIXED, DO NOT MODIFY @@ -66,10 +66,10 @@ This produces a multi-architecture manifest that allows Docker to automatically AI-assisted workflows streamline repetitive discovery and mapping tasks, particularly when architecture-specific intrinsics are involved. -| Approach | Time | -|----------|------| -| Manual migration (install tools, research intrinsics, rewrite code, debug, document) | Several hours, depending on complexity | -| Docker MCP Toolkit + GitHub Copilot (prompt, review, merge) | Significantly reduced manual effort | +| Approach | Effort | +|----------|--------| +| Manual migration (install tools, research intrinsics, rewrite code, debug, document) | Several hours to days, depending on complexity | +| Docker MCP Toolkit + GitHub Copilot (prompt, review, merge) | Reduced to minutes for initial migration, plus review time | Actual time savings depend on codebase size and complexity, but structured tool invocation reduces the need for manual documentation lookup and repetitive edits. @@ -117,14 +117,14 @@ The Docker MCP Toolkit and Arm MCP Server support more than the example migratio - **Knowledge base**: The `knowledge_base_search` tool covers all content from [learn.arm.com](https://learn.arm.com) Learning Paths, intrinsics documentation, and software compatibility information. - **Dynamic MCP**: AI agents can discover and add new MCP servers from the Docker MCP Catalog during a conversation without manual configuration. -## Summary +## What you've learned In this Learning Path, you: -1. Installed and configured the Docker MCP Toolkit with the Arm MCP Server, GitHub MCP Server, and Sequential Thinking MCP Server. -2. Connected VS Code with GitHub Copilot to the MCP Gateway. -3. Examined architecture-specific elements in a legacy x86 AVX2 application. -4. Used AI-assisted MCP tools to analyze, refactor, and update the codebase for Arm64. -5. Built and validated the migrated application on Arm64. +- Installed and configured the Docker MCP Toolkit with the Arm MCP Server, GitHub MCP Server, and Sequential Thinking MCP Server +- Connected VS Code with GitHub Copilot to the MCP Gateway +- Examined architecture-specific elements in a legacy x86 AVX2 application +- Used AI-assisted MCP tools to analyze, refactor, and update the codebase for Arm64 +- Built and validated the migrated application on Arm64 The Docker MCP Toolkit enables AI assistants to invoke structured migration tools inside the containerized Arm MCP server. This approach reduces manual lookup and repetitive refactoring work while keeping developers in control of review and validation. diff --git a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/_index.md b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/_index.md index 7237c418bd..9208107622 100644 --- a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/_index.md @@ -1,9 +1,5 @@ --- title: Automate x86 to Arm Migration with Docker MCP Toolkit, VS Code and GitHub Copilot - -draft: true -cascade: - draft: true description: Learn how to use the Docker MCP Toolkit with the Arm MCP Server and GitHub Copilot to automate container and code migration from x86 to Arm64. Through a hands-on example, migrate a legacy C++ application with AVX2 intrinsics to Arm NEON. @@ -44,10 +40,6 @@ operatingsystems: - macOS further_reading: - - resource: - title: "Automate x86 to Arm Migration with Docker MCP Toolkit, VS Code, and GitHub Copilot" - link: https://www.docker.com/blog/automate-arm-migration-docker-mcp-copilot/ - type: blog - resource: title: Docker MCP Toolkit Documentation link: https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/