mcp-quickbase 2.0.1

package/dist/utils/retry.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateBackoff = calculateBackoff;
+exports.withRetry = withRetry;
+const logger_1 = require("./logger");
+const logger = (0, logger_1.createLogger)('RetryUtil');
+/**
+ * Default retry options
+ */
+const DEFAULT_RETRY_OPTIONS = {
+    maxRetries: 3,
+    baseDelay: 1000,
+    maxDelay: 10000,
+    backoffFactor: 2,
+    isRetryable: (error) => {
+        // Default logic for determining if an error is retryable
+        if (!error)
+            return false;
+        // Handle fetch response errors
+        if (typeof error === 'object' && error !== null && 'status' in error) {
+            const httpError = error;
+            // Retry 429 (Too Many Requests), 408 (Request Timeout), and 5xx errors
+            return httpError.status === 429 ||
+                httpError.status === 408 ||
+                (httpError.status >= 500 && httpError.status < 600);
+        }
+        // Handle network errors
+        if (error instanceof Error) {
+            return error.message.includes('network') ||
+                error.message.includes('timeout') ||
+                error.message.includes('connection');
+        }
+        return false;
+    }
+};
+/**
+ * Calculates the delay time for a retry attempt with exponential backoff
+ * @param attempt Retry attempt number (0-based)
+ * @param options Retry options
+ * @returns Delay time in milliseconds
+ */
+function calculateBackoff(attempt, options) {
+    const { baseDelay, backoffFactor = 2, maxDelay = 10000 } = options;
+    // Use exponential backoff with jitter
+    const exponentialDelay = baseDelay * Math.pow(backoffFactor, attempt);
+    const jitter = Math.random() * 0.2 * exponentialDelay; // 20% jitter
+    const delay = exponentialDelay + jitter;
+    // Ensure delay doesn't exceed maximum
+    return Math.min(delay, maxDelay);
+}
+/**
+ * Wrapper function that adds retry logic to any async function
+ * @param fn Function to add retry logic to
+ * @param options Retry options
+ * @returns Function with retry logic
+ */
+function withRetry(fn, options = {}) {
+    const fullOptions = { ...DEFAULT_RETRY_OPTIONS, ...options };
+    return async function retryWrapper(...args) {
+        let lastError;
+        for (let attempt = 0; attempt <= fullOptions.maxRetries; attempt++) {
+            try {
+                if (attempt > 0) {
+                    logger.info(`Retry attempt ${attempt} of ${fullOptions.maxRetries}`);
+                }
+                return await fn(...args);
+            }
+            catch (error) {
+                lastError = error;
+                const shouldRetry = attempt < fullOptions.maxRetries &&
+                    fullOptions.isRetryable &&
+                    fullOptions.isRetryable(error);
+                if (!shouldRetry) {
+                    logger.debug('Error not retryable or max retries reached', { error });
+                    throw error;
+                }
+                const delay = calculateBackoff(attempt, fullOptions);
+                logger.debug(`Retrying after ${delay}ms due to error`, { error });
+                // Wait before retrying
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+        // This should never be reached due to the loop structure,
+        // but TypeScript requires it for type safety
+        throw lastError;
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"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"}

package/dist/utils/validation.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/**
+ * Custom validation error with additional context
+ */
+export declare class ValidationError extends Error {
+    readonly context?: {
+        toolName?: string;
+        issues?: z.ZodIssue[];
+        originalParams?: unknown;
+    } | undefined;
+    constructor(message: string, context?: {
+        toolName?: string;
+        issues?: z.ZodIssue[];
+        originalParams?: unknown;
+    } | undefined);
+}
+/**
+ * Create Zod schema for MCP server tool registration
+ * Returns object with property schemas for MCP server
+ */
+export declare function createMcpZodSchema(schema: Record<string, unknown>): Record<string, z.ZodTypeAny>;
+/**
+ * Create Zod object schema for parameter validation
+ * Returns complete Zod schema for validation
+ */
+export declare function createValidationSchema(schema: Record<string, unknown>): z.ZodSchema;
+/**
+ * Validate parameters using JSON Schema with comprehensive error handling
+ */
+export declare function validateParams<T>(params: unknown, schema: Record<string, unknown>, toolName?: string): T;
+export declare const createZodSchema: typeof createMcpZodSchema;
+export declare const createZodObjectSchema: typeof createValidationSchema;

package/dist/utils/validation.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createZodObjectSchema = exports.createZodSchema = exports.ValidationError = void 0;
+exports.createMcpZodSchema = createMcpZodSchema;
+exports.createValidationSchema = createValidationSchema;
+exports.validateParams = validateParams;
+const zod_1 = require("zod");
+const logger_1 = require("./logger");
+const logger = (0, logger_1.createLogger)('Validation');
+/**
+ * Custom validation error with additional context
+ */
+class ValidationError extends Error {
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Type guard for valid JSON Schema objects
+ */
+function isValidJSONSchema(schema) {
+    return typeof schema === 'object' &&
+        schema !== null &&
+        'type' in schema;
+}
+/**
+ * Schema cache for performance optimization
+ */
+class SchemaCache {
+    static get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            // Move to end for LRU behavior
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    static set(key, schema) {
+        // Remove existing key if present (for LRU update)
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        // Evict oldest entries if cache is full (proper LRU eviction)
+        while (this.cache.size >= this.MAX_SIZE) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+            else {
+                break; // Safety check
+            }
+        }
+        this.cache.set(key, schema);
+    }
+    static clear() {
+        this.cache.clear();
+    }
+    static getStats() {
+        return { size: this.cache.size, maxSize: this.MAX_SIZE };
+    }
+}
+SchemaCache.cache = new Map();
+SchemaCache.MAX_SIZE = 100;
+/**
+ * Convert JSON Schema property to Zod type
+ */
+function convertPropertyToZod(prop) {
+    if (!prop || typeof prop !== 'object') {
+        logger.warn('Invalid property schema, defaulting to unknown', { prop });
+        return zod_1.z.unknown();
+    }
+    const { type, enum: enumValues, items, format } = prop;
+    // Handle enum constraints
+    if (enumValues && Array.isArray(enumValues) && enumValues.length > 0) {
+        if (enumValues.every(v => typeof v === 'string')) {
+            return zod_1.z.enum(enumValues);
+        }
+        const literals = enumValues.map(v => zod_1.z.literal(v));
+        if (literals.length === 1) {
+            return literals[0];
+        }
+        return zod_1.z.union([literals[0], literals[1], ...literals.slice(2)]);
+    }
+    // Handle primitive types
+    switch (type) {
+        case 'string': {
+            let stringSchema = zod_1.z.string();
+            if (format === 'email')
+                stringSchema = stringSchema.email();
+            if (format === 'uri')
+                stringSchema = stringSchema.url();
+            return stringSchema;
+        }
+        case 'number':
+            return zod_1.z.number();
+        case 'integer':
+            return zod_1.z.number().int();
+        case 'boolean':
+            return zod_1.z.boolean();
+        case 'array':
+            if (items && typeof items === 'object') {
+                const itemSchema = convertPropertyToZod(items);
+                return zod_1.z.array(itemSchema);
+            }
+            return zod_1.z.array(zod_1.z.unknown());
+        case 'object':
+            // For nested objects, we'd need recursive handling
+            // For now, treat as record of unknown values
+            return zod_1.z.record(zod_1.z.unknown());
+        default:
+            logger.warn('Unsupported schema type, defaulting to unknown', { type, prop });
+            return zod_1.z.unknown();
+    }
+}
+/**
+ * Create Zod schema for MCP server tool registration
+ * Returns object with property schemas for MCP server
+ */
+function createMcpZodSchema(schema) {
+    if (!isValidJSONSchema(schema)) {
+        logger.warn('Invalid schema provided to createMcpZodSchema', { schema });
+        return {};
+    }
+    if (schema.type !== 'object' || !schema.properties) {
+        return {};
+    }
+    const properties = schema.properties;
+    const required = schema.required || [];
+    const zodSchemaObj = {};
+    try {
+        Object.entries(properties).forEach(([key, prop]) => {
+            let zodType = convertPropertyToZod(prop);
+            // Make optional if not in required array
+            if (!required.includes(key)) {
+                zodType = zodType.optional();
+            }
+            zodSchemaObj[key] = zodType;
+        });
+    }
+    catch (error) {
+        logger.error('Error creating MCP Zod schema', { error, schema });
+        return {};
+    }
+    return zodSchemaObj;
+}
+/**
+ * Create Zod object schema for parameter validation
+ * Returns complete Zod schema for validation
+ */
+function createValidationSchema(schema) {
+    if (!isValidJSONSchema(schema)) {
+        logger.warn('Invalid schema provided to createValidationSchema', { schema });
+        return zod_1.z.object({});
+    }
+    // Create cache key
+    const cacheKey = JSON.stringify(schema);
+    // Check cache first
+    const cached = SchemaCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    let zodSchema;
+    try {
+        if (schema.type === 'object' && schema.properties) {
+            const mcpSchema = createMcpZodSchema(schema);
+            zodSchema = zod_1.z.object(mcpSchema);
+        }
+        else {
+            // Non-object schemas (rare but possible)
+            zodSchema = zod_1.z.object({});
+        }
+    }
+    catch (error) {
+        logger.error('Error creating validation schema', { error, schema });
+        zodSchema = zod_1.z.object({});
+    }
+    // Cache the result
+    SchemaCache.set(cacheKey, zodSchema);
+    return zodSchema;
+}
+/**
+ * Validate parameters using JSON Schema with comprehensive error handling
+ */
+function validateParams(params, schema, toolName) {
+    try {
+        const zodSchema = createValidationSchema(schema);
+        logger.debug('Validating parameters', {
+            toolName,
+            paramsType: typeof params,
+            schemaType: schema.type
+        });
+        const result = zodSchema.parse(params);
+        logger.debug('Parameter validation successful', { toolName });
+        return result;
+    }
+    catch (error) {
+        if (error instanceof zod_1.z.ZodError) {
+            const context = toolName ? ` in tool "${toolName}"` : '';
+            const issues = error.errors.map(err => {
+                const path = err.path.length > 0 ? err.path.join('.') : 'root';
+                return `${path}: ${err.message}`;
+            });
+            const validationError = new ValidationError(`Parameter validation failed${context}: ${issues.join(', ')}`, {
+                toolName,
+                issues: error.errors,
+                originalParams: params
+            });
+            logger.error('Parameter validation failed', {
+                toolName,
+                error: validationError.message,
+                issues: error.errors,
+                params: typeof params === 'object' ? 'object' : params
+            });
+            throw validationError;
+        }
+        logger.error('Unexpected validation error', { error, toolName });
+        throw error;
+    }
+}
+// Legacy exports for backward compatibility
+exports.createZodSchema = createMcpZodSchema;
+exports.createZodObjectSchema = createValidationSchema;
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -0,0 +1,41 @@
+# 📚 Quickbase MCP Server Documentation
+
+This directory contains comprehensive documentation for Quickbase MCP Server v2.
+
+## 📋 Documentation Index
+
+### Getting Started
+- **[Quick Start Guide](quickstart.md)** - Get up and running in 5 minutes
+- **[Quick Reference](quick-reference.md)** - Common commands and troubleshooting
+
+### Development
+- **[Developer Guide](developer-guide.md)** - Comprehensive guide for developers
+- **[Architecture Overview](architecture.md)** - System design and components
+- **[Tools Reference](tools.md)** - Complete list of all 18 MCP tools
+
+### Operations
+- **[Deployment Guide](deployment.md)** - Production deployment instructions
+- **[Claude Prompts](claude-prompts.md)** - Example prompts for Claude interactions
+
+### Quality & Performance
+- **[Security Review](security-review.md)** - Security considerations and best practices
+- **[Performance Benchmarks](performance-benchmarks.md)** - Performance metrics and optimization
+- **[QA Report](final-qa-report.md)** - Quality assurance testing results
+
+## 🎯 Quick Links
+
+- **New users**: Start with [Quick Start Guide](quickstart.md)
+- **Developers**: See [Developer Guide](developer-guide.md)
+- **Tool usage**: Check [Tools Reference](tools.md)
+- **Production**: Review [Deployment Guide](deployment.md)
+
+## 📖 Documentation Standards
+
+All documentation follows these principles:
+- Clear, concise language
+- Practical examples
+- Up-to-date with v2.0.0
+- No redundancy between files
+- Consistent formatting
+
+Last updated: January 2025

package/docs/architecture.md

@@ -0,0 +1,94 @@
+# 🏗️ Quickbase MCP Server Architecture
+
+## 📋 Architecture Overview
+
+The Quickbase MCP Server follows a layered architecture:
+
+```
+┌────────────────────────────────────┐
+│           MCP Interface            │
+└────────────────────┬───────────────┘
+                     │
+┌────────────────────▼───────────────┐
+│         Quickbase Client           │
+│                                    │
+│  ┌──────────┐  ┌────────────────┐  │
+│  │  Cache   │  │  Error Handler │  │
+│  └──────────┘  └────────────────┘  │
+│                                    │
+│  ┌──────────┐  ┌────────────────┐  │
+│  │  Logger  │  │  Retry Logic   │  │
+│  └──────────┘  └────────────────┘  │
+└────────────────────┬───────────────┘
+                     │
+┌────────────────────▼───────────────┐
+│        Quickbase REST API          │
+└────────────────────────────────────┘
+```
+
+## 📊 Components
+
+### 🔗 MCP Interface
+- Exposes MCP-compliant tools
+- Handles parameter validation with JSON Schema
+- Formats responses according to MCP standards
+- Supports both stdio and HTTP transports
+
+### 🔄 Quickbase Client
+- Core client for interacting with Quickbase REST API
+- Manages authentication and HTTP requests
+- Implements TypeScript-first API wrappers
+- Provides structured error handling
+
+### 🛠️ Supporting Services
+
+#### 📋 Cache Service
+- Stores frequently accessed data (table schemas, field definitions)
+- Implements intelligent cache invalidation
+- Configurable TTL settings (default: 1 hour)
+- LRU eviction policy for memory management
+
+#### ⚠️ Error Handler
+- Classifies and formats API errors
+- Provides detailed error context for debugging
+- Handles error recovery with exponential backoff
+- Redacts sensitive information from error logs
+
+#### 📝 Logger
+- Structured logging with configurable levels
+- Automatic PII and sensitive data redaction
+- JSON-formatted logs for machine processing
+- Context-aware logging with request tracing
+
+#### 🔄 Retry Logic
+- Handles transient HTTP and network errors
+- Implements exponential backoff with jitter
+- Configurable retry limits and timeouts
+- Circuit breaker pattern for failing services
+
+## 🏢 Separation of Concerns
+
+The architecture follows clean separation principles:
+
+### 1. 🔗 Interface Layer (MCP Tools)
+- **Responsibility**: Expose Quickbase functionality via MCP protocol
+- **Components**: Tool registry, parameter validation, response formatting
+- **Benefits**: Protocol-agnostic business logic, easy testing
+
+### 2. 💼 Business Logic Layer (Quickbase Client)
+- **Responsibility**: Core Quickbase operations and data transformations
+- **Components**: API client, data models, business rules
+- **Benefits**: Reusable across different interfaces, focused testing
+
+### 3. 🛠️ Infrastructure Layer
+- **Responsibility**: Cross-cutting concerns and external dependencies
+- **Components**: Cache, logging, error handling, retry logic
+- **Benefits**: Centralized infrastructure management, easy configuration
+
+### 📊 Benefits of This Architecture
+
+- **🧪 Testability**: Each layer can be tested in isolation
+- **🔄 Maintainability**: Changes are isolated to specific layers
+- **🚀 Scalability**: Infrastructure components can be optimized independently
+- **🔌 Flexibility**: Interface layer can be swapped without affecting business logic
+- **🔒 Security**: Centralized handling of authentication and data protection