@centry-digital/bukku-mcp 1.1.0 → 2.0.0

package/README.md

@@ -1,269 +0,0 @@
-# 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

@@ -1,62 +0,0 @@
-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

@@ -1,195 +0,0 @@
-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/errors/transform.d.ts

@@ -1,14 +0,0 @@
-/**
- * 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;

package/build/errors/transform.js

@@ -1,141 +0,0 @@
-/**
- * HTTP to MCP Error Transformation
- * Converts HTTP error responses into conversational MCP error messages
- */
-export function transformHttpError(status, body, operation) {
-    // Handle authentication errors (401)
-    if (status === 401) {
-        return {
-            isError: true,
-            content: [
-                {
-                    type: 'text',
-                    text: `Bukku authentication failed for "${operation}". The BUKKU_API_TOKEN environment variable is either missing or invalid. Please check your token and restart the server with the correct credentials.`,
-                },
-            ],
-        };
-    }
-    // Handle permission errors (403)
-    if (status === 403) {
-        return {
-            isError: true,
-            content: [
-                {
-                    type: 'text',
-                    text: `You don't have permission to "${operation}". Please check your Bukku account permissions and ensure you have access to this resource.`,
-                },
-            ],
-        };
-    }
-    // Handle not found errors (404)
-    if (status === 404) {
-        return {
-            isError: true,
-            content: [
-                {
-                    type: 'text',
-                    text: `I couldn't find that item when trying to "${operation}". Try listing the available items first to see what's accessible.`,
-                },
-            ],
-        };
-    }
-    // Handle validation errors (400, 422)
-    if (status === 400 || status === 422) {
-        const parsedBody = body;
-        const errors = parsedBody?.errors;
-        if (errors && typeof errors === 'object') {
-            // Multiple validation errors - show all at once
-            const errorMessages = Object.entries(errors)
-                .map(([field, messages]) => `  - ${field}: ${messages.join(', ')}`)
-                .join('\n');
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: 'text',
-                        text: `Validation failed for "${operation}":\n${errorMessages}\n\nPlease fix these issues and try again.`,
-                    },
-                ],
-            };
-        }
-        else {
-            // Single error message
-            const message = parsedBody?.message || 'Invalid request';
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: 'text',
-                        text: `${message} when trying to "${operation}". Please check your input and try again.`,
-                    },
-                ],
-            };
-        }
-    }
-    // Handle service unavailable (503)
-    if (status === 503) {
-        return {
-            isError: true,
-            content: [
-                {
-                    type: 'text',
-                    text: `Bukku is temporarily unavailable while trying to "${operation}". Please try again in a few moments.`,
-                },
-            ],
-        };
-    }
-    // Handle server errors (500+)
-    if (status !== null && status >= 500) {
-        // Include response body for debugging server errors
-        // Often these contain validation errors that should have been 400s
-        const parsedBody = body;
-        const bodyText = body ? `\n\nServer response: ${JSON.stringify(parsedBody, null, 2)}` : '';
-        return {
-            isError: true,
-            content: [
-                {
-                    type: 'text',
-                    text: `An unexpected error occurred on Bukku's servers while trying to "${operation}". Please try again, and if the issue persists, contact Bukku support.${bodyText}`,
-                },
-            ],
-        };
-    }
-    // Fallback for unknown status codes
-    return {
-        isError: true,
-        content: [
-            {
-                type: 'text',
-                text: `An error occurred while trying to "${operation}". Please check your request and try again.`,
-            },
-        ],
-    };
-}
-export function transformNetworkError(error, operation) {
-    // Check if it's a network-related error
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    if (errorMessage.includes('fetch') ||
-        errorMessage.includes('connect') ||
-        errorMessage.includes('network') ||
-        error instanceof TypeError) {
-        return {
-            isError: true,
-            content: [
-                {
-                    type: 'text',
-                    text: `Couldn't connect to Bukku while trying to "${operation}". Please check your internet connection and ensure the Bukku API is accessible.`,
-                },
-            ],
-        };
-    }
-    // Fallback for unknown errors
-    return {
-        isError: true,
-        content: [
-            {
-                type: 'text',
-                text: `An unexpected error occurred while trying to "${operation}": ${errorMessage}. Please try again.`,
-            },
-        ],
-    };
-}

package/build/errors/transform.test.d.ts

@@ -1 +0,0 @@
-export {};