midnight-mcp 0.0.1 → 0.0.4

package/dist/utils/health.js

@@ -0,0 +1,132 @@
+/**
+ * Health check utilities for MCP server monitoring
+ */
+import { githubClient } from "../pipeline/index.js";
+// Track server start time
+const startTime = Date.now();
+// Get package version
+const VERSION = process.env.npm_package_version || "0.0.3";
+/**
+ * Check if GitHub API is accessible
+ */
+async function checkGitHubAPI() {
+    const start = Date.now();
+    try {
+        // Try to get rate limit info (lightweight API call)
+        const rateLimit = await githubClient.getRateLimit();
+        const latency = Date.now() - start;
+        if (rateLimit.remaining < 100) {
+            return {
+                status: "warn",
+                message: `Rate limit low: ${rateLimit.remaining}/${rateLimit.limit} remaining`,
+                latency,
+            };
+        }
+        return {
+            status: "pass",
+            message: `Rate limit: ${rateLimit.remaining}/${rateLimit.limit}`,
+            latency,
+        };
+    }
+    catch (error) {
+        return {
+            status: "fail",
+            message: `GitHub API error: ${error instanceof Error ? error.message : String(error)}`,
+            latency: Date.now() - start,
+        };
+    }
+}
+/**
+ * Check if ChromaDB is accessible (optional dependency)
+ */
+async function checkVectorStore() {
+    try {
+        // Import dynamically to handle optional dependency
+        const { vectorStore } = await import("../db/index.js");
+        // Check if vector store is initialized
+        if (vectorStore) {
+            return {
+                status: "pass",
+                message: "Vector store available",
+            };
+        }
+        return {
+            status: "warn",
+            message: "Vector store not initialized (semantic search unavailable)",
+        };
+    }
+    catch {
+        return {
+            status: "warn",
+            message: "Vector store not configured (semantic search unavailable)",
+        };
+    }
+}
+/**
+ * Check memory usage
+ */
+function checkMemory() {
+    const usage = process.memoryUsage();
+    const heapUsedMB = Math.round(usage.heapUsed / 1024 / 1024);
+    const heapTotalMB = Math.round(usage.heapTotal / 1024 / 1024);
+    const percentUsed = Math.round((usage.heapUsed / usage.heapTotal) * 100);
+    if (percentUsed > 90) {
+        return {
+            status: "fail",
+            message: `High memory usage: ${heapUsedMB}MB/${heapTotalMB}MB (${percentUsed}%)`,
+        };
+    }
+    if (percentUsed > 75) {
+        return {
+            status: "warn",
+            message: `Elevated memory usage: ${heapUsedMB}MB/${heapTotalMB}MB (${percentUsed}%)`,
+        };
+    }
+    return {
+        status: "pass",
+        message: `Memory: ${heapUsedMB}MB/${heapTotalMB}MB (${percentUsed}%)`,
+    };
+}
+/**
+ * Perform a full health check
+ */
+export async function getHealthStatus() {
+    const checks = [];
+    // Run all health checks in parallel
+    const [githubCheck, vectorCheck] = await Promise.all([
+        checkGitHubAPI(),
+        checkVectorStore(),
+    ]);
+    const memoryCheck = checkMemory();
+    checks.push({ name: "github_api", ...githubCheck }, { name: "vector_store", ...vectorCheck }, { name: "memory", ...memoryCheck });
+    // Determine overall status
+    const hasFailure = checks.some((c) => c.status === "fail");
+    const hasWarning = checks.some((c) => c.status === "warn");
+    let status = "healthy";
+    if (hasFailure) {
+        status = "unhealthy";
+    }
+    else if (hasWarning) {
+        status = "degraded";
+    }
+    return {
+        status,
+        timestamp: new Date().toISOString(),
+        version: VERSION,
+        uptime: Math.round((Date.now() - startTime) / 1000),
+        checks,
+    };
+}
+/**
+ * Get a quick health check (no external calls)
+ */
+export function getQuickHealthStatus() {
+    return {
+        status: "healthy",
+        timestamp: new Date().toISOString(),
+        version: VERSION,
+        uptime: Math.round((Date.now() - startTime) / 1000),
+        checks: [{ name: "server", status: "pass" }],
+    };
+}
+//# sourceMappingURL=health.js.map

package/dist/utils/index.d.ts

@@ -2,4 +2,13 @@ export { config } from "./config.js";
 export type { Config, RepositoryConfig } from "./config.js";
 export { DEFAULT_REPOSITORIES } from "./config.js";
 export { logger } from "./logger.js";
+export { MCPError, ErrorCodes, createUserError, formatErrorResponse, withErrorHandling, } from "./errors.js";
+export { validateQuery, validateRepository, validatePath, validateRef, validateNumber, validateToolArgs, sanitizeString, } from "./validation.js";
+export type { ValidationResult } from "./validation.js";
+export { getHealthStatus, getQuickHealthStatus } from "./health.js";
+export type { HealthStatus } from "./health.js";
+export { updateRateLimitFromHeaders, updateRateLimit, getRateLimitStatus, shouldProceedWithRequest, getTimeUntilReset, formatRateLimitStatus, decrementRemaining, } from "./rate-limit.js";
+export type { RateLimitInfo, RateLimitStatus } from "./rate-limit.js";
+export { Cache, createCacheKey, searchCache, fileCache, metadataCache, pruneAllCaches, } from "./cache.js";
+export type { CacheOptions, CacheEntry, CacheStats } from "./cache.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -1,4 +1,13 @@
 export { config } from "./config.js";
 export { DEFAULT_REPOSITORIES } from "./config.js";
 export { logger } from "./logger.js";
+export { MCPError, ErrorCodes, createUserError, formatErrorResponse, withErrorHandling, } from "./errors.js";
+// Validation utilities
+export { validateQuery, validateRepository, validatePath, validateRef, validateNumber, validateToolArgs, sanitizeString, } from "./validation.js";
+// Health check utilities
+export { getHealthStatus, getQuickHealthStatus } from "./health.js";
+// Rate limit tracking
+export { updateRateLimitFromHeaders, updateRateLimit, getRateLimitStatus, shouldProceedWithRequest, getTimeUntilReset, formatRateLimitStatus, decrementRemaining, } from "./rate-limit.js";
+// Caching utilities
+export { Cache, createCacheKey, searchCache, fileCache, metadataCache, pruneAllCaches, } from "./cache.js";
 //# sourceMappingURL=index.js.map

package/dist/utils/logger.d.ts

@@ -1,13 +1,42 @@
 type LogLevel = "debug" | "info" | "warn" | "error";
+type LogFormat = "text" | "json";
 declare class Logger {
     private level;
-    constructor(level?: LogLevel);
+    private format;
+    private service;
+    constructor(level?: LogLevel, format?: LogFormat, service?: string);
+    /**
+     * Set log format at runtime
+     */
+    setFormat(format: LogFormat): void;
+    /**
+     * Set log level at runtime
+     */
+    setLevel(level: LogLevel): void;
     private shouldLog;
+    private formatTextMessage;
+    private formatJsonMessage;
     private formatMessage;
     debug(message: string, meta?: object): void;
     info(message: string, meta?: object): void;
     warn(message: string, meta?: object): void;
     error(message: string, meta?: object): void;
+    /**
+     * Create a child logger with additional context
+     */
+    child(context: object): ChildLogger;
+}
+/**
+ * Child logger that includes additional context in all log messages
+ */
+declare class ChildLogger {
+    private parent;
+    private context;
+    constructor(parent: Logger, context: object);
+    debug(message: string, meta?: object): void;
+    info(message: string, meta?: object): void;
+    warn(message: string, meta?: object): void;
+    error(message: string, meta?: object): void;
 }
 export declare const logger: Logger;
 export {};

package/dist/utils/logger.js

@@ -7,17 +7,51 @@ const LOG_LEVELS = {
 };
 class Logger {
     level;
-    constructor(level = "info") {
+    format;
+    service;
+    constructor(level = "info", format = "text", service = "midnight-mcp") {
+        this.level = level;
+        this.format = format;
+        this.service = service;
+    }
+    /**
+     * Set log format at runtime
+     */
+    setFormat(format) {
+        this.format = format;
+    }
+    /**
+     * Set log level at runtime
+     */
+    setLevel(level) {
         this.level = level;
     }
     shouldLog(level) {
         return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
     }
-    formatMessage(level, message, meta) {
+    formatTextMessage(level, message, meta) {
         const timestamp = new Date().toISOString();
         const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
         return `[${timestamp}] [${level.toUpperCase()}] ${message}${metaStr}`;
     }
+    formatJsonMessage(level, message, meta) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            service: this.service,
+        };
+        if (meta) {
+            entry.meta = meta;
+        }
+        return JSON.stringify(entry);
+    }
+    formatMessage(level, message, meta) {
+        if (this.format === "json") {
+            return this.formatJsonMessage(level, message, meta);
+        }
+        return this.formatTextMessage(level, message, meta);
+    }
     debug(message, meta) {
         if (this.shouldLog("debug")) {
             console.error(this.formatMessage("debug", message, meta));
@@ -38,6 +72,37 @@ class Logger {
             console.error(this.formatMessage("error", message, meta));
         }
     }
+    /**
+     * Create a child logger with additional context
+     */
+    child(context) {
+        return new ChildLogger(this, context);
+    }
+}
+/**
+ * Child logger that includes additional context in all log messages
+ */
+class ChildLogger {
+    parent;
+    context;
+    constructor(parent, context) {
+        this.parent = parent;
+        this.context = context;
+    }
+    debug(message, meta) {
+        this.parent.debug(message, { ...this.context, ...meta });
+    }
+    info(message, meta) {
+        this.parent.info(message, { ...this.context, ...meta });
+    }
+    warn(message, meta) {
+        this.parent.warn(message, { ...this.context, ...meta });
+    }
+    error(message, meta) {
+        this.parent.error(message, { ...this.context, ...meta });
+    }
 }
-export const logger = new Logger(config.logLevel);
+// Determine log format from environment
+const logFormat = process.env.LOG_FORMAT === "json" ? "json" : "text";
+export const logger = new Logger(config.logLevel, logFormat);
 //# sourceMappingURL=logger.js.map

package/dist/utils/rate-limit.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Rate limit tracking and management utilities
+ * Tracks GitHub API rate limits and warns before hitting limits
+ */
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: Date;
+    used: number;
+}
+export interface RateLimitStatus {
+    isLimited: boolean;
+    isWarning: boolean;
+    remaining: number;
+    limit: number;
+    resetAt: Date;
+    percentUsed: number;
+    message: string;
+}
+/**
+ * Update rate limit info from API response headers
+ */
+export declare function updateRateLimitFromHeaders(headers: Record<string, string | undefined>): void;
+/**
+ * Update rate limit info directly
+ */
+export declare function updateRateLimit(info: RateLimitInfo): void;
+/**
+ * Get current rate limit status
+ */
+export declare function getRateLimitStatus(): RateLimitStatus;
+/**
+ * Check if we should proceed with an API call
+ * Returns true if safe to proceed, false if we should wait/fail
+ */
+export declare function shouldProceedWithRequest(): {
+    proceed: boolean;
+    reason?: string;
+    waitMs?: number;
+};
+/**
+ * Get time until rate limit resets
+ */
+export declare function getTimeUntilReset(): number;
+/**
+ * Check if cached rate limit info is stale
+ */
+export declare function isRateLimitStale(): boolean;
+/**
+ * Get cached rate limit info
+ */
+export declare function getCachedRateLimit(): RateLimitInfo | null;
+/**
+ * Decrement remaining count (for optimistic tracking)
+ */
+export declare function decrementRemaining(): void;
+/**
+ * Format rate limit status for display
+ */
+export declare function formatRateLimitStatus(): string;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/utils/rate-limit.js

@@ -0,0 +1,148 @@
+/**
+ * Rate limit tracking and management utilities
+ * Tracks GitHub API rate limits and warns before hitting limits
+ */
+import { logger } from "./logger.js";
+// Warning threshold - warn when this percentage of rate limit is used
+const WARNING_THRESHOLD = 0.8; // 80%
+// Critical threshold - consider limited when this percentage is used
+const CRITICAL_THRESHOLD = 0.95; // 95%
+// Cached rate limit info
+let cachedRateLimit = null;
+let lastUpdate = 0;
+const CACHE_TTL = 60 * 1000; // 1 minute cache
+/**
+ * Update rate limit info from API response headers
+ */
+export function updateRateLimitFromHeaders(headers) {
+    const limit = parseInt(headers["x-ratelimit-limit"] || "5000", 10);
+    const remaining = parseInt(headers["x-ratelimit-remaining"] || "5000", 10);
+    const resetTimestamp = parseInt(headers["x-ratelimit-reset"] || "0", 10);
+    cachedRateLimit = {
+        limit,
+        remaining,
+        reset: new Date(resetTimestamp * 1000),
+        used: limit - remaining,
+    };
+    lastUpdate = Date.now();
+    // Log warning if approaching limit
+    const percentUsed = (cachedRateLimit.used / cachedRateLimit.limit) * 100;
+    if (percentUsed >= WARNING_THRESHOLD * 100) {
+        logger.warn("GitHub API rate limit warning", {
+            remaining: cachedRateLimit.remaining,
+            limit: cachedRateLimit.limit,
+            percentUsed: Math.round(percentUsed),
+            resetAt: cachedRateLimit.reset.toISOString(),
+        });
+    }
+}
+/**
+ * Update rate limit info directly
+ */
+export function updateRateLimit(info) {
+    cachedRateLimit = info;
+    lastUpdate = Date.now();
+}
+/**
+ * Get current rate limit status
+ */
+export function getRateLimitStatus() {
+    if (!cachedRateLimit) {
+        return {
+            isLimited: false,
+            isWarning: false,
+            remaining: 5000,
+            limit: 5000,
+            resetAt: new Date(),
+            percentUsed: 0,
+            message: "Rate limit info not yet available",
+        };
+    }
+    const percentUsed = cachedRateLimit.used / cachedRateLimit.limit;
+    const isWarning = percentUsed >= WARNING_THRESHOLD;
+    const isLimited = percentUsed >= CRITICAL_THRESHOLD || cachedRateLimit.remaining <= 10;
+    let message;
+    if (isLimited) {
+        const minutesUntilReset = Math.ceil((cachedRateLimit.reset.getTime() - Date.now()) / 60000);
+        message = `Rate limited! Resets in ${minutesUntilReset} minutes`;
+    }
+    else if (isWarning) {
+        message = `Warning: ${cachedRateLimit.remaining} API calls remaining (${Math.round(percentUsed * 100)}% used)`;
+    }
+    else {
+        message = `${cachedRateLimit.remaining}/${cachedRateLimit.limit} API calls remaining`;
+    }
+    return {
+        isLimited,
+        isWarning,
+        remaining: cachedRateLimit.remaining,
+        limit: cachedRateLimit.limit,
+        resetAt: cachedRateLimit.reset,
+        percentUsed: Math.round(percentUsed * 100),
+        message,
+    };
+}
+/**
+ * Check if we should proceed with an API call
+ * Returns true if safe to proceed, false if we should wait/fail
+ */
+export function shouldProceedWithRequest() {
+    if (!cachedRateLimit) {
+        return { proceed: true };
+    }
+    if (cachedRateLimit.remaining <= 10) {
+        const waitMs = Math.max(0, cachedRateLimit.reset.getTime() - Date.now());
+        return {
+            proceed: false,
+            reason: `Rate limit nearly exhausted (${cachedRateLimit.remaining} remaining)`,
+            waitMs,
+        };
+    }
+    return { proceed: true };
+}
+/**
+ * Get time until rate limit resets
+ */
+export function getTimeUntilReset() {
+    if (!cachedRateLimit) {
+        return 0;
+    }
+    return Math.max(0, cachedRateLimit.reset.getTime() - Date.now());
+}
+/**
+ * Check if cached rate limit info is stale
+ */
+export function isRateLimitStale() {
+    return Date.now() - lastUpdate > CACHE_TTL;
+}
+/**
+ * Get cached rate limit info
+ */
+export function getCachedRateLimit() {
+    return cachedRateLimit;
+}
+/**
+ * Decrement remaining count (for optimistic tracking)
+ */
+export function decrementRemaining() {
+    if (cachedRateLimit && cachedRateLimit.remaining > 0) {
+        cachedRateLimit.remaining--;
+        cachedRateLimit.used++;
+    }
+}
+/**
+ * Format rate limit status for display
+ */
+export function formatRateLimitStatus() {
+    const status = getRateLimitStatus();
+    if (status.isLimited) {
+        return `⛔ ${status.message}`;
+    }
+    else if (status.isWarning) {
+        return `⚠️ ${status.message}`;
+    }
+    else {
+        return `✅ ${status.message}`;
+    }
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/utils/validation.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Input validation and sanitization utilities
+ * Protects against injection attacks and malformed inputs
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    sanitized: string;
+    warnings: string[];
+    errors: string[];
+}
+/**
+ * Sanitize a string by removing dangerous patterns
+ */
+export declare function sanitizeString(input: string, maxLength?: number): string;
+/**
+ * Validate and sanitize a search query
+ */
+export declare function validateQuery(query: unknown): ValidationResult;
+/**
+ * Validate and sanitize a repository name
+ */
+export declare function validateRepository(repo: unknown): ValidationResult;
+/**
+ * Validate and sanitize a file path
+ */
+export declare function validatePath(path: unknown): ValidationResult;
+/**
+ * Validate and sanitize a git ref (branch, tag, or commit)
+ */
+export declare function validateRef(ref: unknown): ValidationResult;
+/**
+ * Validate a numeric input within bounds
+ */
+export declare function validateNumber(value: unknown, options: {
+    min?: number;
+    max?: number;
+    defaultValue: number;
+}): {
+    isValid: boolean;
+    value: number;
+    error?: string;
+};
+/**
+ * Validate tool arguments with automatic sanitization
+ */
+export declare function validateToolArgs<T extends Record<string, unknown>>(args: T, validators: Partial<Record<keyof T, (value: unknown) => ValidationResult>>): {
+    isValid: boolean;
+    sanitized: Partial<T>;
+    errors: string[];
+    warnings: string[];
+};
+//# sourceMappingURL=validation.d.ts.map