112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
# Bilagun MCP server
|
|
|
|
Lets an AI assistant (Claude Desktop, Claude Code…) manage the Bilagun website in plain language,
|
|
through the website's REST API. Examples:
|
|
|
|
- "Crea la ficha de Kira, perra de unos 2 años, tamaño mediano, muy cariñosa. Déjala en borrador."
|
|
- "Marca a Txuri como adoptada."
|
|
- "Sube esta foto como principal de Hartz."
|
|
- "Añade 'arena para gatos' a lo que necesitamos, en castellano y en euskera."
|
|
|
|
## Tools
|
|
|
|
| Tool | What it does |
|
|
|---|---|
|
|
| `list_animals` | List animals (filter by language, status, species, text) |
|
|
| `get_animal` | Full record: story, profile, translation |
|
|
| `create_animal` | New animal (draft by default). With `language: "eu"` + `translationOf` it creates the Basque version and links it |
|
|
| `update_animal` | Change name, story, texts or profile fields |
|
|
| `set_status` | available / pending / adopted (both languages) |
|
|
| `upload_photo` | Upload a JPG/PNG/WebP (local file or URL) as main photo or to the gallery |
|
|
| `get_needs` / `set_needs` | Material needs list shown on the website (es / eu) |
|
|
|
|
It can't read the contact messages, delete content or change settings: that stays in the dashboard.
|
|
|
|
## Two ways to run it
|
|
|
|
| | Remote (recommended) | Local |
|
|
|---|---|---|
|
|
| Where it runs | On the server, next to WordPress (service `mcp` in `docker-compose.yml`) | On each person's computer |
|
|
| What each person needs | A URL and their own application password | Node 20+, this folder, `npm install` |
|
|
| Photos | By URL or dragged into the chat (base64) | Also local file paths |
|
|
|
|
In both cases every person uses **their own WordPress user and application password**. The remote
|
|
server stores no credentials: it checks them against WordPress on each request and forwards them,
|
|
so each person acts with their own permissions and access can be revoked from the dashboard.
|
|
|
|
## 1. Create the access (per person)
|
|
|
|
1. In WordPress create a user for the person (role **Editor** is enough).
|
|
2. *Users → Profile → Application passwords* → name it "Asistente" → **Add**. Copy it (shown only once).
|
|
3. Build the credential: base64 of `user:application-password`:
|
|
|
|
```bash
|
|
printf 'asistente:xxxx xxxx xxxx xxxx xxxx xxxx' | base64
|
|
```
|
|
|
|
## 2a. Remote server (Dokploy)
|
|
|
|
After deploying, in Dokploy add a **domain** to the service `mcp`, port **3000** (e.g. `mcp.gureametsabilagun.pireon.dev`, HTTPS on).
|
|
Check it: `https://mcp.gureametsabilagun.pireon.dev/healthz` → `{"ok":true}`.
|
|
|
|
**Claude Code (from this repository)**
|
|
|
|
The repo includes `.mcp.json`, so Claude Code offers the `bilagun` server when you open the project.
|
|
Each person only sets their own credential (never committed):
|
|
|
|
```bash
|
|
# ~/.zshrc or ~/.bashrc
|
|
export BILAGUN_MCP_AUTH="$(printf 'asistente:xxxx xxxx xxxx xxxx xxxx xxxx' | base64)"
|
|
# optional, if the MCP domain is different:
|
|
# export BILAGUN_MCP_URL="https://mcp.example.org/mcp"
|
|
```
|
|
|
|
Open a new terminal, run `claude` in the project, approve the `bilagun` server and check it with `/mcp`.
|
|
|
|
**Claude Code (any folder)**
|
|
|
|
```bash
|
|
claude mcp add --transport http --scope user bilagun https://mcp.gureametsabilagun.pireon.dev/mcp \
|
|
--header "Authorization: Basic <base64 from step 1>"
|
|
```
|
|
|
|
**Other clients** (Cursor, VS Code, Claude Desktop via `mcp-remote`…): use the same URL and header.
|
|
Clients that only allow a *Bearer token* can use `Authorization: Bearer <same base64>`.
|
|
|
|
> claude.ai web/mobile "custom connectors" require OAuth login, which this server does not implement yet.
|
|
|
|
Server settings (environment): `BILAGUN_URL` (internal WordPress URL, default `http://wordpress`),
|
|
`BILAGUN_PUBLIC_URL`, `RATE_LIMIT` (requests per minute and IP, default 120).
|
|
It exposes `POST /mcp` (Streamable HTTP, stateless) and `GET /healthz`.
|
|
|
|
## 2b. Local server (stdio)
|
|
|
|
```bash
|
|
cd mcp && npm install
|
|
claude mcp add bilagun \
|
|
--env BILAGUN_URL=https://gureametsabilagun.pireon.dev \
|
|
--env BILAGUN_USER=asistente \
|
|
--env "BILAGUN_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx" \
|
|
-- node /absolute/path/to/mcp/index.js
|
|
```
|
|
|
|
Claude Desktop (`claude_desktop_config.json`):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"bilagun": {
|
|
"command": "node",
|
|
"args": ["/absolute/path/to/mcp/index.js"],
|
|
"env": {
|
|
"BILAGUN_URL": "https://gureametsabilagun.pireon.dev",
|
|
"BILAGUN_USER": "asistente",
|
|
"BILAGUN_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Application passwords only work over HTTPS (the production site already is).
|