# MCP-Assisted Migration to Forge v3

Forge v3 introduces an AI-powered migration assistant via the SAIF MCP (Model Context Protocol) server that automates the migration process from Forge v2 to v3.

**The challenge:** Manual migration involves dozens of file edits across .NET projects, Terraform modules, and pipeline configurations—time-consuming and error-prone.

**The solution:** The SAIF MCP server provides Copilot with migration knowledge, automated file discovery, and step-by-step execution guidance, reducing migration time from hours to minutes.

[TOC]

---

## 📋 Overview

| Aspect            | Details                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------- |
| **Goal**          | Migrate a Forge v2 application to v3 using AI-assisted automation via the SAIF MCP server |
| **Prerequisites** | VS Code with Copilot, .NET 10 SDK, SAIF CLI 3.0+, Aspire 13.1+                            |
| **Time estimate** | ~30-45 minutes (vs 2-4 hours manual)                                                      |
| **Difficulty**    | Intermediate (requires understanding of git, pipelines, and basic troubleshooting)        |

---

## 🔧 Prerequisites

Before starting, ensure you have:

- ✅ **VS Code installed** with the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
- ✅ **.NET 10 SDK** — Download from [dotnet.microsoft.com/download/dotnet/10.0](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)
- ✅ **SAIF CLI 3.0+** — Verify with `saif --version`
- ✅ **Aspire 13.1+** — Verify with `aspire --version`
- ✅ **Repository access** — Clone permissions for your application repository
- ✅ **Azure DevOps access** — Permissions to create/delete pipelines

> 💡 **Tip:** If your SAIF CLI or Aspire versions are outdated, run `saif doctor fix --self` to update the CLI, then `saif doctor fix` to update Aspire and other tools, with a 20-second pause between runs to ensure all updates complete.

---

## 🚀 Instructions

> **Signposting:** This guide walks through (1) updating prerequisites, (2) initializing the MCP server, (3) running the AI-assisted migration, and (4) cleaning up old pipelines.

### Step 1: Update Prerequisites

Before starting the migration, ensure all tools are up to date.

```powershell
# Verify current versions
dotnet --version  # Should be 10.0.x
saif --version    # Should be 3.0.x
aspire --version  # Should be 13.1.x

# If outdated, update SAIF CLI and Aspire
saif doctor fix --self
Start-Sleep -Seconds 20
saif doctor fix
Start-Sleep -Seconds 20

# Verify updates
saif --version
aspire --version
```

**Expected result:** All version checks pass with minimum required versions.

> ⚠️ **Important:** Close all open terminals and VS Code instances after updating to ensure the new Aspire CLI path is loaded.

---

### Step 2: Initialize MCP Server

The MCP server connects GitHub Copilot to the Forge platform documentation and migration tools.

1. **Close all VS Code windows and terminals** to pick up the updated Aspire path
2. **Open VS Code** in your application repository root
3. **Open a new terminal** in VS Code (`Ctrl+` `)
4. **Initialize MCP configuration:**

```powershell
saif agent init
```

**Expected result:** A `.vscode/mcp.json` configuration file is created in your repository.

> 💡 **Tip:** The `mcp.json` file is ignored by git (in `.gitignore`) and specific to your local environment.

---

### Step 3: Run AI-Assisted Migration

Now you'll use Copilot's agent chat to execute the migration.

1. **Open Copilot Agent Chat** in VS Code:
   - Click the Copilot icon in the sidebar
   - Switch to the **Agent Chat** tab (not inline chat)

2. **Select the agent model:**
   - Choose **Claude Opus** or **Claude Sonnet** for best results
   - Opus has stronger reasoning for complex migrations; Sonnet is faster

3. **Invoke the migration prompt:**

```text
/mcp.forge.migrate-to-v3
```

**What happens next:**

- Copilot retrieves the [Forge v2 to v3 Migration Guide](forge-v2-to-v3.md)
- Creates a local copy in `docs/migration/forge-v2-to-v3.md` for progress tracking
- Establishes a todo list with 10 migration tasks
- Systematically executes each task:
  - Discovers files that need updates
  - Applies changes using multi-file edit operations
  - Runs `dotnet build` after each section
  - Updates progress checkboxes in the local migration doc
  - Marks todos complete before moving to the next task

> 💡 **Tip:** The agent will use `#runSubagent` to parallelize file discovery tasks, significantly speeding up the migration.

**Expected result:** Copilot progressively completes all 10 migration tasks, providing status updates after each section.

---

### Step 4: Review and Test Migration

After Copilot completes the migration, verify the changes.

1. **Review the changes** in git:

```powershell
git status
git diff
```

2. **Build the project:**

```powershell
dotnet clean
dotnet restore
dotnet build
```

3. **Run tests:**

```powershell
dotnet test
```

4. **Start the AppHost locally:**

```powershell
cd src/{YourApp}.AppHost
aspire run
```

**Expected result:** All builds succeed, tests pass, and the Aspire dashboard loads successfully.

---

### Step 5: Update Azure DevOps Pipelines

The final step is cleaning up old Okta-specific pipelines and creating the new unified auth pipelines.

> ⚠️ **Important:** Complete these steps in the Azure DevOps portal—they cannot be automated via the MCP server.

#### Delete Legacy Pipelines

Navigate to **Pipelines** in your Azure DevOps project and delete these pipelines:

- `{project-id}-okta-appauth-pr`
- `{project-id}-okta-appauth`
- `{project-id}-okta-userauth-pr`
- `{project-id}-okta-userauth`

**How to delete:**

1. Go to the pipeline in Azure DevOps
2. Click the **⋯** (More actions) menu
3. Select **Delete**
4. Confirm deletion

#### Create New Auth Pipelines

Create two new pipelines using the updated YAML files:

1. **`{project-id}-auth-pr`** — PR validation for auth infrastructure
   - Source: `.azdo/azure-pipelines-auth-pr.yml`
   - Trigger: Pull requests affecting `infra/auth/**`

2. **`{project-id}-auth`** — Production deployment for auth infrastructure
   - Source: `.azdo/azure-pipelines-auth.yml`
   - Trigger: Manual (same as existing pipelines)

**How to create:**

1. In Azure DevOps, go to **Pipelines** → **New pipeline**
2. Select **Azure Repos Git**
3. Choose your repository
4. Select **Existing Azure Pipelines YAML file**
5. Browse to the YAML file path
6. Click **Continue** → **Save** (not Run)
7. Rename the pipeline to match the naming convention

**Expected result:** Four legacy Okta pipelines deleted, two new unified auth pipelines created.

---

## ✅ Verify It Worked

After completing all steps, verify the migration:

1. **Check version compatibility:**

   ```powershell
   # All .csproj files should target net10.0
   Select-String -Path "**/*.csproj" -Pattern "<TargetFramework>net10.0</TargetFramework>"
   ```

2. **Verify Aspire SDK:**

   ```powershell
   # AppHost project should use Aspire.AppHost.Sdk/13.1.0
   Get-Content "src/*AppHost/*.csproj" | Select-String "Aspire.AppHost.Sdk"
   ```

3. **Check folder structure:**

   - ✅ `infra/api/` exists (renamed from `infra/app/`)
   - ✅ `infra/auth/corp/` exists (new for Entra ID)
   - ✅ `infra/auth/ext/` contains Okta configuration

4. **Confirm pipeline updates:**

   - ✅ `.azdo/azure-pipelines-api.yml` references `azure-dotnet-api-v3.yml@templates`
   - ✅ Pipeline templates reference `refs/heads/releases/v3`
   - ✅ New auth pipelines exist in Azure DevOps

**Success indicator:**

```
Build succeeded.
    0 Warning(s)
    0 Error(s)
```

---

## 🎯 Key Takeaways

After completing this guide, you will have:

- ✅ Upgraded your application to .NET 10, Aspire 13, and Forge 3.0 packages
- ✅ Restructured infrastructure to support dual authentication (Entra ID + Okta)
- ✅ Updated pipelines to use v3 templates with `refs/heads/releases/v3`
- ✅ Cleaned up legacy Okta-specific pipelines
- ✅ Experienced AI-assisted migration with the SAIF MCP server

---

## 🔍 Troubleshooting

### Problem: MCP server not found

**Cause:** SAIF CLI is outdated or MCP configuration wasn't initialized.

**Solution:**

```powershell
# Update SAIF CLI
saif doctor fix --self
Start-Sleep -Seconds 20
saif doctor fix

# Reinitialize MCP
saif agent init

# Restart VS Code
```

---

### Problem: Copilot doesn't recognize /mcp.forge.migrate-to-v3

**Cause:** MCP server isn't running or the prompt isn't registered.

**Solution:**

1. Verify `mcp.json` exists in `.vscode/`
2. Restart VS Code to reload MCP configuration
3. In Agent Chat, type `/` and verify `mcp.forge.migrate-to-v3` appears in the suggestions
4. If still missing, run `saif agent mcp` manually and check for errors

---

### Problem: Migration stops partway through

**Cause:** Copilot encountered an unexpected file structure or build error.

**Solution:**

1. Check the Copilot chat for error messages
2. Review the last completed todo item
3. Manually complete the failed step using the [manual migration guide](forge-v2-to-v3.md)
4. Ask Copilot to resume from the next task: "Continue with the next migration task"

---

### Problem: Build fails after migration

**Cause:** Package restore issue or stale build artifacts.

**Solution:**

```powershell
# Clear NuGet cache and rebuild
dotnet nuget locals all --clear
dotnet clean
dotnet restore
dotnet build
```

If errors persist, compare your changes to the [manual migration guide](forge-v2-to-v3.md) to identify missing steps.

---

## 📝 Example

### Complete Example: Migrating IT-API-EXP-EXAMPLE

This example shows the complete workflow for migrating an experience API.

```powershell
# 1. Verify prerequisites
dotnet --version   # 10.0.101
saif --version     # 3.0.5
aspire --version   # 13.1.0

# 2. Close all terminals and VS Code windows

# 3. Reopen VS Code in repository root
cd C:\repos\it-api-exp-example
code .

# 4. Initialize MCP in VS Code terminal
saif agent init

# 5. Open Copilot Agent Chat
# - Click Copilot icon → Agent Chat tab
# - Select Claude Opus model
# - Type: /mcp.forge.migrate-to-v3

# 6. Monitor progress
# Copilot outputs:
# ✅ Task 0: Baseline Build complete
# ✅ Task 1: .NET 10 SDK verified
# ✅ Task 2: SAIF Tools updated
# ✅ Task 3: dotnet-outdated-tool installed
# ✅ Task 4: .NET 10 Upgrade complete
# ✅ Task 5: Package Updates complete
# ✅ Task 6: AppHost Changes complete
# ✅ Task 7: Infrastructure Restructuring complete
# ✅ Task 8: Terraform Variable Casing complete
# ✅ Task 9: Entra ID Migration complete
# ✅ Task 10: Pipeline Updates complete

# 7. Review changes
git status
git diff

# 8. Test locally
dotnet build
dotnet test
cd src/Example.AppHost
aspire run

# 9. Update Azure DevOps pipelines
# - Delete: it-api-exp-example-okta-appauth, it-api-exp-example-okta-appauth-pr
# - Delete: it-api-exp-example-okta-userauth, it-api-exp-example-okta-userauth-pr
# - Create: it-api-exp-example-auth-pr (from .azdo/azure-pipelines-auth-pr.yml)
# - Create: it-api-exp-example-auth (from .azdo/azure-pipelines-auth.yml)

# 10. Commit and create PR
git checkout -b migrate-to-forge-v3
git add .
git commit -m "Migrate to Forge v3.0"
git push origin migrate-to-forge-v3
```

**Result:**

- Migration completed in ~35 minutes
- All tests passing
- PR ready for review with automated changes

---

## 📚 Related Documentation

- [Forge v2 to v3 Migration Guide](forge-v2-to-v3.md) - Full manual migration steps
- [Version Compatibility Matrix](../../reference/version-compatibility.md) - Supported versions for Forge 3.0
- [SAIF CLI Reference](../../reference/tools/saifcli.md) - MCP commands and capabilities

---

## 🚀 Next Steps

After completing the migration:

| Task                                     | Guide                                                                             |
| ---------------------------------------- | --------------------------------------------------------------------------------- |
| Configure Entra ID app roles and scopes  | [Security Configuration](../security/index.md)                                    |
| Update TypeSpec definitions for auth     | [Security Configuration](../security/index.md)                                    |
| Test authentication in local environment | [Create JWT for Testing APIs](../security/testing/create-jwt-for-testing-apis.md) |
| Deploy to development environment        | Run your updated pipelines in Azure DevOps                                        |
| Review breaking changes                  | [Forge 3.0 Release Notes](../../release-notes/3.0.0.md)                           |

---

## 🤖 About the SAIF MCP Server

The SAIF MCP (Model Context Protocol) server is a built-in feature of the SAIF CLI that provides AI assistants like GitHub Copilot with direct access to:

- **Forge documentation** — Migration guides, how-tos, and reference material
- **Guided workflows** — Pre-built prompts for common tasks (create application, add feature, troubleshoot, migrate)
- **Template information** — Complete template metadata and parameter descriptions
- **CLI commands** — Searchable command help and examples

**How it works:**

1. `saif agent init` creates a `.vscode/mcp.json` configuration file
2. The MCP server runs locally and connects to GitHub Copilot via VS Code
3. Copilot can invoke MCP tools and prompts using `/mcp.forge.*` syntax
4. The server retrieves documentation from the live Forge docs site and caches it locally

**Available MCP prompts:**

- `/mcp.forge.create-application` — Start a new project on the Golden Path
- `/mcp.forge.add-feature` — Add features like Cosmos DB, events, or frontend
- `/mcp.forge.troubleshoot-issue` — Debug common Forge issues
- `/mcp.forge.explain-architecture` — Learn about Forge concepts
- `/mcp.forge.migrate-to-v3` — Automated migration from v2 to v3