09 — Create and Verify an Astro Route

Walkthrough

This is the full Astro round-trip. Unlike WordPress posts which sit as drafts indefinitely, Astro routes go live on the next Cloudflare Pages build (~30–90 seconds after the GitHub commit).

Y

You

Vibe-code a “Coming soon” splash page for the launch — gradient indigo, centered hero with email signup, sticky footer with social links. Add it as a new route /launch on astro-site.

Claude

create_astro_route

Pushed. The new file lives at src/pages/launch.astro on branch main of supportsn/astro-site.

• Commit: a7d4e2c — [astro] create route /launch
• GitHub URL: https://github.com/supportsn/astro-site/blob/main/src/pages/launch.astro
• Build status: pending (Cloudflare Pages auto-rebuilds on push)

Wait ~60 seconds, then visit https://sn-astro-sites.pages.dev/launch — Cloudflare will have built and deployed the new route by then.

The MCP server doesn’t pretend the route is live yet — it returns build_status: pending because Cloudflare Pages is the source of truth on whether the build succeeded. The optional check_astro_deploy tool can poll the CF API directly (requires CLOUDFLARE_API_TOKEN secret), but the simplest check is to visit the URL after a minute.

Verifying the commit landed

GitHub shows the new file in src/pages/:

Verifying the build deployed

The live Astro site at sn-astro-sites.pages.dev:

Click into /launch after the build completes to confirm. If you see a 404 after 2 minutes, open the Cloudflare Pages dashboard for the project — most likely the build failed (vd typo in HTML breaking Astro’s parser). The log_url returned by check_astro_deploy jumps straight to the failed build log.

Audit trail

The MCP call lands in the worker audit log like any other:

Note delete_astro_route is not in the regular tools list — it’s super-admin-only (filtered out of regular-user token UI + runtime-rejected for non-super tokens) since removing a deployed route has real impact on the live site. Restore is via git revert on the deletion commit.

Goal

Demonstrate the full Astro round-trip: HTML authored in chat ⇒ MCP commits an .astro file to the Astro repo ⇒ Cloudflare Pages builds ⇒ the page is reachable at the live URL within ~1 minute.

Prerequisites

• Connector connected (scenario 01).
• A site with platform: astro linked to the user, pointing at a GitHub repo (e.g. acme-org/marketing-site) that is wired to Cloudflare Pages.
• The user has at least read access to the Cloudflare Pages dashboard for that project (only to watch the build — not required for the MCP call).

Setup state

• Claude Desktop on a new conversation.
• A GitHub tab open on the Astro repo’s src/pages/ folder.
• A Cloudflare Pages tab open on the project’s Deployments view.
• A browser tab open on the site’s production URL (https://acme.example.com) so the 404 for the new route can be captured before the build finishes.

Steps

1. Action: In the composer, paste:

   List my Astro routes for the marketing site.

   Press Enter. Expected: Claude calls list_astro_routes, returns a table of existing .astro files under src/pages/. Note the current count. Recorder: hold on the table for two seconds.

2. Action: Type:

   Build a landing page for our new product “Beacon”. Hero with headline, three feature columns, footer CTA. Path should be /beacon. Use semantic HTML; Tailwind classes are fine because the project has Tailwind. Save it as an Astro route.

   Expected: Claude writes the .astro file content in chat (including frontmatter --- block and HTML), then calls create_astro_route with { site_id, route: "/beacon", content, commit_message }. Tool card resolves green. Recorder: capture the tool card; the route field is the key input.

3. Action: Wait for Claude’s reply. Expected: Claude returns { commit_sha, html_url, expected_live_url: "https://acme.example.com/beacon" }. Recorder: copy the expected_live_url to clipboard for step 6.

4. Action: Switch to the GitHub tab and refresh src/pages/. Expected: A new file beacon.astro appears, last commit message matches what Claude sent. Recorder: click the file; pause on the source for two seconds.

5. Action: Switch to the Cloudflare Pages Deployments tab and refresh. Expected: A new deployment is Building (or Queued within a few seconds of the commit). Wait until status flips to Success — typically 30–90 seconds. Recorder: time-lapse this part; cut to ~5 seconds of build wait.

6. Action: Switch to the production URL tab and navigate to /beacon. Expected: The page renders with the hero, three columns, and footer CTA — matching what Claude produced. Recorder: scroll the page once top-to-bottom; this is the closing shot.

7. Action: Back in Claude Desktop, type:

   List my Astro routes again.

   Expected: The new /beacon row is now in the table. Recorder: optional; only include if there’s room.

Verification

• GitHub repo shows the new commit at src/pages/beacon.astro.
• Cloudflare Pages Deployments shows a successful build for that commit SHA.
• The live URL returns HTTP 200 and the expected markup.
• MCP Audit log records tools/call create_astro_route with ok.

Rollback / cleanup

• In GitHub, delete src/pages/beacon.astro (MCP can’t delete). Cloudflare Pages will rebuild and the route will 404 again within ~1 minute.
• Or call update_astro_route with empty/placeholder content to keep the route but blank the page.

Edge cases to capture in the recording

• Route already exists: create_astro_route returns E_ROUTE_EXISTS. Show Claude switching to update_astro_route automatically (or asking the user first).
• Cloudflare Pages build fails (e.g. syntax error in the generated .astro): the deployment row turns red. Show the user fetching the build log, asking Claude to fix, then calling update_astro_route to land the patched file.
• DNS not pointed to Pages yet: the production URL still 404s after a successful build. Mention this is a DNS/setup issue, not a tool issue, and show how to fall back to the Pages preview URL.