# GeoBuddy MCP — Claude Desktop Installer (.mcpb)

This folder builds the one-click Claude Desktop installer for GeoBuddy's MCP
endpoint. Customers download the `.mcpb` file, double-click it, and enter
their site URL + API key (from **GeoBuddy > AI / MCP** in wp-admin) — Claude
Desktop handles the rest.

## How it works

`server/index.js` is a small stdio-to-HTTP bridge: Claude Desktop speaks
newline-delimited JSON-RPC on stdin/stdout, and the bridge POSTs each message
to `<site_url>/wp-json/geobuddy-mcp/v1/mcp` with the `X-MCP-Key` header. It
carries the `Mcp-Session-Id` returned by `initialize` on every later request
and swallows the `202` replies the endpoint sends for notifications.

The site URL, API key, and self-signed-certificate toggle reach the bridge as
environment variables (`GEOBUDDY_SITE_URL`, `GEOBUDDY_API_KEY`,
`GEOBUDDY_ALLOW_INSECURE_SSL`) via the manifest's `user_config` substitution,
which keeps the key out of the process command line.

It deliberately uses only Node built-ins. An earlier version shelled out to
`npx mcp-remote`, which failed in Claude Desktop: it performs OAuth discovery
the endpoint does not implement, rejects `http://` URLs and untrusted
certificates, and calls `process.exit` on any connection error — surfacing as
"Server transport closed unexpectedly" with no explanation. The bridge instead
stays alive and returns a JSON-RPC error describing what went wrong.

## Building

From the plugin root:

```bash
npm run build:mcpb
```

This validates `manifest.json` and packs `geobuddy-mcp.mcpb` for distribution.
The build-time `mcpb` CLI (`@anthropic-ai/mcpb`) is invoked via `npx`; there is
nothing to install for either developers or customers.

## Bumping version

Keep `manifest.json`'s `version` in sync with `GEOBUDDY_VERSION` in
`geobuddy.php` when cutting a new plugin release.