@iflow-mcp/apple-rag-mcp 4.6.2

package/src/services/database.ts

@@ -0,0 +1,202 @@
+/**
+ * PostgreSQL Database Service with pgvector
+ * Optimized for Cloudflare Workers with external database connection
+ */
+import postgres from "postgres";
+import type { AppConfig, SearchOptions, SearchResult } from "../types/index.js";
+import { logger } from "../utils/logger.js";
+
+export class DatabaseService {
+  private sql: ReturnType<typeof postgres>;
+  constructor(config: AppConfig) {
+    // Direct PostgreSQL connection - no checks, no logs
+    this.sql = postgres({
+      host: config.RAG_DB_HOST,
+      port: config.RAG_DB_PORT,
+      database: config.RAG_DB_DATABASE,
+      username: config.RAG_DB_USER,
+      password: config.RAG_DB_PASSWORD,
+      ssl: config.RAG_DB_SSLMODE === "require",
+      max: 5,
+      idle_timeout: 60000,
+      connect_timeout: 10000,
+      prepare: true,
+      connection: {
+        application_name: "apple-rag-mcp",
+      },
+      transform: {
+        undefined: null,
+      },
+    });
+  }
+
+  /**
+   * Initialize database - no checks, trust ready state
+   */
+  async initialize(): Promise<void> {
+    // Database assumed ready - no checks, no logs, instant return
+  }
+
+  /**
+   * Semantic search using vector similarity
+   */
+  async semanticSearch(
+    queryEmbedding: number[],
+    options: SearchOptions = {}
+  ): Promise<SearchResult[]> {
+    const { resultCount = 5 } = options;
+
+    try {
+      const results = await this.sql`
+        SELECT id, url, title, content, chunk_index, total_chunks
+        FROM chunks
+        WHERE embedding IS NOT NULL
+        ORDER BY embedding <=> ${JSON.stringify(queryEmbedding)}::halfvec
+        LIMIT ${resultCount}
+      `;
+
+      return results.map((row) => ({
+        id: row.id as string,
+        url: row.url as string,
+        title: row.title as string | null,
+        content: row.content as string,
+        contentLength: (row.content as string).length,
+        chunk_index: row.chunk_index as number,
+        total_chunks: row.total_chunks as number,
+      }));
+    } catch (error) {
+      logger.error(
+        `Database semantic search failed (operation: semantic_search, embeddingDimensions: ${queryEmbedding.length}, resultCount: ${resultCount}): ${String(error)}`
+      );
+      throw new Error(`Vector search failed: ${error}`);
+    }
+  }
+
+  /**
+   * Keyword search optimized for Apple Developer Documentation
+   * Uses PostgreSQL 'simple' configuration for precise matching of technical terms,
+   * API names, and special symbols (@State, SecItemAdd, etc.)
+   */
+  async keywordSearch(
+    query: string,
+    options: SearchOptions = {}
+  ): Promise<SearchResult[]> {
+    const { resultCount = 5 } = options;
+
+    try {
+      const results = await this.sql`
+        SELECT id, url, title, content, chunk_index, total_chunks
+        FROM chunks
+        WHERE to_tsvector('simple', COALESCE(title, '') || ' ' || content)
+              @@ plainto_tsquery('simple', ${query})
+        LIMIT ${resultCount}
+      `;
+
+      return results.map((row) => ({
+        id: row.id as string,
+        url: row.url as string,
+        title: row.title as string | null,
+        content: row.content as string,
+        contentLength: (row.content as string).length,
+        chunk_index: row.chunk_index as number,
+        total_chunks: row.total_chunks as number,
+      }));
+    } catch (error) {
+      logger.error(
+        `Database keyword search failed (operation: keyword_search, query: ${query.substring(0, 50)}, resultCount: ${resultCount}): ${String(error)}`
+      );
+      throw new Error(`Keyword search failed: ${error}`);
+    }
+  }
+
+  /**
+   * Normalize URL for flexible matching
+   */
+  private normalizeUrl(url: string): string {
+    // Remove trailing slash
+    let normalized = url.replace(/\/$/, "");
+
+    // Ensure https:// prefix
+    if (
+      !normalized.startsWith("http://") &&
+      !normalized.startsWith("https://")
+    ) {
+      normalized = `https://${normalized}`;
+    }
+
+    // Convert http:// to https://
+    if (normalized.startsWith("http://")) {
+      normalized = normalized.replace("http://", "https://");
+    }
+
+    return normalized;
+  }
+
+  /**
+   * Get page content by URL from pages table with flexible matching
+   */
+  async getPageByUrl(url: string): Promise<{
+    id: string;
+    url: string;
+    title: string | null;
+    content: string;
+  } | null> {
+    const normalizedUrl = this.normalizeUrl(url);
+
+    try {
+      // Try exact match first
+      let results = await this.sql`
+        SELECT id, url, title, content
+        FROM pages
+        WHERE url = ${normalizedUrl}
+        LIMIT 1
+      `;
+
+      // If no exact match, try flexible matching
+      if (results.length === 0) {
+        // Try with/without trailing slash
+        const alternativeUrl = normalizedUrl.endsWith("/")
+          ? normalizedUrl.slice(0, -1)
+          : `${normalizedUrl}/`;
+
+        results = await this.sql`
+          SELECT id, url, title, content
+          FROM pages
+          WHERE url = ${alternativeUrl}
+          LIMIT 1
+        `;
+      }
+
+      if (results.length === 0) {
+        return null;
+      }
+
+      const row = results[0];
+      return {
+        id: row.id as string,
+        url: row.url as string,
+        title: row.title as string | null,
+        content: row.content as string,
+      };
+    } catch (error) {
+      logger.error(
+        `Database page lookup failed (operation: page_lookup, url: ${url.substring(0, 100)}, normalizedUrl: ${this.normalizeUrl(url).substring(0, 100)}): ${String(error)}`
+      );
+      throw new Error(`Page lookup failed: ${error}`);
+    }
+  }
+
+  /**
+   * Close database connection
+   */
+  async close(): Promise<void> {
+    try {
+      await this.sql.end();
+    } catch (error) {
+      logger.error(
+        `Database close failed (operation: database_close): ${String(error)}`
+      );
+      // Don't re-throw - closing errors are not critical
+    }
+  }
+}

package/src/services/deepinfra-base.ts

@@ -0,0 +1,81 @@
+/**
+ * DeepInfra client utilities (config + base service)
+ * Minimal single-key client with retry support.
+ */
+
+import { logger } from "../utils/logger.js";
+
+export const DEEPINFRA_CONFIG = {
+  BASE_URL: "https://api.deepinfra.com",
+  TIMEOUT_MS: 5_000,
+  USER_AGENT: "Apple-RAG-MCP/2.0.0",
+  EMBEDDING_MODEL: "Qwen/Qwen3-Embedding-4B",
+  RERANKER_MODEL_PRIMARY: "Qwen/Qwen3-Reranker-8B",
+  RERANKER_MODEL_FALLBACK: "Qwen/Qwen3-Reranker-4B",
+} as const;
+
+export abstract class DeepInfraService<TRequest, TResponse, TResult> {
+  protected abstract readonly endpoint: string;
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    if (!apiKey) throw new Error("DEEPINFRA_API_KEY is required");
+    this.apiKey = apiKey;
+  }
+
+  protected async call(
+    input: TRequest,
+    operationName: string
+  ): Promise<TResult> {
+    const startTime = Date.now();
+    const payload = this.buildPayload(input);
+    let lastError!: Error;
+
+    for (let i = 0; i < 3; i++) {
+      try {
+        const json = await this.singleRequest(this.endpoint, payload);
+        logger.info(
+          `${operationName} completed (${((Date.now() - startTime) / 1000).toFixed(1)}s)`
+        );
+        return this.processResponse(json, input);
+      } catch (e) {
+        lastError = e instanceof Error ? e : new Error(String(e));
+      }
+    }
+
+    logger.error(
+      `${operationName} failed after 3 attempts (${((Date.now() - startTime) / 1000).toFixed(1)}s): ${lastError.message}`
+    );
+    throw lastError;
+  }
+
+  protected async singleRequest(
+    endpoint: string,
+    payload: unknown
+  ): Promise<TResponse> {
+    const res = await fetch(`${DEEPINFRA_CONFIG.BASE_URL}${endpoint}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        "User-Agent": DEEPINFRA_CONFIG.USER_AGENT,
+      },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(DEEPINFRA_CONFIG.TIMEOUT_MS),
+    });
+
+    if (!res.ok) {
+      throw new Error(
+        `API error ${res.status}: ${await res.text().catch(() => "")}`
+      );
+    }
+
+    return (await res.json()) as TResponse;
+  }
+
+  protected abstract buildPayload(input: TRequest): unknown;
+  protected abstract processResponse(
+    response: TResponse,
+    input: TRequest
+  ): TResult;
+}

package/src/services/embedding.ts

@@ -0,0 +1,96 @@
+/**
+ * Modern Embedding Service - MCP Optimized
+ * DeepInfra API integration (single provider, no fallback)
+ */
+
+import type { EmbeddingService as IEmbeddingService } from "../types/index.js";
+import { logger } from "../utils/logger.js";
+import { DEEPINFRA_CONFIG, DeepInfraService } from "./deepinfra-base.js";
+
+interface EmbeddingInput {
+  text: string;
+}
+
+interface EmbeddingPayload {
+  model: "Qwen/Qwen3-Embedding-4B";
+  input: string;
+  encoding_format: "float";
+}
+
+interface EmbeddingResponse {
+  data: Array<{
+    embedding: number[];
+  }>;
+}
+
+export class EmbeddingService
+  extends DeepInfraService<EmbeddingInput, EmbeddingResponse, number[]>
+  implements IEmbeddingService
+{
+  protected readonly endpoint = "/v1/openai/embeddings";
+
+  /**
+   * Create embedding (single provider)
+   */
+  async createEmbedding(text: string): Promise<number[]> {
+    if (!text?.trim()) {
+      throw new Error("Text cannot be empty for embedding generation");
+    }
+
+    const input: EmbeddingInput = { text: text.trim() };
+    return this.call(input, "Embedding generation");
+  }
+
+  /**
+   * Build API payload from request
+   */
+  protected buildPayload(input: EmbeddingInput): EmbeddingPayload {
+    return {
+      model: DEEPINFRA_CONFIG.EMBEDDING_MODEL,
+      input: input.text,
+      encoding_format: "float",
+    };
+  }
+
+  /**
+   * Process API response and return normalized embedding
+   */
+  protected processResponse(
+    response: EmbeddingResponse,
+    _input: EmbeddingInput
+  ): number[] {
+    const embedding = this.extractEmbedding(response);
+    return this.normalizeL2(embedding);
+  }
+
+  /**
+   * Extract embedding from API response
+   */
+  private extractEmbedding(response: EmbeddingResponse): number[] {
+    const embedding = response.data?.[0]?.embedding;
+
+    if (!embedding || !Array.isArray(embedding)) {
+      throw new Error("No embedding data received from DeepInfra API");
+    }
+
+    if (embedding.length === 0) {
+      throw new Error("Empty embedding received from DeepInfra API");
+    }
+
+    return embedding;
+  }
+
+  /**
+   * L2 normalization for optimal vector search performance
+   */
+  private normalizeL2(embedding: number[]): number[] {
+    const norm = Math.sqrt(embedding.reduce((sum, val) => sum + val * val, 0));
+
+    if (norm === 0) {
+      logger.warn("Zero norm embedding detected, returning original");
+      return [...embedding];
+    }
+
+    return embedding.map((val) => val / norm);
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Modern Service Factory - Cloudflare Worker Native
+ * Creates and configures all services with optimal performance
+ */
+
+import { AuthMiddleware } from "../auth/auth-middleware.js";
+import type { AppConfig, Services, WorkerEnv } from "../types/index.js";
+import { RAGService } from "./rag.js";
+import { RateLimitService } from "./rate-limit.js";
+import { ToolCallLogger } from "./tool-call-logger.js";
+
+/**
+ * Create all services from Worker environment with validation
+ */
+export async function createServices(env: WorkerEnv): Promise<Services> {
+  try {
+    // Convert Worker env to app config
+    const config = createAppConfig(env);
+
+    // Initialize services
+    const auth = new AuthMiddleware(env.DB);
+    const rag = new RAGService(config, env);
+    const rateLimit = new RateLimitService(env.DB);
+    const logger = new ToolCallLogger(env.DB);
+
+    // Initialize async services
+    await rag.initialize();
+
+    return {
+      rag,
+      auth,
+      database: rag.database,
+      embedding: rag.embedding,
+      rateLimit,
+      logger,
+    };
+  } catch (error) {
+    // Import logger here to avoid circular dependency
+    const { logger } = await import("../utils/logger.js");
+    logger.error(
+      `Service initialization failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    throw error;
+  }
+}
+
+/**
+ * Convert Worker environment to app configuration
+ */
+function createAppConfig(env: WorkerEnv): AppConfig {
+  return {
+    RAG_DB_HOST: env.RAG_DB_HOST,
+    RAG_DB_PORT: parseInt(env.RAG_DB_PORT, 10),
+    RAG_DB_DATABASE: env.RAG_DB_DATABASE,
+    RAG_DB_USER: env.RAG_DB_USER,
+    RAG_DB_PASSWORD: env.RAG_DB_PASSWORD,
+    RAG_DB_SSLMODE: env.RAG_DB_SSLMODE,
+  };
+}

package/src/services/ip-authentication.ts

@@ -0,0 +1,62 @@
+/**
+ * IP Authentication Service with D1 timeout protection
+ */
+
+import type { UserTokenData } from "../auth/token-validator.js";
+import { backgroundD1Write, withD1Timeout } from "../utils/d1-utils.js";
+import { logger } from "../utils/logger.js";
+
+interface UserRecord {
+  user_id: string;
+  email?: string;
+  name?: string;
+}
+
+export class IPAuthenticationService {
+  constructor(private d1: D1Database) {}
+
+  async checkIPAuthentication(clientIP: string): Promise<UserTokenData | null> {
+    const user = await withD1Timeout(
+      () => this.queryIP(clientIP),
+      null,
+      "ip_auth"
+    );
+
+    if (!user) return null;
+
+    backgroundD1Write(
+      logger.getContext(),
+      () => this.updateLastUsed(clientIP, user.user_id),
+      "ip_last_used"
+    );
+
+    return {
+      userId: user.user_id,
+      email: user.email || "ip-authenticated",
+      name: user.name || "IP User",
+    };
+  }
+
+  private async queryIP(clientIP: string): Promise<UserRecord | null> {
+    const result = await this.d1
+      .prepare(
+        `SELECT uai.user_id, u.email, u.name
+         FROM user_authorized_ips uai
+         JOIN users u ON uai.user_id = u.id
+         WHERE uai.ip_address = ?`
+      )
+      .bind(clientIP)
+      .all();
+
+    return (result.results?.[0] as unknown as UserRecord | undefined) ?? null;
+  }
+
+  private async updateLastUsed(ipAddress: string, userId: string): Promise<void> {
+    await this.d1
+      .prepare(
+        "UPDATE user_authorized_ips SET last_used_at = ? WHERE ip_address = ? AND user_id = ?"
+      )
+      .bind(new Date().toISOString(), ipAddress, userId)
+      .run();
+  }
+}

package/src/services/rag.ts

@@ -0,0 +1,158 @@
+/**
+ * Modern RAG Service - Cloudflare Worker Native
+ * Optimized for edge computing with zero-dependency architecture
+ */
+
+import type {
+  AppConfig,
+  RAGQuery,
+  RAGResult,
+  SearchResult,
+  WorkerEnv,
+} from "../types/index.js";
+import { logger } from "../utils/logger.js";
+import { DatabaseService } from "./database.js";
+import { EmbeddingService } from "./embedding.js";
+import { RerankerService } from "./reranker.js";
+import { type RankedSearchResult, SearchEngine } from "./search-engine.js";
+
+export class RAGService {
+  readonly database: DatabaseService;
+  readonly embedding: EmbeddingService;
+  private readonly reranker: RerankerService;
+  private readonly searchEngine: SearchEngine;
+
+  constructor(config: AppConfig, env: WorkerEnv) {
+    this.database = new DatabaseService(config);
+    this.embedding = new EmbeddingService(env.DEEPINFRA_API_KEY);
+    this.reranker = new RerankerService(env.DEEPINFRA_API_KEY);
+    this.searchEngine = new SearchEngine(
+      this.database,
+      this.embedding,
+      this.reranker
+    );
+  }
+
+  /**
+   * Initialize - no-op since database initialization is removed
+   */
+  async initialize(): Promise<void> {
+    // No initialization needed - database trusted ready
+  }
+
+  /**
+   * Perform RAG query with intelligent processing and detailed timing
+   */
+  async query(request: RAGQuery): Promise<RAGResult> {
+    const startTime = Date.now();
+    const { query, result_count = 4 } = request;
+
+    // No started log - only completion with timing
+
+    // Input validation
+    if (!query?.trim()) {
+      return this.createErrorResponse(
+        query,
+        "Query cannot be empty. Please provide a search query to find relevant Apple Developer Documentation.",
+        "Try searching for topics like 'SwiftUI navigation', 'iOS app development', or 'API documentation'.",
+        startTime
+      );
+    }
+
+    const trimmedQuery = query.trim();
+    if (trimmedQuery.length > 10000) {
+      return this.createErrorResponse(
+        query,
+        "Query is too long. Please limit your query to 10000 characters or less.",
+        "Try to make your query more concise and specific.",
+        startTime
+      );
+    }
+
+    try {
+      // Initialize services (if not already initialized)
+      await this.initialize();
+
+      // Execute search
+      const resultCount = Math.min(Math.max(result_count, 1), 20);
+
+      const searchResult = await this.searchEngine.search(trimmedQuery, {
+        resultCount,
+      });
+
+      // Format results
+      const formattedResults = this.formatResults(searchResult.results);
+      const totalTime = Date.now() - startTime;
+
+      // Log completion with timing
+      logger.info(
+        `RAG query completed (${(totalTime / 1000).toFixed(1)}s) - results: ${formattedResults.length}, query: ${query.substring(0, 50)}`
+      );
+
+      return {
+        success: true,
+        query: trimmedQuery,
+        results: formattedResults,
+        additionalUrls: searchResult.additionalUrls,
+        count: formattedResults.length,
+        processing_time_ms: totalTime,
+      };
+    } catch (error) {
+      logger.error(
+        `RAG query failed for query "${trimmedQuery.substring(0, 50)}": ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+      return this.createErrorResponse(
+        trimmedQuery,
+        `Search failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        "Please try again with a different query or check your connection.",
+        startTime
+      );
+    }
+  }
+
+  /**
+   * Format search results for MCP response
+   */
+  private formatResults(
+    results: readonly RankedSearchResult[]
+  ): SearchResult[] {
+    return results.map((result) => ({
+      id: result.id,
+      url: result.url,
+      title: result.title,
+      content: result.content,
+      contentLength: result.content.length,
+      chunk_index: result.chunk_index,
+      total_chunks: result.total_chunks,
+      mergedChunkIndices: result.mergedChunkIndices,
+    }));
+  }
+
+  /**
+   * Create standardized error response
+   */
+  private createErrorResponse(
+    query: string,
+    _error: string,
+    _suggestion: string,
+    startTime: number
+  ): RAGResult {
+    return {
+      success: false,
+      query,
+      results: [],
+      additionalUrls: [],
+      count: 0,
+      processing_time_ms: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Clean up resources
+   */
+  async close(): Promise<void> {
+    if (this.database) {
+      await this.database.close();
+    }
+  }
+}