Skip to content

build-with-ai.mdx

Latest commit

 

History

History
389 lines (272 loc) · 16.5 KB

build-with-ai.mdx

File metadata and controls

389 lines (272 loc) · 16.5 KB
Raw
title Building Astro sites with AI tools
sidebar
label
Build with AI
tableOfContents
minHeadingLevel maxHeadingLevel
2
4
i18nReady true
description Resources and tips for building Astro sites with AI assistance

import Since from '/components/Since.astro'; import ReadMore from '/components/ReadMore.astro'; import { Steps, LinkButton, Card, Tabs, TabItem } from '@astrojs/starlight/components';

AI-powered editors and agentic coding tools generally have good knowledge of Astro's core APIs and concepts. However, some may use older APIs and may not be aware of newer features or recent changes to the framework.

This guide covers how to enhance AI tools with up-to-date Astro knowledge and provides best practices for building Astro sites with AI assistance.

Astro Docs MCP Server

You can ensure your AI tools have current Astro knowledge through the Astro Docs MCP (Model Context Protocol) server. This provides real-time access to the latest documentation, helping AI tools avoid outdated recommendations and ensuring they understand current best practices.

:::tip[What is MCP?] Model Context Protocol (MCP) is a standardized way for AI tools to access external tools and data sources. :::

Unlike AI models trained on static data, the MCP server provides access to the latest Astro documentation. The server is free, open-source, and runs remotely with nothing to install locally.

The Astro Docs MCP server uses the kapa.ai API to maintain an up-to-date index of the Astro documentation.

Server Details

  • Name: Astro Docs
  • URL: https://mcp.docs.astro.build/mcp
  • Transport: Streamable HTTP

Installation

The setup process varies depending on your AI development tool. You may see some tools refer to MCP servers as connectors, adapters, extensions, or plugins.

Manual setup

Many tools support a common JSON configuration format for MCP servers. If there are not specific instructions for your chosen tool, you may be able to add the Astro Docs MCP server by including the following configuration in your tool's MCP settings:

```json title="MCP Configuration" {3-6} { "mcpServers": { "Astro docs": { "type": "http", "url": "https://mcp.docs.astro.build/mcp" } } } ``` ```json title="MCP Configuration" {3-7} { "mcpServers": { "Astro docs": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"] } } } ``` #### Claude Code CLI

Claude Code is an agentic coding tool that runs on the command line. Enabling the Astro Docs MCP server allows it to access the latest documentation while generating Astro code.

Install using the terminal command:

claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp

More info on using MCP servers with Claude Code

Claude Code GitHub Action

Claude Code also provides a GitHub Action that can be used to run commands in response to GitHub events. Enabling the Astro Docs MCP server allows it to access the latest documentation while answering questions in comments or generating Astro code.

You can configure it to use the Astro Docs MCP server for documentation access by adding the following to the workflow file:

# ...rest of your workflow configuration
- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "astro-docs": {
            "type": "http",
            "url": "https://mcp.docs.astro.build/mcp"
          }
        }
      }
    allowed_tools: "mcp__astro-docs__search_astro_docs"

More info on using MCP servers with the Claude Code GitHub Action

Codex CLI

Codex CLI is a command-line AI coding tool that can use the Astro Docs MCP server to access documentation while generating Astro code.

You can configure MCP servers at the global level in the ~/.codex/config.toml file, or in a .codex/config.toml file in a project root.

[mcp_servers.astro-docs]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]

More info on using MCP servers with Codex CLI

Cursor

Cursor is an AI code editor. Adding the Astro Docs MCP server allows Cursor to access the latest Astro documentation while performing development tasks.

Install by clicking the button below:

Add to Cursor

More info on using MCP servers with Cursor

Visual Studio Code

Visual Studio Code supports MCP servers when using Copilot Chat. Adding the Astro Docs MCP server allows VS Code to access the latest Astro documentation when answering questions or performing coding tasks.

Install by clicking the button below:

Add to VS Code

More info on using MCP servers with VS Code

Warp

Warp (formerly Warp Terminal) is an agent development environment built for coding with multiple AI agents. Adding the Astro Docs MCP server allows Warp to access the latest Astro documentation when answering questions or performing coding tasks.

  1. Open your Warp settings and go to AI > MCP Servers > Manage MCP Servers.
  2. Click "Add".
  3. Enter the following configuration. You can optionally configure the Astro MCP server to activate on startup using the start_on_launch flag: 
    {
  "mcpServers": {
    "Astro docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"],
      "env": {},
      "working_directory": null,
      "start_on_launch": true
    }
  }
}
  4. Click "Save".

More info on using MCP servers with Warp

Claude.ai / Claude Desktop

Claude.ai is a general-purpose AI assistant. Adding the Astro Docs MCP server allows it to access the latest documentation when answering Astro questions or generating Astro code.

  1. Navigate to the Claude.ai connector settings.
  2. Click "Add custom connector". You may need to scroll down to find this option.
  3. Enter the server URL: https://mcp.docs.astro.build/mcp.
  4. Set the name to "Astro docs".

More info on using MCP servers with Claude.ai

Windsurf

Windsurf is an AI-powered agentic coding tool, available as editor plugins or a standalone editor. It can use the Astro Docs MCP server to access documentation while performing coding tasks.

Windsurf doesn't support streaming HTTP, so it requires a local proxy configuration:

  1. Open ~/.codeium/windsurf/mcp_config.json in your editor.

  2. Add the following configuration to your Windsurf MCP settings:

    {
  "mcpServers": {
    "Astro docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
    }
  }
}

  3. Save the configuration and restart Windsurf.

More info on using MCP servers with Windsurf

Gemini CLI

Gemini CLI is a command-line AI coding tool that can use the Astro Docs MCP server to access documentation while generating Astro code.

You can configure MCP servers at the global level in the ~/.gemini/settings.json file, or in a .gemini/settings.json file in a project root.

{
  "mcpServers": {
    "Astro docs": {
      "httpUrl": "https://mcp.docs.astro.build/mcp",
    }
  }
}

More info on using MCP servers with Gemini CLI

Google Antigravity

Google Antigravity is an agentic development platform.

  1. Open ~/.gemini/antigravity/mcp_config.json by following the Connecting Custom MCP Servers guide.
  2. Add the following configuration to mcp_config.json: 
    {
  "mcpServers": {
    "astro-docs": {
      "serverUrl": "https://mcp.docs.astro.build/mcp"
    }
  }
}
  3. Save the file and click "Refresh" in the "Manage MCPs" tab.

Zed

Zed supports MCP servers when using its AI capabilities. It can use the Astro Docs MCP server to access documentation while performing coding tasks.

  1. Open ~/.config/zed/settings.json in your editor.

  2. Add the following configuration to your Zed MCP settings:

    {
   "context_servers": {
     "Astro docs": {
       "settings": {},
       "enabled": true,
       "url": "https://mcp.docs.astro.build/mcp"
     }
   }
}

  3. Save the configuration.

More info on using MCP servers with Zed

ChatGPT

Refer to the OpenAI MCP documentation for specific setup instructions.

Raycast

Raycast can connect to MCP servers to enhance its AI capabilities. Adding the Astro Docs MCP server allows Raycast to access the latest Astro documentation while answering questions.

Install by clicking the button below:

Add to Raycast

More info on using MCP servers with Raycast

Opencode AI

Opencode AI is an open-source, terminal-based AI coding tool that can use the Astro Docs MCP server to access documentation while generating Astro code.

You can configure MCP servers in your Opencode configuration file, typically named opencode.json, located in your project root or your global configuration directory (e.g. ~/.config/opencode/opencode.json).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "Astro docs": {
      "type": "remote",
      "url": "https://mcp.docs.astro.build/mcp",
      "enabled": true
    }
  }
}

More info on using Opencode AI

GitHub Copilot Coding Agent

GitHub Copilot can be used as a coding agent powered by GitHub Actions. Enabling the Astro Docs MCP server allows it to access the latest Astro documentation when answering questions or performing coding tasks.

You can configure it to use the Astro Docs MCP server for documentation access by adding the following to your repository's Copilot coding agent settings available at https://github.com/<your-org>/<your-repo>/settings/copilot/coding_agent:

{
  "mcpServers": {
    "astro-docs": {
      "type": "http",
      "url": "https://mcp.docs.astro.build/mcp",
      "tools": ["mcp__astro-docs__search_astro_docs"]
    }
  }
}

Learn more about extending GitHub Copilot coding agent with MCP servers.

Usage

Once configured, you can ask your AI tool questions about Astro, and it will retrieve information directly from the latest docs. Coding agents will be able to consult the latest documentation when performing coding tasks, and chatbots will be able to accurately answer questions about Astro features, APIs, and best practices.

:::note[Remember] The Astro Docs MCP server provides access to current documentation, but your AI tools are still responsible for interpretation and code generation. AI makes mistakes, so always review generated code carefully and test thoroughly. :::

Troubleshooting

If you encounter issues:

  • Verify that your tool supports streamable HTTP transport.
  • Check that the server URL is correct: https://mcp.docs.astro.build/mcp.
  • Ensure your tool has proper internet access.
  • Consult your specific tool's MCP integration documentation.

If you are still having problems, open an issue in the Astro Docs MCP Server repository.

Discord AI Support

The same technology that powers Astro's MCP server is also available as a chatbot in the Astro Discord for self-serve support. Visit the #support-ai channel to ask questions about Astro or your project code in natural language. Your conversation is automatically threaded, and you can ask an unlimited number of follow-up questions.

Conversations with the chatbot are public, and are subject to the same server rules for language and behavior as the rest of our channels, but they are not actively visited by our volunteer support members. For assistance from the community, please create a thread in our regular #support channel.

Background mode

When an AI coding agent is detected on macOS and Linux, astro dev and, since v7.2.0, astro preview automatically start the server as a detached background process. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs.

On Windows, or without an AI coding agent, the server starts in the foreground and logs to the terminal. You can still opt in explicitly by passing the --background flag.

A lock file (.astro/dev.json or .astro/preview.json) is written when the server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project.

To opt out of automatic background mode, set the ASTRO_DEV_BACKGROUND or ASTRO_PREVIEW_BACKGROUND environment variable before running the command:

ASTRO_DEV_BACKGROUND=0 astro dev
ASTRO_PREVIEW_BACKGROUND=0 astro preview

See the CLI reference for the full list of flags and subcommands for astro dev and astro preview.

Health endpoint

The dev server exposes a /_astro/status endpoint that returns {"ok": true} as JSON. This allows agents and other tools to check programmatically whether the dev server is ready to accept requests. This endpoint is only available in the dev server and does not exist in production builds.

Tips for AI-Powered Astro Development

  • Start with templates: Rather than building from scratch, ask AI tools to start with an existing Astro template or use npm create astro@latest with a template option.
  • Use astro add for integrations: Ask AI tools to use astro add for official integrations (e.g. astro add tailwind, astro add react). For other packages, install using the command for your preferred package manager rather than editing package.json directly.
  • Verify current APIs: AI tools may use outdated patterns. Ask them to check the latest documentation, especially for newer features like sessions and actions. This is also important for features that have seen significant changes since their initial launch, such as content collections, or previously experimental features that may no longer be experimental.
  • Use project rules: If your AI tool supports it, set up project rules to enforce best practices and coding standards, such as the ones listed above.