@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/mcp/legacyState.ts

@@ -0,0 +1,22 @@
+import { access, readFile, rename } from 'node:fs/promises'
+
+export async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function readJsonFile<T>(filePath: string): Promise<T> {
+  const raw = await readFile(filePath, 'utf-8')
+  return JSON.parse(raw) as T
+}
+
+export async function archiveFileWithSuffix(filePath: string, suffix: string = '.migrated'): Promise<string> {
+  const archiveBasePath = `${filePath}${suffix}`
+  const archivePath = (await pathExists(archiveBasePath)) ? `${archiveBasePath}.${Date.now()}` : archiveBasePath
+  await rename(filePath, archivePath)
+  return archivePath
+}

package/src/mcp/rateLimit.ts

@@ -0,0 +1,358 @@
+/**
+ * MCP Rate Limiter
+ *
+ * Provides rate limiting for MCP tool calls using the existing
+ * RateLimitStore infrastructure. Supports both per-tool limits
+ * and global limits per containerTag.
+ */
+
+import { RateLimitStore, MemoryRateLimitStore, RedisRateLimitStore } from '../api/middleware/rateLimit.js'
+import { createMcpEnvelopeError, createToolResponse } from './results.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Result of a rate limit check
+ */
+export interface RateLimitResult {
+  /** Whether the request is allowed */
+  allowed: boolean
+  /** Remaining requests in the current window */
+  remaining: number
+  /** Seconds until the limit resets */
+  resetIn: number
+  /** The limit that applies */
+  limit: number
+  /** Which limit was hit (if any) */
+  limitType?: 'tool' | 'global'
+}
+
+/**
+ * Configuration for a rate limit
+ */
+export interface RateLimitConfig {
+  /** Maximum requests allowed */
+  maxRequests: number
+  /** Time window in milliseconds */
+  windowMs: number
+}
+
+/**
+ * Tool-specific rate limit configurations
+ */
+export interface ToolLimits {
+  [toolName: string]: RateLimitConfig
+}
+
+// ============================================================================
+// Default Limits
+// ============================================================================
+
+/**
+ * Tool-specific rate limits
+ *
+ * Limits are based on:
+ * - Computational cost (embedding generation is expensive)
+ * - Side effects (delete is destructive)
+ * - Read vs write operations
+ */
+const DEFAULT_TOOL_LIMITS: ToolLimits = {
+  // Write operations with embedding generation - most expensive
+  supermemory_add: {
+    maxRequests: 50,
+    windowMs: 60 * 1000, // 50 req/min
+  },
+
+  // Search operations - moderately expensive
+  supermemory_search: {
+    maxRequests: 100,
+    windowMs: 60 * 1000, // 100 req/min
+  },
+
+  // Profile operations - moderately expensive
+  supermemory_profile: {
+    maxRequests: 50,
+    windowMs: 60 * 1000, // 50 req/min
+  },
+
+  // Remember - creates facts with potential embedding
+  supermemory_remember: {
+    maxRequests: 100,
+    windowMs: 60 * 1000, // 100 req/min
+  },
+
+  // Recall - semantic search over facts
+  supermemory_recall: {
+    maxRequests: 200,
+    windowMs: 60 * 1000, // 200 req/min
+  },
+
+  // List - lightweight read operation
+  supermemory_list: {
+    maxRequests: 200,
+    windowMs: 60 * 1000, // 200 req/min
+  },
+
+  // Delete - destructive, strict limit
+  supermemory_delete: {
+    maxRequests: 20,
+    windowMs: 60 * 1000, // 20 req/min
+  },
+}
+
+/**
+ * Global rate limit per containerTag
+ * Applies across all tools to prevent abuse
+ */
+const DEFAULT_GLOBAL_LIMIT: RateLimitConfig = {
+  maxRequests: 1000,
+  windowMs: 15 * 60 * 1000, // 1000 req/15min
+}
+
+// ============================================================================
+// MCPRateLimiter Class
+// ============================================================================
+
+/**
+ * Rate limiter for MCP tool calls
+ *
+ * Provides two levels of rate limiting:
+ * 1. Per-tool limits: Different limits for each tool based on cost
+ * 2. Global limit: Overall limit per containerTag across all tools
+ *
+ * Uses the same store infrastructure as the API rate limiter,
+ * supporting both in-memory (single instance) and Redis (distributed).
+ */
+export class MCPRateLimiter {
+  private store: RateLimitStore
+  private toolLimits: ToolLimits
+  private globalLimit: RateLimitConfig
+  private readonly keyPrefix = 'mcp:'
+
+  constructor(options?: {
+    store?: RateLimitStore
+    toolLimits?: { [toolName: string]: RateLimitConfig }
+    globalLimit?: Partial<RateLimitConfig>
+  }) {
+    // Initialize store - use Redis if available, fallback to memory
+    this.store = options?.store ?? this.createDefaultStore()
+
+    // Merge tool limits with defaults
+    this.toolLimits = { ...DEFAULT_TOOL_LIMITS }
+    if (options?.toolLimits) {
+      for (const [key, value] of Object.entries(options.toolLimits)) {
+        this.toolLimits[key] = value
+      }
+    }
+
+    // Merge global limit with defaults
+    this.globalLimit = {
+      ...DEFAULT_GLOBAL_LIMIT,
+      ...options?.globalLimit,
+    }
+  }
+
+  /**
+   * Create the default rate limit store
+   * Uses Redis if REDIS_URL is set, otherwise in-memory
+   */
+  private createDefaultStore(): RateLimitStore {
+    if (process.env.REDIS_URL) {
+      return new RedisRateLimitStore()
+    }
+    return new MemoryRateLimitStore()
+  }
+
+  /**
+   * Get the rate limit configuration for a tool
+   * Returns a default configuration for unknown tools
+   */
+  getToolLimit(toolName: string): RateLimitConfig {
+    return (
+      this.toolLimits[toolName] ?? {
+        maxRequests: 100,
+        windowMs: 60 * 1000, // Default: 100 req/min
+      }
+    )
+  }
+
+  /**
+   * Get the global rate limit configuration
+   */
+  getGlobalLimit(): RateLimitConfig {
+    return this.globalLimit
+  }
+
+  /**
+   * Check if a request is allowed under rate limits
+   *
+   * @param containerTag - The container tag (user/context identifier)
+   * @param toolName - The MCP tool being called
+   * @returns Rate limit result with allowed status and metadata
+   */
+  async checkLimit(containerTag: string, toolName: string): Promise<RateLimitResult> {
+    const now = Date.now()
+    const tag = containerTag || 'default'
+
+    // Check tool-specific limit first
+    const toolLimit = this.getToolLimit(toolName)
+    const toolKey = `${this.keyPrefix}tool:${tag}:${toolName}`
+    const toolEntry = await this.store.increment(toolKey, toolLimit.windowMs)
+
+    const toolRemaining = Math.max(0, toolLimit.maxRequests - toolEntry.count)
+    const toolResetIn = Math.ceil((toolEntry.resetTime - now) / 1000)
+
+    if (toolEntry.count > toolLimit.maxRequests) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetIn: toolResetIn,
+        limit: toolLimit.maxRequests,
+        limitType: 'tool',
+      }
+    }
+
+    // Check global limit
+    const globalKey = `${this.keyPrefix}global:${tag}`
+    const globalEntry = await this.store.increment(globalKey, this.globalLimit.windowMs)
+
+    const globalRemaining = Math.max(0, this.globalLimit.maxRequests - globalEntry.count)
+    const globalResetIn = Math.ceil((globalEntry.resetTime - now) / 1000)
+
+    if (globalEntry.count > this.globalLimit.maxRequests) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetIn: globalResetIn,
+        limit: this.globalLimit.maxRequests,
+        limitType: 'global',
+      }
+    }
+
+    // Request is allowed - return the more restrictive remaining count
+    return {
+      allowed: true,
+      remaining: Math.min(toolRemaining, globalRemaining),
+      resetIn: Math.min(toolResetIn, globalResetIn),
+      limit: toolLimit.maxRequests,
+    }
+  }
+
+  /**
+   * Get current rate limit status without incrementing counters
+   *
+   * @param containerTag - The container tag (user/context identifier)
+   * @param toolName - The MCP tool to check
+   * @returns Current rate limit status
+   */
+  async getStatus(containerTag: string, toolName: string): Promise<RateLimitResult> {
+    const now = Date.now()
+    const tag = containerTag || 'default'
+
+    // Get tool-specific status
+    const toolLimit = this.getToolLimit(toolName)
+    const toolKey = `${this.keyPrefix}tool:${tag}:${toolName}`
+    const toolEntry = await this.store.get(toolKey)
+
+    let toolRemaining = toolLimit.maxRequests
+    let toolResetIn = 0
+
+    if (toolEntry && toolEntry.resetTime > now) {
+      toolRemaining = Math.max(0, toolLimit.maxRequests - toolEntry.count)
+      toolResetIn = Math.ceil((toolEntry.resetTime - now) / 1000)
+    }
+
+    // Get global status
+    const globalKey = `${this.keyPrefix}global:${tag}`
+    const globalEntry = await this.store.get(globalKey)
+
+    let globalRemaining = this.globalLimit.maxRequests
+    let globalResetIn = 0
+
+    if (globalEntry && globalEntry.resetTime > now) {
+      globalRemaining = Math.max(0, this.globalLimit.maxRequests - globalEntry.count)
+      globalResetIn = Math.ceil((globalEntry.resetTime - now) / 1000)
+    }
+
+    // Check if either limit is exceeded (or at capacity - next request would be blocked)
+    // Use >= because when count equals maxRequests, the next request would be blocked
+    if (toolEntry && toolEntry.count >= toolLimit.maxRequests && toolEntry.resetTime > now) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetIn: toolResetIn,
+        limit: toolLimit.maxRequests,
+        limitType: 'tool',
+      }
+    }
+
+    if (globalEntry && globalEntry.count >= this.globalLimit.maxRequests && globalEntry.resetTime > now) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetIn: globalResetIn,
+        limit: this.globalLimit.maxRequests,
+        limitType: 'global',
+      }
+    }
+
+    return {
+      allowed: true,
+      remaining: Math.min(toolRemaining, globalRemaining),
+      resetIn: Math.max(toolResetIn, globalResetIn),
+      limit: toolLimit.maxRequests,
+    }
+  }
+}
+
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+
+let rateLimiterInstance: MCPRateLimiter | null = null
+
+/**
+ * Get or create the global MCP rate limiter instance
+ */
+export function getMCPRateLimiter(): MCPRateLimiter {
+  if (!rateLimiterInstance) {
+    rateLimiterInstance = new MCPRateLimiter()
+  }
+  return rateLimiterInstance
+}
+
+/**
+ * Create a rate limit error response for MCP
+ *
+ * @param result - The rate limit result
+ * @param toolName - The tool that was rate limited
+ * @returns MCP-compatible error response
+ */
+export function createRateLimitErrorResponse(
+  result: RateLimitResult,
+  toolName: string
+) {
+  const limitTypeMessage =
+    result.limitType === 'global' ? 'Global rate limit exceeded' : `Rate limit exceeded for ${toolName}`
+
+  return createToolResponse({
+    tool: toolName,
+    ok: false,
+    data: null,
+    errors: [
+      createMcpEnvelopeError(
+        'RATE_LIMIT_EXCEEDED',
+        `${limitTypeMessage}. Try again in ${result.resetIn} seconds. (Limit: ${result.limit} requests)`,
+        {
+          limit: result.limit,
+          limitType: result.limitType ?? 'tool',
+          remaining: result.remaining,
+          resetIn: result.resetIn,
+        },
+        true
+      ),
+    ],
+  })
+}

package/src/mcp/resources.ts

@@ -0,0 +1,309 @@
+/**
+ * MCP Resource Definitions for Supermemory
+ *
+ * Exposes supermemory data as MCP resources that can be read by clients.
+ * Resources use URI patterns to identify different data types.
+ */
+
+import { ValidationError } from '../utils/errors.js'
+
+// ============================================================================
+// Resource URI Patterns
+// ============================================================================
+
+/**
+ * Resource URI patterns:
+ * - memory://profiles/{containerTag} - User profile for a container
+ * - memory://documents/{id} - Specific document by ID
+ * - memory://search?q={query}&container={containerTag} - Search results
+ * - memory://facts/{containerTag} - Facts for a container
+ * - memory://stats - Overall statistics
+ */
+
+export const RESOURCE_TEMPLATES = [
+  {
+    uriTemplate: 'memory://profiles/{containerTag}',
+    name: 'User Profile',
+    description: 'Get the user profile containing extracted facts for a specific container',
+    mimeType: 'application/json',
+  },
+  {
+    uriTemplate: 'memory://documents/{id}',
+    name: 'Document',
+    description: 'Get a specific document by its ID',
+    mimeType: 'application/json',
+  },
+  {
+    uriTemplate: 'memory://search',
+    name: 'Search Results',
+    description: 'Search for memories. Query params: q (query), container (containerTag), limit, mode',
+    mimeType: 'application/json',
+  },
+  {
+    uriTemplate: 'memory://facts/{containerTag}',
+    name: 'Container Facts',
+    description: 'Get all facts for a specific container',
+    mimeType: 'application/json',
+  },
+  {
+    uriTemplate: 'memory://stats',
+    name: 'Statistics',
+    description: 'Get overall supermemory statistics',
+    mimeType: 'application/json',
+  },
+]
+
+// ============================================================================
+// Resource Parser
+// ============================================================================
+
+export interface ParsedResourceUri {
+  type: 'profile' | 'document' | 'search' | 'facts' | 'stats' | 'unknown'
+  params: Record<string, string>
+}
+
+/**
+ * Parse a resource URI into its components
+ */
+export function parseResourceUri(uri: string): ParsedResourceUri {
+  // Handle memory:// protocol
+  if (!uri.startsWith('memory://')) {
+    return { type: 'unknown', params: {} }
+  }
+
+  const path = uri.substring('memory://'.length)
+  const [pathPart, queryPart] = path.split('?')
+
+  // Parse query parameters
+  const params: Record<string, string> = {}
+  if (queryPart) {
+    const searchParams = new URLSearchParams(queryPart)
+    for (const [key, value] of searchParams.entries()) {
+      params[key] = value
+    }
+  }
+
+  // Parse path
+  if (!pathPart) {
+    return { type: 'unknown', params }
+  }
+
+  const segments = pathPart.split('/').filter(Boolean)
+
+  if (segments[0] === 'profiles' && segments[1]) {
+    return { type: 'profile', params: { containerTag: segments[1], ...params } }
+  }
+
+  if (segments[0] === 'documents' && segments[1]) {
+    return { type: 'document', params: { id: segments[1], ...params } }
+  }
+
+  if (segments[0] === 'search') {
+    return { type: 'search', params }
+  }
+
+  if (segments[0] === 'facts' && segments[1]) {
+    return { type: 'facts', params: { containerTag: segments[1], ...params } }
+  }
+
+  if (segments[0] === 'stats') {
+    return { type: 'stats', params }
+  }
+
+  return { type: 'unknown', params }
+}
+
+/**
+ * Build a resource URI from components
+ */
+export function buildResourceUri(
+  type: 'profile' | 'document' | 'search' | 'facts' | 'stats',
+  params?: Record<string, string>
+): string {
+  switch (type) {
+    case 'profile':
+      if (!params?.containerTag) {
+        throw new ValidationError('containerTag required for profile URI', {
+          containerTag: ['containerTag parameter is required for profile URIs'],
+        })
+      }
+      return `memory://profiles/${encodeURIComponent(params.containerTag)}`
+
+    case 'document':
+      if (!params?.id) {
+        throw new ValidationError('id required for document URI', {
+          id: ['id parameter is required for document URIs'],
+        })
+      }
+      return `memory://documents/${encodeURIComponent(params.id)}`
+
+    case 'search': {
+      const searchParams = new URLSearchParams()
+      if (params?.q) searchParams.set('q', params.q)
+      if (params?.container) searchParams.set('container', params.container)
+      if (params?.limit) searchParams.set('limit', params.limit)
+      if (params?.mode) searchParams.set('mode', params.mode)
+      const queryString = searchParams.toString()
+      return queryString ? `memory://search?${queryString}` : 'memory://search'
+    }
+
+    case 'facts':
+      if (!params?.containerTag) {
+        throw new ValidationError('containerTag required for facts URI', {
+          containerTag: ['containerTag parameter is required for facts URIs'],
+        })
+      }
+      return `memory://facts/${encodeURIComponent(params.containerTag)}`
+
+    case 'stats':
+      return 'memory://stats'
+
+    default:
+      throw new ValidationError(`Unknown resource type: ${type}`, {
+        type: [`Invalid resource type '${type}'. Valid types: profiles, documents, search, facts, stats`],
+      })
+  }
+}
+
+// ============================================================================
+// Resource Response Types
+// ============================================================================
+
+export interface ProfileResource {
+  uri: string
+  containerTag: string
+  staticFacts: Array<{
+    id: string
+    content: string
+    category?: string
+    confidence: number
+    extractedAt: string
+  }>
+  dynamicFacts: Array<{
+    id: string
+    content: string
+    category?: string
+    expiresAt?: string
+    extractedAt: string
+  }>
+  createdAt: string
+  updatedAt: string
+  version: number
+}
+
+export interface DocumentResource {
+  uri: string
+  id: string
+  title?: string
+  content: string
+  contentType: string
+  containerTag?: string
+  sourceUrl?: string
+  metadata?: Record<string, unknown>
+  createdAt: string
+  updatedAt: string
+}
+
+export interface SearchResource {
+  uri: string
+  query: string
+  results: Array<{
+    id: string
+    content: string
+    similarity: number
+    containerTag?: string
+    metadata?: Record<string, unknown>
+  }>
+  totalCount: number
+  searchTimeMs: number
+}
+
+export interface FactsResource {
+  uri: string
+  containerTag: string
+  facts: Array<{
+    id: string
+    content: string
+    type: 'static' | 'dynamic'
+    category?: string
+    confidence: number
+    createdAt: string
+    expiresAt?: string
+  }>
+  totalCount: number
+}
+
+export interface StatsResource {
+  uri: string
+  totalDocuments: number
+  totalMemories: number
+  totalFacts: number
+  containerTags: string[]
+  indexedVectors: number
+  lastUpdated: string
+}
+
+// ============================================================================
+// Resource List Response
+// ============================================================================
+
+export interface ResourceListItem {
+  uri: string
+  name: string
+  description?: string
+  mimeType?: string
+}
+
+export const MAX_LISTED_RESOURCE_CONTAINERS = 5
+export const MAX_LISTED_RESOURCE_DOCUMENTS = 5
+
+/**
+ * Generate a list of available resources for a given state
+ */
+export function generateResourceList(containerTags: string[], documentIds: string[]): ResourceListItem[] {
+  const resources: ResourceListItem[] = []
+
+  // Add stats resource
+  resources.push({
+    uri: 'memory://stats',
+    name: 'Supermemory Statistics',
+    description: 'Overall statistics and health of the memory system',
+    mimeType: 'application/json',
+  })
+
+  // Add search resource
+  resources.push({
+    uri: 'memory://search',
+    name: 'Search Memories',
+    description: 'Search through stored memories (add ?q=query to search)',
+    mimeType: 'application/json',
+  })
+
+  // Add profile resources for each container
+  for (const tag of containerTags.slice(0, MAX_LISTED_RESOURCE_CONTAINERS)) {
+    resources.push({
+      uri: buildResourceUri('profile', { containerTag: tag }),
+      name: `Profile: ${tag}`,
+      description: `User profile and facts for container "${tag}"`,
+      mimeType: 'application/json',
+    })
+
+    resources.push({
+      uri: buildResourceUri('facts', { containerTag: tag }),
+      name: `Facts: ${tag}`,
+      description: `All facts for container "${tag}"`,
+      mimeType: 'application/json',
+    })
+  }
+
+  // Add only a few recent documents to keep resource discovery bounded.
+  for (const id of documentIds.slice(0, MAX_LISTED_RESOURCE_DOCUMENTS)) {
+    resources.push({
+      uri: buildResourceUri('document', { id }),
+      name: `Document: ${id}`,
+      mimeType: 'application/json',
+    })
+  }
+
+  return resources
+}