Provides the complete Alpine.js documentation as resources, including directives, magic properties, global API, and official plugins, enabling AI assistants to accurately reference Alpine.js when building applications.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@alpine-mcp Show me how to use x-for directive"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Tool | Purpose |
| Search individual documentation pages with qmd's BM25 index |
| Read a complete page returned by search |
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.
Related MCP server: Vue Docs MCP
alpine-mcp requires Node.js 22 or newer.
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 mcp add alpine -- npx -y alpine-mcpcodex mcp add alpine -- npx -y alpine-mcpOr add it directly to ~/.codex/config.toml:
[mcp_servers.alpine]
command = "npx"
args = ["-y", "alpine-mcp"]Add to ~/.cursor/mcp.json or .cursor/mcp.json:
{
"mcpServers": {
"alpine": {
"command": "npx",
"args": ["-y", "alpine-mcp"]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"alpine": {
"command": "npx",
"args": ["-y", "alpine-mcp"]
}
}
}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"]
}
}
}Add a local stdio server through the extension's MCP settings using npx as the command and -y alpine-mcp as the arguments.
npx -y alpine-mcpEach server process builds a small temporary qmd index at startup. Search is lexical and does not download qmd's optional embedding or reranking models.
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."
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 generateRefresh from a specific release or commit:
ALPINE_REF=v3.14.9 npm run generateA 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 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.
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.
git clone https://github.com/BillyNoyes/alpine-mcp.git
cd alpine-mcp
npm install
npm test
npm run typecheck
npm run buildFor 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.
MIT
Read one complete Alpine.js documentation page returned by search_alpine_docs.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Document path such as directives/transition.md. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry behavioral disclosure. It says 'Read' which implies read-only, but doesn't mention return format, error handling, or any side effects. Minimal disclosure beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action and source, no wasted words. Ideal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description covers the core action and workflow, but doesn't specify the return format or behavior on invalid paths. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'path' parameter, and the description adds no additional semantics about the parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Read' and resource 'Alpine.js documentation page', and references the sibling tool that produces the path, distinguishing it from search_alpine_docs. Clear purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates it should be used after search_alpine_docs by saying 'returned by search_alpine_docs', but doesn't explicitly state when not to use it or alternatives beyond that. Provides context but not exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the latest bundled official Alpine.js documentation using qmd BM25 search.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Alpine.js concept, API, directive, or question to search for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals that the search is BM25 relevance-based and targets the latest bundled docs, but does not disclose what the results look like (snippets, file paths, relevance scores), how many results come back, or whether it is a safe read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the verb, resource, and search method with zero wasted words. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple two-parameter search tool, but with no output schema and no annotations, the description should state what results are returned and ideally hint that a search result can be followed by read_alpine_doc. The missing return-format guidance leaves an agent guessing how to consume the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% — the query parameter already has a useful description ('Alpine.js concept, API, directive, or question'), and the limit parameter is self-evident from its name, type, and default. The description adds no parameter detail but also needs little; the schema carries the load adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search), a precise resource (latest bundled official Alpine.js documentation), and the method (qmd BM25 search). This clearly distinguishes it from the sibling read_alpine_doc — one finds content, the other retrieves a specific document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to search versus when to read. The natural workflow — search to discover relevant docs, then read_alpine_doc to view a specific one — is only implied by the sibling name and the tool's verb, never stated. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0read_alpine_docsearch_alpine_docsScored across 2 tools
search_alpine_docs and read_alpine_doc have clearly distinct purposes: finding relevant pages versus retrieving full content. No overlap or ambiguity exists between them.
Both tools follow the same verb_noun convention with snake_case (search_alpine_docs, read_alpine_doc). The pattern is perfectly consistent and predictable.
With only 2 tools, the server is borderline per the calibration scale, though the narrow scope (documentation search/read) justifies a minimal surface. It feels slightly thin but not unreasonable.
For an Alpine.js documentation server, search and read cover the full user workflow end-to-end. There are no obvious gaps in the stated purpose—discovery via search and retrieval via read are complete.
The documentation, as a tool your agent can call: 950+ AI-dev guides. Search + fetch tools.
Tailor Platform for AI assistants: search, list and read the platform documentation.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Read-only canon of design and copy rules for AI agents to audit generated UI, served as resources.
