enable-nz-mcp

A public, hosted MCP server that exposes the content of enable.co.nz as searchable tools, connectable from Copilot Studio, VS Code Copilot, Claude Desktop, or any MCP client.

This is a personal portfolio project. It is not affiliated with Enable New Zealand or any employer, and reads only publicly available content from a public website.

• Server: https://enable-nz-mcp.duckdns.org/mcp (Streamable HTTP)
• Health check: https://enable-nz-mcp.duckdns.org/health

---

Architecture

GitHub Actions (weekly cron)
  └─ crawl enable.co.nz → build index.db.new
     └─ rsync over SSH → droplet:/opt/enable-nz-mcp/data/index.db.new
        └─ atomic mv → index.db

DigitalOcean droplet (Ubuntu 24.04, Sydney)
  ├─ Caddy  → TLS termination + reverse proxy on enable-nz-mcp.duckdns.org
  └─ pm2    → node dist/server.js  (port 8081, localhost only)
                └─ opens a fresh SQLite read connection per query

The server never caches the index in memory — every tool call opens a fresh readonly connection against index.db on disk. A weekly crawl rebuilds the index and swaps it in with a single atomic mv, so the index refreshes with zero downtime and no restart.

Read-only in every direction: the crawler only reads enable.co.nz, and the MCP tools only read the local SQLite index. No write operations of any kind.

---

Tools

search_enable_nz

Full-text search across enable.co.nz.

Param	Type	Required	Notes
query	string	yes	Search terms
limit	integer	no	Default 5, max 20
section	string	no	Restrict to one section, e.g. services

Returns matching pages ranked by relevance, each with url, title, section, and a highlighted snippet.

get_page

Retrieve one page's full text by URL.

Param	Type	Required
url	string	yes

Returns url, title, section, description, content, and crawled_at. Content over ~15,000 characters is truncated, with truncated: true in the response.

list_sections

No input. Lists the site's top-level sections with page counts, and the index's crawled_at timestamp — useful for orienting before a search, or checking how fresh the data is.

---

Example queries

Once connected, ask your MCP client things like:

• "Search enable.co.nz for wheelchair funding information."
• "What sections does the enable.co.nz index cover?"
• "Get the full content of https://www.enable.co.nz/services and summarise it."

---

Connecting an MCP client

Copilot Studio

1. Open your agent → Tools → Add a tool → New tool → Model Context Protocol.
2. Server name: enable-nz-mcp (or anything you like — this is just a label).
3. Server URL: https://enable-nz-mcp.duckdns.org/mcp
4. Authentication: No authentication (leave as-is unless the server has API_KEY set, in which case choose an API key/bearer auth option and supply it).
5. Create → Copilot Studio connects over Streamable HTTP (the only transport it supports since it dropped SSE in August 2025) and lists search_enable_nz, get_page, and list_sections. Add the tool to your agent and test with a prompt like "search enable.co.nz for wheelchair funding".

VS Code Copilot

1. Open the Command Palette → MCP: Add Server.
2. Choose HTTP and enter https://enable-nz-mcp.duckdns.org/mcp.
3. VS Code will list search_enable_nz, get_page, and list_sections as available tools once connected.

Claude Desktop

1. Settings → Connectors → Add custom connector.
2. URL: https://enable-nz-mcp.duckdns.org/mcp.
3. Claude will negotiate the Streamable HTTP transport automatically.

Any other MCP client

Point it at https://enable-nz-mcp.duckdns.org/mcp using the Streamable HTTP transport. If API_KEY is set on the server, send Authorization: Bearer <key>.

---

Local development

npm ci
cp .env.example .env        # edit as needed

npm run crawl                # builds data/index.db.new
mv data/index.db.new data/index.db

npm run dev                  # starts the server with tsx, reading .env

Test the running server with MCP Inspector:

npx @modelcontextprotocol/inspector
# connect to http://127.0.0.1:8081/mcp

Or smoke-test by hand:

curl http://127.0.0.1:8081/health

curl -X POST http://127.0.0.1:8081/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Run the test suite:

npm test

---

Deployment

The server runs on an existing DigitalOcean droplet under its own unprivileged system user (mcpsvc), isolated from other services on the same box — mcpsvc has no sudo and no read access outside /opt/enable-nz-mcp. See deploy/ecosystem.config.cjs for the pm2 process config and deploy/Caddyfile.example for the reverse-proxy block.

Both pm2 and Caddy config changes need root, so mcpsvc can go no further than pm2 save on its own — an administrator has to run pm2 startup (to persist the process across reboots) and install/reload the Caddy site block. Rate limiting is not currently applied at the Caddy layer: it requires the third-party caddy-ratelimit plugin, which isn't in this box's Caddy build.

The .github/workflows/refresh-index.yml workflow re-crawls the site weekly (Sunday 02:00 UTC, or manually via workflow_dispatch), gates on a minimum page count/size, and deploys the new index via rsync + an atomic mv over SSH. It needs three repository secrets: DEPLOY_SSH_KEY, DEPLOY_HOST, DEPLOY_USER — using a dedicated deploy keypair restricted via a command= directive in authorized_keys so it can only run the rsync/mv, not an arbitrary shell.

---

Out of scope for v1

• Embeddings / semantic search (keyword search via SQLite FTS5 is sufficient for one marketing site)
• Headless-browser rendering
• Multi-site support
• Write operations of any kind
• User-level auth or per-tenant isolation