JIAD Bukku MCP

Production remote MCP bridge for Jusni Iljas Al Djabbar Sdn Bhd.

This version runs directly on Cloudflare Workers and does not use Cloudflare Containers or Docker. It is intended to fit the Cloudflare Workers Free plan for normal JIAD usage.

Production endpoint:

https://bukku.jusniiljas.com/mcp

Architecture

ChatGPT
   |
   | HTTPS + Bearer token
   v
bukku.jusniiljas.com/mcp
   |
   v
Cloudflare Worker
   |
   v
Bukku API

The upstream Bukku source is pinned as a Git submodule under vendor/bukku so the existing tool registry can be reused while replacing the local stdio transport with Cloudflare's HTTP MCP handler.

Related MCP server: zoho-bookkeeper-mcp

Security

The Worker expects three Cloudflare secrets:

• BUKKU_API_TOKEN

• BUKKU_COMPANY_SUBDOMAIN

• MCP_AUTH_TOKEN

No secret values belong in GitHub. /mcp requires Authorization: Bearer <MCP_AUTH_TOKEN>.

BUKKU_COMPANY_SUBDOMAIN must contain the company slug (for example, jiad). A matching HTTPS Bukku login URL is also accepted and normalized. Malformed configuration returns an authenticated HTTP 503 instead of sending an invalid company header to Bukku.

Verify or rotate MCP authentication on Windows

With PowerShell 7 and Node.js 24, run ./scripts/mcp-token.ps1 -Rotate to generate a cryptographic token, save it using Windows user-bound encryption, upload it through stdin, and verify that same value. The encrypted .mcp-token.dpapi file is ignored by Git and can only be decrypted by the same Windows user.

Run ./scripts/mcp-token.ps1 to verify again, or ./scripts/mcp-token.ps1 -Copy to copy the token for your MCP client's Bearer authentication field without printing it. Rotation requires updating clients that used the previous token.

Secret uploads can briefly continue serving the previous value. Verification retries initialization on HTTP 401 for up to 55 seconds; do not repeatedly rotate while propagation is pending. It checks public health, rejection of missing/incorrect credentials, MCP initialization, ping, all tool pages, and read-only currency/contact calls. Accounting records and tokens are not printed. A persistent failure exits unsuccessfully.

Run npm test and npm run typecheck before deploying code changes.

First-time setup

If you already cloned this repository before the Worker-only conversion, update it with:

git pull
git submodule update --init --recursive
npm install

If cloning fresh:

git clone --recurse-submodules https://github.com/anasmotawh/jiad-bukku-mcp.git
cd jiad-bukku-mcp
npm install

Authenticate Wrangler if needed:

npx wrangler login

Set secrets if they are not already present:

npx wrangler secret put BUKKU_API_TOKEN
npx wrangler secret put BUKKU_COMPANY_SUBDOMAIN
npx wrangler secret put MCP_AUTH_TOKEN

Deploy:

npm run deploy

Docker Desktop is not required for this version.

Endpoints

• GET /health - Worker health check, no accounting data.

• /mcp - authenticated MCP endpoint.

Upstream compatibility

The project currently reuses the upstream SDK v1 Bukku MCP server definitions through Cloudflare's createLegacyMcpHandler bridge. The upstream Bukku repository is pinned to commit 94c1a5c1668f451ef9b067b4d9d1fa73162a9401.

Most Bukku tools are ordinary HTTP API operations and are suitable for Workers. The upstream file-upload tool still assumes a local filesystem path; that specific tool is not expected to work correctly in the Worker runtime until it is redesigned to accept uploaded bytes rather than a machine-local path.

Cloudflare Free plan note

This project no longer declares Containers or Durable Objects. Cloudflare Workers Free limits still apply, particularly CPU time and daily request limits. If the full upstream tool registry proves too CPU-heavy during initialization, the next optimization is to split or lazily register tool groups rather than moving back to paid Containers.