alpine-mcp

An MCP (Model Context Protocol) server for the complete Alpine.js v3 documentation. It ships a commit-pinned snapshot of the official Markdown and uses Tobi Lütke's qmd for local full-text search.

Website · npm

Tools

The server also exposes each page as an alpine://docs/<path>.md resource. The original combined alpine://directives, alpine://magics, alpine://globals, and alpine://plugins resources remain available for compatibility.

Installation

alpine-mcp requires Node.js 22 or newer.

Claude Desktop

Add to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "alpine": {
      "command": "npx",
      "args": ["-y", "alpine-mcp"]
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add alpine -- npx -y alpine-mcp

OpenAI Codex

codex mcp add alpine -- npx -y alpine-mcp

Or add it directly to ~/.codex/config.toml:

[mcp_servers.alpine]
command = "npx"
args = ["-y", "alpine-mcp"]

Cursor

Add to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "alpine": {
      "command": "npx",
      "args": ["-y", "alpine-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "alpine": {
      "command": "npx",
      "args": ["-y", "alpine-mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json in your workspace for GitHub Copilot. If the file already exists, merge the alpine entry into its top-level servers object:

{
  "servers": {
    "alpine": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "alpine-mcp"]
    }
  }
}

Cline and Roo Code

Add a local stdio server through the extension's MCP settings using npx as the command and -y alpine-mcp as the arguments.

Any MCP client

npx -y alpine-mcp

Each server process builds a small temporary qmd index at startup. Search is lexical and does not download qmd's optional embedding or reranking models.

Usage

Once registered, ask your AI assistant questions such as:

• "How do I use x-transition with custom CSS classes?"
• "What modifiers does x-on support?"
• "How do I persist state across page loads with Alpine?"
• "Show me how to use the Focus plugin for a modal."

Documentation updates

The generator resolves an Alpine branch, tag, or SHA to one immutable commit, downloads that commit's GitHub archive, and atomically replaces docs/ only after every page has been extracted and validated. One upstream Markdown page becomes one local file, so new and removed Alpine pages are discovered without a hand-maintained manifest. docs/.source.json records the exact source commit.

Refresh from Alpine's current main:

npm run generate

Refresh from a specific release or commit:

ALPINE_REF=v3.14.9 npm run generate

A weekly GitHub Actions workflow runs the same generator and opens or updates a documentation-only pull request on automation/update-alpine-docs. It never pushes directly to protected main or creates version tags.

The repository must enable Settings → Actions → General → Allow GitHub Actions to create and approve pull requests and Settings → General → Allow auto-merge. No additional access-token secret is needed.

The updater runs unattended. GitHub holds pull_request workflow runs for PRs opened with GITHUB_TOKEN until a maintainer approves them, so that run shows as waiting for approval and can be ignored. The updater instead dispatches ci.yml on the documentation branch; the dispatched run reports the required validate check on the PR's head commit and needs no approval. It then enables squash auto-merge, so a passing update lands on main by itself and a failing one stays open for investigation.

After a docs update merges, bump and commit the package version and publish a matching GitHub Release to ship it to npm. Installed packages use their bundled snapshot; they do not fetch upstream docs at startup. Published builds use committed Markdown rather than making network requests during packaging.

Publishing

Publishing a GitHub Release automatically validates, builds, and publishes the matching version to npm with provenance. The release tag must match the version in package.json, including the v prefix—for example, package version 2.0.0 must use tag v2.0.0. Pre-releases are published under npm's next dist-tag; regular releases use latest.

Merge the publishing workflow into the default branch before creating the tag and GitHub Release. npm trusted publishing must authorize BillyNoyes/alpine-mcp, the publish.yml workflow, and the npm GitHub environment. The workflow uses GitHub OIDC to obtain a short-lived publishing credential, so it does not require an npm access-token secret.

Project structure

• src/index.ts initializes the catalog, qmd index, and MCP transport.
• src/server/ defines the MCP server and registers resource and tool handlers.
• src/documents/ owns documentation discovery and resource retrieval.
• src/search/ owns qmd lifecycle and search-result snippets.
• scripts/docs/ contains the fetch, archive, corpus, and generation pipeline.
• site/ contains the Vite, Alpine.js, and Tailwind GitHub Pages site.

Development

git clone https://github.com/BillyNoyes/alpine-mcp.git
cd alpine-mcp
npm install
npm test
npm run typecheck
npm run build

For local MCP configuration, run node /path/to/alpine-mcp/build/index.js.

Documentation is sourced from the official Alpine.js repository and redistributed under Alpine's MIT license, included at docs/ALPINE-LICENSE.txt.

License

MIT