midnight-mcp 0.0.1 → 0.0.4

package/dist/tools/search.d.ts

@@ -62,57 +62,15 @@ export type SearchDocsInput = z.infer<typeof SearchDocsInputSchema>;
 /**
  * Search Compact smart contract code and patterns
  */
-export declare function searchCompact(input: SearchCompactInput): Promise<{
-    results: {
-        code: string;
-        relevanceScore: number;
-        source: {
-            repository: string;
-            filePath: string;
-            lines: string;
-        };
-        codeType: string;
-        name: string;
-    }[];
-    totalResults: number;
-    query: string;
-}>;
+export declare function searchCompact(input: SearchCompactInput): Promise<{}>;
 /**
  * Search TypeScript SDK code, types, and API implementations
  */
-export declare function searchTypeScript(input: SearchTypeScriptInput): Promise<{
-    results: {
-        code: string;
-        relevanceScore: number;
-        source: {
-            repository: string;
-            filePath: string;
-            lines: string;
-        };
-        codeType: string;
-        name: string;
-        isExported: boolean;
-    }[];
-    totalResults: number;
-    query: string;
-}>;
+export declare function searchTypeScript(input: SearchTypeScriptInput): Promise<{}>;
 /**
  * Full-text search across official Midnight documentation
  */
-export declare function searchDocs(input: SearchDocsInput): Promise<{
-    results: {
-        content: string;
-        relevanceScore: number;
-        source: {
-            repository: string;
-            filePath: string;
-            section: string;
-        };
-    }[];
-    totalResults: number;
-    query: string;
-    category: "guides" | "api" | "concepts" | "all";
-}>;
+export declare function searchDocs(input: SearchDocsInput): Promise<{}>;
 export declare const searchTools: ({
     name: string;
     description: string;

package/dist/tools/search.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { vectorStore } from "../db/index.js";
-import { logger } from "../utils/index.js";
+import { logger, validateQuery, validateNumber, searchCache, createCacheKey, } from "../utils/index.js";
 // Schema definitions for tool inputs
 export const SearchCompactInputSchema = z.object({
     query: z.string().describe("Natural language search query for Compact code"),
@@ -44,13 +44,39 @@ export const SearchDocsInputSchema = z.object({
  * Search Compact smart contract code and patterns
  */
 export async function searchCompact(input) {
-    logger.debug("Searching Compact code", { query: input.query });
+    // Validate input
+    const queryValidation = validateQuery(input.query);
+    if (!queryValidation.isValid) {
+        return {
+            error: "Invalid query",
+            details: queryValidation.errors,
+            suggestion: "Provide a valid search query with at least 2 characters",
+        };
+    }
+    const limitValidation = validateNumber(input.limit, {
+        min: 1,
+        max: 50,
+        defaultValue: 10,
+    });
+    const sanitizedQuery = queryValidation.sanitized;
+    const limit = limitValidation.value;
+    logger.debug("Searching Compact code", {
+        query: sanitizedQuery,
+        originalQuery: input.query,
+    });
+    // Check cache first
+    const cacheKey = createCacheKey("compact", sanitizedQuery, limit, input.filter?.repository);
+    const cached = searchCache.get(cacheKey);
+    if (cached) {
+        logger.debug("Search cache hit", { cacheKey });
+        return cached;
+    }
     const filter = {
         language: "compact",
         ...input.filter,
     };
-    const results = await vectorStore.search(input.query, input.limit, filter);
-    return {
+    const results = await vectorStore.search(sanitizedQuery, limit, filter);
+    const response = {
         results: results.map((r) => ({
             code: r.content,
             relevanceScore: r.score,
@@ -63,24 +89,53 @@ export async function searchCompact(input) {
             name: r.metadata.codeName,
         })),
         totalResults: results.length,
-        query: input.query,
+        query: sanitizedQuery,
+        ...(queryValidation.warnings.length > 0 && {
+            warnings: queryValidation.warnings,
+        }),
     };
+    // Cache the response
+    searchCache.set(cacheKey, response);
+    return response;
 }
 /**
  * Search TypeScript SDK code, types, and API implementations
  */
 export async function searchTypeScript(input) {
-    logger.debug("Searching TypeScript code", { query: input.query });
+    // Validate input
+    const queryValidation = validateQuery(input.query);
+    if (!queryValidation.isValid) {
+        return {
+            error: "Invalid query",
+            details: queryValidation.errors,
+            suggestion: "Provide a valid search query with at least 2 characters",
+        };
+    }
+    const limitValidation = validateNumber(input.limit, {
+        min: 1,
+        max: 50,
+        defaultValue: 10,
+    });
+    const sanitizedQuery = queryValidation.sanitized;
+    const limit = limitValidation.value;
+    logger.debug("Searching TypeScript code", { query: sanitizedQuery });
+    // Check cache
+    const cacheKey = createCacheKey("typescript", sanitizedQuery, limit, input.includeTypes, input.includeExamples);
+    const cached = searchCache.get(cacheKey);
+    if (cached) {
+        logger.debug("Search cache hit", { cacheKey });
+        return cached;
+    }
     const filter = {
         language: "typescript",
     };
-    const results = await vectorStore.search(input.query, input.limit, filter);
+    const results = await vectorStore.search(sanitizedQuery, limit, filter);
     // Filter based on type preferences
     let filteredResults = results;
     if (!input.includeTypes) {
         filteredResults = results.filter((r) => r.metadata.codeType !== "type" && r.metadata.codeType !== "interface");
     }
-    return {
+    const response = {
         results: filteredResults.map((r) => ({
             code: r.content,
             relevanceScore: r.score,
@@ -94,14 +149,42 @@ export async function searchTypeScript(input) {
             isExported: r.metadata.isPublic,
         })),
         totalResults: filteredResults.length,
-        query: input.query,
+        query: sanitizedQuery,
+        ...(queryValidation.warnings.length > 0 && {
+            warnings: queryValidation.warnings,
+        }),
     };
+    searchCache.set(cacheKey, response);
+    return response;
 }
 /**
  * Full-text search across official Midnight documentation
  */
 export async function searchDocs(input) {
-    logger.debug("Searching documentation", { query: input.query });
+    // Validate input
+    const queryValidation = validateQuery(input.query);
+    if (!queryValidation.isValid) {
+        return {
+            error: "Invalid query",
+            details: queryValidation.errors,
+            suggestion: "Provide a valid search query with at least 2 characters",
+        };
+    }
+    const limitValidation = validateNumber(input.limit, {
+        min: 1,
+        max: 50,
+        defaultValue: 10,
+    });
+    const sanitizedQuery = queryValidation.sanitized;
+    const limit = limitValidation.value;
+    logger.debug("Searching documentation", { query: sanitizedQuery });
+    // Check cache
+    const cacheKey = createCacheKey("docs", sanitizedQuery, limit, input.category);
+    const cached = searchCache.get(cacheKey);
+    if (cached) {
+        logger.debug("Search cache hit", { cacheKey });
+        return cached;
+    }
     const filter = {
         language: "markdown",
     };
@@ -110,8 +193,8 @@ export async function searchDocs(input) {
         // Docs are typically in the midnight-docs repo
         filter.repository = "midnightntwrk/midnight-docs";
     }
-    const results = await vectorStore.search(input.query, input.limit, filter);
-    return {
+    const results = await vectorStore.search(sanitizedQuery, limit, filter);
+    const response = {
         results: results.map((r) => ({
             content: r.content,
             relevanceScore: r.score,
@@ -122,9 +205,14 @@ export async function searchDocs(input) {
             },
         })),
         totalResults: results.length,
-        query: input.query,
+        query: sanitizedQuery,
         category: input.category,
+        ...(queryValidation.warnings.length > 0 && {
+            warnings: queryValidation.warnings,
+        }),
     };
+    searchCache.set(cacheKey, response);
+    return response;
 }
 // Tool definitions for MCP
 export const searchTools = [

package/dist/utils/cache.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Generic caching utilities for MCP server
+ * Provides TTL-based caching with memory management
+ */
+export interface CacheOptions {
+    ttl: number;
+    maxSize?: number;
+    name?: string;
+}
+export interface CacheEntry<T> {
+    value: T;
+    expiresAt: number;
+    createdAt: number;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    size: number;
+    hitRate: number;
+}
+/**
+ * Generic cache implementation with TTL and size limits
+ */
+export declare class Cache<T> {
+    private cache;
+    private options;
+    private stats;
+    constructor(options: CacheOptions);
+    /**
+     * Get a value from the cache
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set a value in the cache
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a key from the cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Remove expired entries
+     */
+    prune(): number;
+    /**
+     * Evict the oldest entry to make room
+     */
+    private evictOldest;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get or set with a factory function
+     */
+    getOrSet(key: string, factory: () => Promise<T>, ttl?: number): Promise<T>;
+}
+/**
+ * Create a cache key from multiple parts
+ */
+export declare function createCacheKey(...parts: (string | number | boolean | undefined)[]): string;
+export declare const searchCache: Cache<unknown>;
+export declare const fileCache: Cache<string>;
+export declare const metadataCache: Cache<unknown>;
+/**
+ * Prune all caches periodically
+ */
+export declare function pruneAllCaches(): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/utils/cache.js

@@ -0,0 +1,172 @@
+/**
+ * Generic caching utilities for MCP server
+ * Provides TTL-based caching with memory management
+ */
+import { logger } from "./logger.js";
+/**
+ * Generic cache implementation with TTL and size limits
+ */
+export class Cache {
+    cache = new Map();
+    options;
+    stats = { hits: 0, misses: 0 };
+    constructor(options) {
+        this.options = {
+            ttl: options.ttl,
+            maxSize: options.maxSize || 1000,
+            name: options.name || "cache",
+        };
+    }
+    /**
+     * Get a value from the cache
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            return undefined;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            this.stats.misses++;
+            return undefined;
+        }
+        this.stats.hits++;
+        return entry.value;
+    }
+    /**
+     * Set a value in the cache
+     */
+    set(key, value, ttl) {
+        // Enforce size limit
+        if (this.cache.size >= this.options.maxSize) {
+            this.evictOldest();
+        }
+        const now = Date.now();
+        this.cache.set(key, {
+            value,
+            expiresAt: now + (ttl || this.options.ttl),
+            createdAt: now,
+        });
+    }
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete a key from the cache
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        this.cache.clear();
+        logger.debug(`Cache cleared: ${this.options.name}`);
+    }
+    /**
+     * Remove expired entries
+     */
+    prune() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+                pruned++;
+            }
+        }
+        if (pruned > 0) {
+            logger.debug(`Cache pruned: ${this.options.name}`, { pruned });
+        }
+        return pruned;
+    }
+    /**
+     * Evict the oldest entry to make room
+     */
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.createdAt < oldestTime) {
+                oldestTime = entry.createdAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            size: this.cache.size,
+            hitRate: total > 0 ? this.stats.hits / total : 0,
+        };
+    }
+    /**
+     * Get or set with a factory function
+     */
+    async getOrSet(key, factory, ttl) {
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = await factory();
+        this.set(key, value, ttl);
+        return value;
+    }
+}
+/**
+ * Create a cache key from multiple parts
+ */
+export function createCacheKey(...parts) {
+    return parts
+        .filter((p) => p !== undefined)
+        .map((p) => String(p))
+        .join(":");
+}
+// Pre-configured caches for common use cases
+export const searchCache = new Cache({
+    ttl: 5 * 60 * 1000, // 5 minutes
+    maxSize: 500,
+    name: "search",
+});
+export const fileCache = new Cache({
+    ttl: 10 * 60 * 1000, // 10 minutes
+    maxSize: 200,
+    name: "file",
+});
+export const metadataCache = new Cache({
+    ttl: 15 * 60 * 1000, // 15 minutes
+    maxSize: 100,
+    name: "metadata",
+});
+/**
+ * Prune all caches periodically
+ */
+export function pruneAllCaches() {
+    searchCache.prune();
+    fileCache.prune();
+    metadataCache.prune();
+}
+// Auto-prune every 5 minutes
+setInterval(pruneAllCaches, 5 * 60 * 1000);
+//# sourceMappingURL=cache.js.map

package/dist/utils/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * User-friendly error messages and error handling utilities
+ */
+export declare class MCPError extends Error {
+    readonly code: string;
+    readonly suggestion?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, suggestion?: string, details?: Record<string, unknown>);
+    toJSON(): {
+        details?: Record<string, unknown> | undefined;
+        error: string;
+        code: string;
+        suggestion: string | undefined;
+    };
+}
+/**
+ * Common error codes
+ */
+export declare const ErrorCodes: {
+    readonly RATE_LIMIT: "RATE_LIMIT_EXCEEDED";
+    readonly NOT_FOUND: "RESOURCE_NOT_FOUND";
+    readonly NETWORK: "NETWORK_ERROR";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly UNKNOWN_REPO: "UNKNOWN_REPOSITORY";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly CHROMADB_UNAVAILABLE: "CHROMADB_UNAVAILABLE";
+    readonly OPENAI_UNAVAILABLE: "OPENAI_UNAVAILABLE";
+};
+/**
+ * Create user-friendly error from various error types
+ */
+export declare function createUserError(error: unknown, context?: string): MCPError;
+/**
+ * Format error for MCP response
+ */
+export declare function formatErrorResponse(error: unknown, context?: string): {
+    error: string;
+    code: string;
+    suggestion?: string;
+};
+/**
+ * Wrap a function with error handling
+ */
+export declare function withErrorHandling<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, context: string): T;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.js

@@ -0,0 +1,95 @@
+/**
+ * User-friendly error messages and error handling utilities
+ */
+export class MCPError extends Error {
+    code;
+    suggestion;
+    details;
+    constructor(message, code, suggestion, details) {
+        super(message);
+        this.name = "MCPError";
+        this.code = code;
+        this.suggestion = suggestion;
+        this.details = details;
+    }
+    toJSON() {
+        return {
+            error: this.message,
+            code: this.code,
+            suggestion: this.suggestion,
+            ...(this.details && { details: this.details }),
+        };
+    }
+}
+/**
+ * Common error codes
+ */
+export const ErrorCodes = {
+    RATE_LIMIT: "RATE_LIMIT_EXCEEDED",
+    NOT_FOUND: "RESOURCE_NOT_FOUND",
+    NETWORK: "NETWORK_ERROR",
+    INVALID_INPUT: "INVALID_INPUT",
+    UNKNOWN_REPO: "UNKNOWN_REPOSITORY",
+    PARSE_ERROR: "PARSE_ERROR",
+    CHROMADB_UNAVAILABLE: "CHROMADB_UNAVAILABLE",
+    OPENAI_UNAVAILABLE: "OPENAI_UNAVAILABLE",
+};
+/**
+ * Create user-friendly error from various error types
+ */
+export function createUserError(error, context) {
+    const message = error instanceof Error ? error.message : String(error);
+    const ctx = context ? ` while ${context}` : "";
+    // Rate limit errors
+    if (message.includes("rate limit") ||
+        message.includes("403") ||
+        message.includes("API rate limit")) {
+        return new MCPError(`GitHub API rate limit exceeded${ctx}`, ErrorCodes.RATE_LIMIT, "Add GITHUB_TOKEN to your config to increase limits from 60 to 5000 requests/hour. " +
+            "Get a token at https://github.com/settings/tokens");
+    }
+    // Not found errors
+    if (message.includes("404") || message.includes("Not Found")) {
+        return new MCPError(`Resource not found${ctx}`, ErrorCodes.NOT_FOUND, "Check that the repository, file, or version exists and is publicly accessible.");
+    }
+    // Network errors
+    if (message.includes("network") ||
+        message.includes("ECONNREFUSED") ||
+        message.includes("ETIMEDOUT") ||
+        message.includes("timeout")) {
+        return new MCPError(`Network error${ctx}`, ErrorCodes.NETWORK, "Check your internet connection and try again. If the problem persists, " +
+            "the service may be temporarily unavailable.");
+    }
+    // ChromaDB errors
+    if (message.includes("chroma") || message.includes("8000")) {
+        return new MCPError(`ChromaDB is not available${ctx}`, ErrorCodes.CHROMADB_UNAVAILABLE, "ChromaDB is optional. Without it, search uses keyword matching instead of semantic search. " +
+            "To enable semantic search, run: docker run -d -p 8000:8000 chromadb/chroma");
+    }
+    // OpenAI errors
+    if (message.includes("openai") || message.includes("embedding")) {
+        return new MCPError(`OpenAI API error${ctx}`, ErrorCodes.OPENAI_UNAVAILABLE, "OpenAI is optional. Without it, search uses keyword matching. " +
+            "To enable semantic search, add OPENAI_API_KEY to your config.");
+    }
+    // Default error
+    return new MCPError(`An error occurred${ctx}: ${message}`, "UNKNOWN_ERROR", "If this problem persists, please report it at https://github.com/Olanetsoft/midnight-mcp/issues");
+}
+/**
+ * Format error for MCP response
+ */
+export function formatErrorResponse(error, context) {
+    const mcpError = error instanceof MCPError ? error : createUserError(error, context);
+    return mcpError.toJSON();
+}
+/**
+ * Wrap a function with error handling
+ */
+export function withErrorHandling(fn, context) {
+    return (async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            throw createUserError(error, context);
+        }
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/health.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Health check utilities for MCP server monitoring
+ */
+export interface HealthStatus {
+    status: "healthy" | "degraded" | "unhealthy";
+    timestamp: string;
+    version: string;
+    uptime: number;
+    checks: {
+        name: string;
+        status: "pass" | "warn" | "fail";
+        message?: string;
+        latency?: number;
+    }[];
+}
+/**
+ * Perform a full health check
+ */
+export declare function getHealthStatus(): Promise<HealthStatus>;
+/**
+ * Get a quick health check (no external calls)
+ */
+export declare function getQuickHealthStatus(): Omit<HealthStatus, "checks"> & {
+    checks: {
+        name: string;
+        status: "pass";
+    }[];
+};
+//# sourceMappingURL=health.d.ts.map