@centry-digital/bukku-mcp 1.1.1 → 2.0.1

package/README.md

@@ -15,7 +15,7 @@ With this MCP server connected, you can ask your AI things like:
 - "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:
+The server exposes **169 tools** covering the full Bukku API:
 
 | Category | Tools | What you can do |
 |----------|-------|-----------------|
@@ -26,16 +26,14 @@ The server exposes **173 tools** covering the full Bukku API:
 | **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 |
+| **Organisation** | 17 | 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
+- [Node.js](https://nodejs.org) v20 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))
 
@@ -48,12 +46,10 @@ Get up and running in under 2 minutes.
 
 ### Step 2: Add to your AI client
 
-For Claude Desktop, open your config file:
+**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": {
@@ -69,62 +65,7 @@ Add this configuration:
 }
 ```
 
-### 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):**
+**Claude Code** — add to your project or home `.claude/settings.json`:
 
 ```json
 {
@@ -141,128 +82,51 @@ Open your configuration file:
 }
 ```
 
-**If you installed globally:**
-
-```json
-{
-  "mcpServers": {
-    "bukku": {
-      "command": "bukku-mcp",
-      "env": {
-        "BUKKU_API_TOKEN": "your-token-here",
-        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
-      }
-    }
-  }
-}
-```
+### Step 3: Restart your AI client
 
-After updating the config, restart Claude Desktop.
+Quit and reopen your AI client. You're ready to go.
 
-### Claude Code
+## Installation
 
-Add to `.claude/settings.json` in your home directory or project:
+### npx (recommended)
 
-**Using npx (recommended):**
+No installation needed — downloads and runs the latest version:
 
-```json
-{
-  "mcpServers": {
-    "bukku": {
-      "command": "npx",
-      "args": ["-y", "@centry-digital/bukku-mcp"],
-      "env": {
-        "BUKKU_API_TOKEN": "your-token-here",
-        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
-      }
-    }
-  }
-}
+```bash
+npx @centry-digital/bukku-mcp
 ```
 
-**If you installed globally:**
+### npm global install
 
-```json
-{
-  "mcpServers": {
-    "bukku": {
-      "command": "bukku-mcp",
-      "env": {
-        "BUKKU_API_TOKEN": "your-token-here",
-        "BUKKU_COMPANY_SUBDOMAIN": "your-subdomain"
-      }
-    }
-  }
-}
+```bash
+npm install -g @centry-digital/bukku-mcp
 ```
 
-### Other MCP Clients
+Then use `bukku-mcp` as the command in your AI client config instead of `npx`.
+
+## Configuration
 
-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.
+| 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`) |
 
 ## 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
+- Your API token may be invalid or expired — regenerate 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`
+- Verify JSON syntax is correct (no trailing commas)
+- Restart your AI client after editing the config
+- Check Node.js v20+ 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
+## Related
 
-**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
-```
+- [GitHub repository](https://github.com/centry-digital/bukku)
 
 ## License
 

package/build/config/env.d.ts

@@ -17,3 +17,4 @@ export type Env = z.infer<typeof envSchema>;
  */
 export declare function validateEnv(): Env;
 export {};
+//# sourceMappingURL=env.d.ts.map

package/build/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;GAKG;AACH,QAAA,MAAM,SAAS;;;iBAGb,CAAC;AAEH,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,GAAG,CAuBjC"}

package/build/config/env.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { log } from "../utils/logger.js";
+import { createLogger } from 'core';
+const log = createLogger('bukku-mcp');
 /**
  * Environment variable schema.
  * Required vars:

package/build/index.d.ts

@@ -11,3 +11,4 @@
  * 6. Log startup to stderr
  */
 export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}