### Install Astro Docs MCP Server in Cursor

Source: https://github.com/withastro/docs-mcp/blob/main/README.md

This URL is used to install the Astro Docs MCP server in Cursor. It requires opening the link in a browser as GitHub does not support deep links for Cursor.

```url
cursor://anysphere.cursor-deeplink/mcp/install?name=Astro%20docs&config=eyJ1cmwiOiJodHRwczovL21jcC5kb2NzLmFzdHJvLmJ1aWxkL21jcCJ9
```

--------------------------------

### Install Astro Docs MCP Server in VS Code

Source: https://github.com/withastro/docs-mcp/blob/main/README.md

This URL is used to install the Astro Docs MCP server in VS Code. It requires opening the link in a browser as GitHub does not support deep links for VS Code.

```url
vscode:mcp/install?%7B%22name%22%3A%22Astro%20docs%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.docs.astro.build%2Fmcp%22%7D
```

--------------------------------

### Interact with MCP HTTP API Endpoint (Shell)

Source: https://context7.com/withastro/docs-mcp/llms.txt

Example of making a direct HTTP POST request to the MCP server's `/mcp` endpoint to list available tools. Demonstrates the JSON-RPC format for requests.

```shell
# Direct HTTP request to the MCP endpoint (JSON-RPC format)
curl -X POST https://mcp.docs.astro.build/mcp \
  -H "Content-Type: application/json" \
  -d '{ 
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# Expected response listing available tools
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search_astro_docs",
        "title": "Search Astro Docs",
        "description": "Search the official Astro framework docs",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string", "description": "Search query" }
          },
          "required": ["query"]
        }
      }
    ]
  }
}
```

--------------------------------

### Netlify Edge Function Handler for MCP Requests

Source: https://context7.com/withastro/docs-mcp/llms.txt

Handles incoming MCP requests, creates server instances, and manages transport lifecycle for Netlify Edge Functions. It uses the @modelcontextprotocol/sdk and fetch-to-node libraries. Expects a Request object and returns a Response object, handling POST requests for MCP interactions and returning 405 for GET requests.

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { toFetchResponse, toReqRes } from "fetch-to-node";

export default async function handler(req: Request) {
  if (req.method === "GET") {
    return new Response("Method Not Allowed", {
      status: 405,
      headers: { "Content-Type": "text/plain", Allow: "POST" },
    });
  }

  try {
    const { req: nodeReq, res: nodeRes } = toReqRes(req);
    const server = getServer();
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined, // Stateless mode
    });
    await server.connect(transport);

    const body = await req.json();
    await transport.handleRequest(nodeReq, nodeRes, body);

    nodeRes.on("close", () => {
      transport.close();
      server.close();
    });

    return toFetchResponse(nodeRes);
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    return Response.json({ error: errorMessage }, { status: 500 });
  }
}

export const config: Config = {
  path: ["/mcp"],
  method: ["POST", "GET"],
};
```

--------------------------------

### Adding MCP Server to Windsurf (SSE Proxy)

Source: https://context7.com/withastro/docs-mcp/llms.txt

Windsurf requires a local proxy since it doesn't support streamable HTTP transport directly. Use mcp-remote as a bridge.

```APIDOC
## Adding MCP Server to Windsurf (SSE Proxy)

Windsurf requires a local proxy since it doesn't support streamable HTTP transport directly. Use mcp-remote as a bridge.

### Request Body

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

--------------------------------

### Windsurf MCP Server Configuration

Source: https://github.com/withastro/docs-mcp/blob/main/README.md

This JSON configuration is used for Windsurf to connect to the Astro Docs MCP server. It specifies a command to run a local proxy due to Windsurf's lack of direct support for streamable HTTP.

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

--------------------------------

### Configure MCP Server Connection (JSON)

Source: https://context7.com/withastro/docs-mcp/llms.txt

Configuration settings for connecting an MCP-compatible AI tool to the Astro Docs server. Specifies the server URL and transport protocol.

```json
{
  "mcpServers": {
    "Astro docs": {
      "url": "https://mcp.docs.astro.build/mcp",
      "transport": "http"
    }
  }
}
```

--------------------------------

### MCP Server Configuration

Source: https://context7.com/withastro/docs-mcp/llms.txt

Configure your MCP-compatible AI tool to connect to the Astro Docs server.

```APIDOC
## MCP Server Configuration

Configure your MCP-compatible AI tool to connect to the Astro Docs server using these settings.

### Request Body

```json
{
  "mcpServers": {
    "Astro docs": {
      "url": "https://mcp.docs.astro.build/mcp",
      "transport": "http"
    }
  }
}
```
```

--------------------------------

### Adding MCP Server to Claude Code

Source: https://context7.com/withastro/docs-mcp/llms.txt

Use the Claude Code CLI to add the Astro Docs MCP server to your local configuration.

```APIDOC
## Adding MCP Server to Claude Code

Use the Claude Code CLI to add the Astro Docs MCP server to your local configuration.

### Command

```sh
claude mcp add --transport http "Astro docs" https://mcp.docs.astro.build/mcp
```
```

--------------------------------

### Netlify Edge Function Handler (/mcp)

Source: https://context7.com/withastro/docs-mcp/llms.txt

Handles incoming MCP requests, creates server instances, and manages the transport lifecycle for the Astro Docs MCP Server. It supports POST requests for processing and returns a 405 for other methods.

```APIDOC
## POST /mcp

### Description
Processes incoming MCP requests, creates server instances, and manages the transport lifecycle. This endpoint is designed to be used with AI tools requiring context-aware documentation assistance.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Query Parameters
None

#### Request Body
- **query** (string) - Required - The query to be processed by the AI.
- **integration_id** (string) - Required - The identifier for the integration being used.

### Request Example
```json
{
  "query": "How do I fetch data in Astro?",
  "integration_id": "vscode-copilot"
}
```

### Response
#### Success Response (200)
- **result** (object) - The AI-generated response to the query.
- **error** (string) - An error message if the request failed.

#### Response Example
```json
{
  "result": {
    "answer": "In Astro, you can fetch data using the `fetch` API within `load` functions or server-side scripts...",
    "sources": [
      {
        "title": "Fetching Data",
        "url": "https://docs.astro.build/en/guides/fetching-data/"
      }
    ]
  }
}
```

#### Error Response (500)
- **error** (string) - A message describing the internal server error.

#### Error Response Example
```json
{
  "error": "Internal server error: Failed to process request."
}
```
```

--------------------------------

### Kapa.ai Search Integration Function

Source: https://context7.com/withastro/docs-mcp/llms.txt

Sends search queries to the Kapa.ai API and formats the response. This function requires environment variables KAPA_API_KEY, KAPA_PROJECT_ID, and KAPA_INTEGRATION_ID. It handles API requests and returns either the JSON response or an error object.

```typescript
interface SearchResponse {
  search_results: Array<{ 
    title: string;
    source_url: string;
    content: string;
    source_type: string;
  }>;
}

async function sendKapaRequest<T = unknown>(
  action: string,
  query: string
): Promise<T | { error: string }> {
  const url = `https://api.kapa.ai/query/v1/projects/${projectId}/${action}/`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": apiKey!,
    },
    body: JSON.stringify({
      query,
      integration_id: integrationId,
    }),
  });

  if (!response.ok) {
    return { error: "Error: Unable to fetch data from API. Please try again later." };
  }
  return await response.json();
}

// Required environment variables for Kapa.ai integration
// KAPA_API_KEY - API key for authentication
// KAPA_PROJECT_ID - Project identifier
// KAPA_INTEGRATION_ID - Integration identifier
```

--------------------------------

### Kapa.ai Search Integration

Source: https://context7.com/withastro/docs-mcp/llms.txt

Internal function for sending search queries to the Kapa.ai API and handling response formatting. Requires API key, project ID, and integration ID.

```APIDOC
## Kapa.ai Search API

### Description
This internal function sends search queries to the Kapa.ai API and formats the response. It is used by the Netlify Edge Function Handler to retrieve relevant documentation.

### Method
POST

### Endpoint
`https://api.kapa.ai/query/v1/projects/{projectId}/{action}/`

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The Kapa.ai project ID.
- **action** (string) - Required - The action to perform (e.g., 'query').

#### Query Parameters
None

#### Request Body
- **query** (string) - Required - The search query.
- **integration_id** (string) - Required - The identifier for the integration.

### Request Example
```json
{
  "query": "How do I deploy an Astro site?",
  "integration_id": "astro-docs-bot"
}
```

### Response
#### Success Response (200)
- **search_results** (array) - An array of search result objects, each containing:
  - **title** (string) - The title of the search result.
  - **source_url** (string) - The URL of the source document.
  - **content** (string) - A snippet of the content from the source.
  - **source_type** (string) - The type of the source (e.g., 'documentation').

#### Response Example
```json
{
  "search_results": [
    {
      "title": "Deployment",
      "source_url": "https://docs.astro.build/en/guides/deploy/",
      "content": "Astro supports various deployment targets, including Netlify, Vercel, GitHub Pages, and more...",
      "source_type": "documentation"
    }
  ]
}
```

#### Error Response
- **error** (string) - A message describing the error.

#### Error Response Example
```json
{
  "error": "Error: Unable to fetch data from API. Please try again later."
}
```

### Environment Variables
- **KAPA_API_KEY**: API key for authentication.
- **KAPA_PROJECT_ID**: Project identifier.
- **KAPA_INTEGRATION_ID**: Integration identifier.
```

--------------------------------

### Copy Text to Clipboard Function (JavaScript)

Source: https://github.com/withastro/docs-mcp/blob/main/public/index.html

A JavaScript function that copies the provided text to the user's clipboard. It offers visual feedback to the user by changing the button text and background color temporarily. This function is useful for interactive elements like copying server URLs or configuration values.

```javascript
function copyToClipboard(text) {
  navigator.clipboard.writeText(text).then(() => {
    // Simple visual feedback
    const originalText = event.target.textContent;
    event.target.textContent = 'Copied!';
    event.target.style.background = 'rgba(255, 255, 255, 0.3)';
    setTimeout(() => {
      event.target.textContent = originalText;
      event.target.style.background = 'rgba(255, 255, 255, 0.1)';
    }, 1000);
  });
}
```

--------------------------------

### Define search_astro_docs Tool (TypeScript)

Source: https://context7.com/withastro/docs-mcp/llms.txt

Defines the 'search_astro_docs' MCP tool, which interfaces with Kapa.ai to perform semantic searches on the Astro documentation. It includes input schema validation and response formatting.

```typescript
// MCP Tool Definition
server.registerTool(
  "search_astro_docs",
  {
    title: "Search Astro Docs",
    description: "Search the official Astro framework docs",
    inputSchema: { query: z.string().describe("Search query") },
  },
  async ({ query }) => {
    if (!query) {
      throw new Error("Query is required");
    }
    const result = await sendKapaRequest<SearchResponse>("search", query);
    return formatResponse(result);
  }
);

// Example MCP Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_astro_docs",
    "arguments": {
      "query": "how to create an Astro component"
    }
  }
}

// Example Response Structure
{
  "content": [
    {
      "type": "text",
      "text": "{\"search_results\":[{\"title\":\"Components\",\"source_url\":\"https://docs.astro.build/en/basics/astro-components/\",\"content\":\"Astro components are the basic building blocks...\",\"source_type\":\"docs\"}]}"
    }
  ]
}
```

--------------------------------

### Add Astro Docs MCP Server in Claude Code

Source: https://github.com/withastro/docs-mcp/blob/main/README.md

This command-line instruction adds the Astro Docs MCP server to Claude Code. It specifies the transport protocol as http and provides the server URL.

```bash
claude mcp add --transport http "Astro docs" https://mcp.docs.astro.build/mcp
```

--------------------------------

### search_astro_docs Tool

Source: https://context7.com/withastro/docs-mcp/llms.txt

The primary MCP tool that searches the official Astro documentation using semantic search powered by Kapa.ai. Returns structured results with titles, URLs, content snippets, and source types.

```APIDOC
## search_astro_docs Tool

The primary MCP tool that searches the official Astro documentation using semantic search powered by Kapa.ai. Returns structured results with titles, URLs, content snippets, and source types.

### Tool Definition

```typescript
// MCP Tool Definition
server.registerTool(
  "search_astro_docs",
  {
    title: "Search Astro Docs",
    description: "Search the official Astro framework docs",
    inputSchema: { query: z.string().describe("Search query") },
  },
  async ({ query }) => {
    if (!query) {
      throw new Error("Query is required");
    }
    const result = await sendKapaRequest<SearchResponse>("search", query);
    return formatResponse(result);
  }
);
```

### Example MCP Request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_astro_docs",
    "arguments": {
      "query": "how to create an Astro component"
    }
  }
}
```

### Example Response Structure

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"search_results\":[{\"title\":\"Components\",\"source_url\":\"https://docs.astro.build/en/basics/astro-components/\",\"content\":\"Astro components are the basic building blocks...\",\"source_type\":\"docs\"}]}"
    }
  ]
}
```
```

--------------------------------

### POST /mcp

Source: https://context7.com/withastro/docs-mcp/llms.txt

The MCP server exposes a single POST endpoint at `/mcp` that handles all MCP protocol requests using the streamable HTTP transport.

```APIDOC
## POST /mcp

The MCP server exposes a single POST endpoint at `/mcp` that handles all MCP protocol requests using the streamable HTTP transport.

### Method

POST

### Endpoint

/mcp

### Description

Handles all MCP protocol requests using the streamable HTTP transport.

### Request Body

The request body should be in JSON-RPC 2.0 format.

### Request Example

```sh
# Direct HTTP request to the MCP endpoint (JSON-RPC format)
curl -X POST https://mcp.docs.astro.build/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

### Response

#### Success Response (200)

Returns a JSON-RPC 2.0 response containing the result of the requested method. For `tools/list`, it returns a list of available tools.

#### Response Example (tools/list)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search_astro_docs",
        "title": "Search Astro Docs",
        "description": "Search the official Astro framework docs",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string", "description": "Search query" }
          },
          "required": ["query"]
        }
      }
    ]
  }
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.