pi-astro-mcp

A pi extension that connects to the Astro Docs MCP server and exposes a search_astro_docs tool for searching the official Astro framework documentation.

Works on macOS, Linux, and Windows — no native binaries, no shell commands, just HTTPS.

Prerequisites

• Node.js 18 or later
• pi — install with:

npm install -g @mariozechner/pi-coding-agent

New to pi? Run pi after installing, then /login to authenticate with your preferred provider (Anthropic, OpenAI, etc.). See pi providers for the full list.

Install

pi install git:github.com/wdalhaj/pi-astro-mcp

That's it. pi install clones the repo and runs npm install automatically.

Pin to a specific version (tag or commit):

pi install git:github.com/wdalhaj/pi-astro-mcp@v1.0.0

Local path (for development):

pi install /path/to/pi-astro-mcp

Usage

Start pi as normal:

pi

The extension auto-connects to the Astro Docs MCP server on startup. You'll see a notification:

🚀 Astro Docs MCP: connected (1 tool)

Then just ask about Astro — the LLM will use search_astro_docs automatically:

How do I use Astro view transitions?
What are Astro content collections?
How does SSR work in Astro?
Explain Astro islands architecture

If the connection drops, the extension auto-reconnects on the next tool call.

Troubleshooting

"connection failed" on startup

The Astro Docs MCP server is at https://mcp.docs.astro.build/mcp. Make sure you have internet access and the server is reachable:

curl -s -o /dev/null -w "%{http_code}" https://mcp.docs.astro.build/mcp
# Should return 200 or 405

"Cannot find module" errors

Reinstall to re-fetch dependencies:

pi install git:github.com/wdalhaj/pi-astro-mcp

Extension not loading

Check that pi can see it:

pi list

If it doesn't appear, reinstall. If it does appear but doesn't work, try:

pi -e git:github.com/wdalhaj/pi-astro-mcp   # test without auto-discovery

Uninstall

pi remove git:github.com/wdalhaj/pi-astro-mcp

Development

Clone and test locally:

git clone https://github.com/wdalhaj/pi-astro-mcp.git
cd pi-astro-mcp
npm install

# Test with the local extension
pi -e ./extensions/index.ts

# Or install as a local package
pi install /path/to/pi-astro-mcp

How It Works

The extension uses the MCP Streamable HTTP transport to connect to the remote Astro Docs MCP server. No local server process is needed — the extension connects directly over HTTPS on each session start.

pi  →  extension  →  StreamableHTTPClientTransport  →  https://mcp.docs.astro.build/mcp

The MCP server exposes a single tool (search_astro_docs) which the extension registers with pi so the LLM can call it like any other tool.

Publish (maintainers)

npm version patch    # bump version
git push && git push --tags
npm publish

Users update with pi update git:github.com/wdalhaj/pi-astro-mcp.

License

MIT