brinkcommerce-dev-mcp 0.1.0-beta.1

package/dist/logger.js

@@ -0,0 +1,98 @@
+/**
+ * Centralized logger utility for BrinkCommerce MCP server
+ *
+ * This logger ensures all output goes to stderr to avoid interfering with
+ * stdio JSON-RPC communication on stdout. Supports configurable log levels
+ * and environment variable control.
+ */
+class Logger {
+    options;
+    levels = {
+        error: 0,
+        warn: 1,
+        info: 2,
+        debug: 3,
+    };
+    constructor() {
+        this.options = this.parseEnvironmentOptions();
+    }
+    parseEnvironmentOptions() {
+        // Handle SILENT flag
+        if (process.env.SILENT === "true") {
+            return { level: "error", silent: true };
+        }
+        // Handle MCP_DEBUG flag
+        if (process.env.MCP_DEBUG === "true") {
+            return { level: "debug", silent: false };
+        }
+        // Handle LOG_LEVEL environment variable
+        const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+        const validLevels = ["error", "warn", "info", "debug"];
+        const level = validLevels.includes(envLevel) ? envLevel : "info";
+        return { level, silent: false };
+    }
+    shouldLog(level) {
+        if (this.options.silent && level !== "error") {
+            return false;
+        }
+        return this.levels[level] <= this.levels[this.options.level];
+    }
+    formatMessage(level, ...args) {
+        const timestamp = new Date().toISOString();
+        const prefix = `[${timestamp}] [${level.toUpperCase()}]`;
+        const message = args
+            .map((arg) => (typeof arg === "string" ? arg : JSON.stringify(arg)))
+            .join(" ");
+        return `${prefix} ${message}`;
+    }
+    log(level, ...args) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        const message = this.formatMessage(level, ...args);
+        // Always write to stderr to avoid interfering with stdout JSON-RPC
+        process.stderr.write(message + "\n");
+    }
+    /**
+     * Log error messages (always shown unless completely silent)
+     */
+    error(...args) {
+        this.log("error", ...args);
+    }
+    /**
+     * Log warning messages
+     */
+    warn(...args) {
+        this.log("warn", ...args);
+    }
+    /**
+     * Log informational messages (default level)
+     */
+    info(...args) {
+        this.log("info", ...args);
+    }
+    /**
+     * Log debug messages (only shown when LOG_LEVEL=debug or MCP_DEBUG=true)
+     */
+    debug(...args) {
+        this.log("debug", ...args);
+    }
+    /**
+     * Get current logger configuration
+     */
+    getConfig() {
+        return { ...this.options };
+    }
+    /**
+     * Update logger configuration (mainly for testing)
+     */
+    setConfig(options) {
+        this.options = { ...this.options, ...options };
+    }
+}
+// Export singleton instance
+export const logger = new Logger();
+// For backwards compatibility, also export individual methods
+export const { error, warn, info, debug } = logger;
+// Export the logger class for testing
+export { Logger };

package/dist/openapi-utils.d.ts

@@ -0,0 +1,84 @@
+import { OpenAPIV3 } from "openapi-types";
+export type OpenAPISpec = OpenAPIV3.Document;
+export interface APIEndpoint {
+    path: string;
+    method: string;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    parameters?: OpenAPIV3.ParameterObject[];
+    requestBody?: OpenAPIV3.RequestBodyObject;
+    responses?: OpenAPIV3.ResponsesObject;
+    deprecated?: boolean;
+    security?: OpenAPIV3.SecurityRequirementObject[];
+    externalDocs?: OpenAPIV3.ExternalDocumentationObject;
+}
+export interface APISchema {
+    name: string;
+    type: string;
+    properties?: Record<string, OpenAPIV3.SchemaObject>;
+    description?: string;
+    required?: string[];
+    enum?: unknown[];
+    format?: string;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    nullable?: boolean;
+    default?: unknown;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    items?: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+    additionalProperties?: boolean | OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+    allOf?: (OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject)[];
+    oneOf?: (OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject)[];
+    anyOf?: (OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject)[];
+    example?: unknown;
+}
+export declare class OpenAPIManager {
+    private specs;
+    private docsBaseUrl;
+    private config;
+    private fetcher;
+    private refreshTimer?;
+    constructor(docsBaseUrl?: string);
+    initialize(): Promise<void>;
+    private loadSpecsFromCache;
+    private getFormatFromUrl;
+    private setupAutoRefresh;
+    private checkAndRefreshStale;
+    private reloadSpec;
+    loadAllSpecs(): Promise<void>;
+    cleanup(): void;
+    getSpec(name: string): OpenAPISpec | undefined;
+    getAllSpecs(): {
+        name: string;
+        spec: OpenAPISpec;
+    }[];
+    getServers(specName: string): OpenAPIV3.ServerObject[] | undefined;
+    getSecuritySchemes(specName: string): Record<string, OpenAPIV3.SecuritySchemeObject> | undefined;
+    getGlobalSecurity(specName: string): OpenAPIV3.SecurityRequirementObject[] | undefined;
+    getTags(specName: string): OpenAPIV3.TagObject[] | undefined;
+    getExternalDocs(specName: string): OpenAPIV3.ExternalDocumentationObject | undefined;
+    getInfoExtras(specName: string): {
+        contact?: OpenAPIV3.ContactObject;
+        license?: OpenAPIV3.LicenseObject;
+        termsOfService?: string;
+    } | undefined;
+    getEndpoints(specName: string, options?: {
+        method?: string;
+        tag?: string;
+    }): APIEndpoint[];
+    getEndpoint(specName: string, path: string, method: string): APIEndpoint | undefined;
+    getSchemas(specName: string): APISchema[];
+    getSchema(specName: string, schemaName: string): APISchema | undefined;
+    searchSchemas(query: string): {
+        specName: string;
+        schema: APISchema;
+    }[];
+    formatEndpointDetails(endpoint: APIEndpoint): string;
+    formatSchemaDetails(schema: APISchema): string;
+}

package/dist/openapi-utils.js

@@ -0,0 +1,501 @@
+import yaml from "js-yaml";
+import SwaggerParser from "swagger-parser";
+import { SpecFetcher } from "./spec-fetcher.js";
+import { defaultSpecConfig } from "./config.js";
+import { logger } from "./logger.js";
+export class OpenAPIManager {
+    specs = new Map();
+    docsBaseUrl;
+    config;
+    fetcher;
+    refreshTimer;
+    constructor(docsBaseUrl) {
+        this.docsBaseUrl = docsBaseUrl ?? process.env.DOCS_BASE_URL ?? "https://docs.brinkcommerce.com";
+        this.config = defaultSpecConfig;
+        this.fetcher = new SpecFetcher(this.config.cache);
+    }
+    async initialize() {
+        await this.fetcher.initialize();
+        // Force refresh if environment variable is set
+        const forceRefresh = process.env.SPECS_FORCE_REFRESH === "true";
+        // Fetch all specs (using cache if fresh)
+        await this.fetcher.refreshAll(this.config.sources, forceRefresh);
+        // Load specs into memory
+        await this.loadSpecsFromCache();
+        // Setup auto-refresh
+        this.setupAutoRefresh();
+    }
+    async loadSpecsFromCache() {
+        for (const source of this.config.sources) {
+            try {
+                const content = await this.fetcher.loadFromCache(source.name);
+                if (!content) {
+                    logger.warn(`No cached content found for ${source.name}`);
+                    continue;
+                }
+                const format = this.getFormatFromUrl(source.url);
+                let spec;
+                if (format === "json") {
+                    spec = JSON.parse(content);
+                }
+                else {
+                    spec = yaml.load(content);
+                }
+                // Validate and dereference the spec
+                // @ts-expect-error - SwaggerParser.dereference is not typed but works
+                const validatedSpec = (await SwaggerParser.dereference(spec));
+                this.specs.set(source.name, validatedSpec);
+                logger.debug(`Loaded spec ${source.name} into memory`);
+            }
+            catch (error) {
+                logger.error(`Failed to load spec ${source.name}:`, error.message);
+            }
+        }
+    }
+    getFormatFromUrl(url) {
+        const urlPath = new URL(url).pathname;
+        const match = urlPath.match(/\.(json|yaml|yml)$/i);
+        if (!match) {
+            throw new Error(`Cannot determine format from URL: ${url}`);
+        }
+        return match[1].toLowerCase();
+    }
+    setupAutoRefresh() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+        }
+        this.refreshTimer = setInterval(async () => {
+            await this.checkAndRefreshStale();
+        }, this.config.cache.checkInterval);
+        logger.info(`Auto-refresh setup: checking every ${this.config.cache.checkInterval / 1000 / 60} minutes`);
+    }
+    async checkAndRefreshStale() {
+        logger.debug("Checking for stale specs...");
+        for (const source of this.config.sources) {
+            if (this.fetcher.isStale(source.name)) {
+                try {
+                    logger.info(`Refreshing stale spec: ${source.name}`);
+                    await this.fetcher.refreshIfNeeded(source);
+                    await this.reloadSpec(source.name);
+                }
+                catch (error) {
+                    logger.warn(`Failed to refresh ${source.name}:`, error.message);
+                }
+            }
+        }
+    }
+    async reloadSpec(specName) {
+        const source = this.config.sources.find((s) => s.name === specName);
+        if (!source) {
+            logger.warn(`Cannot reload spec ${specName}: source not found in config`);
+            return;
+        }
+        const content = await this.fetcher.loadFromCache(specName);
+        if (!content) {
+            logger.warn(`Cannot reload spec ${specName}: no cached content`);
+            return;
+        }
+        try {
+            const format = this.getFormatFromUrl(source.url);
+            let spec;
+            if (format === "json") {
+                spec = JSON.parse(content);
+            }
+            else {
+                spec = yaml.load(content);
+            }
+            // @ts-expect-error - SwaggerParser.dereference is not typed but works
+            const validatedSpec = (await SwaggerParser.dereference(spec));
+            this.specs.set(specName, validatedSpec);
+            logger.debug(`Reloaded spec ${specName} from cache`);
+        }
+        catch (error) {
+            logger.error(`Failed to reload spec ${specName}:`, error.message);
+        }
+    }
+    async loadAllSpecs() {
+        // For backwards compatibility, delegate to initialize
+        await this.initialize();
+    }
+    cleanup() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = undefined;
+            logger.info("Auto-refresh timer stopped");
+        }
+    }
+    getSpec(name) {
+        return this.specs.get(name);
+    }
+    getAllSpecs() {
+        return Array.from(this.specs.entries()).map(([name, spec]) => ({ name, spec }));
+    }
+    // New methods for additional OpenAPI fields
+    getServers(specName) {
+        const spec = this.specs.get(specName);
+        return spec?.servers;
+    }
+    getSecuritySchemes(specName) {
+        const spec = this.specs.get(specName);
+        if (!spec?.components?.securitySchemes)
+            return undefined;
+        // Filter out reference objects and return only resolved security schemes
+        const schemes = {};
+        for (const [name, scheme] of Object.entries(spec.components.securitySchemes)) {
+            if (!("$ref" in scheme)) {
+                schemes[name] = scheme;
+            }
+        }
+        return Object.keys(schemes).length > 0 ? schemes : undefined;
+    }
+    getGlobalSecurity(specName) {
+        const spec = this.specs.get(specName);
+        return spec?.security;
+    }
+    getTags(specName) {
+        const spec = this.specs.get(specName);
+        return spec?.tags;
+    }
+    getExternalDocs(specName) {
+        const spec = this.specs.get(specName);
+        return spec?.externalDocs;
+    }
+    getInfoExtras(specName) {
+        const spec = this.specs.get(specName);
+        if (!spec)
+            return undefined;
+        const extras = {};
+        if (spec.info.contact)
+            extras.contact = spec.info.contact;
+        if (spec.info.license)
+            extras.license = spec.info.license;
+        if (spec.info.termsOfService)
+            extras.termsOfService = spec.info.termsOfService;
+        return Object.keys(extras).length > 0 ? extras : undefined;
+    }
+    getEndpoints(specName, options = {}) {
+        const spec = this.specs.get(specName);
+        if (!spec)
+            return [];
+        const endpoints = [];
+        for (const [path, pathItem] of Object.entries(spec.paths)) {
+            if (!pathItem)
+                continue;
+            const methods = [
+                "get",
+                "put",
+                "post",
+                "delete",
+                "options",
+                "head",
+                "patch",
+                "trace",
+            ];
+            for (const method of methods) {
+                const operation = pathItem[method];
+                if (!operation)
+                    continue;
+                const endpoint = {
+                    path,
+                    method: method.toUpperCase(),
+                    operationId: operation.operationId,
+                    summary: operation.summary,
+                    description: operation.description,
+                    tags: operation.tags,
+                    parameters: operation.parameters,
+                    requestBody: operation.requestBody,
+                    responses: operation.responses,
+                    // New fields
+                    deprecated: operation.deprecated,
+                    security: operation.security,
+                    externalDocs: operation.externalDocs,
+                };
+                // Apply filters
+                if (options.method && endpoint.method !== options.method.toUpperCase()) {
+                    continue;
+                }
+                if (options.tag && !endpoint.tags?.includes(options.tag)) {
+                    continue;
+                }
+                endpoints.push(endpoint);
+            }
+        }
+        return endpoints;
+    }
+    getEndpoint(specName, path, method) {
+        const endpoints = this.getEndpoints(specName);
+        return endpoints.find((e) => e.path === path && e.method === method.toUpperCase());
+    }
+    getSchemas(specName) {
+        const spec = this.specs.get(specName);
+        if (!spec?.components?.schemas)
+            return [];
+        return Object.entries(spec.components.schemas).map(([name, schema]) => {
+            // Check if it's a reference object
+            if ("$ref" in schema) {
+                return {
+                    name,
+                    type: "reference",
+                    description: `Reference to ${schema.$ref}`,
+                };
+            }
+            // It's a SchemaObject - use type assertion for accessing all fields
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const schemaObj = schema;
+            return {
+                name,
+                type: schemaObj.type ?? "object",
+                properties: schemaObj.properties,
+                description: schemaObj.description,
+                required: schemaObj.required,
+                // New fields - validation & format
+                enum: schemaObj.enum,
+                format: schemaObj.format,
+                pattern: schemaObj.pattern,
+                minimum: schemaObj.minimum,
+                maximum: schemaObj.maximum,
+                minLength: schemaObj.minLength,
+                maxLength: schemaObj.maxLength,
+                nullable: schemaObj.nullable,
+                default: schemaObj.default,
+                readOnly: schemaObj.readOnly,
+                writeOnly: schemaObj.writeOnly,
+                // Array support (only exists on ArraySchemaObject)
+                items: schemaObj.items,
+                // Object support
+                additionalProperties: schemaObj.additionalProperties,
+                // Composition
+                allOf: schemaObj.allOf,
+                oneOf: schemaObj.oneOf,
+                anyOf: schemaObj.anyOf,
+                // Examples
+                example: schemaObj.example,
+            };
+        });
+    }
+    getSchema(specName, schemaName) {
+        const schemas = this.getSchemas(specName);
+        return schemas.find((s) => s.name === schemaName);
+    }
+    searchSchemas(query) {
+        const results = [];
+        for (const [specName] of this.specs.entries()) {
+            const schemas = this.getSchemas(specName);
+            for (const schema of schemas) {
+                // Search in schema name, description, and property names
+                const searchText = [
+                    schema.name,
+                    schema.description ?? "",
+                    ...Object.keys(schema.properties ?? {}),
+                ]
+                    .join(" ")
+                    .toLowerCase();
+                if (searchText.includes(query.toLowerCase())) {
+                    results.push({ specName, schema });
+                }
+            }
+        }
+        return results;
+    }
+    formatEndpointDetails(endpoint) {
+        let details = `## ${endpoint.method} ${endpoint.path}\n\n`;
+        // Show deprecation warning prominently at the top
+        if (endpoint.deprecated) {
+            details += `⚠️ **DEPRECATED** - This endpoint is deprecated and may be removed in a future version.\n\n`;
+        }
+        if (endpoint.summary) {
+            details += `**Summary:** ${endpoint.summary}\n\n`;
+        }
+        if (endpoint.description) {
+            details += `**Description:** ${endpoint.description}\n\n`;
+        }
+        if (endpoint.tags && endpoint.tags.length > 0) {
+            details += `**Tags:** ${endpoint.tags.join(", ")}\n\n`;
+        }
+        // Show security requirements
+        if (endpoint.security && endpoint.security.length > 0) {
+            details += `**Security:**\n`;
+            for (const req of endpoint.security) {
+                const schemes = Object.entries(req);
+                if (schemes.length === 0) {
+                    details += `- None required (public endpoint)\n`;
+                }
+                else {
+                    for (const [scheme, scopes] of schemes) {
+                        if (scopes && scopes.length > 0) {
+                            details += `- \`${scheme}\` (scopes: ${scopes.join(", ")})\n`;
+                        }
+                        else {
+                            details += `- \`${scheme}\`\n`;
+                        }
+                    }
+                }
+            }
+            details += "\n";
+        }
+        if (endpoint.parameters && endpoint.parameters.length > 0) {
+            details += `**Parameters:**\n`;
+            for (const param of endpoint.parameters) {
+                const requiredMark = param.required ? " (required)" : "";
+                const schema = param.schema;
+                const format = schema?.format ? `, format: ${schema.format}` : "";
+                const enumVals = schema?.enum ? `, enum: [${schema.enum.join(", ")}]` : "";
+                details += `- \`${param.name}\` (${param.in}${requiredMark}${format}${enumVals}) - ${param.description ?? "No description"}\n`;
+            }
+            details += "\n";
+        }
+        if (endpoint.requestBody) {
+            details += `**Request Body:**\n`;
+            details += "```json\n";
+            details += JSON.stringify(endpoint.requestBody, null, 2);
+            details += "\n```\n\n";
+        }
+        if (endpoint.responses) {
+            details += `**Responses:**\n`;
+            for (const [code, response] of Object.entries(endpoint.responses)) {
+                const desc = "$ref" in response
+                    ? `Reference to ${response.$ref}`
+                    : (response.description ?? "No description");
+                details += `- **${code}**: ${desc}\n`;
+            }
+        }
+        // Show external docs if available
+        if (endpoint.externalDocs) {
+            details += `\n**External Documentation:** ${endpoint.externalDocs.description ?? "More info"} - ${endpoint.externalDocs.url}\n`;
+        }
+        details += `\n📚 **Documentation**: ${this.docsBaseUrl}/api-reference\n`;
+        details += `💡 **Examples**: ${this.docsBaseUrl}/examples\n`;
+        return details;
+    }
+    formatSchemaDetails(schema) {
+        let details = `## ${schema.name} Schema\n\n`;
+        if (schema.description) {
+            details += `**Description:** ${schema.description}\n\n`;
+        }
+        // Build type string with format
+        let typeStr = schema.type;
+        if (schema.format) {
+            typeStr += ` (format: ${schema.format})`;
+        }
+        if (schema.nullable) {
+            typeStr += " | null";
+        }
+        details += `**Type:** ${typeStr}\n\n`;
+        // Show array item type
+        if (schema.type === "array" && schema.items) {
+            const itemType = "$ref" in schema.items
+                ? schema.items.$ref.split("/").pop()
+                : schema.items.type ?? "unknown";
+            details += `**Items:** ${itemType}\n\n`;
+        }
+        // Show enum values
+        if (schema.enum && schema.enum.length > 0) {
+            details += `**Allowed Values:**\n`;
+            for (const val of schema.enum) {
+                details += `- \`${val}\`\n`;
+            }
+            details += "\n";
+        }
+        // Show composition (allOf, oneOf, anyOf)
+        if (schema.allOf && schema.allOf.length > 0) {
+            details += `**Composed of (allOf):**\n`;
+            for (const item of schema.allOf) {
+                if ("$ref" in item) {
+                    details += `- ${item.$ref.split("/").pop()}\n`;
+                }
+                else {
+                    details += `- inline schema (${item.type ?? "object"})\n`;
+                }
+            }
+            details += "\n";
+        }
+        if (schema.oneOf && schema.oneOf.length > 0) {
+            details += `**One of:**\n`;
+            for (const item of schema.oneOf) {
+                if ("$ref" in item) {
+                    details += `- ${item.$ref.split("/").pop()}\n`;
+                }
+                else {
+                    details += `- inline schema (${item.type ?? "object"})\n`;
+                }
+            }
+            details += "\n";
+        }
+        if (schema.anyOf && schema.anyOf.length > 0) {
+            details += `**Any of:**\n`;
+            for (const item of schema.anyOf) {
+                if ("$ref" in item) {
+                    details += `- ${item.$ref.split("/").pop()}\n`;
+                }
+                else {
+                    details += `- inline schema (${item.type ?? "object"})\n`;
+                }
+            }
+            details += "\n";
+        }
+        // Show validation constraints
+        const constraints = [];
+        if (schema.minimum !== undefined)
+            constraints.push(`min: ${schema.minimum}`);
+        if (schema.maximum !== undefined)
+            constraints.push(`max: ${schema.maximum}`);
+        if (schema.minLength !== undefined)
+            constraints.push(`minLength: ${schema.minLength}`);
+        if (schema.maxLength !== undefined)
+            constraints.push(`maxLength: ${schema.maxLength}`);
+        if (schema.pattern)
+            constraints.push(`pattern: ${schema.pattern}`);
+        if (constraints.length > 0) {
+            details += `**Constraints:** ${constraints.join(", ")}\n\n`;
+        }
+        // Show default value
+        if (schema.default !== undefined) {
+            details += `**Default:** \`${JSON.stringify(schema.default)}\`\n\n`;
+        }
+        // Show read/write only
+        if (schema.readOnly) {
+            details += `**Read Only:** Yes\n\n`;
+        }
+        if (schema.writeOnly) {
+            details += `**Write Only:** Yes\n\n`;
+        }
+        // Show additionalProperties
+        if (schema.additionalProperties !== undefined) {
+            if (schema.additionalProperties === true) {
+                details += `**Additional Properties:** Allowed (any type)\n\n`;
+            }
+            else if (schema.additionalProperties === false) {
+                details += `**Additional Properties:** Not allowed\n\n`;
+            }
+            else if ("$ref" in schema.additionalProperties) {
+                details += `**Additional Properties:** ${schema.additionalProperties.$ref.split("/").pop()}\n\n`;
+            }
+            else {
+                const addPropsType = schema.additionalProperties.type;
+                details += `**Additional Properties:** ${addPropsType ?? "object"}\n\n`;
+            }
+        }
+        // Show properties
+        if (schema.properties) {
+            details += `**Properties:**\n`;
+            for (const [propName, propSpec] of Object.entries(schema.properties)) {
+                const required = schema.required?.includes(propName) ? " (required)" : "";
+                const propType = propSpec.type ?? "unknown";
+                const propFormat = propSpec.format ? `, format: ${propSpec.format}` : "";
+                const propEnum = propSpec.enum ? `, enum: [${propSpec.enum.slice(0, 3).join(", ")}${propSpec.enum.length > 3 ? ", ..." : ""}]` : "";
+                const propReadOnly = propSpec.readOnly ? " [read-only]" : "";
+                const propWriteOnly = propSpec.writeOnly ? " [write-only]" : "";
+                details += `- \`${propName}\` (${propType}${propFormat}${propEnum})${required}${propReadOnly}${propWriteOnly} - ${propSpec.description ?? "No description"}\n`;
+            }
+            details += "\n";
+        }
+        // Show example
+        if (schema.example !== undefined) {
+            details += `**Example:**\n`;
+            details += "```json\n";
+            details += JSON.stringify(schema.example, null, 2);
+            details += "\n```\n";
+        }
+        return details;
+    }
+}