# Install Wormhole with Claude — paste this to your AI agent

**You (a human) don't need to know PHP, servers, or config.** Copy everything below the
line and paste it to Claude (Claude Code, or any agent with filesystem + shell access).
It will set up a wormhole for your wiki and hand you back a URL to share.

If you don't have a wiki yet, that's fine — Claude can point it at any folder of markdown.

---

## ▼▼▼ COPY FROM HERE — paste to your Claude ▼▼▼

You are installing **Wormhole**, a small MCP server that lets other people's AI agents
reason over a markdown wiki I choose to share — through a per-consumer access gate, with
nothing shared unless I say so. The reference implementation is a single PHP file. Your job
is to install and configure it for me, and hand me back a URL to share. Work carefully;
this exposes my knowledge, so **default to private and confirm before anything is shared.**

Do this, checking with me at each decision:

1. **Get the code.** Download the package from `https://www.davidbicho.com/wormhole/wormhole-server.zip`
   and unzip it. It contains: `mcp.php` (the server), `_wormhole-access.example.md` (the gate
   template), `tokens.example.php`, `new-token.php` (a token CLI), `.htaccess`, and a `README.md`.
   Read the README first — it is the source of truth for how the gate works.

2. **Find my vault.** Ask me where my markdown wiki lives (an Obsidian vault, a folder of
   `.md` files, etc.). Note the **vault root** and the **subfolder that holds the linked
   pages** — by convention that's `Wiki/`, but confirm the real name with me. Do NOT assume.

3. **Place the files.** Copy `mcp.php`, `_wormhole-access.md` (copied from the example),
   and (only if I want private sharing) `tokens.php` into my **vault root** — next to my
   `Wiki/` folder. My existing files are NOT moved. `mcp.php`/`tokens.php` are ignored by
   the server (not `.md`), and `_`-prefixed files are never shared.

4. **Set the gate — ASK ME, don't guess.** Edit `_wormhole-access.md`:
   - Set `owner:` to my name (used to attribute my knowledge to me when an agent answers).
   - Set `wiki-path:` to my pages folder (default `Wiki`; or `.` for the vault root).
   - **Ask me: public or private?**
     - *Public* (anyone with the URL, no token): add a `public:` block. **Warn me that with
       `"*"` every current AND future page is shared unless denied.** Help me add `deny:`
       filename globs (e.g. `"private*"`, `"*ekonomi*"`) and `deny-content:` words (e.g.
       `kontonummer`) for anything sensitive. If my vault has a `Raw/` or drafts folder,
       remind me `wiki-path` already excludes it — but double-check.
     - *Private* (specific people): add a named consumer block instead of `public:`, and go
       to step 5 for a token. No `public:` block = nothing is reachable without a token.
   - **Before finishing, show me the final gate and the list of pages it would expose, and
     get my explicit OK.** If I'm sharing my whole wiki, list what would be private too.

5. **Tokens (only if private).** Run `php new-token.php <vault-root> <consumer-name>` to mint
   a bearer token per person I'm sharing with. Give me each token to hand out. Never print
   tokens into any file that gets served.

6. **Make it reachable.** My files must be served by PHP over HTTPS.
   - If I already run a web server (Apache/nginx with PHP) serving my vault, the URL is
     `https://<my-domain>/<path-to-vault>/mcp.php`. The included `.htaccess` handles the
     auth header and protects secret files — make sure it's in place.
   - If I don't have a web server, offer options: run `php -S 0.0.0.0:8080` in the vault
     for a quick local/LAN test (tell me it's not production), or set up a proper host.
     Explain the trade-offs; don't silently expose my machine to the internet.

7. **Verify it works.** Test the endpoint over HTTP before telling me it's ready:
   - `initialize` returns a result with my `owner` in the instructions.
   - `tools/list` shows `list_shared_pages`, `search_pages`, `get_page`.
   - `tools/call list_shared_pages` returns exactly the pages I approved — and does NOT
     return anything I marked private. **Explicitly test that a private page is blocked.**
   - Without a token: returns the `public:` set (or nothing, if I chose private).

8. **Hand me the result.** Give me:
   - The **URL** to share: `https://…/mcp.php`
   - For each person, their **token** (if private).
   - The one-line command they run to connect:
     `claude mcp add my-brain <URL> --transport http` (add
     `--header "Authorization: Bearer <token>"` if private).

Throughout: I own the security. You provide the mechanism and warn me clearly; you never
decide on your own that something is safe to share. When in doubt, share less and ask.

## ▲▲▲ COPY TO HERE ▲▲▲

---

That's it. Your Claude does the PHP, the config, and the testing — you just answer its
questions and get a URL. More at [davidbicho.com/wormhole](https://www.davidbicho.com/wormhole).