@centry-digital/bukku-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Centry Digital Sdn. Bhd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,269 @@
+# Bukku MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@centry-digital/bukku-mcp)](https://www.npmjs.com/package/@centry-digital/bukku-mcp)
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects AI assistants to [Bukku](https://bukku.my), a Malaysian accounting platform. This gives your AI the ability to read, create, and manage your accounting data — invoices, bills, payments, contacts, products, and more.
+
+## What can it do?
+
+With this MCP server connected, you can ask your AI things like:
+
+- "List my unpaid sales invoices"
+- "Create an invoice for RM 5,000 to Acme Corp for consulting services"
+- "Show me all purchase bills from last month"
+- "Record a bank transfer of RM 10,000 from Maybank to CIMB"
+- "Create a new contact for my supplier"
+- "Upload this receipt and attach it to the purchase bill"
+
+The server exposes **173 tools** covering the full Bukku API:
+
+| Category | Tools | What you can do |
+|----------|-------|-----------------|
+| **Sales** | 42 | Quotes, orders, delivery orders, invoices, credit notes, payments, refunds |
+| **Purchases** | 36 | Purchase orders, bills, credit notes, goods received notes, payments, refunds |
+| **Banking** | 18 | Money in, money out, bank transfers |
+| **Contacts** | 12 | Customers, suppliers, contact groups |
+| **Products** | 18 | Products, product bundles, product groups |
+| **Accounting** | 13 | Journal entries, chart of accounts |
+| **Files** | 3 | Upload and manage file attachments |
+| **Organisation** | 21 | Locations, tags, tag groups |
+| **Reference Data** | 10 | Tax codes, currencies, payment methods, terms, and more |
+
+## Quick Start
+
+Get up and running in under 2 minutes.
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org) v18 or later
+- A [Bukku](https://bukku.my) account with API access enabled
+- An AI client that supports MCP (e.g. [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code))
+
+### Step 1: Get your Bukku API token
+
+1. Log into your Bukku account
+2. Go to **Control Panel > Integrations > API Access**
+3. Generate a new API token (or copy your existing one)
+4. Note your company subdomain — e.g. `mycompany` from `mycompany.bukku.my`
+
+### Step 2: Add to your AI client
+
+For Claude Desktop, open your config file:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add this configuration:
+
+```json
+{
+  "mcpServers": {
+    "bukku": {
+      "command": "npx",
+      "args": ["-y", "@centry-digital/bukku-mcp"],
+      "env": {
+        "BUKKU_API_TOKEN": "your-token-here",
+        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
+      }
+    }
+  }
+}
+```
+
+### Step 3: Restart your AI client
+
+Quit and reopen Claude Desktop. That's it — you're ready to go!
+
+## Installation
+
+### npx (recommended)
+
+The quickest way to use the server is with `npx`. No installation needed — it downloads and runs the latest version automatically:
+
+```bash
+npx @centry-digital/bukku-mcp
+```
+
+This is what the Quick Start configuration uses. `npx` ensures you're always running the latest version without manual updates.
+
+### npm global install
+
+If you prefer a persistent installation:
+
+```bash
+npm install -g @centry-digital/bukku-mcp
+```
+
+Then update your AI client configuration to use the installed command instead:
+
+```json
+{
+  "mcpServers": {
+    "bukku": {
+      "command": "bukku-mcp",
+      "env": {
+        "BUKKU_API_TOKEN": "your-token-here",
+        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BUKKU_API_TOKEN` | Yes | Your Bukku API token from Control Panel > Integrations > API Access |
+| `BUKKU_COMPANY_SUBDOMAIN` | Yes | Your company subdomain (e.g. `mycompany` from `mycompany.bukku.my`) |
+
+### Claude Desktop
+
+Open your configuration file:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+**Using npx (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "bukku": {
+      "command": "npx",
+      "args": ["-y", "@centry-digital/bukku-mcp"],
+      "env": {
+        "BUKKU_API_TOKEN": "your-token-here",
+        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
+      }
+    }
+  }
+}
+```
+
+**If you installed globally:**
+
+```json
+{
+  "mcpServers": {
+    "bukku": {
+      "command": "bukku-mcp",
+      "env": {
+        "BUKKU_API_TOKEN": "your-token-here",
+        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
+      }
+    }
+  }
+}
+```
+
+After updating the config, restart Claude Desktop.
+
+### Claude Code
+
+Add to `.claude/settings.json` in your home directory or project:
+
+**Using npx (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "bukku": {
+      "command": "npx",
+      "args": ["-y", "@centry-digital/bukku-mcp"],
+      "env": {
+        "BUKKU_API_TOKEN": "your-token-here",
+        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
+      }
+    }
+  }
+}
+```
+
+**If you installed globally:**
+
+```json
+{
+  "mcpServers": {
+    "bukku": {
+      "command": "bukku-mcp",
+      "env": {
+        "BUKKU_API_TOKEN": "your-token-here",
+        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Any client that supports the [MCP stdio transport](https://modelcontextprotocol.io/docs/concepts/transports) can use this server. Use the `npx @centry-digital/bukku-mcp` command with the two environment variables shown above.
+
+## Troubleshooting
+
+**"Configuration Error" on startup**
+- Check that both `BUKKU_API_TOKEN` and `BUKKU_COMPANY_SUBDOMAIN` are set in your client config
+- Verify the environment variables are inside the `"env"` object
+
+**"Token validation failed"**
+- Your API token may be invalid or expired
+- Log into Bukku and regenerate your token at Control Panel > Integrations > API Access
+
+**Server doesn't appear in your AI client**
+- Verify your configuration JSON syntax is correct (no trailing commas)
+- Make sure you've restarted your AI client after editing the config
+- Check that Node.js v18 or later is installed: `node --version`
+
+**"Could not resolve package" with npx**
+- Check that you have Node.js v18 or later installed
+- Verify your network connection and proxy settings if applicable
+- Try running `npm view @centry-digital/bukku-mcp` to confirm the package is accessible
+
+**Permission errors with global install**
+- Consider using `npx` instead (no installation needed)
+- Or fix npm permissions: [https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
+
+## Development
+
+Want to contribute or run from source? Here's how to set up your development environment.
+
+### Clone and build
+
+```bash
+git clone https://github.com/centry-digital/bukku-mcp.git
+cd bukku-mcp
+npm install
+npm run build
+```
+
+### Commands
+
+```bash
+npm run build    # Compile TypeScript
+npm test         # Run tests
+npm start        # Start server (requires env vars)
+```
+
+### Project structure
+
+```
+src/
+├── client/       # Bukku API HTTP client
+├── config/       # Environment validation
+├── errors/       # Error handling and transformation
+├── tools/        # MCP tool definitions (one folder per category)
+│   ├── sales/
+│   ├── purchases/
+│   ├── banking/
+│   ├── contacts/
+│   ├── products/
+│   ├── accounting/
+│   ├── files/
+│   └── ...
+└── index.ts      # Server entry point
+```
+
+## License
+
+MIT

package/build/client/bukku-client.d.ts

@@ -0,0 +1,62 @@
+import type { Env } from "../config/env.js";
+/**
+ * HTTP client for Bukku API.
+ * Handles authentication via Bearer token and Company-Subdomain header.
+ * Base URL: https://api.bukku.my
+ */
+export declare class BukkuClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly subdomain;
+    constructor(env: Env);
+    /**
+     * Build headers for all requests.
+     * CRITICAL: Never log the actual token value - use "Bearer ***" for debugging.
+     */
+    private getHeaders;
+    /**
+     * Map file extensions to MIME types for common file types.
+     * Returns null for unknown extensions.
+     */
+    private getMimeType;
+    /**
+     * Build URL with query parameters.
+     */
+    private buildUrl;
+    /**
+     * GET request with optional query parameters.
+     */
+    get(path: string, params?: Record<string, string | number | undefined>): Promise<unknown>;
+    /**
+     * POST request with JSON body.
+     */
+    post(path: string, body: unknown): Promise<unknown>;
+    /**
+     * PUT request with JSON body.
+     */
+    put(path: string, body: unknown): Promise<unknown>;
+    /**
+     * PATCH request with JSON body (for status updates).
+     */
+    patch(path: string, body: unknown): Promise<unknown>;
+    /**
+     * DELETE request.
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * POST multipart/form-data request for file uploads.
+     * Reads file from disk and sends as multipart form data.
+     * CRITICAL: Does NOT manually set Content-Type - fetch sets it automatically with boundary.
+     *
+     * @param path - API endpoint path
+     * @param filePath - Absolute path to file on disk
+     * @returns API response
+     */
+    postMultipart(path: string, filePath: string): Promise<unknown>;
+    /**
+     * Validate token on startup by making a lightweight API call.
+     * Uses GET /contacts with page_size=1 to verify authentication.
+     * Exits process if token is invalid (401).
+     */
+    validateToken(): Promise<void>;
+}

package/build/client/bukku-client.js

@@ -0,0 +1,195 @@
+import { log } from "../utils/logger.js";
+import { readFile } from "node:fs/promises";
+import { basename, extname } from "node:path";
+/**
+ * HTTP client for Bukku API.
+ * Handles authentication via Bearer token and Company-Subdomain header.
+ * Base URL: https://api.bukku.my
+ */
+export class BukkuClient {
+    baseUrl = "https://api.bukku.my";
+    token;
+    subdomain;
+    constructor(env) {
+        this.token = env.BUKKU_API_TOKEN;
+        this.subdomain = env.BUKKU_COMPANY_SUBDOMAIN;
+    }
+    /**
+     * Build headers for all requests.
+     * CRITICAL: Never log the actual token value - use "Bearer ***" for debugging.
+     */
+    getHeaders(includeContentType = false) {
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            "Company-Subdomain": this.subdomain,
+            Accept: "application/json",
+        };
+        if (includeContentType) {
+            headers["Content-Type"] = "application/json";
+        }
+        return headers;
+    }
+    /**
+     * Map file extensions to MIME types for common file types.
+     * Returns null for unknown extensions.
+     */
+    getMimeType(extension) {
+        const mimeMap = {
+            ".pdf": "application/pdf",
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".jpeg": "image/jpeg",
+            ".gif": "image/gif",
+            ".txt": "text/plain",
+            ".csv": "text/csv",
+            ".json": "application/json",
+            ".xml": "application/xml",
+            ".zip": "application/zip",
+        };
+        return mimeMap[extension.toLowerCase()] || null;
+    }
+    /**
+     * Build URL with query parameters.
+     */
+    buildUrl(path, params) {
+        const url = new URL(path, this.baseUrl);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined) {
+                    url.searchParams.append(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    /**
+     * GET request with optional query parameters.
+     */
+    async get(path, params) {
+        const url = this.buildUrl(path, params);
+        const response = await fetch(url, {
+            method: "GET",
+            headers: this.getHeaders(),
+        });
+        if (!response.ok) {
+            throw response;
+        }
+        return response.json();
+    }
+    /**
+     * POST request with JSON body.
+     */
+    async post(path, body) {
+        const url = this.buildUrl(path);
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.getHeaders(true),
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw response;
+        }
+        return response.json();
+    }
+    /**
+     * PUT request with JSON body.
+     */
+    async put(path, body) {
+        const url = this.buildUrl(path);
+        const response = await fetch(url, {
+            method: "PUT",
+            headers: this.getHeaders(true),
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw response;
+        }
+        return response.json();
+    }
+    /**
+     * PATCH request with JSON body (for status updates).
+     */
+    async patch(path, body) {
+        const url = this.buildUrl(path);
+        const response = await fetch(url, {
+            method: "PATCH",
+            headers: this.getHeaders(true),
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw response;
+        }
+        return response.json();
+    }
+    /**
+     * DELETE request.
+     */
+    async delete(path) {
+        const url = this.buildUrl(path);
+        const response = await fetch(url, {
+            method: "DELETE",
+            headers: this.getHeaders(),
+        });
+        if (!response.ok) {
+            throw response;
+        }
+    }
+    /**
+     * POST multipart/form-data request for file uploads.
+     * Reads file from disk and sends as multipart form data.
+     * CRITICAL: Does NOT manually set Content-Type - fetch sets it automatically with boundary.
+     *
+     * @param path - API endpoint path
+     * @param filePath - Absolute path to file on disk
+     * @returns API response
+     */
+    async postMultipart(path, filePath) {
+        const url = this.buildUrl(path);
+        // Read file from disk
+        const fileBuffer = await readFile(filePath);
+        const fileName = basename(filePath);
+        const fileExtension = extname(filePath);
+        // Determine MIME type, fallback to generic binary
+        const mimeType = this.getMimeType(fileExtension) || "application/octet-stream";
+        // Create File object and FormData
+        const file = new File([fileBuffer], fileName, { type: mimeType });
+        const form = new FormData();
+        form.append("file", file);
+        // Get auth headers WITHOUT Content-Type (fetch sets it with boundary)
+        const headers = this.getHeaders(false);
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: form,
+        });
+        if (!response.ok) {
+            throw response;
+        }
+        return response.json();
+    }
+    /**
+     * Validate token on startup by making a lightweight API call.
+     * Uses GET /contacts with page_size=1 to verify authentication.
+     * Exits process if token is invalid (401).
+     */
+    async validateToken() {
+        try {
+            await this.get("/contacts", { page_size: 1 });
+            log("Token validated successfully");
+        }
+        catch (error) {
+            if (error instanceof Response && error.status === 401) {
+                log("Authentication Error\n");
+                log("The provided BUKKU_API_TOKEN is invalid or expired.\n");
+                log("Please check:");
+                log("  1. Token is copied correctly (no extra spaces)");
+                log("  2. API Access is enabled in Bukku Control Panel -> Integrations");
+                log("  3. Token has not been revoked or regenerated\n");
+                process.exit(1);
+            }
+            // For other errors, log and exit
+            log("Failed to validate token:", error);
+            process.exit(1);
+        }
+    }
+}

package/build/config/env.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * Environment variable schema.
+ * Required vars:
+ * - BUKKU_API_TOKEN: Bearer token from Bukku API settings
+ * - BUKKU_COMPANY_SUBDOMAIN: Company subdomain (e.g., 'mycompany' from mycompany.bukku.my)
+ */
+declare const envSchema: z.ZodObject<{
+    BUKKU_API_TOKEN: z.ZodString;
+    BUKKU_COMPANY_SUBDOMAIN: z.ZodString;
+}, z.core.$strip>;
+export type Env = z.infer<typeof envSchema>;
+/**
+ * Validates environment variables on startup.
+ * Exits process with code 1 if validation fails.
+ * Prints setup checklist to stderr on failure.
+ */
+export declare function validateEnv(): Env;
+export {};

package/build/config/env.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { log } from "../utils/logger.js";
+/**
+ * Environment variable schema.
+ * Required vars:
+ * - BUKKU_API_TOKEN: Bearer token from Bukku API settings
+ * - BUKKU_COMPANY_SUBDOMAIN: Company subdomain (e.g., 'mycompany' from mycompany.bukku.my)
+ */
+const envSchema = z.object({
+    BUKKU_API_TOKEN: z.string().min(1, "BUKKU_API_TOKEN is required"),
+    BUKKU_COMPANY_SUBDOMAIN: z.string().min(1, "BUKKU_COMPANY_SUBDOMAIN is required"),
+});
+/**
+ * Validates environment variables on startup.
+ * Exits process with code 1 if validation fails.
+ * Prints setup checklist to stderr on failure.
+ */
+export function validateEnv() {
+    const result = envSchema.safeParse(process.env);
+    if (!result.success) {
+        log("Configuration Error\n");
+        log("Missing required environment variables:");
+        for (const issue of result.error.issues) {
+            log(`  - ${issue.path.join(".")}: ${issue.message}`);
+        }
+        log("\nSetup checklist:");
+        log("  1. Go to Bukku web app -> Control Panel -> Integrations");
+        log("  2. Turn on API Access and copy the Access Token");
+        log("  3. Set BUKKU_API_TOKEN=<your-token>");
+        log("  4. Set BUKKU_COMPANY_SUBDOMAIN=<your-subdomain>");
+        log("     (e.g., 'mycompany' from mycompany.bukku.my)");
+        log("  5. Restart Claude Desktop\n");
+        process.exit(1);
+    }
+    return result.data;
+}

package/build/errors/transform.d.ts

@@ -0,0 +1,14 @@
+/**
+ * HTTP to MCP Error Transformation
+ * Converts HTTP error responses into conversational MCP error messages
+ */
+export interface MCPErrorResponse {
+    isError: true;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    [key: string]: unknown;
+}
+export declare function transformHttpError(status: number | null, body: unknown, operation: string): MCPErrorResponse;
+export declare function transformNetworkError(error: unknown, operation: string): MCPErrorResponse;