@mindstone-engineering/mcp-server-quickbooks 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,97 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Mindstone Engineering
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+**Licensor**: Mindstone Engineering
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+**Software**: QuickBooks MCP Server
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A "Competing
+Use" means making the Software available to third parties as a commercial
+hosted service that directly competes with any product or service provided by
+the Licensor.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, OF
+ANY CHARACTER INCLUDING DAMAGES FOR LOSS OF GOODWILL, LOST PROFITS, LOST SALES
+OR BUSINESS, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, LOST CONTENT,
+DATA OR DATA USE, BREACH OF DUTY OF GOOD FAITH, OR ANY AND ALL OTHER DAMAGES
+OR LOSSES OF ANY KIND OR NATURE WHATSOEVER (WHETHER DIRECT, INDIRECT, SPECIAL,
+COLLATERAL, INCIDENTAL, CONSEQUENTIAL OR OTHERWISE) ARISING OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THIS LICENSE, EVEN IF SUCH PARTY SHALL HAVE
+BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### Trademark
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Change Date
+
+Four years from the date the Software is made available under these Terms and
+Conditions: **2030-04-08**
+
+## Change License
+
+MIT License
+
+## License Details
+
+| Parameter | Value |
+|---|---|
+| Licensor | Mindstone Engineering |
+| Software | QuickBooks MCP Server |
+| Use Limitation | Competing Use |
+| Change Date | 2030-04-08 |
+| Change License | MIT |

package/README.md

@@ -0,0 +1,120 @@
+# @mindstone-engineering/mcp-server-quickbooks
+
+[![npm version](https://img.shields.io/npm/v/@mindstone-engineering/mcp-server-quickbooks.svg)](https://www.npmjs.com/package/@mindstone-engineering/mcp-server-quickbooks)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](./LICENSE)
+
+QuickBooks Online MCP server for Model Context Protocol hosts. Manage invoices, bills, customers, vendors, employees, and accounts in QuickBooks Online through a standardised MCP interface.
+
+## Requirements
+
+- Node.js 20+
+- npm
+
+## Quick Start
+
+### Install & build
+
+```bash
+cd <path-to-repo>/connectors/quickbooks
+npm install
+npm run build
+```
+
+### npx (once published)
+
+```bash
+npx -y @mindstone-engineering/mcp-server-quickbooks
+```
+
+### Local
+
+```bash
+node dist/index.js
+```
+
+## Configuration
+
+### Environment variables
+
+- `QUICKBOOKS_CLIENT_ID` — Intuit Developer app client ID
+- `QUICKBOOKS_CLIENT_SECRET` — Intuit Developer app client secret
+- `QUICKBOOKS_REFRESH_TOKEN` — OAuth 2.0 refresh token
+- `QUICKBOOKS_REALM_ID` — QuickBooks company (realm) ID
+- `QUICKBOOKS_ENVIRONMENT` — `sandbox` or `production` (default: `production`)
+- `MCP_HOST_BRIDGE_STATE` — optional path to a host bridge state file used for credential management
+- `MINDSTONE_REBEL_BRIDGE_STATE` — backwards-compatible alias for `MCP_HOST_BRIDGE_STATE`
+
+## Host configuration examples
+
+### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "QuickBooks": {
+      "command": "npx",
+      "args": ["-y", "@mindstone-engineering/mcp-server-quickbooks"],
+      "env": {
+        "QUICKBOOKS_CLIENT_ID": "your-client-id",
+        "QUICKBOOKS_CLIENT_SECRET": "your-client-secret",
+        "QUICKBOOKS_REFRESH_TOKEN": "your-refresh-token",
+        "QUICKBOOKS_REALM_ID": "your-realm-id"
+      }
+    }
+  }
+}
+```
+
+### Local development (no npm publish needed)
+
+```json
+{
+  "mcpServers": {
+    "QuickBooks": {
+      "command": "node",
+      "args": ["<path-to-repo>/connectors/quickbooks/dist/index.js"],
+      "env": {
+        "QUICKBOOKS_CLIENT_ID": "your-client-id",
+        "QUICKBOOKS_CLIENT_SECRET": "your-client-secret",
+        "QUICKBOOKS_REFRESH_TOKEN": "your-refresh-token",
+        "QUICKBOOKS_REALM_ID": "your-realm-id"
+      }
+    }
+  }
+}
+```
+
+## Tools (13)
+
+### Configuration
+- `configure_quickbooks` — Configure QuickBooks Online OAuth credentials
+
+### Query
+- `query_quickbooks` — Run a QuickBooks query using QuickBooks Query Language
+- `get_quickbooks_entity` — Get a single entity by type and ID
+
+### Customers
+- `list_quickbooks_customers` — List customers
+- `create_quickbooks_customer` — Create a new customer
+
+### Vendors
+- `list_quickbooks_vendors` — List vendors
+- `create_quickbooks_vendor` — Create a new vendor
+
+### Invoices
+- `list_quickbooks_invoices` — List invoices
+- `create_quickbooks_invoice` — Create a new invoice
+
+### Bills
+- `list_quickbooks_bills` — List bills (accounts payable)
+- `create_quickbooks_bill` — Create a new bill
+
+### Employees
+- `list_quickbooks_employees` — List employees
+
+### Accounts
+- `list_quickbooks_accounts` — List chart of accounts
+
+## Licence
+
+[FSL-1.1-MIT](./LICENSE) — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.

package/dist/bridge.d.ts

@@ -5,7 +5,7 @@ export declare const BRIDGE_STATE_PATH: string;
 /**
  * Send a request to the host app bridge.
  *
- * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * The bridge is an HTTP server running inside the host app (e.g. the host application)
  * that handles credential management and other cross-process operations.
  */
 export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{

package/dist/bridge.js

@@ -18,7 +18,7 @@ const loadBridgeState = () => {
 /**
  * Send a request to the host app bridge.
  *
- * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * The bridge is an HTTP server running inside the host app (e.g. the host application)
  * that handles credential management and other cross-process operations.
  */
 export const bridgeRequest = async (urlPath, body) => {

package/dist/index.d.ts

@@ -15,8 +15,8 @@
  * - QUICKBOOKS_REFRESH_TOKEN: OAuth2 refresh token
  * - QUICKBOOKS_REALM_ID: QuickBooks company ID (Realm ID)
  * - QUICKBOOKS_ENVIRONMENT: "sandbox" or "production" (default: "production")
- * - MCP_HOST_BRIDGE_STATE: Path to bridge state file for app communication
- * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path
+ * - MCP_HOST_BRIDGE_STATE: Path to bridge state file for app communication (primary)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy/deprecated bridge state path
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -15,8 +15,8 @@
  * - QUICKBOOKS_REFRESH_TOKEN: OAuth2 refresh token
  * - QUICKBOOKS_REALM_ID: QuickBooks company ID (Realm ID)
  * - QUICKBOOKS_ENVIRONMENT: "sandbox" or "production" (default: "production")
- * - MCP_HOST_BRIDGE_STATE: Path to bridge state file for app communication
- * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path
+ * - MCP_HOST_BRIDGE_STATE: Path to bridge state file for app communication (primary)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy/deprecated bridge state path
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';

package/dist/tools/accounts.js

@@ -2,7 +2,7 @@
  * QuickBooks account (chart of accounts) tools.
  */
 import { z } from 'zod';
-import { withErrorHandling } from '../utils.js';
+import { withErrorHandling, escapeQboql } from '../utils.js';
 import { qboQuery } from '../client.js';
 export function registerAccountTools(server) {
     server.registerTool('list_quickbooks_accounts', {
@@ -24,7 +24,7 @@ Account types: Bank, Accounts Receivable, Other Current Asset, Fixed Asset, Othe
         const limit = Math.min(args.limit ?? 100, 1000);
         const conditions = [];
         if (args.accountType)
-            conditions.push(`AccountType = '${args.accountType}'`);
+            conditions.push(`AccountType = '${escapeQboql(args.accountType)}'`);
         if (args.active !== undefined)
             conditions.push(`Active = ${args.active}`);
         const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';

package/dist/tools/bills.js

@@ -2,7 +2,7 @@
  * QuickBooks bill tools.
  */
 import { z } from 'zod';
-import { withErrorHandling } from '../utils.js';
+import { withErrorHandling, escapeQboql, validateAlphanumericId } from '../utils.js';
 import { qboFetch, qboQuery } from '../client.js';
 export function registerBillTools(server) {
     server.registerTool('list_quickbooks_bills', {
@@ -19,7 +19,9 @@ Example: { "vendorId": "123" }`,
         annotations: { readOnlyHint: true },
     }, withErrorHandling(async (args) => {
         const limit = Math.min(args.limit ?? 50, 1000);
-        const where = args.vendorId ? ` WHERE VendorRef = '${args.vendorId}'` : '';
+        if (args.vendorId)
+            validateAlphanumericId(args.vendorId, 'vendorId');
+        const where = args.vendorId ? ` WHERE VendorRef = '${escapeQboql(args.vendorId)}'` : '';
         const query = `SELECT * FROM Bill${where} ORDERBY TxnDate DESC`;
         const bills = await qboQuery('Bill', query, limit);
         return JSON.stringify({ ok: true, bills, count: bills.length });

package/dist/tools/customers.js

@@ -2,7 +2,7 @@
  * QuickBooks customer tools.
  */
 import { z } from 'zod';
-import { withErrorHandling } from '../utils.js';
+import { withErrorHandling, escapeQboql } from '../utils.js';
 import { qboFetch, qboQuery } from '../client.js';
 export function registerCustomerTools(server) {
     server.registerTool('list_quickbooks_customers', {
@@ -25,7 +25,7 @@ Example: { "searchTerm": "Smith" }`,
         if (args.active !== undefined)
             conditions.push(`Active = ${args.active}`);
         if (args.searchTerm) {
-            conditions.push(`DisplayName LIKE '%${args.searchTerm.replace(/'/g, "\\'")}%'`);
+            conditions.push(`DisplayName LIKE '%${escapeQboql(args.searchTerm)}%'`);
         }
         const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
         const query = `SELECT * FROM Customer${where} ORDERBY DisplayName`;

package/dist/tools/invoices.js

@@ -2,7 +2,7 @@
  * QuickBooks invoice tools.
  */
 import { z } from 'zod';
-import { withErrorHandling } from '../utils.js';
+import { withErrorHandling, escapeQboql, validateAlphanumericId } from '../utils.js';
 import { qboFetch, qboQuery } from '../client.js';
 export function registerInvoiceTools(server) {
     server.registerTool('list_quickbooks_invoices', {
@@ -35,8 +35,10 @@ WORKFLOW:
         else if (args.status === 'overdue') {
             conditions.push(`Balance > '0' AND DueDate < '${new Date().toISOString().split('T')[0]}'`);
         }
-        if (args.customerId)
-            conditions.push(`CustomerRef = '${args.customerId}'`);
+        if (args.customerId) {
+            validateAlphanumericId(args.customerId, 'customerId');
+            conditions.push(`CustomerRef = '${escapeQboql(args.customerId)}'`);
+        }
         const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
         const query = `SELECT * FROM Invoice${where} ORDERBY TxnDate DESC`;
         const invoices = await qboQuery('Invoice', query, limit);

package/dist/tools/vendors.js

@@ -2,7 +2,7 @@
  * QuickBooks vendor tools.
  */
 import { z } from 'zod';
-import { withErrorHandling } from '../utils.js';
+import { withErrorHandling, escapeQboql } from '../utils.js';
 import { qboFetch, qboQuery } from '../client.js';
 export function registerVendorTools(server) {
     server.registerTool('list_quickbooks_vendors', {
@@ -24,7 +24,7 @@ Example: { "searchTerm": "Office" }`,
         if (args.active !== undefined)
             conditions.push(`Active = ${args.active}`);
         if (args.searchTerm) {
-            conditions.push(`DisplayName LIKE '%${args.searchTerm.replace(/'/g, "\\'")}%'`);
+            conditions.push(`DisplayName LIKE '%${escapeQboql(args.searchTerm)}%'`);
         }
         const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
         const query = `SELECT * FROM Vendor${where} ORDERBY DisplayName`;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export declare const REQUEST_TIMEOUT_MS = 30000;
-export declare const USER_AGENT = "MindstoneRebel/1.0 (QuickBooks-MCP)";
+export declare const USER_AGENT = "mcp-server-quickbooks/0.1.0";
 export declare const TOKEN_URL = "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer";
 export interface BridgeState {
     port: number;

package/dist/types.js

@@ -1,5 +1,5 @@
 export const REQUEST_TIMEOUT_MS = 30_000;
-export const USER_AGENT = 'MindstoneRebel/1.0 (QuickBooks-MCP)';
+export const USER_AGENT = 'mcp-server-quickbooks/0.1.0';
 export const TOKEN_URL = 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer';
 export class QuickBooksError extends Error {
     code;

package/dist/utils.d.ts

@@ -1,5 +1,15 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Escape a user-supplied string value for safe interpolation into a QBOQL query.
+ * Escapes backslashes and single quotes to prevent injection.
+ */
+export declare function escapeQboql(value: string): string;
+/**
+ * Validate that an ID value contains only alphanumeric characters, hyphens, and underscores.
+ * Throws QuickBooksError if the value contains unexpected characters.
+ */
+export declare function validateAlphanumericId(value: string, fieldName: string): void;
 /**
  * Wraps a tool handler with standard error handling.
  *

package/dist/utils.js

@@ -1,4 +1,20 @@
 import { QuickBooksError } from './types.js';
+/**
+ * Escape a user-supplied string value for safe interpolation into a QBOQL query.
+ * Escapes backslashes and single quotes to prevent injection.
+ */
+export function escapeQboql(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/**
+ * Validate that an ID value contains only alphanumeric characters, hyphens, and underscores.
+ * Throws QuickBooksError if the value contains unexpected characters.
+ */
+export function validateAlphanumericId(value, fieldName) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
+        throw new QuickBooksError(`Invalid ${fieldName}: must contain only alphanumeric characters, hyphens, and underscores.`, 'INVALID_INPUT', `Provide a valid ${fieldName} containing only letters, numbers, hyphens, and underscores.`);
+    }
+}
 /**
  * Wraps a tool handler with standard error handling.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstone-engineering/mcp-server-quickbooks",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "QuickBooks Online MCP server for Model Context Protocol hosts — invoices, bills, customers, vendors, accounts",
   "license": "FSL-1.1-MIT",
   "type": "module",