brinkcommerce-dev-mcp 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -29,7 +29,7 @@ The MCP protocol has no mechanism to force user confirmation - all safety measur
 ### Read-Only Mode
 
 To use this MCP server in read-only mode for API documentation exploration only:
-- Simply don't configure the `BRINK_CLIENT_ID` and `BRINK_CLIENT_SECRET` environment variables
+- Simply don't configure the `BRINK_CLIENT_ID`, `BRINK_CLIENT_SECRET`, and `BRINK_API_KEY` environment variables
 - All write operations will fail with authentication errors
 - Documentation tools (`list_apis`, `search_schemas`, etc.) will work normally
 
@@ -147,7 +147,9 @@ If you have connection issues on Windows, use this alternative configuration:
 
 ## Configure API Access (Optional)
 
-The server works out of the box for **API documentation** queries. To use **management tools** (create products, update inventory, etc.), add your BrinkCommerce credentials:
+The server works out of the box for **API documentation** queries. To use **management tools** (create products, update inventory, etc.), add your BrinkCommerce credentials.
+
+The Management API requires **both** an OAuth2 client (for the bearer token) **and** a Management API key (sent as `x-api-key`). All four variables below are required for management tools:
 
 ### Claude Desktop
 
@@ -160,7 +162,8 @@ The server works out of the box for **API documentation** queries. To use **mana
       "env": {
         "BRINK_CLIENT_ID": "your-client-id",
         "BRINK_CLIENT_SECRET": "your-client-secret",
-        "BRINK_CUSTOMER_NAME": "your-customer-name"
+        "BRINK_CUSTOMER_NAME": "your-customer-name",
+        "BRINK_API_KEY": "your-management-api-key"
       }
     }
   }
@@ -174,6 +177,7 @@ claude mcp add brinkcommerce \
   -e BRINK_CLIENT_ID=your-client-id \
   -e BRINK_CLIENT_SECRET=your-client-secret \
   -e BRINK_CUSTOMER_NAME=your-customer-name \
+  -e BRINK_API_KEY=your-management-api-key \
   -- npx -y brinkcommerce-dev-mcp@beta
 ```
 
@@ -452,7 +456,7 @@ make help
 | `BRINK_CLIENT_SECRET` | OAuth2 client secret for BrinkCommerce API | - | For management tools |
 | `BRINK_CUSTOMER_NAME` | Your BrinkCommerce customer name | - | For management tools |
 | `BRINK_REGION` | BrinkCommerce region (eu-west-1, us-east-1) | `eu-west-1` | Optional |
-| `BRINK_API_KEY` | API key for additional authentication | - | Optional |
+| `BRINK_API_KEY` | Management API key (sent as `x-api-key` alongside the OAuth bearer token) | - | For management tools |
 | `BRINKCOMMERCE_CACHE_DIR` | Cache directory location | Platform-specific | Optional |
 | `SPECS_FORCE_REFRESH` | Force refresh all specs on startup | `false` | Optional |
 | `LOG_LEVEL` | Logging verbosity (debug/info/warn/error) | `info` | Optional |

package/dist/tools/order-extended-tools.d.ts

@@ -7,6 +7,9 @@ interface ExtendedToolParams {
     from?: string;
     to?: string;
     compensationId?: string;
+    paymentAction?: "AUTO" | "MANUAL" | "SKIP";
+    giftCardAction?: "AUTO" | "MANUAL" | "SKIP";
+    bonusAction?: "AUTO" | "MANUAL" | "SKIP";
     modificationId?: string;
     stateId?: string;
     code?: string;
@@ -358,6 +361,21 @@ export declare const compensationTools: {
                     type: string;
                     description: string;
                 };
+                paymentAction: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                giftCardAction: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                bonusAction: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
             };
             required: string[];
         };
@@ -378,6 +396,21 @@ export declare const compensationTools: {
                     type: string;
                     description: string;
                 };
+                paymentAction: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                giftCardAction: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                bonusAction: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
             };
             required: string[];
         };

package/dist/tools/order-extended-tools.js

@@ -20,6 +20,26 @@ const destructiveAnnotations = {
     destructiveHint: true,
     openWorldHint: true,
 };
+/**
+ * Build a StartCompensationRequest from tool parameters.
+ * Always returns an object (at minimum empty) to ensure the request body is not undefined.
+ */
+function buildStartCompensationRequest(params) {
+    const request = {};
+    // Add payment action if specified
+    if (params.paymentAction) {
+        request.payment = { actionType: params.paymentAction };
+    }
+    // Add gift card action if specified
+    if (params.giftCardAction) {
+        request.giftCard = { actionType: params.giftCardAction };
+    }
+    // Add bonus action if specified
+    if (params.bonusAction) {
+        request.bonus = { actionType: params.bonusAction };
+    }
+    return request;
+}
 // ==================== TOOL DEFINITIONS ====================
 /**
  * Order Query Tool Definitions
@@ -296,6 +316,21 @@ export const compensationTools = {
                     type: "string",
                     description: "The compensation ID (UUID format)",
                 },
+                paymentAction: {
+                    type: "string",
+                    enum: ["AUTO", "MANUAL", "SKIP"],
+                    description: "How to handle payment action. AUTO (default): automatically process, MANUAL: mark as manually handled, SKIP: skip this action",
+                },
+                giftCardAction: {
+                    type: "string",
+                    enum: ["AUTO", "MANUAL", "SKIP"],
+                    description: "How to handle gift card action. AUTO (default): automatically process, MANUAL: mark as manually handled, SKIP: skip this action",
+                },
+                bonusAction: {
+                    type: "string",
+                    enum: ["AUTO", "MANUAL", "SKIP"],
+                    description: "How to handle bonus action. AUTO (default): automatically process, MANUAL: mark as manually handled, SKIP: skip this action",
+                },
             },
             required: ["compensationId"],
         },
@@ -311,6 +346,21 @@ export const compensationTools = {
                     type: "string",
                     description: "The compensation ID (UUID format)",
                 },
+                paymentAction: {
+                    type: "string",
+                    enum: ["AUTO", "MANUAL", "SKIP"],
+                    description: "How to handle payment action. AUTO (default): automatically process, MANUAL: mark as manually handled, SKIP: skip this action",
+                },
+                giftCardAction: {
+                    type: "string",
+                    enum: ["AUTO", "MANUAL", "SKIP"],
+                    description: "How to handle gift card action. AUTO (default): automatically process, MANUAL: mark as manually handled, SKIP: skip this action",
+                },
+                bonusAction: {
+                    type: "string",
+                    enum: ["AUTO", "MANUAL", "SKIP"],
+                    description: "How to handle bonus action. AUTO (default): automatically process, MANUAL: mark as manually handled, SKIP: skip this action",
+                },
             },
             required: ["compensationId"],
         },
@@ -1205,8 +1255,10 @@ export async function handleStartCompensation(params) {
         if (!params.compensationId) {
             return { content: [{ type: "text", text: "Error: Missing required field 'compensationId'" }], isError: true };
         }
+        // Build request object with action options
+        const request = buildStartCompensationRequest(params);
         const client = createOrderManagementClient();
-        const result = await client.startCompensation(params.compensationId);
+        const result = await client.startCompensation(params.compensationId, request);
         if (result.success) {
             return { content: [{ type: "text", text: `Successfully started compensation: ${params.compensationId}` }] };
         }
@@ -1221,8 +1273,10 @@ export async function handleRestartCompensation(params) {
         if (!params.compensationId) {
             return { content: [{ type: "text", text: "Error: Missing required field 'compensationId'" }], isError: true };
         }
+        // Build request object with action options
+        const request = buildStartCompensationRequest(params);
         const client = createOrderManagementClient();
-        const result = await client.restartCompensation(params.compensationId);
+        const result = await client.restartCompensation(params.compensationId, request);
         if (result.success) {
             return { content: [{ type: "text", text: `Successfully restarted compensation: ${params.compensationId}` }] };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brinkcommerce-dev-mcp",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "BrinkCommerce MCP Server - API documentation and management tools for products, orders, inventory, prices, discounts, taxes, and stores",
   "main": "dist/index.js",
   "bin": {

package/CLAUDE.md

@@ -1,105 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Development Commands
-
-Build and development commands available via npm scripts and Makefile:
-
-```bash
-# Build and run
-npm run build          # Compile TypeScript to dist/
-npm run dev            # Development mode with hot reload using tsx
-npm start              # Start the built MCP server
-
-# Make commands (recommended)
-make setup             # Install dependencies and build
-make build             # Build TypeScript to JavaScript  
-make dev               # Run in development mode with hot reload
-make start             # Start MCP server (stdio mode)
-make test              # Test MCP server with example APIs
-make clean             # Clean build artifacts
-make claude-config     # Generate Claude configuration for local use
-make install-global    # Install globally via npm link
-make claude-config-global # Generate config for global install
-```
-
-## Architecture Overview
-
-This is a Model Context Protocol (MCP) server that provides Claude with access to BrinkCommerce OpenAPI specifications. The server enables natural language queries about APIs, endpoints, schemas, and data models.
-
-### Core Components
-
-- **`src/index.ts`** - Main MCP server implementation with stdio transport
-- **`src/openapi-utils.ts`** - OpenAPI specification parsing and management utilities
-- **`openapi-specs/`** - Directory containing BrinkCommerce API specifications (JSON/YAML)
-
-### Key Classes
-
-**OpenAPIManager** (`src/openapi-utils.ts`):
-- Loads and validates OpenAPI specs from the `openapi-specs/` directory
-- Provides methods to query endpoints, schemas, and API information
-- Handles spec dereferencing using SwaggerParser
-- Supports search functionality across all loaded APIs
-
-**MCP Server** (`src/index.ts`):
-- Implements the Model Context Protocol for Claude integration
-- Exposes 8 tools: `list_apis`, `get_api_info`, `list_endpoints`, `get_endpoint_details`, `list_schemas`, `get_schema`, `search_schemas`, `get_docs_info`
-- Provides resource access to raw OpenAPI specs via `openapi://` URIs
-- Uses stdio transport for communication with Claude
-- Self-documenting with comprehensive context for LLMs
-
-### Environment Configuration
-
-- **`DOCS_BASE_URL`** - Override documentation base URL (defaults to `https://brink-commerce.gitbook.io/brink-commerce`)
-- **`SPECS_FORCE_REFRESH`** - Force refresh of all specs on startup (set to `true` to enable)
-- **`BRINKCOMMERCE_CACHE_DIR`** - Override cache directory (highest priority)
-- **`XDG_CACHE_HOME`** - Linux/Unix cache directory (used if set, creates `$XDG_CACHE_HOME/brinkcommerce-dev-mcp`)
-
-## Working with OpenAPI Specs
-
-The server automatically fetches OpenAPI specifications from configured URLs and caches them locally with automatic 48-hour refresh. API specifications are configured in `src/config.ts` and each spec becomes an API that can be queried through the MCP tools.
-
-**Note**: Users may refer to the platform as "Brink", "Brink Commerce", or "BrinkCommerce" - these all refer to the same platform. The API names themselves don't include "brink" prefix (e.g., use "product-management" not "brink-product-management").
-
-### Cache Directory Resolution
-
-The server uses a smart cache directory resolution strategy for cross-platform compatibility:
-
-1. **`BRINKCOMMERCE_CACHE_DIR`** environment variable (highest priority)
-2. **`XDG_CACHE_HOME/brinkcommerce-dev-mcp`** on Linux/Unix systems
-3. **Platform-specific user cache directories:**
-   - **Linux**: `~/.cache/brinkcommerce-dev-mcp`
-   - **macOS**: `~/Library/Caches/brinkcommerce-dev-mcp`  
-   - **Windows**: `%LOCALAPPDATA%\brinkcommerce-dev-mcp\Cache`
-4. **`node_modules/.cache/brinkcommerce-dev-mcp`** (project-level fallback)
-5. **System temp directory** (last resort)
-
-This ensures cache persistence across different environments and survives `npm ci` operations when using user-level cache directories.
-
-BrinkCommerce APIs included:
-- Core APIs: Product Management, Order Management, Price Management, Stock Management, Store Management, Tax Management, Discount Management
-- Shopper API and payment provider integrations: Adyen, Avarda, Klarna, Ledyer, Svea, Walley, Qliro, and more
-- Supporting services: Voyado, Retain24, BSG/KBS Gift Cards, Bonus, Ingrid, NShift, Zaver
-
-The server provides both high-level API information and detailed endpoint/schema inspection capabilities through natural language queries via Claude, with automatic cache management and 48-hour refresh cycles.
-
-## Library Documentation
-
-Comprehensive documentation for all project dependencies is available in the `/docs/libraries/` directory:
-
-### Core Libraries
-- **[MCP TypeScript SDK](docs/libraries/mcp-typescript-sdk.md)** - Model Context Protocol implementation for creating servers and clients
-- **[dotenv](docs/libraries/dotenv.md)** - Environment variable management from .env files
-- **[js-yaml](docs/libraries/js-yaml.md)** - YAML parser and writer for JavaScript
-- **[node-fetch](docs/libraries/node-fetch.md)** - HTTP client bringing Fetch API to Node.js
-- **[swagger-parser](docs/libraries/swagger-parser.md)** - OpenAPI specification parsing and validation
-
-Each documentation file includes:
-- Installation and setup instructions
-- Code examples and usage patterns
-- Configuration options and best practices
-- Common use cases and troubleshooting
-- Migration guides for version updates
-
-This documentation was retrieved using Context7 and provides comprehensive reference material for working with the project's dependencies.