zapql-mcp 0.1.1

package/README.md

@@ -0,0 +1,146 @@
+# ZapQL MCP Server
+
+Autonomous SQL Server query optimizer via the [Model Context Protocol](https://modelcontextprotocol.io). Connect Claude (or any MCP-compatible agent) directly to your SQL Server and get instant query analysis and AI-powered optimization suggestions.
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+npm install
+npm run build
+```
+
+### 2. Configure environment
+
+Create `~/.zapql/.env`:
+
+```env
+# Required
+SQL_CONNECTION_STRING=Server=your-server,1433;Database=your-db;User Id=your-user;Password=your-password;Encrypt=false
+ZAPQL_API_KEY=any-string-you-choose
+
+# Optional — enables AI optimization suggestions
+LITELLM_API_KEY=your-openai-or-litellm-key
+LITELLM_MODEL=gpt-4          # default: gpt-4
+ZAPQL_TOP_N=20                # number of optimization suggestions
+```
+
+### 3. Add to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zapql": {
+      "command": "node",
+      "args": ["/path/to/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. ZapQL tools will appear in the tool panel.
+
+---
+
+## Tools
+
+### `connect_database`
+Establish a connection to a SQL Server instance.
+
+```
+Input:  connectionString (string)
+Output: connection status, server info, database name
+```
+
+### `analyze_query`
+Analyze a SQL query for performance issues without executing it.
+
+```
+Input:  connectionString (string), queryText (string)
+Output: issues list, complexity score, execution plan, suggestions
+```
+
+Detects: SELECT *, missing WHERE clause, leading wildcards, N+1 patterns, NOT IN subqueries, excessive OR conditions, implicit conversions.
+
+### `optimize_query`
+Get AI-powered optimization suggestions for a slow query.
+
+```
+Input:  connectionString (string), originalQuery (string), context? (string)
+Output: optimizedQuery, explanation, performance comparison, cost improvement estimate
+```
+
+Requires `LITELLM_API_KEY`. Results are cached in SQLite at `~/.zapql/cache.db`.
+
+---
+
+## MCP Resources
+
+| Resource | Description |
+|----------|-------------|
+| `zapql:///connections` | List of active database connections |
+| `zapql:///queries/{connection}` | Recent queries for a connection |
+| `zapql:///optimization/{queryId}` | Cached optimization result |
+
+---
+
+## Architecture
+
+```
+Claude Desktop
+     │  MCP Protocol (stdio)
+     ▼
+ZapQL MCP Server (Node.js)
+     ├── Tools: connect_database, analyze_query, optimize_query
+     ├── Resources: connections, queries, optimization results
+     ├── SQLServerDriver (mssql) ──→ Your SQL Server
+     ├── QueryCache (in-memory + SQLite persistence)
+     └── LiteLLM ──→ OpenAI / any LLM provider
+```
+
+---
+
+## Development
+
+```bash
+npm run build       # Compile TypeScript
+npm test            # Run unit tests (node:test)
+npm run dev         # Run with tsx (no compile step)
+npm run lint        # Type-check without emit
+```
+
+Tests run against `dist/` (compiled output). No SQL Server connection required for unit tests — the SQL driver is mocked.
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SQL_CONNECTION_STRING` | ✅ | — | mssql connection string |
+| `ZAPQL_API_KEY` | ✅ | — | Internal API key (any string) |
+| `LITELLM_API_KEY` | — | — | Enables optimize_query |
+| `LITELLM_MODEL` | — | `gpt-4` | LLM model for optimization |
+| `ZAPQL_TOP_N` | — | `20` | Max optimization suggestions |
+
+Config file: `~/.zapql/.env` (loaded automatically on startup)
+
+---
+
+## Logs
+
+Log files at `~/.zapql/logs/zapql-YYYY-MM-DD.log`. Structured JSON. Rotates daily, keeps 7 days.
+
+---
+
+## Status
+
+- ✅ MCP tools: connect_database, analyze_query, optimize_query
+- ✅ MCP resources: connections, queries, optimization
+- ✅ SQLite state persistence  
+- ✅ In-memory query cache with TTL
+- ✅ Comprehensive error handling
+- ⏳ Integration tests (US-016)

package/dist/cache/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cache module exports
+ *
+ * Provides comprehensive caching functionality for ZapQL MCP server
+ */
+export { QueryCache, CacheType, getQueryCache, resetQueryCache, type CacheStats, type CacheConfig } from './query-cache';

package/dist/cache/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Cache module exports
+ *
+ * Provides comprehensive caching functionality for ZapQL MCP server
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetQueryCache = exports.getQueryCache = exports.CacheType = exports.QueryCache = void 0;
+var query_cache_1 = require("./query-cache");
+Object.defineProperty(exports, "QueryCache", { enumerable: true, get: function () { return query_cache_1.QueryCache; } });
+Object.defineProperty(exports, "CacheType", { enumerable: true, get: function () { return query_cache_1.CacheType; } });
+Object.defineProperty(exports, "getQueryCache", { enumerable: true, get: function () { return query_cache_1.getQueryCache; } });
+Object.defineProperty(exports, "resetQueryCache", { enumerable: true, get: function () { return query_cache_1.resetQueryCache; } });
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,6CAOuB;AANrB,yGAAA,UAAU,OAAA;AACV,wGAAA,SAAS,OAAA;AACT,4GAAA,aAAa,OAAA;AACb,8GAAA,eAAe,OAAA"}

package/dist/cache/query-cache.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Query Cache System for ZapQL MCP Server
+ *
+ * Provides comprehensive caching for database queries and API calls with:
+ * - Configurable TTL (Time To Live) caching
+ * - LRU eviction with memory size limits
+ * - Different cache policies for different data types
+ * - Cache hit/miss metrics and logging
+ * - SQLite persistence for optimization results
+ */
+/**
+ * Cache types with different TTL policies
+ */
+export declare enum CacheType {
+    EXECUTION_PLAN = "execution_plan",// 5 minutes TTL
+    DMV_QUERIES = "dmv_queries",// 1 minute TTL
+    OPTIMIZATION = "optimization",// Permanent (stored in SQLite)
+    GENERAL = "general"
+}
+/**
+ * Cache statistics for monitoring
+ */
+export interface CacheStats {
+    totalEntries: number;
+    totalSize: number;
+    hitCount: number;
+    missCount: number;
+    evictionCount: number;
+    hitRate: number;
+    averageEntrySize: number;
+    oldestEntry?: Date;
+    newestEntry?: Date;
+    entriesByType: Record<CacheType, number>;
+}
+/**
+ * Cache configuration options
+ */
+export interface CacheConfig {
+    maxSizeBytes: number;
+    defaultTtlMs: number;
+    cleanupIntervalMs: number;
+    enableMetrics: boolean;
+    sqlitePath?: string;
+}
+/**
+ * Comprehensive query cache system with LRU eviction and persistent storage
+ */
+export declare class QueryCache {
+    private cache;
+    private config;
+    private logger;
+    private db;
+    private cleanupTimer;
+    private hitCount;
+    private missCount;
+    private evictionCount;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Generate cache key from connection string and query content
+     */
+    static generateCacheKey(connectionString: string, queryContent: string, type: CacheType): string;
+    /**
+     * Set cache entry with appropriate TTL based on type
+     */
+    set<T>(key: string, value: T, type?: CacheType, customTtlMs?: number): void;
+    /**
+     * Get cache entry if not expired
+     */
+    get<T>(key: string, type?: CacheType): T | null;
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key: string, type?: CacheType): boolean;
+    /**
+     * Delete cache entry
+     */
+    delete(key: string, type?: CacheType): boolean;
+    /**
+     * Clear all cache entries or entries of specific type
+     */
+    clear(type?: CacheType): void;
+    /**
+     * Get comprehensive cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): void;
+    /**
+     * Close cache and cleanup resources
+     */
+    close(): void;
+    /**
+     * Initialize SQLite database for persistent optimization results
+     */
+    private initializeSQLiteDatabase;
+    /**
+     * Store optimization result permanently in SQLite
+     */
+    private setPermanentOptimization;
+    /**
+     * Get optimization result from SQLite
+     */
+    private getPermanentOptimization;
+    /**
+     * Check if permanent optimization exists
+     */
+    private hasPermanentOptimization;
+    /**
+     * Delete permanent optimization
+     */
+    private deletePermanentOptimization;
+    /**
+     * Clear all permanent optimizations
+     */
+    private clearPermanentOptimizations;
+    /**
+     * Get count of permanent optimization entries
+     */
+    private getOptimizationCount;
+    /**
+     * Ensure cache doesn't exceed size limit using LRU eviction
+     */
+    private ensureCapacity;
+    /**
+     * Evict least recently used entries to free up space
+     */
+    private evictLRU;
+    /**
+     * Estimate memory size of value in bytes
+     */
+    private estimateSize;
+    /**
+     * Get total size of all cache entries
+     */
+    private getTotalSize;
+    /**
+     * Record cache hit for metrics
+     */
+    private recordHit;
+    /**
+     * Record cache miss for metrics
+     */
+    private recordMiss;
+    /**
+     * Start periodic cleanup timer
+     */
+    private startCleanupTimer;
+}
+/**
+ * Get or create singleton cache instance
+ */
+export declare function getQueryCache(config?: Partial<CacheConfig>): QueryCache;
+/**
+ * Reset singleton cache instance (primarily for testing)
+ */
+export declare function resetQueryCache(): void;