brinkcommerce-dev-mcp 0.1.0-beta.1

package/dist/api-docs-tools.js

@@ -0,0 +1,522 @@
+import { docsConfig, merchantPortalAcademyConfig } from "./config.js";
+import { platformOverview, listApisContent, listEndpointsContent, errorMessages, contextualTips, nextSteps, } from "./help-content.js";
+/**
+ * MCP Tool Definitions for API Documentation
+ */
+// Annotations for read-only tools
+const readOnlyAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false, // These only read local cached specs
+};
+export const apiDocsTools = {
+    get_docs_info: {
+        name: "get_docs_info",
+        description: "🏁 START HERE! Get comprehensive Brink Commerce platform overview, architecture, capabilities, and usage guide. Essential first step to understand what you can build and how to approach development with Brink APIs.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            examples: [{}],
+        },
+        annotations: readOnlyAnnotations,
+    },
+    search_schemas: {
+        name: "search_schemas",
+        description: "Search across all Brink/BrinkCommerce APIs for data models containing specific fields. Perfect for finding how to work with products, orders, customers, prices, inventory, etc. Often more useful than browsing APIs randomly.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search term to find in schema names, descriptions, or field names (e.g., 'email', 'price', 'stock', 'customer', 'product')",
+                    examples: ["email", "price", "inventory", "customer", "sku", "payment"],
+                },
+            },
+            required: ["query"],
+        },
+        annotations: readOnlyAnnotations,
+    },
+    list_apis: {
+        name: "list_apis",
+        description: "List all available Brink/BrinkCommerce API specifications. 📚 TIP: Try 'get_docs_info' first to understand the platform, then use this to browse specific APIs. Returns categorized APIs you can explore further.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            examples: [{}],
+        },
+        annotations: readOnlyAnnotations,
+    },
+    get_api_info: {
+        name: "get_api_info",
+        description: "Get detailed information about a specific Brink API including endpoints, schemas, and purpose. Perfect for exploring what an API offers before diving into specific endpoints.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                apiName: {
+                    type: "string",
+                    description: "Name of the API specification (e.g., 'product-management', 'order-management', 'shopper-klarna')",
+                    examples: ["product-management", "order-management", "shopper-api"],
+                },
+            },
+            required: ["apiName"],
+        },
+        annotations: readOnlyAnnotations,
+    },
+    list_endpoints: {
+        name: "list_endpoints",
+        description: "List all endpoints for a Brink API with optional filtering by HTTP method or tag. Great for discovering available operations like creating products, processing orders, or managing inventory.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                apiName: {
+                    type: "string",
+                    description: "Name of the API specification (e.g., 'product-management', 'order-management')",
+                    examples: ["product-management", "order-management", "shopper-api"],
+                },
+                method: {
+                    type: "string",
+                    enum: ["GET", "POST", "PUT", "DELETE", "PATCH"],
+                    description: "Filter by HTTP method (e.g., 'GET' for retrieval, 'POST' for creation)",
+                    examples: ["GET", "POST"],
+                },
+                tag: {
+                    type: "string",
+                    description: "Filter by OpenAPI tag/category (e.g., 'Products', 'Orders', 'Customers')",
+                    examples: ["Products", "Orders", "Customers"],
+                },
+            },
+            required: ["apiName"],
+        },
+        annotations: readOnlyAnnotations,
+    },
+    get_endpoint_details: {
+        name: "get_endpoint_details",
+        description: "Get comprehensive details about a specific endpoint including parameters, request/response schemas, and authentication requirements. Essential for implementing API calls.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                apiName: {
+                    type: "string",
+                    description: "Name of the API specification (e.g., 'product-management', 'order-management')",
+                    examples: ["product-management", "order-management", "shopper-api"],
+                },
+                path: {
+                    type: "string",
+                    description: "API path (e.g., /products/{id}, /orders, /carts/{cartId}/items)",
+                    examples: ["/products/{id}", "/orders", "/carts/{cartId}/items"],
+                },
+                method: {
+                    type: "string",
+                    enum: ["GET", "POST", "PUT", "DELETE", "PATCH"],
+                    description: "HTTP method",
+                    examples: ["GET", "POST"],
+                },
+            },
+            required: ["apiName", "path", "method"],
+        },
+        annotations: readOnlyAnnotations,
+    },
+    list_schemas: {
+        name: "list_schemas",
+        description: "List all data models/schemas for a Brink API. See the structure of products, orders, customers, and other commerce entities used by the API.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                apiName: {
+                    type: "string",
+                    description: "Name of the API specification (e.g., 'product-management', 'order-management')",
+                    examples: ["product-management", "order-management", "shopper-api"],
+                },
+            },
+            required: ["apiName"],
+        },
+        annotations: readOnlyAnnotations,
+    },
+    get_schema: {
+        name: "get_schema",
+        description: "Get detailed information about a specific data model/schema including all fields, types, and validation rules. Essential for understanding data structures in Brink Commerce.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                apiName: {
+                    type: "string",
+                    description: "Name of the API specification (e.g., 'product-management', 'order-management')",
+                    examples: ["product-management", "order-management", "shopper-api"],
+                },
+                schemaName: {
+                    type: "string",
+                    description: "Name of the schema (e.g., Product, Order, Customer, Cart)",
+                    examples: ["Product", "Order", "Customer", "Cart", "Payment"],
+                },
+            },
+            required: ["apiName", "schemaName"],
+        },
+        annotations: readOnlyAnnotations,
+    },
+};
+/**
+ * Handle list_apis tool call
+ */
+export function handleListApis(apiManager) {
+    const specs = apiManager.getAllSpecs();
+    if (specs.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No OpenAPI specifications loaded. The MCP server automatically fetches BrinkCommerce API specifications from configured sources.",
+                },
+            ],
+        };
+    }
+    // Group APIs by category for better organization
+    const coreApis = [];
+    const shopperApis = [];
+    const integrationApis = [];
+    specs.forEach(({ name, spec }) => {
+        const apiInfo = `**${spec.info.title}** (\`${name}\`)
+- Version: ${spec.info.version}
+- ${spec.info.description ?? "No description"}
+- ${Object.keys(spec.paths).length} endpoints`;
+        if (name.toLowerCase().includes("shopper")) {
+            shopperApis.push(apiInfo);
+        }
+        else if (name.toLowerCase().includes("management") ||
+            name.toLowerCase().includes("api")) {
+            coreApis.push(apiInfo);
+        }
+        else {
+            integrationApis.push(apiInfo);
+        }
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: listApisContent(coreApis, shopperApis, integrationApis),
+            },
+        ],
+    };
+}
+/**
+ * Handle get_api_info tool call
+ */
+export function handleGetApiInfo(apiManager, args) {
+    const apiName = args.apiName; // Required parameter
+    const spec = apiManager.getSpec(apiName);
+    if (!spec) {
+        // Get list of available API names for suggestion
+        const availableApis = apiManager
+            .getAllSpecs()
+            .map((s) => s.name)
+            .slice(0, 5);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessages.apiNotFound(apiName, availableApis),
+                },
+            ],
+        };
+    }
+    // Build the info output with all available fields
+    let info = `# ${spec.info.title}
+
+**Version:** ${spec.info.version}
+**Description:** ${spec.info.description ?? "No description"}
+`;
+    // Add servers
+    const servers = apiManager.getServers(apiName);
+    if (servers && servers.length > 0) {
+        info += `\n## Servers\n`;
+        for (const server of servers) {
+            info += `- \`${server.url}\`${server.description ? ` - ${server.description}` : ""}\n`;
+            if (server.variables) {
+                for (const [varName, varObj] of Object.entries(server.variables)) {
+                    info += `  - \`{${varName}}\`: ${varObj.description ?? "No description"} (default: \`${varObj.default}\`)\n`;
+                }
+            }
+        }
+    }
+    // Add security schemes
+    const securitySchemes = apiManager.getSecuritySchemes(apiName);
+    if (securitySchemes) {
+        info += `\n## Authentication\n`;
+        for (const [name, scheme] of Object.entries(securitySchemes)) {
+            if (scheme.type === "http") {
+                info += `- **${name}**: HTTP ${scheme.scheme}${scheme.bearerFormat ? ` (${scheme.bearerFormat})` : ""}\n`;
+            }
+            else if (scheme.type === "apiKey") {
+                info += `- **${name}**: API Key in ${scheme.in} (\`${scheme.name}\`)\n`;
+            }
+            else if (scheme.type === "oauth2") {
+                info += `- **${name}**: OAuth 2.0\n`;
+                if (scheme.flows) {
+                    for (const [flowName, flow] of Object.entries(scheme.flows)) {
+                        if (flow) {
+                            info += `  - ${flowName} flow\n`;
+                        }
+                    }
+                }
+            }
+            else if (scheme.type === "openIdConnect") {
+                info += `- **${name}**: OpenID Connect (${scheme.openIdConnectUrl})\n`;
+            }
+            if (scheme.description) {
+                info += `  ${scheme.description}\n`;
+            }
+        }
+    }
+    // Add global security requirements
+    const globalSecurity = apiManager.getGlobalSecurity(apiName);
+    if (globalSecurity && globalSecurity.length > 0) {
+        info += `\n## Required Security\n`;
+        for (const req of globalSecurity) {
+            const schemes = Object.keys(req);
+            if (schemes.length > 0) {
+                info += `- ${schemes.join(" AND ")}\n`;
+            }
+        }
+    }
+    // Add tags with descriptions
+    const tags = apiManager.getTags(apiName);
+    if (tags && tags.length > 0) {
+        info += `\n## Tags\n`;
+        for (const tag of tags) {
+            info += `- **${tag.name}**${tag.description ? `: ${tag.description}` : ""}\n`;
+        }
+    }
+    // Add info extras (contact, license, terms)
+    const extras = apiManager.getInfoExtras(apiName);
+    if (extras) {
+        if (extras.contact) {
+            info += `\n## Contact\n`;
+            if (extras.contact.name)
+                info += `- Name: ${extras.contact.name}\n`;
+            if (extras.contact.email)
+                info += `- Email: ${extras.contact.email}\n`;
+            if (extras.contact.url)
+                info += `- URL: ${extras.contact.url}\n`;
+        }
+        if (extras.license) {
+            info += `\n## License\n`;
+            info += `- ${extras.license.name}${extras.license.url ? ` (${extras.license.url})` : ""}\n`;
+        }
+        if (extras.termsOfService) {
+            info += `\n## Terms of Service\n`;
+            info += `${extras.termsOfService}\n`;
+        }
+    }
+    // Add external docs
+    const externalDocs = apiManager.getExternalDocs(apiName);
+    if (externalDocs) {
+        info += `\n## External Documentation\n`;
+        info += `- ${externalDocs.description ?? "Documentation"}: ${externalDocs.url}\n`;
+    }
+    // Add stats
+    info += `\n## Statistics\n`;
+    info += `**Available Paths:** ${Object.keys(spec.paths).length}\n`;
+    info += `**Schemas:** ${spec.components?.schemas ? Object.keys(spec.components.schemas).length : 0}\n`;
+    // Add paths
+    info += `\n## Paths\n`;
+    info += Object.keys(spec.paths)
+        .map((path) => `- ${path}`)
+        .join("\n");
+    info += `\n\n📚 **Full Documentation**: ${docsConfig.baseUrl}${docsConfig.sections.apiReferences}`;
+    return {
+        content: [
+            {
+                type: "text",
+                text: info,
+            },
+        ],
+    };
+}
+/**
+ * Handle list_endpoints tool call
+ */
+export function handleListEndpoints(apiManager, args) {
+    const apiName = args.apiName; // Required parameter
+    const endpoints = apiManager.getEndpoints(apiName, {
+        method: args.method,
+        tag: args.tag,
+    });
+    if (endpoints.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessages.noEndpointsFound(apiName),
+                },
+            ],
+        };
+    }
+    const endpointList = endpoints
+        .map((endpoint) => {
+        const tags = endpoint.tags ? ` [${endpoint.tags.join(", ")}]` : "";
+        return `**${endpoint.method} ${endpoint.path}**${tags}
+  ${endpoint.summary ?? "No summary"}`;
+    })
+        .join("\n\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: listEndpointsContent(apiName, endpointList),
+            },
+        ],
+    };
+}
+/**
+ * Handle get_endpoint_details tool call
+ */
+export function handleGetEndpointDetails(apiManager, args) {
+    const apiName = args.apiName; // Required parameter
+    const path = args.path; // Required parameter
+    const method = args.method; // Required parameter
+    const endpoint = apiManager.getEndpoint(apiName, path, method);
+    if (!endpoint) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessages.endpointNotFound(method, path, apiName),
+                },
+            ],
+        };
+    }
+    const details = apiManager.formatEndpointDetails(endpoint);
+    // Add contextual help based on the endpoint type
+    let contextualHelp = "";
+    const methodLower = method.toLowerCase();
+    if (methodLower === "get") {
+        contextualHelp = "\n\n" + contextualTips.get;
+    }
+    else if (methodLower === "post") {
+        contextualHelp = "\n\n" + contextualTips.post;
+    }
+    else if (methodLower === "put") {
+        contextualHelp = "\n\n" + contextualTips.put;
+    }
+    else if (methodLower === "patch") {
+        contextualHelp = "\n\n" + contextualTips.patch;
+    }
+    else if (methodLower === "delete") {
+        contextualHelp = "\n\n" + contextualTips.delete;
+    }
+    // Add related endpoints suggestion
+    const relatedEndpoints = apiManager
+        .getEndpoints(apiName)
+        .filter((e) => e.path.includes(path.split("/")[1]) && e.path !== path)
+        .slice(0, 3);
+    let relatedSection = "";
+    if (relatedEndpoints.length > 0) {
+        relatedSection =
+            "\n\n**Related Endpoints:**\n" +
+                relatedEndpoints.map((e) => `• ${e.method} ${e.path}`).join("\n");
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: details + contextualHelp + relatedSection + "\n\n" + nextSteps.endpointDetails,
+            },
+        ],
+    };
+}
+/**
+ * Handle list_schemas tool call
+ */
+export function handleListSchemas(apiManager, args) {
+    const apiName = args.apiName; // Required parameter
+    const schemas = apiManager.getSchemas(apiName);
+    if (schemas.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessages.noSchemasFound(apiName),
+                },
+            ],
+        };
+    }
+    const schemaList = schemas
+        .map((schema) => `**${schema.name}** (${schema.type})\n  ${schema.description ?? "No description"}`)
+        .join("\n\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `# Schemas for ${apiName}\n\n${schemaList}`,
+            },
+        ],
+    };
+}
+/**
+ * Handle get_schema tool call
+ */
+export function handleGetSchema(apiManager, args) {
+    const apiName = args.apiName; // Required parameter
+    const schemaName = args.schemaName; // Required parameter
+    const schema = apiManager.getSchema(apiName, schemaName);
+    if (!schema) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessages.schemaNotFound(schemaName, apiName),
+                },
+            ],
+        };
+    }
+    const details = apiManager.formatSchemaDetails(schema);
+    return {
+        content: [
+            {
+                type: "text",
+                text: details,
+            },
+        ],
+    };
+}
+/**
+ * Handle search_schemas tool call
+ */
+export function handleSearchSchemas(apiManager, args) {
+    const query = args.query; // Required parameter
+    const results = apiManager.searchSchemas(query);
+    if (results.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessages.noSearchResults(query),
+                },
+            ],
+        };
+    }
+    const resultList = results
+        .map(({ specName, schema }) => `**${schema.name}** (${specName})\n  ${schema.description ?? "No description"}`)
+        .join("\n\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `# Schema search results for '${query}'\n\n${resultList}`,
+            },
+        ],
+    };
+}
+/**
+ * Handle get_docs_info tool call
+ */
+export function handleGetDocsInfo() {
+    return {
+        content: [
+            {
+                type: "text",
+                text: platformOverview(docsConfig, merchantPortalAcademyConfig),
+            },
+        ],
+    };
+}

package/dist/auth.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Get OAuth2 access token using client credentials flow
+ * Requests all available scopes and caches the token
+ *
+ * @param _scope Optional scope parameter (ignored - always requests all scopes)
+ * @returns Access token for BrinkCommerce Management API
+ * @throws Error if credentials are missing or token request fails
+ */
+export declare function getAccessToken(_scope?: string): Promise<string>;
+/**
+ * Clear the cached token
+ * Useful for testing or forcing token refresh
+ */
+export declare function clearTokenCache(): void;
+/**
+ * Check if a valid token is currently cached
+ *
+ * @returns true if a valid token exists in cache
+ */
+export declare function hasValidToken(): boolean;

package/dist/auth.js

@@ -0,0 +1,80 @@
+import fetch from "node-fetch";
+import { logger } from "./logger.js";
+// Single cached token (all scopes)
+let tokenCache = null;
+/**
+ * Get OAuth2 access token using client credentials flow
+ * Requests all available scopes and caches the token
+ *
+ * @param _scope Optional scope parameter (ignored - always requests all scopes)
+ * @returns Access token for BrinkCommerce Management API
+ * @throws Error if credentials are missing or token request fails
+ */
+export async function getAccessToken(_scope) {
+    // Return cached token if still valid (with 60s buffer)
+    if (tokenCache && tokenCache.expiresAt > Date.now() + 60000) {
+        logger.debug("Using cached OAuth token");
+        return tokenCache.token;
+    }
+    logger.info("Fetching new OAuth token (all scopes)");
+    // Get credentials from environment
+    const clientId = process.env.BRINK_CLIENT_ID;
+    const clientSecret = process.env.BRINK_CLIENT_SECRET;
+    const region = process.env.BRINK_REGION ?? "eu-west-1";
+    const customerName = process.env.BRINK_CUSTOMER_NAME;
+    // Validate required credentials
+    if (!clientId || !clientSecret || !customerName) {
+        throw new Error("Missing required environment variables: BRINK_CLIENT_ID, BRINK_CLIENT_SECRET, BRINK_CUSTOMER_NAME");
+    }
+    // Build token endpoint URL
+    const tokenUrl = `https://management.${region}.${customerName}.brinkcommerce.io/auth/oauth2/token`;
+    // Encode credentials for Basic Auth
+    const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+    try {
+        const response = await fetch(tokenUrl, {
+            method: "POST",
+            headers: {
+                Authorization: `Basic ${credentials}`,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: "grant_type=client_credentials",
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            logger.error(`OAuth token request failed: ${response.status} ${response.statusText}`, {
+                error: errorText,
+            });
+            throw new Error(`OAuth token request failed: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        // Cache token with expiration time
+        tokenCache = {
+            token: data.access_token,
+            expiresAt: Date.now() + data.expires_in * 1000,
+        };
+        logger.info("Successfully fetched OAuth token", {
+            expiresIn: data.expires_in,
+        });
+        return data.access_token;
+    }
+    catch (error) {
+        logger.error("Failed to fetch OAuth token", { error });
+        throw error;
+    }
+}
+/**
+ * Clear the cached token
+ * Useful for testing or forcing token refresh
+ */
+export function clearTokenCache() {
+    tokenCache = null;
+    logger.debug("Token cache cleared");
+}
+/**
+ * Check if a valid token is currently cached
+ *
+ * @returns true if a valid token exists in cache
+ */
+export function hasValidToken() {
+    return tokenCache !== null && tokenCache.expiresAt > Date.now() + 60000;
+}

package/dist/cache-utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolves the cache directory path using the following priority:
+ * 1. BRINKCOMMERCE_CACHE_DIR environment variable
+ * 2. XDG_CACHE_HOME/brinkcommerce-dev-mcp (Linux only)
+ * 3. User cache directory via env-paths (cross-platform standard locations)
+ * 4. node_modules/.cache/brinkcommerce-dev-mcp (if in project context)
+ * 5. os.tmpdir()/brinkcommerce-dev-mcp/cache (last resort)
+ */
+export declare function getCacheDirectory(): string;
+/**
+ * Get cache directory with explicit override option
+ */
+export declare function getCacheDirectoryWithOverride(override?: string): string;
+/**
+ * Get information about the selected cache directory and why it was chosen
+ */
+export declare function getCacheDirectoryInfo(): {
+    path: string;
+    reason: string;
+};