AI-assisted migration of classic SharePoint pages (wiki, web part, publishing) to modern SharePoint pages. An AI agent (Claude Code, GitHub Copilot, or any MCP-capable host) drives a local Model Context Protocol (MCP) server to do the work.
Classic pages can't be opened in the modern editor and miss out on modern features (responsive layout, modern web parts, Viva, Copilot surfaces). Microsoft already provides a deterministic PnP page transformation pipeline — if that meets your needs, use it.
This project is a complementary, AI-driven alternative. Reach for it when pages have custom HTML, script editor blocks, or layouts that need judgment calls, and you want a human-in-the-loop review per page.
| Your situation | Use |
|---|---|
| Bulk, deterministic migration; official support needed | PnP page transformation |
| Custom HTML / script / layouts needing judgment | This project |
| One-off, high-fidelity migration with per-page review | This project |
The agent runs a local MCP server and works through five migration skills:
- extract-and-understand — reads the classic page into an internal model.
- transform-and-create — maps each piece to the closest modern web part and creates the modern page.
- compare-and-refine — opens both pages, scores how closely they match, and iterates to improve fidelity.
- advanced-page-refinement — performs a comprehensive visual fidelity pass on an existing modern page and updates it in place.
- migrate-site — runs the above across every classic page in a site.
Sign-in uses a real browser via Playwright. You authenticate once per tenant; SharePoint cookies are saved in ~/.classic-to-modern/cookie-cache.json and reused. Each MCP process uses an isolated browser profile under ~/.classic-to-modern/browser-profiles/ so parallel migrations do not contend for one Chromium profile.
For page transformations, fast, lower-cost models also works well.
The table below shows the final scores of transforming 5 benchmark pages with different models.
| Page | GPT-5.6-Luna-Medium | GPT-5.4-mini-Medium | GPT-5.6-Sol-Medium |
|---|---|---|---|
| How To Use This Library | 90 -> 90 (high) | 85 -> 85 (high) | 90 -> 90 (high) |
| PnP Page Modernization | 70 -> 90 (high) | 90 -> 90 (high) | 90 -> 90 (high) |
| Copilot in SharePoint | 70 -> 90 (high) | 60 -> 80 (high) | 90 -> 90 (high) |
| Baseline Security in SharePoint | 60 -> 70 (high) | 70 -> 90 (high) | 70 -> 70 (low) |
| SharePoint Classic Content Deprecation | 90 -> 90 (high) | 100 -> 100 (high) | 90 -> 90 (high) |
| Final average | 86 | 89 | 86 |
This is a small, page-specific benchmark rather than a quality guarantee.
When requesting a site migration, specify the page-subagent model:
Migrate the classic pages on
https://contoso.sharepoint.com/sites/Marketing. Use GPT-5.4-mini-Medium for page migration subagents.
- Node.js 20+
- An MCP-capable AI host (Claude Code, GitHub Copilot with MCP, etc.)
- A SharePoint Online tenant with permission to read classic pages and create modern pages on the target site
- Chrome / Edge installed locally (Playwright drives a real browser for auth)
git clone https://github.com/pnp/SharePointPageModernizationAgent.git
cd SharePointPageModernizationAgentThe setup script checks Node.js, installs dependencies, builds the server, runs a
smoke test, verifies the MCP server starts (a real initialize handshake), and
creates .mcp.json for you. Run it from the repo root:
# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File .\setup.ps1# macOS / Linux / WSL / Git Bash
./setup.shThen skip to How to use.
cd mcp-server
npm install
npx tscRun everything from the repo root — do not install the skills or tools globally.
1. Start your host and confirm the server is loaded with /mcp (look for classic-to-modern):
copilot # GitHub Copilot CLI
claude # Claude Code2. Sign in when prompted — the agent opens a browser via Playwright the first time it touches a page. One sign-in per tenant.
3. Migrate a page by describing it in plain language:
Migrate this classic page to a modern page:
https://contoso.sharepoint.com/sites/Marketing/SitePages/OldHome.aspx
The agent extracts, transforms, creates, and refines automatically, then gives you the URL of the new modern page. Some variations:
Just extract and analyze
https://contoso.sharepoint.com/sites/HR/SitePages/Policies.aspx— don't create the modern page yet, show me what you found.
Migrate this page but keep any script editor content as an explanatory text note instead of trying to reproduce it.
Redo the migration for
OldHome.aspxand overwrite the existing modern page.
Publishing pages can be migrated in the same site when the Site Pages feature is activated (a Site Pages library exists). If that feature isn't activated, the site can't host a modern page in place — tell the agent a destination site:
Migrate
https://contoso.sharepoint.com/sites/News/Pages/Article.aspxand create the modern page onhttps://contoso.sharepoint.com/sites/NewsModern.
4. Migrate a whole site by pointing the agent at it:
Migrate all classic pages on
https://contoso.sharepoint.com/sites/Marketingto modern pages.
It discovers the pages, migrates them (several in parallel), and reports quality scores plus any pages needing a closer look. You can also scope or plan first:
If matching page-understanding JSON already exists for discovered pages, the agent lists those pages and asks whether to reuse the existing analysis or run extraction again.
List the classic pages on
https://contoso.sharepoint.com/sites/Marketingand give me a migration plan first — don't migrate anything yet.
Migrate only the pages under the
SitePageslibrary onhttps://contoso.sharepoint.com/sites/Marketing.
5. Review and refine. Open the generated pages against the originals before publishing or deleting anything. The agent first seeks a supported modern web part, then a source-derived static Text web part, and uses yellow explanatory text only when neither can represent the classic behavior. Ask the agent to fix anything that's off:
Compare the modern page you just created against the classic original and tell me the fidelity score.
The layout is off on
OldHome.aspx— please compare and refine that page again.
The hero image didn't come across. Re-check the classic page and fix the image web part on the modern page.
Deeply refine the existing modern page to match the classic source, including its Text web-part styling and unresolved placeholders.
- Start with a single page. Validate results on one representative page before launching a site-wide run.
- Mind the token cost. Migrations are AI-powered and consume model tokens. Large pages and site-wide runs can use a lot, which may incur cost depending on your plan — another reason to test on one page first.
- Be specific with URLs — paste the full classic page or site URL.
- Re-run refinement if a page isn't close enough, e.g. "the layout is off, please compare and refine that page again."
Licensed under the MIT License.