Add a read-only Pi Index MCP server

[bubbleptr]

Summary

Agents can query the Pi Index directory over a read-only stdio MCP server. Search uses the same case-insensitive AND match as https://piindex.dev/?q=. Every result includes a piindexUrl. There are no write tools, no auth, and no analytics. The only network call is a GET of the public catalog.

This PR does not publish to npm or the MCP Registry, and it should not be merged by the agent that opened it.

Package name

Checked the npm registry on 2026-10-15. All three names 404:

• piindex-mcp (chosen)
• @bubbleptr/piindex-mcp
• @piindex/mcp

piindex-mcp is unscoped so clients can run npx -y piindex-mcp. The registry server name is io.github.bubbleptr/piindex, which matches GitHub auth for the bubbleptr account. package.json mcpName is the same string.

Data

The site now builds /catalog.json from the README catalog, stats snapshot, and published guides (178 packages in this snapshot). The MCP server fetches https://piindex.dev/catalog.json, caches it in memory for 15 minutes, and falls back to mcp/catalog.snapshot.json if the site is unreachable. Queries are not sent anywhere.

No streamable-HTTP endpoint. The site is a static Astro build (output: 'static') deployed as files on Vercel. A remote MCP transport would need a server runtime on each request, which is a hosting change rather than a small static route.

Tools

Tool	Behavior
search_packages	Keyword search, optional category, same rules as ?q= and ?category=.
get_package	Description (EN + ZH), categories, project / repo / npm links, install command, stars and weekly downloads, guide links.
list_categories	Kinds and categories with counts and piindex.dev URLs.
list_packages	Packages in one category or kind.
list_guides	Topic pages, category guides, and package guides.

piindexUrl is the package guide when one is published, otherwise the directory search for that name. guideUrl is set only for a package guide. Topic and category guides that mention the package are listed on guides.

Sample output

Captured locally against the real catalog snapshot (statsGeneratedAt 2026-10-12T09:16:23.459Z). search_packages with query: "子代理", category: "subagents", limit: 2 returned 9 matches. First page:

{
  "directoryUrl": "https://piindex.dev/?q=%E5%AD%90%E4%BB%A3%E7%90%86&category=subagents",
  "total": 9,
  "packages": [
    {
      "name": "pi-subagents",
      "description": "Community subagent extension maintained by Nico Bailon (nicobailon), with chain, parallel execution, and TUI clarification.",
      "descriptionZh": "Nico Bailon（nicobailon）维护的社区子代理扩展，支持链式、并行执行和 TUI 澄清。",
      "install": "pi install npm:pi-subagents",
      "stars": 3905,
      "weeklyDownloads": 99943,
      "piindexUrl": "https://piindex.dev/?q=pi-subagents",
      "guideUrl": null
    },
    {
      "name": "@tintinweb/pi-subagents",
      "description": "Claude Code-style subagents using host SDK sessions, with parallel background tasks, live widgets and optional Git worktree isolation.",
      "install": "pi install npm:@tintinweb/pi-subagents",
      "stars": 1290,
      "weeklyDownloads": 7918,
      "piindexUrl": "https://piindex.dev/packages/tintinweb-pi-subagents/",
      "guideUrl": "https://piindex.dev/packages/tintinweb-pi-subagents/"
    }
  ]
}

get_package for pi-web-access:

{
  "name": "pi-web-access",
  "description": "Web search, URL fetching, PDF extraction and YouTube analysis. Keyless search defaults to Exa MCP with configured fallbacks; DuckDuckGo is explicit-only.",
  "descriptionZh": "Web 搜索、URL 获取、PDF 提取与 YouTube 理解；默认免 Key 搜索使用 Exa MCP，按配置降级，DuckDuckGo 需显式选择。",
  "install": "pi install npm:pi-web-access",
  "projectUrl": "https://github.com/nicobailon/pi-web-access",
  "repoUrl": "https://github.com/nicobailon/pi-web-access",
  "npmUrl": "https://www.npmjs.com/package/pi-web-access",
  "stars": 1620,
  "weeklyDownloads": 191682,
  "weeklyTrendPercent": -17,
  "piindexUrl": "https://piindex.dev/packages/pi-web-access/",
  "guideUrl": "https://piindex.dev/packages/pi-web-access/",
  "guides": [
    {
      "kind": "category",
      "slug": "web-access-search",
      "piindexUrl": "https://piindex.dev/categories/web-access-search/"
    },
    {
      "kind": "package",
      "slug": "pi-web-access",
      "piindexUrl": "https://piindex.dev/packages/pi-web-access/"
    }
  ]
}

list_categories includes Web Access & Search as https://piindex.dev/?category=web-access-search with guide https://piindex.dev/categories/web-access-search/ (8 packages). list_guides returns the two topics (jev, pi-durable), the two category guides, and the three package guides.

A search for Brave returns only @juicesharp/rpiv-web-tools. Brave missing returns nothing, matching the directory's AND behavior.

Tests

• site: bun run validate (unit tests, astro check, static build including /catalog.json, rendered tests).
• mcp: npm test — 12 tests. Tools run in-memory and over the stdio entrypoint against the real snapshot. server.json validates against https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json.

Publish steps

Do these after this PR is merged and the site deploy has published https://piindex.dev/catalog.json. Until that URL is live, the server still answers from the bundled snapshot. Nothing here has been published.

From a checkout of main, with Bun available and the site dependencies installed:

cd site
bun install --frozen-lockfile
cd ../mcp
npm login
npm publish

npm publish runs prepublishOnly, which refreshes catalog.snapshot.json from the README catalog and runs the tests before uploading. piindex-mcp is unscoped, so do not pass --access public.

Confirm the package is on npm and that its mcpName is io.github.bubbleptr/piindex:

npm view piindex-mcp mcpName version

Install mcp-publisher and log in with the GitHub account that owns bubbleptr (a different GitHub user cannot publish under io.github.bubbleptr):

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
sudo mv mcp-publisher /usr/local/bin/
cd mcp
mcp-publisher login github
mcp-publisher publish

mcp-publisher login github prints a device code. Authorize it at https://github.com/login/device as bubbleptr, then run mcp-publisher publish from mcp/ so it picks up server.json. npm must already show 0.1.0; the registry checks mcpName on the published package.

Confirm the listing:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.bubbleptr/piindex"

Install snippets for Cursor, Claude Desktop, VS Code, and Pi are in mcp/README.md (English, plus a short 中文 section).