@prmichaelsen/remember-mcp 0.1.0

package/src/firestore/paths.ts

@@ -0,0 +1,124 @@
+/**
+ * Firestore collection path helpers
+ * Following the environment-based prefix + users subcollection pattern
+ *
+ * Pattern from agentbase.me:
+ * - Environment prefix: e0.remember-mcp (dev), remember-mcp (prod)
+ * - User-scoped data: {BASE}.users/{user_id}/* (per agent/patterns/firestore-users-pattern-best-practices.md)
+ * - Shared data: {BASE}.templates/default, {BASE}.user-permissions
+ */
+
+const APP_NAME = 'remember-mcp';
+
+/**
+ * Get the database collection prefix based on environment
+ * - Development: Uses ENVIRONMENT env var or DB_PREFIX, defaults to 'e0.remember-mcp'
+ * - Production: Uses base 'remember-mcp'
+ *
+ * This allows developers to use their own database entries as a sandbox per dev or branch.
+ */
+function getBasePrefix(): string {
+  // Check for explicit environment variable (e0, e1, e2, etc.)
+  const environment = process.env.ENVIRONMENT;
+  if (environment && environment !== 'production' && environment !== 'prod') {
+    return `${environment}.${APP_NAME}`;
+  }
+
+  // Check if we're in development mode
+  const isDevelopment = process.env.NODE_ENV === 'development';
+
+  if (isDevelopment) {
+    // Check for custom DB_PREFIX env var first
+    const customPrefix = process.env.DB_PREFIX;
+    if (customPrefix) {
+      return customPrefix;
+    }
+    // Default to e0.{APP_NAME} in development
+    return `e0.${APP_NAME}`;
+  }
+
+  // Production uses the base APP_NAME
+  return APP_NAME;
+}
+
+export const BASE = getBasePrefix();
+
+// ============================================================================
+// USER-SCOPED COLLECTIONS (under users/{user_id}/)
+// Per agent/patterns/firestore-users-pattern-best-practices.md
+// ============================================================================
+
+/**
+ * Get path to user preferences document
+ * Pattern: {BASE}.users/{user_id}/preferences
+ */
+export function getUserPreferencesPath(userId: string): string {
+  return `${BASE}.users/${userId}/preferences`;
+}
+
+/**
+ * Get path to user's templates collection
+ * Pattern: {BASE}.users/{user_id}/templates
+ */
+export function getUserTemplatesPath(userId: string): string {
+  return `${BASE}.users/${userId}/templates`;
+}
+
+/**
+ * Get path to user's access logs collection
+ * Pattern: {BASE}.users/{user_id}/access-logs
+ */
+export function getUserAccessLogsPath(userId: string): string {
+  return `${BASE}.users/${userId}/access-logs`;
+}
+
+/**
+ * Get path to user's trust relationships collection
+ * Pattern: {BASE}.users/{user_id}/trust-relationships
+ */
+export function getUserTrustRelationshipsPath(userId: string): string {
+  return `${BASE}.users/${userId}/trust-relationships`;
+}
+
+// ============================================================================
+// CROSS-USER COLLECTIONS (outside users/)
+// These involve multiple users, so can't be under users/{user_id}/
+// ============================================================================
+
+/**
+ * Get path to user's allowed accessors collection (permissions)
+ * Pattern: {BASE}.user-permissions/{owner_user_id}/allowed-accessors
+ *
+ * Note: Outside users/ because it involves two users (owner + accessor)
+ */
+export function getUserPermissionsPath(ownerUserId: string): string {
+  return `${BASE}.user-permissions/${ownerUserId}/allowed-accessors`;
+}
+
+/**
+ * Get path to specific permission document
+ * Pattern: {BASE}.user-permissions/{owner_user_id}/allowed-accessors/{accessor_user_id}
+ */
+export function getUserPermissionPath(ownerUserId: string, accessorUserId: string): string {
+  return `${BASE}.user-permissions/${ownerUserId}/allowed-accessors/${accessorUserId}`;
+}
+
+// ============================================================================
+// SHARED/GLOBAL COLLECTIONS
+// ============================================================================
+
+/**
+ * Get path to default templates collection
+ * Pattern: {BASE}.templates/default
+ */
+export function getDefaultTemplatesPath(): string {
+  return `${BASE}.templates/default`;
+}
+
+/**
+ * Get path to specific default template
+ * Pattern: {BASE}.templates/default/{template_id}
+ */
+export function getDefaultTemplatePath(templateId: string): string {
+  return `${BASE}.templates/default/${templateId}`;
+}

package/src/server-factory.spec.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from '@jest/globals';
+import { createServer } from './server-factory.js';
+
+describe('Server Factory', () => {
+  describe('Parameter Validation', () => {
+    it('should create server instance with valid parameters', () => {
+      const server = createServer('test-token', 'user123');
+      expect(server).toBeDefined();
+      expect(server).toHaveProperty('setRequestHandler');
+    });
+
+    it('should require accessToken', () => {
+      expect(() => createServer('', 'user123')).toThrow('accessToken is required');
+    });
+
+    it('should require userId', () => {
+      expect(() => createServer('token', '')).toThrow('userId is required');
+    });
+
+    it('should accept custom options', () => {
+      const server = createServer('token', 'user123', {
+        name: 'custom-name',
+        version: '2.0.0',
+      });
+      expect(server).toBeDefined();
+    });
+  });
+
+  describe('Server Isolation', () => {
+    it('should create separate instances for different users', () => {
+      const server1 = createServer('token1', 'user1');
+      const server2 = createServer('token2', 'user2');
+      
+      expect(server1).not.toBe(server2);
+    });
+
+    it('should scope operations to userId', () => {
+      const server = createServer('token', 'user123');
+      expect(server).toBeDefined();
+      // Note: Actual scoping tested in integration tests
+    });
+  });
+
+  describe('Options', () => {
+    it('should use default name if not provided', () => {
+      const server = createServer('token', 'user123');
+      expect(server).toBeDefined();
+    });
+
+    it('should use custom name if provided', () => {
+      const server = createServer('token', 'user123', { name: 'custom' });
+      expect(server).toBeDefined();
+    });
+
+    it('should use custom version if provided', () => {
+      const server = createServer('token', 'user123', { version: '2.0.0' });
+      expect(server).toBeDefined();
+    });
+  });
+});

package/src/server-factory.ts

@@ -0,0 +1,215 @@
+/**
+ * Server factory for mcp-auth compatibility
+ * Creates isolated server instances per user/tenant
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import { logger } from './utils/logger.js';
+
+// Import memory tools
+import { createMemoryTool, handleCreateMemory } from './tools/create-memory.js';
+import { searchMemoryTool, handleSearchMemory } from './tools/search-memory.js';
+import { deleteMemoryTool, handleDeleteMemory } from './tools/delete-memory.js';
+
+export interface ServerOptions {
+  name?: string;
+  version?: string;
+}
+
+/**
+ * Create a server instance for a specific user/tenant
+ * 
+ * This factory function is compatible with mcp-auth wrapping pattern.
+ * It creates isolated server instances with no shared state.
+ * 
+ * @param accessToken - User's access token (reserved for future external APIs)
+ * @param userId - User identifier for scoping operations
+ * @param options - Optional server configuration
+ * @returns Configured MCP Server instance (not connected to transport)
+ * 
+ * @example
+ * ```typescript
+ * // Direct usage
+ * const server = createServer('token', 'user123');
+ * const transport = new StdioServerTransport();
+ * await server.connect(transport);
+ * 
+ * // With mcp-auth
+ * import { wrapServer } from '@prmichaelsen/mcp-auth';
+ * const wrapped = wrapServer({
+ *   serverFactory: createServer,
+ *   authProvider: new JWTAuthProvider({ ... }),
+ *   tokenResolver: new APITokenResolver({ ... }),
+ *   resourceType: 'remember',
+ *   transport: { type: 'sse', port: 3000 }
+ * });
+ * ```
+ */
+export function createServer(
+  accessToken: string,
+  userId: string,
+  options: ServerOptions = {}
+): Server {
+  if (!accessToken) {
+    throw new Error('accessToken is required');
+  }
+  
+  if (!userId) {
+    throw new Error('userId is required');
+  }
+  
+  logger.debug('Creating server instance', { userId });
+  
+  // Create MCP server
+  const server = new Server(
+    {
+      name: options.name || 'remember-mcp',
+      version: options.version || '0.1.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+  
+  // Register handlers with userId scope
+  registerHandlers(server, userId, accessToken);
+  
+  return server;
+}
+
+/**
+ * Register MCP handlers scoped to userId
+ */
+function registerHandlers(server: Server, userId: string, accessToken: string): void {
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'health_check',
+          description: 'Check server health and database connections',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+          },
+        },
+        createMemoryTool,
+        searchMemoryTool,
+        deleteMemoryTool,
+      ],
+    };
+  });
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      let result: string;
+
+      switch (name) {
+        case 'health_check':
+          result = await handleHealthCheck(userId);
+          break;
+
+        case 'remember_create_memory':
+          result = await handleCreateMemory(args as any, userId);
+          break;
+
+        case 'remember_search_memory':
+          result = await handleSearchMemory(args as any, userId);
+          break;
+
+        case 'remember_delete_memory':
+          result = await handleDeleteMemory(args as any, userId);
+          break;
+
+        default:
+          throw new McpError(
+            ErrorCode.MethodNotFound,
+            `Unknown tool: ${name}`
+          );
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: result,
+          },
+        ],
+      };
+    } catch (error) {
+      if (error instanceof McpError) {
+        throw error;
+      }
+
+      logger.error(`Tool execution failed for ${name}:`, error);
+      throw new McpError(
+        ErrorCode.InternalError,
+        `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  });
+}
+
+/**
+ * Health check handler (scoped to userId)
+ */
+async function handleHealthCheck(userId: string): Promise<string> {
+  const health = {
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    userId: userId,
+    server: {
+      name: 'remember-mcp',
+      version: '0.1.0',
+    },
+    databases: {
+      weaviate: {
+        connected: false,
+        userCollection: `Memory_${userId}`,
+      },
+      firestore: {
+        connected: false,
+        userPath: `users/${userId}`,
+      },
+    },
+  };
+
+  try {
+    // Test Weaviate connection
+    const { getWeaviateClient } = await import('./weaviate/client.js');
+    const weaviateClient = getWeaviateClient();
+    health.databases.weaviate.connected = await weaviateClient.isReady();
+  } catch (error) {
+    logger.error('Weaviate health check failed:', error);
+    health.databases.weaviate.connected = false;
+  }
+
+  try {
+    // Test Firestore connection
+    const { testFirestoreConnection } = await import('./firestore/init.js');
+    health.databases.firestore.connected = await testFirestoreConnection();
+  } catch (error) {
+    logger.error('Firestore health check failed:', error);
+    health.databases.firestore.connected = false;
+  }
+
+  // Overall status
+  const allHealthy =
+    health.databases.weaviate.connected &&
+    health.databases.firestore.connected;
+
+  health.status = allHealthy ? 'healthy' : 'degraded';
+
+  return JSON.stringify(health, null, 2);
+}

package/src/server.ts

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import { config, validateConfig } from './config.js';
+import { initWeaviateClient, testWeaviateConnection, getWeaviateClient } from './weaviate/client.js';
+import { initFirestore, testFirestoreConnection } from './firestore/init.js';
+import { logger } from './utils/logger.js';
+
+// Import memory tools
+import { createMemoryTool, handleCreateMemory } from './tools/create-memory.js';
+import { searchMemoryTool, handleSearchMemory } from './tools/search-memory.js';
+import { deleteMemoryTool, handleDeleteMemory } from './tools/delete-memory.js';
+
+/**
+ * Initialize remember-mcp server
+ */
+async function initServer(): Promise<Server> {
+  logger.info('Initializing remember-mcp server...');
+
+  // Validate configuration
+  validateConfig();
+
+  // Initialize databases
+  logger.info('Connecting to databases...');
+  await initWeaviateClient();
+  initFirestore();
+
+  // Test connections
+  const weaviateOk = await testWeaviateConnection();
+  const firestoreOk = await testFirestoreConnection();
+
+  if (!weaviateOk || !firestoreOk) {
+    throw new Error('Database connection failed');
+  }
+
+  logger.info('Database connections established');
+
+  // Create MCP server
+  const server = new Server(
+    {
+      name: 'remember-mcp',
+      version: '0.1.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Register handlers
+  registerHandlers(server);
+
+  logger.info('Server initialized successfully');
+  return server;
+}
+
+/**
+ * Register MCP handlers
+ */
+function registerHandlers(server: Server): void {
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'health_check',
+          description: 'Check server health and database connections',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+          },
+        },
+        createMemoryTool,
+        searchMemoryTool,
+        deleteMemoryTool,
+      ],
+    };
+  });
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      let result: string;
+
+      // Extract userId from args or use default for now
+      // TODO: Get userId from authentication context in M6
+      const userId = (args as any).user_id || 'default_user';
+
+      switch (name) {
+        case 'health_check':
+          result = await handleHealthCheck();
+          break;
+
+        case 'remember_create_memory':
+          result = await handleCreateMemory(args as any, userId);
+          break;
+
+        case 'remember_search_memory':
+          result = await handleSearchMemory(args as any, userId);
+          break;
+
+        case 'remember_delete_memory':
+          result = await handleDeleteMemory(args as any, userId);
+          break;
+
+        default:
+          throw new McpError(
+            ErrorCode.MethodNotFound,
+            `Unknown tool: ${name}`
+          );
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: result,
+          },
+        ],
+      };
+    } catch (error) {
+      if (error instanceof McpError) {
+        throw error;
+      }
+
+      logger.error(`Tool execution failed for ${name}:`, error);
+      throw new McpError(
+        ErrorCode.InternalError,
+        `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  });
+}
+
+/**
+ * Health check handler
+ */
+async function handleHealthCheck(): Promise<string> {
+  const health = {
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    server: {
+      name: 'remember-mcp',
+      version: '0.1.0',
+    },
+    databases: {
+      weaviate: {
+        connected: false,
+        url: config.weaviate.url,
+      },
+      firestore: {
+        connected: false,
+        projectId: config.firebase.projectId,
+      },
+    },
+  };
+
+  try {
+    // Test Weaviate connection
+    const weaviateClient = getWeaviateClient();
+    health.databases.weaviate.connected = await weaviateClient.isReady();
+  } catch (error) {
+    logger.error('Weaviate health check failed:', error);
+    health.databases.weaviate.connected = false;
+  }
+
+  try {
+    // Test Firestore connection
+    health.databases.firestore.connected = await testFirestoreConnection();
+  } catch (error) {
+    logger.error('Firestore health check failed:', error);
+    health.databases.firestore.connected = false;
+  }
+
+  // Overall status
+  const allHealthy =
+    health.databases.weaviate.connected &&
+    health.databases.firestore.connected;
+
+  health.status = allHealthy ? 'healthy' : 'degraded';
+
+  return JSON.stringify(health, null, 2);
+}
+
+/**
+ * Main server startup
+ */
+async function main(): Promise<void> {
+  try {
+    logger.info('Starting remember-mcp server...');
+
+    // Initialize server
+    const server = await initServer();
+
+    // Start with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    logger.info('Server running on stdio transport');
+
+    // Note: When using stdio transport, avoid console.log as it interferes with JSON-RPC
+    // The logger is configured to handle this appropriately
+  } catch (error) {
+    logger.error('Server startup failed:', error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Graceful shutdown handler
+ */
+function setupShutdownHandlers(server: Server): void {
+  const shutdown = async (signal: string) => {
+    logger.info(`Received ${signal}, shutting down gracefully...`);
+    try {
+      await server.close();
+      logger.info('Server closed successfully');
+      process.exit(0);
+    } catch (error) {
+      logger.error('Error during shutdown:', error);
+      process.exit(1);
+    }
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+// Start the server
+main().catch((error) => {
+  logger.error('Fatal error:', error);
+  process.exit(1);
+});