@iflow-mcp/apple-rag-mcp 4.6.2

package/src/auth/token-validator.ts

@@ -0,0 +1,96 @@
+/**
+ * MCP Token Validator with D1 timeout protection
+ */
+
+import { backgroundD1Write, withD1Timeout } from "../utils/d1-utils.js";
+import { logger } from "../utils/logger.js";
+
+export interface TokenValidationResult {
+  valid: boolean;
+  error?: string;
+  userData?: UserTokenData;
+}
+
+export interface UserTokenData {
+  userId: string;
+  email: string;
+  name: string;
+}
+
+export class TokenValidator {
+  constructor(private d1: D1Database) {}
+
+  async validateToken(token: string): Promise<TokenValidationResult> {
+    if (!/^at_[a-f0-9]{32}$/.test(token)) {
+      return { valid: false, error: "Invalid token format" };
+    }
+
+    const userData = await withD1Timeout(
+      () => this.queryUserByToken(token),
+      null,
+      "token_lookup"
+    );
+
+    if (!userData) {
+      return { valid: false, error: "Token not found" };
+    }
+
+    backgroundD1Write(
+      logger.getContext(),
+      () => this.updateLastUsed(token),
+      "token_last_used"
+    );
+
+    return { valid: true, userData };
+  }
+
+  private async queryUserByToken(token: string): Promise<UserTokenData | null> {
+    const result = await this.d1
+      .prepare(
+        `SELECT u.id as user_id, u.email, u.name
+         FROM mcp_tokens t JOIN users u ON t.user_id = u.id
+         WHERE t.mcp_token = ?`
+      )
+      .bind(token)
+      .all();
+
+    if (!result.success || !result.results?.length) return null;
+
+    const row = result.results[0] as Record<string, unknown>;
+    return {
+      userId: row.user_id as string,
+      email: (row.email as string) || "unknown",
+      name: (row.name as string) || "unknown",
+    };
+  }
+
+  private async updateLastUsed(token: string): Promise<void> {
+    await this.d1
+      .prepare("UPDATE mcp_tokens SET last_used_at = ? WHERE mcp_token = ?")
+      .bind(new Date().toISOString(), token)
+      .run();
+  }
+
+  async getUserDataById(userId: string): Promise<UserTokenData> {
+    const result = await withD1Timeout(
+      async () => {
+        const res = await this.d1
+          .prepare("SELECT id, email, name FROM users WHERE id = ?")
+          .bind(userId)
+          .all();
+        if (!res.success || !res.results?.length) throw new Error("User not found");
+        const user = res.results[0] as Record<string, unknown>;
+        return {
+          userId: user.id as string,
+          email: user.email as string,
+          name: (user.name as string) || (user.email as string).split("@")[0],
+        };
+      },
+      null,
+      "user_lookup"
+    );
+
+    if (!result) throw new Error("User not found");
+    return result;
+  }
+}

package/src/mcp/formatters/response-formatter.ts

@@ -0,0 +1,157 @@
+/**
+ * Response Formatting Utilities
+ * Professional response formatting for MCP protocol
+ */
+
+import type { MCPResponse, RAGResult } from "../../types/index.js";
+import { APP_CONSTANTS } from "../protocol-handler.js";
+
+/**
+ * Format RAG response with professional layout
+ */
+export function formatRAGResponse(
+  ragResult: RAGResult,
+  isAuthenticated: boolean,
+  wasAdjusted: boolean = false
+): string {
+  if (
+    !ragResult ||
+    !ragResult.success ||
+    !ragResult.results ||
+    ragResult.results.length === 0
+  ) {
+    return APP_CONSTANTS.NO_RESULTS_MESSAGE;
+  }
+
+  const results = ragResult.results;
+  let response = "";
+
+  results.forEach((result, index) => {
+    let title = `[${index + 1}] ${result.title || "Untitled"}`;
+
+    // Add completeness indicator based on chunk information and merge status
+    const isMerged =
+      result.mergedChunkIndices && result.mergedChunkIndices.length > 1;
+
+    if (result.total_chunks === 1) {
+      title += ` ✅ Complete Document`;
+      response += `${title}\n\n`;
+    } else if (isMerged) {
+      // For merged content, show which specific parts are included
+      const mergedParts = result
+        .mergedChunkIndices!.map((idx) => idx + 1)
+        .join(", ");
+      title += ` 📄 Parts ${mergedParts} merged (${result.total_chunks} total)`;
+      response += `${title}\n\n`;
+      response += `This shows merged content from multiple parts. For the complete document, use Apple RAG MCP fetch tool: \`fetch(url: "${result.url}")\`\n\n`;
+    } else {
+      title += ` 📄 Part ${result.chunk_index + 1} of ${result.total_chunks}`;
+      response += `${title}\n\n`;
+      response += `This is a partial document. For the complete content, use Apple RAG MCP fetch tool: \`fetch(url: "${result.url}")\`\n\n`;
+    }
+
+    response += `${result.content}\n`;
+
+    if (index < results.length - 1) {
+      response += `\n${"─".repeat(80)}\n\n`;
+    }
+  });
+
+  // Additional URLs section
+  if (ragResult.additionalUrls && ragResult.additionalUrls.length > 0) {
+    response += `\n\n${"─".repeat(60)}\n\n`;
+    response += `Additional Related Documentation:\n`;
+    response += `The following ${ragResult.additionalUrls.length} URLs contain supplementary information that may provide additional context or related topics. This includes Apple developer documentation and WWDC video transcripts. Use the \`fetch\` tool to retrieve their complete, cleaned content:\n\n`;
+
+    ragResult.additionalUrls.forEach((item) => {
+      response += `${item.url}\n`;
+
+      // Show title for Apple Developer video URLs
+      if (item.title && item.url.includes("developer.apple.com/videos/play/")) {
+        response += `  └─ ${item.title}\n`;
+      }
+
+      response += `  └─ ${item.characterCount} characters\n\n`;
+    });
+  }
+
+  // Footer message for anonymous users
+  if (!isAuthenticated) {
+    response += `\n\n${APP_CONSTANTS.ANONYMOUS_ACCESS_MESSAGE}`;
+  }
+
+  // Parameter range reminder for AI agents (only when parameter was adjusted)
+  if (wasAdjusted) {
+    response += `\n\nNote: The result_count parameter accepts values between 1 and 10. Values outside this range are automatically adjusted to the nearest valid limit.`;
+  }
+
+  return response;
+}
+
+/**
+ * Format fetch response with professional styling
+ */
+export function formatFetchResponse(
+  result: { success?: boolean; title?: string; content?: string },
+  isAuthenticated: boolean
+): string {
+  if (!result || !result.success) {
+    return "Failed to retrieve content from the specified URL.";
+  }
+
+  let response = "";
+
+  if (result.title) {
+    response += `${result.title}\n\n`;
+  }
+
+  if (result.content) {
+    response += result.content;
+  }
+
+  // Footer message for anonymous users
+  if (!isAuthenticated) {
+    response += `\n\n${APP_CONSTANTS.ANONYMOUS_ACCESS_MESSAGE}`;
+  }
+
+  return response;
+}
+
+/**
+ * Create success response
+ */
+export function createSuccessResponse(
+  requestId: string | number,
+  content: string
+): MCPResponse {
+  return {
+    jsonrpc: "2.0",
+    id: requestId,
+    result: {
+      content: [
+        {
+          type: "text",
+          text: content,
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Create error response
+ */
+export function createErrorResponse(
+  requestId: string | number,
+  code: number,
+  message: string
+): MCPResponse {
+  return {
+    jsonrpc: "2.0",
+    id: requestId,
+    error: {
+      code,
+      message,
+    },
+  };
+}

package/src/mcp/manifest.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP Server Manifest
+ * Centralized server discovery and capability information
+ */
+
+export const SERVER_MANIFEST = {
+  name: "Apple RAG MCP Server",
+  title: "Apple Developer Documentation Search",
+  version: "2.0.0",
+  description:
+    "Ultra-modern MCP server providing AI agents with comprehensive access to Apple's complete developer documentation using advanced RAG technology.",
+  protocolVersion: "2025-06-18",
+  supportedVersions: ["2025-06-18", "2025-03-26"],
+  capabilities: {
+    tools: { listChanged: true },
+    logging: {},
+    experimental: {},
+  },
+  serverInfo: {
+    name: "Apple RAG MCP Server",
+    version: "2.0.0",
+  },
+  endpoints: {
+    mcp: "/",
+    manifest: "/manifest",
+    health: "/health",
+  },
+  transport: {
+    type: "http",
+    methods: ["POST"],
+    headers: {
+      required: ["Content-Type"],
+      optional: ["Authorization", "MCP-Protocol-Version"],
+    },
+  },
+  authorization: {
+    enabled: true,
+    type: "bearer",
+    optional: true,
+  },
+} as const;
+
+export const HEALTH_STATUS = {
+  status: "healthy",
+  version: "2.0.0",
+  protocol: "2025-06-18",
+  supportedVersions: ["2025-06-18", "2025-03-26"],
+} as const;

package/src/mcp/middleware/request-validator.ts

@@ -0,0 +1,135 @@
+/**
+ * Request Validation Middleware
+ * Validates MCP protocol requests and parameters
+ */
+
+import type { MCPNotification, MCPRequest } from "../../types/index.js";
+import {
+  MCP_ERROR_CODES,
+  SUPPORTED_MCP_VERSIONS,
+} from "../protocol-handler.js";
+
+/**
+ * Validate MCP request structure
+ */
+export function isValidMCPRequest(body: unknown): body is MCPRequest {
+  return (
+    body != null &&
+    typeof body === "object" &&
+    "jsonrpc" in body &&
+    (body as Record<string, unknown>).jsonrpc === "2.0" &&
+    "id" in body &&
+    "method" in body &&
+    typeof (body as Record<string, unknown>).method === "string"
+  );
+}
+
+/**
+ * Validate MCP notification structure
+ */
+export function isValidMCPNotification(body: unknown): body is MCPNotification {
+  return (
+    body != null &&
+    typeof body === "object" &&
+    "jsonrpc" in body &&
+    (body as Record<string, unknown>).jsonrpc === "2.0" &&
+    "method" in body &&
+    typeof (body as Record<string, unknown>).method === "string" &&
+    !("id" in body)
+  );
+}
+
+/**
+ * Validate protocol version
+ */
+export function validateProtocolVersion(version?: string): {
+  isValid: boolean;
+  error?: { code: number; message: string };
+} {
+  if (
+    version &&
+    !SUPPORTED_MCP_VERSIONS.includes(
+      version as (typeof SUPPORTED_MCP_VERSIONS)[number]
+    )
+  ) {
+    return {
+      isValid: false,
+      error: {
+        code: MCP_ERROR_CODES.INVALID_PARAMS,
+        message: `Unsupported protocol version: ${version}. Supported versions: ${SUPPORTED_MCP_VERSIONS.join(", ")}`,
+      },
+    };
+  }
+
+  return { isValid: true };
+}
+
+/**
+ * Validate initialize parameters
+ */
+export function validateInitializeParams(params: unknown): {
+  isValid: boolean;
+  error?: { code: number; message: string };
+} {
+  // Basic validation - can be extended
+  if (params && typeof params !== "object") {
+    return {
+      isValid: false,
+      error: {
+        code: MCP_ERROR_CODES.INVALID_PARAMS,
+        message: "Initialize parameters must be an object",
+      },
+    };
+  }
+
+  return { isValid: true };
+}
+
+/**
+ * Validate tool call parameters
+ */
+export function validateToolCallParams(params: unknown): {
+  isValid: boolean;
+  toolCall?: { name: string; arguments?: Record<string, unknown> };
+  error?: { code: number; message: string };
+} {
+  if (!params || typeof params !== "object") {
+    return {
+      isValid: false,
+      error: {
+        code: MCP_ERROR_CODES.INVALID_PARAMS,
+        message: "Tool call parameters are required",
+      },
+    };
+  }
+
+  const p = params as Record<string, unknown>;
+
+  if (!p.name || typeof p.name !== "string") {
+    return {
+      isValid: false,
+      error: {
+        code: MCP_ERROR_CODES.INVALID_PARAMS,
+        message: "Tool name is required and must be a string",
+      },
+    };
+  }
+
+  if (!p.arguments || typeof p.arguments !== "object") {
+    return {
+      isValid: false,
+      error: {
+        code: MCP_ERROR_CODES.INVALID_PARAMS,
+        message: "Tool arguments are required and must be an object",
+      },
+    };
+  }
+
+  return {
+    isValid: true,
+    toolCall: {
+      name: p.name,
+      arguments: p.arguments as Record<string, unknown>,
+    },
+  };
+}