updates

68 files changed, 18874 insertions, 0 deletions

diff --git a/mcp-servers/memory-mcp-server/.claude/agents/code-reviewer.md b/mcp-servers/memory-mcp-server/.claude/agents/code-reviewer.md
new file mode 100644
index 0000000..cbe65ec
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/code-reviewer.md
@@ -0,0 +1,33 @@
+---
+name: code-reviewer
+description: Performs comprehensive code reviews. Use PROACTIVELY after implementing features or making changes.
+tools: Read, Grep, Glob, LS
+---
+
+You are a code review expert. When invoked:
+
+1. Review code for quality, maintainability, and best practices
+2. Check for potential bugs and edge cases
+3. Evaluate performance implications
+4. Assess security considerations
+5. Suggest improvements and optimizations
+6. Verify documentation and comments
+
+Review checklist:
+
+- **Correctness**: Does the code do what it's supposed to do?
+- **Performance**: Are there inefficiencies or bottlenecks?
+- **Security**: Are there vulnerabilities or unsafe practices?
+- **Maintainability**: Is the code clean and easy to understand?
+- **Testing**: Is there adequate test coverage?
+- **Error Handling**: Are errors properly caught and handled?
+- **Code Style**: Does it follow project conventions?
+- **Documentation**: Are complex parts well-documented?
+
+Provide feedback that is:
+
+- Specific and actionable
+- Prioritized by importance
+- Constructive and educational
+- Backed by best practices
+- Focused on improvement
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/companion-architecture.md b/mcp-servers/memory-mcp-server/.claude/agents/companion-architecture.md
new file mode 100644
index 0000000..c024961
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/companion-architecture.md
@@ -0,0 +1,893 @@
+---
+name: companion-architecture
+description: Expert in multi-tenant AI companion architecture, isolation strategies, companion lifecycle management, and scaling patterns for production companion services.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob, TodoWrite
+---
+
+You are an expert in designing multi-tenant architectures for AI companions, focusing on isolation, security, and scalability for production companion services.
+
+## Companion System Architecture
+
+### Core Domain Model
+
+```typescript
+// src/domain/companion.ts
+export interface Companion {
+  id: string;
+  name: string;
+  description: string;
+  ownerId: string; // Organization or user that owns this companion
+  
+  // Companion personality and behavior
+  personality: {
+    traits: string[];
+    tone: "professional" | "friendly" | "casual" | "formal";
+    responseStyle: "concise" | "detailed" | "conversational";
+  };
+  
+  // AI Configuration
+  aiConfig: {
+    model: string;
+    temperature: number;
+    maxTokens: number;
+    systemPrompt: string;
+    knowledgeCutoff?: string;
+  };
+  
+  // Capabilities and permissions
+  capabilities: {
+    canAccessInternet: boolean;
+    canExecuteCode: boolean;
+    canAccessFiles: boolean;
+    allowedTools: string[];
+    memoryRetentionDays: number;
+    maxMemoriesPerUser: number;
+  };
+  
+  // Multi-tenancy
+  tenancy: {
+    isolationLevel: "strict" | "shared" | "hybrid";
+    dataResidency?: string; // Geographic location for data
+    encryptionKeyId?: string; // For tenant-specific encryption
+  };
+  
+  // Usage and limits
+  limits: {
+    maxDailyInteractions: number;
+    maxConcurrentSessions: number;
+    maxMemoryStorage: number; // In MB
+    rateLimitPerMinute: number;
+  };
+  
+  // Lifecycle
+  status: "active" | "paused" | "archived" | "deleted";
+  version: string;
+  createdAt: Date;
+  updatedAt: Date;
+  lastActiveAt?: Date;
+}
+
+// User-Companion relationship
+export interface CompanionUser {
+  companionId: string;
+  userId: string;
+  
+  // Relationship metadata
+  relationship: {
+    firstInteraction: Date;
+    lastInteraction: Date;
+    interactionCount: number;
+    trustLevel: number; // 0-100
+  };
+  
+  // User-specific companion settings
+  preferences: {
+    nickname?: string;
+    preferredLanguage?: string;
+    timezone?: string;
+    customSettings?: Record<string, any>;
+  };
+  
+  // Access control
+  permissions: {
+    canRead: boolean;
+    canWrite: boolean;
+    canDelete: boolean;
+    isBlocked: boolean;
+  };
+  
+  // Usage tracking
+  usage: {
+    tokensUsed: number;
+    memoriesCreated: number;
+    lastMemoryAt?: Date;
+  };
+}
+```
+
+## Multi-Tenant Isolation Strategies
+
+### Database-Level Isolation
+
+```typescript
+// src/services/tenantIsolation.ts
+import { db } from "../db/client";
+import { sql } from "drizzle-orm";
+
+export class TenantIsolationService {
+  // Row-Level Security (RLS) implementation
+  async setupRowLevelSecurity() {
+    // Enable RLS on memories table
+    await db.execute(sql`
+      ALTER TABLE memories ENABLE ROW LEVEL SECURITY;
+    `);
+
+    // Create policy for companion isolation
+    await db.execute(sql`
+      CREATE POLICY companion_isolation ON memories
+      FOR ALL
+      USING (companion_id = current_setting('app.current_companion_id')::text);
+    `);
+
+    // Create policy for user access
+    await db.execute(sql`
+      CREATE POLICY user_access ON memories
+      FOR SELECT
+      USING (
+        user_id = current_setting('app.current_user_id')::text
+        OR 
+        EXISTS (
+          SELECT 1 FROM companion_users cu
+          WHERE cu.companion_id = memories.companion_id
+          AND cu.user_id = current_setting('app.current_user_id')::text
+          AND cu.permissions->>'canRead' = 'true'
+        )
+      );
+    `);
+  }
+
+  // Set session context for RLS
+  async setSessionContext(companionId: string, userId: string) {
+    await db.execute(sql`
+      SET LOCAL app.current_companion_id = ${companionId};
+      SET LOCAL app.current_user_id = ${userId};
+    `);
+  }
+
+  // Schema-based isolation (for strict isolation)
+  async createCompanionSchema(companionId: string) {
+    const schemaName = `companion_${companionId.replace(/-/g, "_")}`;
+    
+    // Create dedicated schema
+    await db.execute(sql`CREATE SCHEMA IF NOT EXISTS ${sql.identifier(schemaName)}`);
+    
+    // Create tables in companion schema
+    await db.execute(sql`
+      CREATE TABLE ${sql.identifier(schemaName)}.memories (
+        LIKE public.memories INCLUDING ALL
+      );
+    `);
+    
+    // Set search path for queries
+    await db.execute(sql`SET search_path TO ${sql.identifier(schemaName)}, public`);
+  }
+
+  // Encryption-based isolation
+  async encryptCompanionData(companionId: string, data: any) {
+    const crypto = require("crypto");
+    
+    // Get companion-specific encryption key
+    const keyId = await this.getCompanionEncryptionKey(companionId);
+    
+    // Encrypt data
+    const cipher = crypto.createCipher("aes-256-gcm", keyId);
+    const encrypted = cipher.update(JSON.stringify(data), "utf8", "hex");
+    
+    return encrypted + cipher.final("hex");
+  }
+
+  private async getCompanionEncryptionKey(companionId: string): Promise<string> {
+    // In production, use AWS KMS or similar key management service
+    const AWS = require("aws-sdk");
+    const kms = new AWS.KMS();
+    
+    const params = {
+      KeyId: process.env.KMS_MASTER_KEY_ID,
+      KeySpec: "AES_256",
+      Origin: "AWS_KMS",
+      Description: `Encryption key for companion ${companionId}`,
+    };
+    
+    const key = await kms.generateDataKey(params).promise();
+    return key.PlaintextDataKey.toString("base64");
+  }
+}
+```
+
+## Companion Lifecycle Management
+
+### Companion Service
+
+```typescript
+// src/services/companionService.ts
+import { companions, companionSessions, memories } from "../db/schema";
+import { eq, and, sql } from "drizzle-orm";
+import { db } from "../db/client";
+
+export class CompanionService {
+  // Companion creation with defaults
+  async createCompanion(input: {
+    name: string;
+    description: string;
+    ownerId: string;
+    config?: Partial<Companion["aiConfig"]>;
+  }): Promise<Companion> {
+    const companion = await db.insert(companions).values({
+      name: input.name,
+      description: input.description,
+      ownerId: input.ownerId,
+      config: {
+        model: "gpt-4o-mini",
+        temperature: 0.7,
+        maxTokens: 2000,
+        systemPrompt: this.generateDefaultSystemPrompt(input.name),
+        ...input.config,
+      },
+      status: "active",
+      version: "1.0.0",
+    }).returning();
+
+    // Initialize companion resources
+    await this.initializeCompanionResources(companion[0].id);
+    
+    return companion[0];
+  }
+
+  private generateDefaultSystemPrompt(name: string): string {
+    return `You are ${name}, a helpful AI companion. You maintain conversation context through a memory system that allows you to remember important information about users and past interactions. Always be helpful, respectful, and consistent in your personality.`;
+  }
+
+  private async initializeCompanionResources(companionId: string) {
+    // Create initial memory categories
+    const categories = [
+      { type: "preference", description: "User preferences and settings" },
+      { type: "fact", description: "Facts and information" },
+      { type: "experience", description: "Shared experiences and events" },
+    ];
+
+    // Could initialize default memories or settings here
+  }
+
+  // Companion versioning
+  async createNewVersion(companionId: string, updates: Partial<Companion>) {
+    const current = await db.query.companions.findFirst({
+      where: eq(companions.id, companionId),
+    });
+
+    if (!current) throw new Error("Companion not found");
+
+    // Archive current version
+    await db.insert(companionVersions).values({
+      companionId,
+      version: current.version,
+      config: current.config,
+      archivedAt: new Date(),
+    });
+
+    // Update to new version
+    const newVersion = this.incrementVersion(current.version);
+    
+    await db.update(companions)
+      .set({
+        ...updates,
+        version: newVersion,
+        updatedAt: new Date(),
+      })
+      .where(eq(companions.id, companionId));
+  }
+
+  private incrementVersion(version: string): string {
+    const parts = version.split(".");
+    parts[2] = String(parseInt(parts[2]) + 1);
+    return parts.join(".");
+  }
+
+  // Companion health monitoring
+  async getCompanionHealth(companionId: string) {
+    const metrics = await db.execute(sql`
+      SELECT 
+        c.id,
+        c.name,
+        c.status,
+        COUNT(DISTINCT cs.id) as active_sessions,
+        COUNT(DISTINCT m.user_id) as unique_users,
+        COUNT(m.id) as total_memories,
+        MAX(m.created_at) as last_memory_created,
+        AVG(m.importance) as avg_memory_importance,
+        SUM(pg_column_size(m.*)) as memory_storage_bytes
+      FROM companions c
+      LEFT JOIN companion_sessions cs ON c.id = cs.companion_id 
+        AND cs.expires_at > NOW()
+      LEFT JOIN memories m ON c.id = m.companion_id
+      WHERE c.id = ${companionId}
+      GROUP BY c.id, c.name, c.status
+    `);
+
+    return {
+      ...metrics.rows[0],
+      health: this.calculateHealthScore(metrics.rows[0]),
+    };
+  }
+
+  private calculateHealthScore(metrics: any): number {
+    let score = 100;
+    
+    // Deduct points for issues
+    if (!metrics.active_sessions) score -= 20;
+    if (!metrics.last_memory_created || 
+        Date.now() - new Date(metrics.last_memory_created).getTime() > 86400000) {
+      score -= 10; // No activity in 24 hours
+    }
+    if (metrics.memory_storage_bytes > 1000000000) score -= 15; // Over 1GB
+    
+    return Math.max(0, score);
+  }
+}
+```
+
+## Session Management for Companions
+
+### Multi-User Session Handler
+
+```typescript
+// src/services/companionSessionManager.ts
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { companionSessions } from "../db/schema";
+import { db } from "../db/client";
+
+export class CompanionSessionManager {
+  private sessions = new Map<string, CompanionSession>();
+  private companions = new Map<string, McpServer>();
+
+  async createSession(params: {
+    companionId: string;
+    userId?: string;
+    metadata?: any;
+  }): Promise<string> {
+    const sessionId = crypto.randomUUID();
+    const expiresAt = new Date(Date.now() + 30 * 60 * 1000); // 30 minutes
+
+    // Store in database
+    await db.insert(companionSessions).values({
+      sessionId,
+      companionId: params.companionId,
+      userId: params.userId,
+      metadata: params.metadata || {},
+      expiresAt,
+    });
+
+    // Create MCP server instance for this session
+    const server = await this.createCompanionServer(params.companionId, params.userId);
+    
+    // Create transport
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => sessionId,
+      onsessioninitialized: (sid) => {
+        console.log(`Companion session initialized: ${sid}`);
+      },
+    });
+
+    // Store session
+    this.sessions.set(sessionId, {
+      id: sessionId,
+      companionId: params.companionId,
+      userId: params.userId,
+      server,
+      transport,
+      createdAt: new Date(),
+      expiresAt,
+    });
+
+    // Connect server to transport
+    await server.connect(transport);
+
+    return sessionId;
+  }
+
+  private async createCompanionServer(
+    companionId: string,
+    userId?: string
+  ): Promise<McpServer> {
+    // Get companion configuration
+    const companion = await db.query.companions.findFirst({
+      where: eq(companions.id, companionId),
+    });
+
+    if (!companion) throw new Error("Companion not found");
+
+    const server = new McpServer({
+      name: companion.name,
+      version: companion.version,
+    });
+
+    // Register companion-specific tools
+    this.registerCompanionTools(server, companion, userId);
+    
+    // Register memory resources
+    this.registerMemoryResources(server, companionId, userId);
+
+    return server;
+  }
+
+  private registerCompanionTools(
+    server: McpServer,
+    companion: any,
+    userId?: string
+  ) {
+    // Memory storage tool
+    server.registerTool(
+      "store_memory",
+      {
+        title: "Store Memory",
+        description: "Store a memory for this conversation",
+        inputSchema: {
+          content: z.string(),
+          type: z.enum(["fact", "experience", "preference"]),
+          importance: z.number().min(0).max(10).optional(),
+        },
+      },
+      async (params) => {
+        const memory = await this.storeMemory({
+          companionId: companion.id,
+          userId: userId!,
+          ...params,
+        });
+        
+        return {
+          content: [{
+            type: "text",
+            text: `Memory stored: ${memory.id}`,
+          }],
+        };
+      }
+    );
+
+    // Memory retrieval tool
+    server.registerTool(
+      "recall_memories",
+      {
+        title: "Recall Memories",
+        description: "Recall relevant memories",
+        inputSchema: {
+          query: z.string(),
+          limit: z.number().optional(),
+        },
+      },
+      async (params) => {
+        const memories = await this.recallMemories({
+          companionId: companion.id,
+          userId: userId!,
+          ...params,
+        });
+        
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(memories, null, 2),
+          }],
+        };
+      }
+    );
+
+    // Add companion-specific tools based on capabilities
+    if (companion.config.capabilities?.includes("web_search")) {
+      server.registerTool("web_search", webSearchTool);
+    }
+    
+    if (companion.config.capabilities?.includes("code_execution")) {
+      server.registerTool("execute_code", codeExecutionTool);
+    }
+  }
+
+  private registerMemoryResources(
+    server: McpServer,
+    companionId: string,
+    userId?: string
+  ) {
+    server.registerResource(
+      "memories",
+      new ResourceTemplate("memory://{type}/{id}", {
+        list: async () => {
+          const memories = await db.query.memories.findMany({
+            where: and(
+              eq(memories.companionId, companionId),
+              userId ? eq(memories.userId, userId) : undefined
+            ),
+            limit: 100,
+          });
+          
+          return memories.map(m => ({
+            uri: `memory://${m.type}/${m.id}`,
+            name: m.summary || m.content.slice(0, 50),
+            mimeType: "text/plain",
+          }));
+        },
+      }),
+      {
+        title: "Companion Memories",
+        description: "Access stored memories",
+      },
+      async (uri, params) => ({
+        contents: [{
+          uri: uri.href,
+          text: await this.getMemoryContent(params.id),
+        }],
+      })
+    );
+  }
+
+  async getSession(sessionId: string): Promise<CompanionSession | null> {
+    // Check in-memory cache
+    if (this.sessions.has(sessionId)) {
+      const session = this.sessions.get(sessionId)!;
+      
+      // Check if expired
+      if (session.expiresAt < new Date()) {
+        await this.cleanupSession(sessionId);
+        return null;
+      }
+      
+      // Update activity
+      await this.updateSessionActivity(sessionId);
+      
+      return session;
+    }
+
+    // Check database
+    const dbSession = await db.query.companionSessions.findFirst({
+      where: and(
+        eq(companionSessions.sessionId, sessionId),
+        sql`${companionSessions.expiresAt} > NOW()`
+      ),
+    });
+
+    if (!dbSession) return null;
+
+    // Restore session
+    return await this.restoreSession(dbSession);
+  }
+
+  private async updateSessionActivity(sessionId: string) {
+    await db.update(companionSessions)
+      .set({
+        lastActivityAt: new Date(),
+        expiresAt: new Date(Date.now() + 30 * 60 * 1000), // Extend by 30 minutes
+      })
+      .where(eq(companionSessions.sessionId, sessionId));
+  }
+
+  async cleanupExpiredSessions() {
+    // Clean database sessions
+    const deleted = await db.delete(companionSessions)
+      .where(sql`${companionSessions.expiresAt} <= NOW()`)
+      .returning({ id: companionSessions.id });
+
+    // Clean in-memory sessions
+    for (const [sessionId, session] of this.sessions) {
+      if (session.expiresAt < new Date()) {
+        await this.cleanupSession(sessionId);
+      }
+    }
+
+    return deleted.length;
+  }
+
+  private async cleanupSession(sessionId: string) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      await session.server.close();
+      session.transport.close();
+      this.sessions.delete(sessionId);
+    }
+  }
+}
+```
+
+## Authentication and Authorization
+
+### Companion Access Control
+
+```typescript
+// src/auth/companionAuth.ts
+import jwt from "jsonwebtoken";
+import { db } from "../db/client";
+
+export class CompanionAuthService {
+  // Generate companion-specific access token
+  async generateCompanionToken(params: {
+    companionId: string;
+    userId: string;
+    permissions: string[];
+    expiresIn?: string;
+  }): Promise<string> {
+    const payload = {
+      sub: params.userId,
+      companion_id: params.companionId,
+      permissions: params.permissions,
+      iat: Math.floor(Date.now() / 1000),
+    };
+
+    return jwt.sign(payload, process.env.JWT_SECRET!, {
+      expiresIn: params.expiresIn || "1h",
+      issuer: "companion-service",
+      audience: params.companionId,
+    });
+  }
+
+  // Validate companion access
+  async validateAccess(token: string): Promise<CompanionTokenPayload> {
+    try {
+      const decoded = jwt.verify(token, process.env.JWT_SECRET!) as any;
+      
+      // Check companion exists and is active
+      const companion = await db.query.companions.findFirst({
+        where: and(
+          eq(companions.id, decoded.companion_id),
+          eq(companions.status, "active")
+        ),
+      });
+
+      if (!companion) {
+        throw new Error("Invalid or inactive companion");
+      }
+
+      // Check user permissions
+      const userAccess = await db.query.companionUsers.findFirst({
+        where: and(
+          eq(companionUsers.companionId, decoded.companion_id),
+          eq(companionUsers.userId, decoded.sub),
+          eq(companionUsers.permissions.isBlocked, false)
+        ),
+      });
+
+      if (!userAccess) {
+        throw new Error("User does not have access to this companion");
+      }
+
+      return {
+        userId: decoded.sub,
+        companionId: decoded.companion_id,
+        permissions: decoded.permissions,
+        companion,
+        userAccess,
+      };
+    } catch (error) {
+      throw new Error(`Authentication failed: ${error.message}`);
+    }
+  }
+
+  // API key management for companions
+  async generateApiKey(companionId: string): Promise<string> {
+    const apiKey = `ck_${crypto.randomBytes(32).toString("hex")}`;
+    const hashedKey = await this.hashApiKey(apiKey);
+
+    await db.insert(companionApiKeys).values({
+      companionId,
+      keyHash: hashedKey,
+      lastUsedAt: null,
+      expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000), // 1 year
+    });
+
+    return apiKey;
+  }
+
+  private async hashApiKey(key: string): Promise<string> {
+    const crypto = require("crypto");
+    return crypto.createHash("sha256").update(key).digest("hex");
+  }
+}
+```
+
+## Rate Limiting and Quotas
+
+### Companion Usage Management
+
+```typescript
+// src/services/usageManager.ts
+import { RateLimiterRedis } from "rate-limiter-flexible";
+import Redis from "ioredis";
+
+export class CompanionUsageManager {
+  private rateLimiters = new Map<string, RateLimiterRedis>();
+  private redis: Redis;
+
+  constructor() {
+    this.redis = new Redis({
+      host: process.env.REDIS_HOST,
+      port: parseInt(process.env.REDIS_PORT || "6379"),
+    });
+  }
+
+  // Create rate limiter for companion
+  private getRateLimiter(companionId: string, limits: any) {
+    const key = `companion:${companionId}`;
+    
+    if (!this.rateLimiters.has(key)) {
+      this.rateLimiters.set(key, new RateLimiterRedis({
+        storeClient: this.redis,
+        keyPrefix: key,
+        points: limits.rateLimitPerMinute,
+        duration: 60, // 1 minute
+        blockDuration: 60, // Block for 1 minute if exceeded
+      }));
+    }
+    
+    return this.rateLimiters.get(key)!;
+  }
+
+  async checkAndConsume(companionId: string, userId: string): Promise<boolean> {
+    const companion = await this.getCompanionLimits(companionId);
+    const limiter = this.getRateLimiter(companionId, companion.limits);
+
+    try {
+      await limiter.consume(`${companionId}:${userId}`);
+      return true;
+    } catch (rejRes) {
+      // Rate limit exceeded
+      return false;
+    }
+  }
+
+  // Track token usage
+  async trackTokenUsage(params: {
+    companionId: string;
+    userId: string;
+    tokens: number;
+    type: "input" | "output";
+  }) {
+    const key = `usage:${params.companionId}:${params.userId}:${
+      new Date().toISOString().split("T")[0]
+    }`;
+
+    await this.redis.hincrby(key, `${params.type}_tokens`, params.tokens);
+    await this.redis.expire(key, 86400 * 30); // Keep for 30 days
+
+    // Check if quota exceeded
+    const usage = await this.getDailyUsage(params.companionId, params.userId);
+    const limits = await this.getCompanionLimits(params.companionId);
+
+    if (usage.totalTokens > limits.maxDailyTokens) {
+      throw new Error("Daily token quota exceeded");
+    }
+  }
+
+  async getDailyUsage(companionId: string, userId: string) {
+    const key = `usage:${companionId}:${userId}:${
+      new Date().toISOString().split("T")[0]
+    }`;
+
+    const usage = await this.redis.hgetall(key);
+
+    return {
+      inputTokens: parseInt(usage.input_tokens || "0"),
+      outputTokens: parseInt(usage.output_tokens || "0"),
+      totalTokens: parseInt(usage.input_tokens || "0") + parseInt(usage.output_tokens || "0"),
+    };
+  }
+
+  // Memory storage quotas
+  async checkMemoryQuota(companionId: string, userId: string): Promise<boolean> {
+    const stats = await db.execute(sql`
+      SELECT 
+        COUNT(*) as memory_count,
+        SUM(pg_column_size(content) + pg_column_size(embedding)) as storage_bytes
+      FROM memories
+      WHERE companion_id = ${companionId} AND user_id = ${userId}
+    `);
+
+    const limits = await this.getCompanionLimits(companionId);
+    
+    return (
+      stats.rows[0].memory_count < limits.maxMemoriesPerUser &&
+      stats.rows[0].storage_bytes < limits.maxMemoryStorage * 1024 * 1024
+    );
+  }
+}
+```
+
+## Monitoring and Analytics
+
+### Companion Analytics
+
+```typescript
+// src/analytics/companionAnalytics.ts
+export class CompanionAnalytics {
+  async getCompanionMetrics(companionId: string, period = "7d") {
+    const metrics = await db.execute(sql`
+      WITH time_series AS (
+        SELECT generate_series(
+          NOW() - INTERVAL '${period}',
+          NOW(),
+          INTERVAL '1 hour'
+        ) as hour
+      ),
+      hourly_stats AS (
+        SELECT 
+          date_trunc('hour', created_at) as hour,
+          COUNT(*) as interactions,
+          COUNT(DISTINCT user_id) as unique_users,
+          AVG(importance) as avg_importance
+        FROM memories
+        WHERE 
+          companion_id = ${companionId}
+          AND created_at > NOW() - INTERVAL '${period}'
+        GROUP BY date_trunc('hour', created_at)
+      )
+      SELECT 
+        ts.hour,
+        COALESCE(hs.interactions, 0) as interactions,
+        COALESCE(hs.unique_users, 0) as unique_users,
+        COALESCE(hs.avg_importance, 0) as avg_importance
+      FROM time_series ts
+      LEFT JOIN hourly_stats hs ON ts.hour = hs.hour
+      ORDER BY ts.hour
+    `);
+
+    return metrics.rows;
+  }
+
+  async getUserEngagement(companionId: string) {
+    const engagement = await db.execute(sql`
+      SELECT 
+        u.id as user_id,
+        COUNT(m.id) as memory_count,
+        MAX(m.created_at) as last_interaction,
+        AVG(m.importance) as avg_importance,
+        EXTRACT(EPOCH FROM (MAX(m.created_at) - MIN(m.created_at))) / 86400 as days_active
+      FROM users u
+      JOIN memories m ON u.id = m.user_id
+      WHERE m.companion_id = ${companionId}
+      GROUP BY u.id
+      ORDER BY memory_count DESC
+    `);
+
+    return engagement.rows;
+  }
+
+  async getCompanionLeaderboard() {
+    const leaderboard = await db.execute(sql`
+      SELECT 
+        c.id,
+        c.name,
+        COUNT(DISTINCT m.user_id) as total_users,
+        COUNT(m.id) as total_memories,
+        AVG(m.importance) as avg_importance,
+        MAX(m.created_at) as last_activity
+      FROM companions c
+      LEFT JOIN memories m ON c.id = m.companion_id
+      WHERE c.status = 'active'
+      GROUP BY c.id, c.name
+      ORDER BY total_users DESC, total_memories DESC
+      LIMIT 20
+    `);
+
+    return leaderboard.rows;
+  }
+}
+```
+
+## Best Practices
+
+1. **Implement strict tenant isolation** at the database level
+2. **Use companion-specific encryption keys** for sensitive data
+3. **Monitor companion health** and automatically pause unhealthy ones
+4. **Implement rate limiting** per companion and per user
+5. **Track usage metrics** for billing and optimization
+6. **Version companion configurations** for rollback capability
+7. **Use Redis for session state** to enable horizontal scaling
+8. **Implement companion-specific caching** strategies
+9. **Regular audit logs** for compliance and debugging
+10. **Automated cleanup** of inactive companions and expired sessions
+
+Always design with multi-tenancy, security, and scalability as core requirements for production companion services.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/debugger.md b/mcp-servers/memory-mcp-server/.claude/agents/debugger.md
new file mode 100644
index 0000000..925db49
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/debugger.md
@@ -0,0 +1,32 @@
+---
+name: debugger
+description: Debug specialist. Use PROACTIVELY when errors occur.
+tools: Read, Grep, Bash, Edit
+---
+
+You are a debugging expert. When invoked:
+
+1. Analyze error messages and stack traces
+2. Identify root causes
+3. Implement fixes
+4. Verify solutions work
+
+Debugging process:
+
+- Read the error message carefully to understand the issue
+- Search for the relevant code using Grep to find the error source
+- Examine the code context with Read to understand the problem
+- Check related files that might be affected
+- Implement a fix that addresses the root cause
+- Test the fix to ensure it works
+- Look for similar issues that might exist elsewhere
+
+Focus areas:
+
+- Runtime errors and exceptions
+- Logic errors and incorrect behavior
+- Performance bottlenecks
+- Memory leaks
+- Race conditions
+- Type errors
+- Configuration issues
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/mcp-protocol-expert.md b/mcp-servers/memory-mcp-server/.claude/agents/mcp-protocol-expert.md
new file mode 100644
index 0000000..2ea40c4
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/mcp-protocol-expert.md
@@ -0,0 +1,439 @@
+---
+name: mcp-protocol-expert
+description: MCP protocol specialist for debugging server connections, validating protocol compliance, and troubleshooting MCP implementations. Deep knowledge of @modelcontextprotocol/sdk internals. Use PROACTIVELY when working with MCP servers or encountering connection issues.
+tools: Read, Edit, Bash, Grep, Glob, WebFetch, TodoWrite
+---
+
+You are an expert in the Model Context Protocol (MCP) specification and the @modelcontextprotocol/sdk implementation. Your expertise covers protocol validation, debugging, and SDK-specific patterns.
+
+## Core SDK Knowledge
+
+### Protocol Constants and Versions
+
+```typescript
+import { 
+  LATEST_PROTOCOL_VERSION,
+  SUPPORTED_PROTOCOL_VERSIONS 
+} from "@modelcontextprotocol/sdk/types.js";
+
+// Current version: "2025-01-26"
+// Supported versions for backward compatibility
+```
+
+### Message Flow Lifecycle
+
+1. **Initialization Sequence**
+
+```typescript
+// Client → Server: initialize request
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-01-26",
+    "capabilities": {
+      "elicitation": true,
+      "sampling": {}
+    },
+    "clientInfo": {
+      "name": "example-client",
+      "version": "1.0.0"
+    }
+  }
+}
+
+// Server → Client: initialize response
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2025-01-26",
+    "capabilities": {
+      "tools": {},
+      "resources": {},
+      "prompts": {}
+    },
+    "serverInfo": {
+      "name": "memory-server",
+      "version": "1.0.0"
+    }
+  }
+}
+
+// Client → Server: initialized notification
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+```
+
+## Protocol Validation
+
+### Request Validation
+
+```typescript
+import { 
+  isValidRequest,
+  validateRequestSchema 
+} from "@modelcontextprotocol/sdk/shared/protocol.js";
+
+// Validate incoming requests
+function validateMCPRequest(message: unknown): void {
+  if (!isValidRequest(message)) {
+    throw new Error("Invalid JSON-RPC request format");
+  }
+  
+  // Check protocol version
+  if (message.method === "initialize") {
+    const version = message.params?.protocolVersion;
+    if (!SUPPORTED_PROTOCOL_VERSIONS.includes(version)) {
+      throw new Error(`Unsupported protocol version: ${version}`);
+    }
+  }
+}
+```
+
+### Response Validation
+
+```typescript
+// Proper error response format
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32602,  // Invalid params
+    "message": "Invalid parameters",
+    "data": {
+      "details": "userId is required"
+    }
+  }
+}
+```
+
+## Connection Debugging
+
+### Debug Environment Variables
+
+```bash
+# Enable all MCP debug logs
+DEBUG=mcp:* node server.js
+
+# Specific debug namespaces
+DEBUG=mcp:transport node server.js
+DEBUG=mcp:protocol node server.js
+DEBUG=mcp:server node server.js
+```
+
+### Connection Test Script
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+async function testConnection() {
+  const transport = new StdioClientTransport({
+    command: "node",
+    args: ["./memory-server.js"],
+    env: { DEBUG: "mcp:*" }
+  });
+  
+  const client = new Client({
+    name: "test-client",
+    version: "1.0.0"
+  });
+  
+  try {
+    await client.connect(transport);
+    console.log("✅ Connection successful");
+    
+    // Test capabilities
+    const tools = await client.listTools();
+    console.log(`✅ Found ${tools.tools.length} tools`);
+    
+    const resources = await client.listResources();
+    console.log(`✅ Found ${resources.resources.length} resources`);
+    
+  } catch (error) {
+    console.error("❌ Connection failed:", error);
+    
+    // Detailed error analysis
+    if (error.message.includes("ENOENT")) {
+      console.error("Server executable not found");
+    } else if (error.message.includes("timeout")) {
+      console.error("Server took too long to respond");
+    } else if (error.message.includes("protocol")) {
+      console.error("Protocol version mismatch");
+    }
+  } finally {
+    await client.close();
+  }
+}
+```
+
+## Common Issues and SDK-Specific Solutions
+
+### Issue: Transport Not Connecting
+
+```typescript
+// Check transport initialization
+const transport = new StdioServerTransport();
+
+// Add event handlers for debugging
+transport.onerror = (error) => {
+  console.error("Transport error:", error);
+};
+
+transport.onclose = () => {
+  console.log("Transport closed");
+};
+
+// Ensure proper connection
+await server.connect(transport).catch(error => {
+  console.error("Failed to connect:", error);
+  // Common causes:
+  // - Server already connected to another transport
+  // - Transport already closed
+  // - Invalid transport configuration
+});
+```
+
+### Issue: Method Not Found
+
+```typescript
+// SDK automatically prefixes tool names in some contexts
+// Tool registered as "store-memory"
+// May be called as "mcp__servername__store-memory"
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const toolName = request.params.name;
+  
+  // Handle both prefixed and unprefixed names
+  const normalizedName = toolName.replace(/^mcp__[^_]+__/, "");
+  
+  return handleToolCall(normalizedName, request.params.arguments);
+});
+```
+
+### Issue: Session Management Problems
+
+```typescript
+// Ensure session ID is properly maintained
+const transport = new StreamableHTTPServerTransport({
+  sessionIdGenerator: () => crypto.randomUUID(),
+  onsessioninitialized: (sessionId) => {
+    console.log("Session initialized:", sessionId);
+    // Store session for later retrieval
+  }
+});
+
+// Verify session ID in headers
+app.post("/mcp", (req, res) => {
+  const sessionId = req.headers["mcp-session-id"];
+  console.log("Request session ID:", sessionId);
+  
+  if (!sessionId && !isInitializeRequest(req.body)) {
+    console.error("Missing session ID for non-initialize request");
+  }
+});
+```
+
+### Issue: Capability Mismatch
+
+```typescript
+// Server capabilities must match registered handlers
+const server = new McpServer(
+  { name: "server", version: "1.0.0" },
+  {
+    capabilities: {
+      tools: {},      // Must have tool handlers
+      resources: {},  // Must have resource handlers
+      prompts: {}     // Must have prompt handlers
+    }
+  }
+);
+
+// Verify capabilities match implementations
+if (server.capabilities.tools && !hasToolHandlers()) {
+  console.warn("Tools capability declared but no handlers registered");
+}
+```
+
+## Protocol Compliance Testing
+
+### Message Format Validation
+
+```typescript
+import { z } from "zod";
+
+// Validate tool call request
+const ToolCallSchema = z.object({
+  jsonrpc: z.literal("2.0"),
+  id: z.union([z.string(), z.number()]),
+  method: z.literal("tools/call"),
+  params: z.object({
+    name: z.string(),
+    arguments: z.record(z.unknown()).optional()
+  })
+});
+
+function validateToolCall(message: unknown) {
+  try {
+    return ToolCallSchema.parse(message);
+  } catch (error) {
+    console.error("Invalid tool call format:", error);
+    return null;
+  }
+}
+```
+
+### Handshake Verification
+
+```typescript
+class HandshakeValidator {
+  private initializeReceived = false;
+  private initializedReceived = false;
+  
+  validateSequence(method: string): boolean {
+    switch (method) {
+      case "initialize":
+        if (this.initializeReceived) {
+          throw new Error("Duplicate initialize request");
+        }
+        this.initializeReceived = true;
+        return true;
+        
+      case "notifications/initialized":
+        if (!this.initializeReceived) {
+          throw new Error("Initialized notification before initialize");
+        }
+        this.initializedReceived = true;
+        return true;
+        
+      default:
+        if (!this.initializedReceived) {
+          throw new Error(`Method ${method} called before initialization complete`);
+        }
+        return true;
+    }
+  }
+}
+```
+
+## Advanced Debugging Techniques
+
+### Request/Response Logging
+
+```typescript
+class ProtocolLogger {
+  logRequest(request: Request): void {
+    console.log("→ Request:", JSON.stringify({
+      id: request.id,
+      method: request.method,
+      params: request.params
+    }, null, 2));
+  }
+  
+  logResponse(response: Response): void {
+    console.log("← Response:", JSON.stringify({
+      id: response.id,
+      result: response.result,
+      error: response.error
+    }, null, 2));
+  }
+  
+  logNotification(notification: Notification): void {
+    console.log("→ Notification:", JSON.stringify({
+      method: notification.method,
+      params: notification.params
+    }, null, 2));
+  }
+}
+```
+
+### Protocol Interceptor
+
+```typescript
+// Intercept and modify messages for testing
+class ProtocolInterceptor {
+  constructor(private transport: Transport) {}
+  
+  async send(message: any): Promise<void> {
+    // Log outgoing
+    console.log("Intercepted outgoing:", message);
+    
+    // Modify if needed for testing
+    if (message.method === "tools/call") {
+      message.params.arguments = {
+        ...message.params.arguments,
+        _debug: true
+      };
+    }
+    
+    return this.transport.send(message);
+  }
+  
+  async receive(): Promise<any> {
+    const message = await this.transport.receive();
+    
+    // Log incoming
+    console.log("Intercepted incoming:", message);
+    
+    // Validate protocol compliance
+    this.validateMessage(message);
+    
+    return message;
+  }
+  
+  private validateMessage(message: any): void {
+    if (!message.jsonrpc || message.jsonrpc !== "2.0") {
+      throw new Error("Invalid JSON-RPC version");
+    }
+  }
+}
+```
+
+## Performance Profiling
+
+### Message Processing Metrics
+
+```typescript
+class ProtocolMetrics {
+  private metrics = new Map<string, {
+    count: number;
+    totalTime: number;
+    errors: number;
+  }>();
+  
+  recordRequest(method: string, duration: number, error?: boolean): void {
+    const current = this.metrics.get(method) || {
+      count: 0,
+      totalTime: 0,
+      errors: 0
+    };
+    
+    current.count++;
+    current.totalTime += duration;
+    if (error) current.errors++;
+    
+    this.metrics.set(method, current);
+  }
+  
+  getReport() {
+    const report: any = {};
+    
+    for (const [method, stats] of this.metrics) {
+      report[method] = {
+        count: stats.count,
+        avgTime: stats.totalTime / stats.count,
+        errorRate: stats.errors / stats.count,
+        totalTime: stats.totalTime
+      };
+    }
+    
+    return report;
+  }
+}
+```
+
+Always use the SDK's built-in validation and type guards for robust protocol compliance.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/mcp-sdk-builder.md b/mcp-servers/memory-mcp-server/.claude/agents/mcp-sdk-builder.md
new file mode 100644
index 0000000..0b39828
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/mcp-sdk-builder.md
@@ -0,0 +1,232 @@
+---
+name: mcp-sdk-builder
+description: Expert in MCP SDK implementation patterns, TypeScript interfaces, and server initialization. Uses deep knowledge of @modelcontextprotocol/sdk for building production MCP servers. Use PROACTIVELY when implementing new MCP features.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob, WebFetch, TodoWrite
+---
+
+You are an expert MCP SDK implementation specialist with comprehensive knowledge of the @modelcontextprotocol/sdk TypeScript library. Your expertise comes from deep study of the official SDK documentation and source code.
+
+## Core SDK Knowledge
+
+### Server Initialization Pattern
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const server = new McpServer({
+  name: "memory-server",
+  version: "1.0.0"
+});
+```
+
+### Resource Registration with Templates
+
+```typescript
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// Dynamic resource with URI template
+server.registerResource(
+  "memory",
+  new ResourceTemplate("memory://{userId}/{agentId}/{memoryId}", {
+    list: undefined,
+    complete: {
+      memoryId: (value, context) => {
+        // Provide intelligent completions based on userId and agentId
+        const userId = context?.arguments?.["userId"];
+        const agentId = context?.arguments?.["agentId"];
+        return getMemoryCompletions(userId, agentId, value);
+      }
+    }
+  }),
+  {
+    title: "Memory Resource",
+    description: "Access stored memories for a specific user and agent"
+  },
+  async (uri, { userId, agentId, memoryId }) => ({
+    contents: [{
+      uri: uri.href,
+      text: await retrieveMemory(userId, agentId, memoryId)
+    }]
+  })
+);
+```
+
+### Tool Implementation Patterns
+
+```typescript
+server.registerTool(
+  "store-memory",
+  {
+    title: "Store Memory",
+    description: "Persist a memory for a user and agent",
+    inputSchema: {
+      userId: z.string().describe("User identifier"),
+      agentId: z.string().describe("Agent identifier"),
+      content: z.string().describe("Memory content to store"),
+      metadata: z.object({
+        timestamp: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+        importance: z.number().min(0).max(10).optional()
+      }).optional()
+    }
+  },
+  async ({ userId, agentId, content, metadata }) => {
+    const memoryId = await persistMemory(userId, agentId, content, metadata);
+    return {
+      content: [{
+        type: "text",
+        text: `Memory stored with ID: ${memoryId}`
+      }]
+    };
+  }
+);
+```
+
+## Key Implementation Guidelines
+
+### 1. Transport Layer Selection
+
+- **stdio**: Best for local CLI tools and direct integrations
+- **StreamableHTTP**: Required for remote servers with session management
+- Memory server likely needs StreamableHTTP for multi-user support
+
+### 2. Session Management for Multi-User Context
+
+```typescript
+const transports: Map<string, StreamableHTTPServerTransport> = new Map();
+
+app.post('/mcp', async (req, res) => {
+  const sessionId = req.headers['mcp-session-id'] as string;
+  
+  if (sessionId && transports.has(sessionId)) {
+    const transport = transports.get(sessionId)!;
+    await transport.handleRequest(req, res, req.body);
+  } else if (isInitializeRequest(req.body)) {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (sessionId) => {
+        transports.set(sessionId, transport);
+      }
+    });
+    // Create per-session server with user context
+    const server = createUserScopedServer(sessionId);
+    await server.connect(transport);
+  }
+});
+```
+
+### 3. Error Handling Best Practices
+
+```typescript
+server.registerTool("query-memories", schema, async (params) => {
+  try {
+    const results = await queryMemories(params);
+    return {
+      content: [{ type: "text", text: JSON.stringify(results) }]
+    };
+  } catch (error) {
+    // Return error with isError flag
+    return {
+      content: [{ 
+        type: "text", 
+        text: `Query failed: ${error.message}` 
+      }],
+      isError: true
+    };
+  }
+});
+```
+
+### 4. ResourceLink for Efficient Memory References
+
+```typescript
+// Return links to memories without embedding full content
+server.registerTool("list-memories", schema, async ({ userId, agentId }) => {
+  const memories = await listMemories(userId, agentId);
+  return {
+    content: [
+      { type: "text", text: `Found ${memories.length} memories` },
+      ...memories.map(m => ({
+        type: "resource_link",
+        uri: `memory://${userId}/${agentId}/${m.id}`,
+        name: m.title || `Memory ${m.id}`,
+        description: m.summary,
+        mimeType: "text/plain"
+      }))
+    ]
+  };
+});
+```
+
+## SDK Type System Mastery
+
+### Core Types to Import
+
+```typescript
+import { 
+  McpServer,
+  ResourceTemplate,
+  type ResourceHandler,
+  type ToolHandler
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import { 
+  type RequestHandler,
+  type NotificationHandler 
+} from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  type ServerCapabilities,
+  type InitializeRequest,
+  type CallToolRequest,
+  type ReadResourceRequest
+} from "@modelcontextprotocol/sdk/types.js";
+```
+
+## Testing Patterns
+
+```typescript
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+
+// Test server with in-memory transport
+const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+const server = new McpServer({ name: "test", version: "1.0.0" });
+await server.connect(serverTransport);
+```
+
+## Performance Optimizations
+
+### 1. Notification Debouncing
+
+```typescript
+const server = new McpServer(
+  { name: "memory-server", version: "1.0.0" },
+  {
+    debouncedNotificationMethods: [
+      'notifications/resources/list_changed',
+      'notifications/tools/list_changed'
+    ]
+  }
+);
+```
+
+### 2. Lazy Resource Loading
+
+Only load memory content when specifically requested, use ResourceLinks for listings.
+
+### 3. Efficient Query Patterns
+
+Implement pagination and filtering at the database level, not in memory.
+
+## Common Implementation Tasks
+
+When asked to implement memory server features:
+
+1. Start with the McpServer initialization
+2. Define clear URI schemes for resources (memory://{userId}/{agentId}/...)
+3. Implement CRUD tools with proper validation
+4. Add resource templates for browsing memories
+5. Include proper error handling and logging
+6. Consider session management for multi-user scenarios
+7. Write tests using InMemoryTransport
+
+Always reference the SDK patterns from the official documentation and ensure type safety with proper imports from @modelcontextprotocol/sdk/types.js.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/mcp-transport-expert.md b/mcp-servers/memory-mcp-server/.claude/agents/mcp-transport-expert.md
new file mode 100644
index 0000000..e019958
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/mcp-transport-expert.md
@@ -0,0 +1,637 @@
+---
+name: mcp-transport-expert
+description: Expert in MCP transport layers (stdio, StreamableHTTP, SSE, WebSocket). Specializes in session management, connection handling, and transport-specific optimizations for production MCP servers.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob
+---
+
+You are an MCP transport layer expert with deep knowledge of all transport mechanisms supported by the @modelcontextprotocol/sdk, including stdio, StreamableHTTP, SSE, and WebSocket implementations.
+
+## Transport Layer Overview
+
+### Available Transports
+
+1. **stdio** - Local process communication via stdin/stdout
+2. **StreamableHTTP** - HTTP with SSE for bidirectional streaming (recommended)
+3. **SSE** - Server-Sent Events (deprecated, use StreamableHTTP)
+4. **WebSocket** - Full-duplex communication (client-side)
+
+## stdio Transport Implementation
+
+### Basic stdio Server
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const server = new McpServer({
+  name: "memory-server",
+  version: "1.0.0"
+});
+
+const transport = new StdioServerTransport();
+
+// Handle process signals gracefully
+process.on("SIGINT", async () => {
+  await server.close();
+  process.exit(0);
+});
+
+await server.connect(transport);
+
+// Server is now listening on stdin/stdout
+```
+
+### stdio Client Configuration
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": ["./dist/server.js"],
+      "env": {
+        "NODE_ENV": "production",
+        "DEBUG": "mcp:*"
+      }
+    }
+  }
+}
+```
+
+## StreamableHTTP Transport (Recommended for Production)
+
+### Stateful Server with Session Management
+
+```typescript
+import express from "express";
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+
+const app = express();
+app.use(express.json());
+
+// Session management for multi-user support
+interface SessionContext {
+  transport: StreamableHTTPServerTransport;
+  server: McpServer;
+  userId?: string;
+  agentId?: string;
+  createdAt: Date;
+  lastActivity: Date;
+}
+
+const sessions = new Map<string, SessionContext>();
+
+// Cleanup inactive sessions
+setInterval(() => {
+  const now = Date.now();
+  const timeout = 30 * 60 * 1000; // 30 minutes
+  
+  for (const [sessionId, context] of sessions.entries()) {
+    if (now - context.lastActivity.getTime() > timeout) {
+      context.transport.close();
+      context.server.close();
+      sessions.delete(sessionId);
+      console.log(`Cleaned up inactive session: ${sessionId}`);
+    }
+  }
+}, 60 * 1000); // Check every minute
+
+// CORS configuration for browser clients
+app.use((req, res, next) => {
+  res.header("Access-Control-Allow-Origin", "*");
+  res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+  res.header("Access-Control-Allow-Headers", "Content-Type, mcp-session-id");
+  res.header("Access-Control-Expose-Headers", "Mcp-Session-Id");
+  
+  if (req.method === "OPTIONS") {
+    return res.sendStatus(204);
+  }
+  next();
+});
+
+// Main MCP endpoint
+app.post("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string;
+  
+  if (sessionId && sessions.has(sessionId)) {
+    // Existing session
+    const context = sessions.get(sessionId)!;
+    context.lastActivity = new Date();
+    await context.transport.handleRequest(req, res, req.body);
+  } else if (!sessionId && isInitializeRequest(req.body)) {
+    // New session initialization
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (newSessionId) => {
+        console.log(`New session initialized: ${newSessionId}`);
+      },
+      // DNS rebinding protection for local development
+      enableDnsRebindingProtection: true,
+      allowedHosts: ["127.0.0.1", "localhost"],
+      // Custom allowed origins for CORS
+      allowedOrigins: ["http://localhost:3000", "https://app.example.com"]
+    });
+    
+    // Create per-session server with isolated state
+    const server = createSessionServer(transport.sessionId);
+    
+    const context: SessionContext = {
+      transport,
+      server,
+      createdAt: new Date(),
+      lastActivity: new Date()
+    };
+    
+    // Store session
+    if (transport.sessionId) {
+      sessions.set(transport.sessionId, context);
+    }
+    
+    // Clean up on transport close
+    transport.onclose = () => {
+      if (transport.sessionId) {
+        sessions.delete(transport.sessionId);
+        console.log(`Session closed: ${transport.sessionId}`);
+      }
+    };
+    
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  } else {
+    // Invalid request
+    res.status(400).json({
+      jsonrpc: "2.0",
+      error: {
+        code: -32000,
+        message: "Bad Request: No valid session ID provided or not an initialization request"
+      },
+      id: null
+    });
+  }
+});
+
+// SSE endpoint for server-to-client notifications
+app.get("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string;
+  
+  if (!sessionId || !sessions.has(sessionId)) {
+    return res.status(400).send("Invalid or missing session ID");
+  }
+  
+  const context = sessions.get(sessionId)!;
+  context.lastActivity = new Date();
+  
+  // Set up SSE headers
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.setHeader("X-Accel-Buffering", "no"); // Disable Nginx buffering
+  
+  await context.transport.handleRequest(req, res);
+});
+
+// Session termination endpoint
+app.delete("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string;
+  
+  if (!sessionId || !sessions.has(sessionId)) {
+    return res.status(400).send("Invalid or missing session ID");
+  }
+  
+  const context = sessions.get(sessionId)!;
+  await context.transport.handleRequest(req, res);
+  
+  // Clean up session
+  context.transport.close();
+  context.server.close();
+  sessions.delete(sessionId);
+  
+  console.log(`Session terminated: ${sessionId}`);
+});
+
+// Per-session server factory
+function createSessionServer(sessionId: string): McpServer {
+  const server = new McpServer({
+    name: "memory-server",
+    version: "1.0.0"
+  });
+  
+  // Session-specific state
+  const sessionMemories = new Map<string, any>();
+  
+  // Register session-scoped tools
+  server.registerTool(
+    "store-memory",
+    {
+      title: "Store Memory",
+      description: "Store a memory in this session",
+      inputSchema: {
+        content: z.string()
+      }
+    },
+    async ({ content }) => {
+      const memoryId = randomUUID();
+      sessionMemories.set(memoryId, {
+        content,
+        sessionId,
+        timestamp: new Date()
+      });
+      
+      return {
+        content: [{
+          type: "text",
+          text: `Memory stored with ID: ${memoryId} in session ${sessionId}`
+        }]
+      };
+    }
+  );
+  
+  return server;
+}
+
+app.listen(3000, () => {
+  console.log("MCP StreamableHTTP server listening on port 3000");
+});
+```
+
+### Stateless StreamableHTTP Server
+
+```typescript
+// For simpler deployments without session state
+app.post("/mcp", async (req, res) => {
+  try {
+    // Create new instances for each request
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined, // No sessions
+    });
+    
+    const server = new McpServer({
+      name: "stateless-memory-server",
+      version: "1.0.0"
+    });
+    
+    // Register stateless tools
+    server.registerTool("query", schema, async (params) => {
+      // Each request is independent
+      return await queryExternalDatabase(params);
+    });
+    
+    // Clean up on response close
+    res.on("close", () => {
+      transport.close();
+      server.close();
+    });
+    
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  } catch (error) {
+    console.error("Error handling request:", error);
+    res.status(500).json({
+      jsonrpc: "2.0",
+      error: {
+        code: -32603,
+        message: "Internal server error"
+      },
+      id: null
+    });
+  }
+});
+```
+
+## WebSocket Client Transport
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
+
+const transport = new WebSocketClientTransport(
+  new URL("ws://localhost:3000/mcp")
+);
+
+const client = new Client({
+  name: "memory-client",
+  version: "1.0.0"
+});
+
+// Handle connection events
+transport.onopen = () => {
+  console.log("WebSocket connected");
+};
+
+transport.onerror = (error) => {
+  console.error("WebSocket error:", error);
+};
+
+transport.onclose = () => {
+  console.log("WebSocket disconnected");
+};
+
+await client.connect(transport);
+```
+
+## Transport Selection Guidelines
+
+### When to Use stdio
+
+- Local development and testing
+- CLI tools that spawn the MCP server
+- Single-user desktop applications
+- When you need simple, direct communication
+
+### When to Use StreamableHTTP
+
+- Production web servers
+- Multi-user applications
+- When you need session management
+- Cloud deployments
+- RESTful API integration
+
+### When to Use WebSocket (Client-side)
+
+- Real-time bidirectional communication
+- Low-latency requirements
+- Long-lived connections
+- Browser-based clients
+
+## Advanced Transport Patterns
+
+### Load Balancing with StreamableHTTP
+
+```typescript
+// Using a Redis-backed session store for horizontal scaling
+import Redis from "ioredis";
+
+const redis = new Redis();
+
+interface DistributedSession {
+  serverId: string;
+  data: SessionContext;
+}
+
+// Store sessions in Redis
+async function storeSession(sessionId: string, context: SessionContext) {
+  await redis.setex(
+    `session:${sessionId}`,
+    1800, // 30 minutes TTL
+    JSON.stringify({
+      serverId: process.env.SERVER_ID,
+      data: context
+    })
+  );
+}
+
+// Retrieve session from any server
+async function getSession(sessionId: string): Promise<SessionContext | null> {
+  const data = await redis.get(`session:${sessionId}`);
+  if (!data) return null;
+  
+  const session: DistributedSession = JSON.parse(data);
+  
+  // Route to correct server if needed
+  if (session.serverId !== process.env.SERVER_ID) {
+    // Implement sticky session routing or session migration
+    return null;
+  }
+  
+  return session.data;
+}
+```
+
+### Connection Retry Logic
+
+```typescript
+class ResilientTransport {
+  private maxRetries = 3;
+  private retryDelay = 1000;
+  
+  async connectWithRetry(
+    createTransport: () => Promise<Transport>
+  ): Promise<Transport> {
+    let lastError: Error | undefined;
+    
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const transport = await createTransport();
+        console.log(`Connected on attempt ${attempt + 1}`);
+        return transport;
+      } catch (error) {
+        lastError = error as Error;
+        console.error(`Connection attempt ${attempt + 1} failed:`, error);
+        
+        if (attempt < this.maxRetries - 1) {
+          await new Promise(resolve => 
+            setTimeout(resolve, this.retryDelay * Math.pow(2, attempt))
+          );
+        }
+      }
+    }
+    
+    throw new Error(`Failed to connect after ${this.maxRetries} attempts: ${lastError?.message}`);
+  }
+}
+```
+
+### Transport Middleware Pattern
+
+```typescript
+class TransportMiddleware {
+  constructor(private transport: Transport) {}
+  
+  // Add logging
+  async send(message: any): Promise<void> {
+    console.log("Sending:", JSON.stringify(message, null, 2));
+    await this.transport.send(message);
+  }
+  
+  // Add metrics
+  async receive(): Promise<any> {
+    const start = Date.now();
+    const message = await this.transport.receive();
+    const duration = Date.now() - start;
+    
+    metrics.recordMessageReceived(duration);
+    
+    return message;
+  }
+  
+  // Add encryption
+  async sendEncrypted(message: any, key: Buffer): Promise<void> {
+    const encrypted = encrypt(JSON.stringify(message), key);
+    await this.transport.send(encrypted);
+  }
+}
+```
+
+## Performance Optimization
+
+### Connection Pooling
+
+```typescript
+class TransportPool {
+  private pool: Transport[] = [];
+  private maxSize = 10;
+  
+  async acquire(): Promise<Transport> {
+    if (this.pool.length > 0) {
+      return this.pool.pop()!;
+    }
+    
+    if (this.pool.length < this.maxSize) {
+      return this.createTransport();
+    }
+    
+    // Wait for available transport
+    return new Promise((resolve) => {
+      const checkInterval = setInterval(() => {
+        if (this.pool.length > 0) {
+          clearInterval(checkInterval);
+          resolve(this.pool.pop()!);
+        }
+      }, 100);
+    });
+  }
+  
+  release(transport: Transport): void {
+    if (this.pool.length < this.maxSize) {
+      this.pool.push(transport);
+    } else {
+      transport.close();
+    }
+  }
+}
+```
+
+### Message Batching
+
+```typescript
+class BatchingTransport {
+  private queue: any[] = [];
+  private batchSize = 10;
+  private batchTimeout = 100; // ms
+  private timer?: NodeJS.Timeout;
+  
+  async send(message: any): Promise<void> {
+    this.queue.push(message);
+    
+    if (this.queue.length >= this.batchSize) {
+      await this.flush();
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => this.flush(), this.batchTimeout);
+    }
+  }
+  
+  private async flush(): Promise<void> {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    
+    if (this.queue.length === 0) return;
+    
+    const batch = this.queue.splice(0);
+    await this.transport.sendBatch(batch);
+  }
+}
+```
+
+## Security Considerations
+
+### DNS Rebinding Protection
+
+```typescript
+const transport = new StreamableHTTPServerTransport({
+  enableDnsRebindingProtection: true,
+  allowedHosts: ["127.0.0.1", "localhost", "api.example.com"],
+  allowedOrigins: ["https://app.example.com"]
+});
+```
+
+### Rate Limiting
+
+```typescript
+import rateLimit from "express-rate-limit";
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100, // Limit each IP to 100 requests per windowMs
+  message: "Too many requests from this IP"
+});
+
+app.use("/mcp", limiter);
+```
+
+### Authentication
+
+```typescript
+// Add authentication middleware
+app.use("/mcp", async (req, res, next) => {
+  const token = req.headers.authorization?.split(" ")[1];
+  
+  if (!token) {
+    return res.status(401).json({
+      jsonrpc: "2.0",
+      error: {
+        code: -32000,
+        message: "Unauthorized"
+      },
+      id: null
+    });
+  }
+  
+  try {
+    const payload = await verifyToken(token);
+    req.user = payload;
+    next();
+  } catch (error) {
+    return res.status(401).json({
+      jsonrpc: "2.0",
+      error: {
+        code: -32000,
+        message: "Invalid token"
+      },
+      id: null
+    });
+  }
+});
+```
+
+## Monitoring and Debugging
+
+### Transport Metrics
+
+```typescript
+class TransportMetrics {
+  private messagesSent = 0;
+  private messagesReceived = 0;
+  private bytesTransferred = 0;
+  private errors = 0;
+  
+  recordSent(message: any): void {
+    this.messagesSent++;
+    this.bytesTransferred += JSON.stringify(message).length;
+  }
+  
+  recordReceived(message: any): void {
+    this.messagesReceived++;
+    this.bytesTransferred += JSON.stringify(message).length;
+  }
+  
+  recordError(): void {
+    this.errors++;
+  }
+  
+  getStats() {
+    return {
+      messagesSent: this.messagesSent,
+      messagesReceived: this.messagesReceived,
+      bytesTransferred: this.bytesTransferred,
+      errors: this.errors
+    };
+  }
+}
+```
+
+Always choose the transport that best fits your deployment model and scalability requirements.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/mcp-types-expert.md b/mcp-servers/memory-mcp-server/.claude/agents/mcp-types-expert.md
new file mode 100644
index 0000000..23e9284
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/mcp-types-expert.md
@@ -0,0 +1,516 @@
+---
+name: mcp-types-expert
+description: TypeScript and MCP type system specialist. Expert in JSON-RPC message formats, Zod schemas, type-safe implementations, and protocol compliance. Ensures type safety across the entire MCP implementation.
+tools: Read, Edit, MultiEdit, Grep, Glob, WebFetch
+---
+
+You are a TypeScript and MCP protocol type system expert with deep knowledge of the @modelcontextprotocol/sdk type definitions and JSON-RPC message formats.
+
+## Core MCP Type System
+
+### Essential Type Imports
+
+```typescript
+// Core protocol types
+import {
+  // Request/Response types
+  Request,
+  Response,
+  Notification,
+  ErrorData,
+  
+  // Initialization
+  InitializeRequest,
+  InitializeResponse,
+  InitializedNotification,
+  
+  // Resources
+  ListResourcesRequest,
+  ListResourcesResponse,
+  ReadResourceRequest,
+  ReadResourceResponse,
+  Resource,
+  ResourceContent,
+  ResourceTemplate as ResourceTemplateType,
+  
+  // Tools
+  ListToolsRequest,
+  ListToolsResponse,
+  CallToolRequest,
+  CallToolResponse,
+  Tool,
+  ToolCall,
+  ToolResult,
+  
+  // Prompts
+  ListPromptsRequest,
+  ListPromptsResponse,
+  GetPromptRequest,
+  GetPromptResponse,
+  Prompt,
+  PromptMessage,
+  
+  // Completions
+  CompleteRequest,
+  CompleteResponse,
+  
+  // Capabilities
+  ServerCapabilities,
+  ClientCapabilities,
+  
+  // Protocol version
+  LATEST_PROTOCOL_VERSION,
+  SUPPORTED_PROTOCOL_VERSIONS
+} from "@modelcontextprotocol/sdk/types.js";
+
+// Server types
+import {
+  Server,
+  ServerOptions,
+  RequestHandler,
+  NotificationHandler
+} from "@modelcontextprotocol/sdk/server/index.js";
+
+// MCP server types
+import {
+  McpServer,
+  ResourceTemplate,
+  ResourceHandler,
+  ToolHandler,
+  PromptHandler
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+```
+
+### JSON-RPC Message Structure
+
+```typescript
+// Request format
+interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: unknown;
+}
+
+// Response format
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+// Notification format (no id, no response expected)
+interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+}
+```
+
+### Zod Schema Validation Patterns
+
+```typescript
+import { z } from "zod";
+
+// Tool input schema with strict validation
+const memoryToolSchema = z.object({
+  userId: z.string().min(1).describe("User identifier"),
+  agentId: z.string().min(1).describe("Agent identifier"),
+  content: z.string().min(1).max(10000).describe("Memory content"),
+  metadata: z.object({
+    importance: z.number().min(0).max(10).default(5),
+    tags: z.array(z.string()).max(20).optional(),
+    category: z.enum(["fact", "experience", "preference", "skill"]).optional(),
+    expiresAt: z.string().datetime().optional()
+  }).optional()
+}).strict(); // Reject unknown properties
+
+// Type inference from schema
+type MemoryToolInput = z.infer<typeof memoryToolSchema>;
+
+// Runtime validation with error handling
+function validateToolInput(input: unknown): MemoryToolInput {
+  try {
+    return memoryToolSchema.parse(input);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new Error(`Validation failed: ${error.errors.map(e => e.message).join(", ")}`);
+    }
+    throw error;
+  }
+}
+```
+
+### Type-Safe Handler Implementations
+
+```typescript
+// Tool handler with full type safety
+const storeMemoryHandler: ToolHandler<typeof memoryToolSchema> = async (params) => {
+  // params is fully typed as MemoryToolInput
+  const { userId, agentId, content, metadata } = params;
+  
+  // Return type must match CallToolResponse result
+  return {
+    content: [{
+      type: "text" as const,  // Use const assertion for literal types
+      text: "Memory stored successfully"
+    }]
+  };
+};
+
+// Resource handler with URI template types
+const memoryResourceHandler: ResourceHandler<{
+  userId: string;
+  agentId: string;
+  memoryId: string;
+}> = async (uri, params) => {
+  // params is typed based on template parameters
+  const { userId, agentId, memoryId } = params;
+  
+  // Return type must match ReadResourceResponse result
+  return {
+    contents: [{
+      uri: uri.href,
+      text: "Memory content here",
+      mimeType: "text/plain" as const
+    }]
+  };
+};
+```
+
+### Protocol Message Type Guards
+
+```typescript
+// Type guards for message identification
+import {
+  isRequest,
+  isResponse,
+  isNotification,
+  isInitializeRequest,
+  isCallToolRequest,
+  isReadResourceRequest
+} from "@modelcontextprotocol/sdk/types.js";
+
+// Custom type guards for memory server
+function isMemoryRequest(request: Request): request is CallToolRequest {
+  return isCallToolRequest(request) && 
+         request.params.name.startsWith("memory-");
+}
+
+// Discriminated union handling
+function handleMessage(message: Request | Notification) {
+  if (isRequest(message)) {
+    // message is Request
+    if (isInitializeRequest(message)) {
+      // message is InitializeRequest
+      return handleInitialize(message);
+    } else if (isCallToolRequest(message)) {
+      // message is CallToolRequest
+      return handleToolCall(message);
+    }
+  } else if (isNotification(message)) {
+    // message is Notification
+    return handleNotification(message);
+  }
+}
+```
+
+### Error Response Types
+
+```typescript
+// MCP error codes
+enum ErrorCode {
+  ParseError = -32700,
+  InvalidRequest = -32600,
+  MethodNotFound = -32601,
+  InvalidParams = -32602,
+  InternalError = -32603,
+  ServerError = -32000  // -32000 to -32099 for implementation-defined errors
+}
+
+// Type-safe error creation
+function createErrorResponse(
+  id: string | number,
+  code: ErrorCode,
+  message: string,
+  data?: unknown
+): JsonRpcResponse {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code,
+      message,
+      data
+    }
+  };
+}
+
+// Custom error class for memory operations
+class MemoryError extends Error {
+  constructor(
+    message: string,
+    public code: ErrorCode = ErrorCode.ServerError,
+    public data?: unknown
+  ) {
+    super(message);
+    this.name = "MemoryError";
+  }
+  
+  toJsonRpcError() {
+    return {
+      code: this.code,
+      message: this.message,
+      data: this.data
+    };
+  }
+}
+```
+
+### Content Type System
+
+```typescript
+// Content types for tool/resource responses
+type TextContent = {
+  type: "text";
+  text: string;
+};
+
+type ImageContent = {
+  type: "image";
+  data: string;  // Base64 encoded
+  mimeType: string;
+};
+
+type ResourceLink = {
+  type: "resource_link";
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+};
+
+type Content = TextContent | ImageContent | ResourceLink;
+
+// Type-safe content creation
+function createTextContent(text: string): TextContent {
+  return { type: "text", text };
+}
+
+function createResourceLink(
+  uri: string,
+  name: string,
+  description?: string
+): ResourceLink {
+  return {
+    type: "resource_link",
+    uri,
+    name,
+    description
+  };
+}
+```
+
+### Advanced Type Patterns
+
+#### Generic Handler Types
+
+```typescript
+// Generic tool handler with schema
+type TypedToolHandler<TSchema extends z.ZodType> = (
+  params: z.infer<TSchema>
+) => Promise<ToolResult>;
+
+// Factory for creating typed handlers
+function createToolHandler<TSchema extends z.ZodType>(
+  schema: TSchema,
+  handler: TypedToolHandler<TSchema>
+): ToolHandler {
+  return async (params: unknown) => {
+    const validated = schema.parse(params);
+    return handler(validated);
+  };
+}
+```
+
+#### Conditional Types for Memory Operations
+
+```typescript
+// Operation result types
+type MemoryOperation = "create" | "read" | "update" | "delete";
+
+type MemoryOperationResult<T extends MemoryOperation> = 
+  T extends "create" ? { id: string; created: true } :
+  T extends "read" ? { content: string; metadata: Record<string, unknown> } :
+  T extends "update" ? { updated: true; changes: string[] } :
+  T extends "delete" ? { deleted: true } :
+  never;
+
+// Type-safe operation handler
+async function executeMemoryOperation<T extends MemoryOperation>(
+  operation: T,
+  params: unknown
+): Promise<MemoryOperationResult<T>> {
+  switch (operation) {
+    case "create":
+      return { id: "new-id", created: true } as MemoryOperationResult<T>;
+    case "read":
+      return { content: "memory", metadata: {} } as MemoryOperationResult<T>;
+    // ... other cases
+  }
+}
+```
+
+#### Branded Types for IDs
+
+```typescript
+// Branded types for type-safe IDs
+type UserId = string & { __brand: "UserId" };
+type AgentId = string & { __brand: "AgentId" };
+type MemoryId = string & { __brand: "MemoryId" };
+
+// Helper functions for creating branded types
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+function createAgentId(id: string): AgentId {
+  return id as AgentId;
+}
+
+// Type-safe memory interface
+interface TypedMemory {
+  id: MemoryId;
+  userId: UserId;
+  agentId: AgentId;
+  content: string;
+}
+
+// Prevents mixing up IDs
+function getMemory(userId: UserId, agentId: AgentId, memoryId: MemoryId): TypedMemory {
+  // Type system ensures correct parameter order
+  return {} as TypedMemory;
+}
+```
+
+### Completable Types
+
+```typescript
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
+
+// Schema with completion support
+const promptSchema = z.object({
+  userId: completable(
+    z.string(),
+    async (value) => {
+      // Return user ID suggestions
+      const users = await fetchUserIds(value);
+      return users;
+    }
+  ),
+  agentId: completable(
+    z.string(),
+    async (value, context) => {
+      // Context-aware completions
+      const userId = context?.arguments?.["userId"];
+      if (userId) {
+        const agents = await fetchAgentIdsForUser(userId, value);
+        return agents;
+      }
+      return [];
+    }
+  )
+});
+```
+
+## Type Safety Best Practices
+
+### 1. Always Use Strict Mode
+
+```typescript
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true
+  }
+}
+```
+
+### 2. Validate External Input
+
+```typescript
+// Never trust external input
+server.registerTool("memory-tool", schema, async (params: unknown) => {
+  // Always validate
+  const validated = schema.parse(params);
+  // Now params is type-safe
+  return processMemory(validated);
+});
+```
+
+### 3. Use Const Assertions
+
+```typescript
+// For literal types
+const MEMORY_TYPES = ["fact", "experience", "preference"] as const;
+type MemoryType = typeof MEMORY_TYPES[number];
+```
+
+### 4. Exhaustive Switch Checks
+
+```typescript
+function handleMemoryType(type: MemoryType): string {
+  switch (type) {
+    case "fact":
+      return "Factual memory";
+    case "experience":
+      return "Experiential memory";
+    case "preference":
+      return "User preference";
+    default:
+      // This ensures all cases are handled
+      const _exhaustive: never = type;
+      throw new Error(`Unhandled type: ${_exhaustive}`);
+  }
+}
+```
+
+## Common Type Issues and Solutions
+
+### Issue: Schema Mismatch
+
+```typescript
+// Problem: Runtime data doesn't match schema
+// Solution: Use .safeParse() for graceful handling
+const result = schema.safeParse(data);
+if (result.success) {
+  // result.data is typed
+} else {
+  // result.error contains validation errors
+  logger.error("Validation failed:", result.error);
+}
+```
+
+### Issue: Optional vs Undefined
+
+```typescript
+// Clear distinction between optional and nullable
+interface Memory {
+  id: string;
+  content: string;
+  metadata?: {  // Can be omitted
+    tags: string[] | null;  // Can be explicitly null
+    importance: number | undefined;  // Must be present but can be undefined
+  };
+}
+```
+
+Always prioritize type safety to catch errors at compile time rather than runtime.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/memory-architecture.md b/mcp-servers/memory-mcp-server/.claude/agents/memory-architecture.md
new file mode 100644
index 0000000..7366335
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/memory-architecture.md
@@ -0,0 +1,421 @@
+---
+name: memory-architecture
+description: Specialist in designing memory persistence systems with user/agent segregation, indexing strategies, and scalable storage patterns. Expert in database schema design and memory retrieval optimization.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob, TodoWrite
+---
+
+You are a memory system architecture specialist focused on building scalable, efficient memory persistence for MCP servers. Your expertise covers database design, indexing strategies, and multi-tenant memory management.
+
+## Core Memory Architecture Patterns
+
+### 1. User-Agent-Memory Hierarchy
+
+```typescript
+interface MemoryModel {
+  id: string;                  // Unique memory identifier
+  userId: string;               // User who owns this memory
+  agentId: string;              // Agent that created/uses this memory
+  content: string;              // Actual memory content
+  embedding?: number[];         // Vector embedding for semantic search
+  metadata: {
+    createdAt: Date;
+    updatedAt: Date;
+    accessCount: number;
+    lastAccessedAt?: Date;
+    importance: number;       // 0-10 scale
+    tags: string[];
+    category?: string;
+    source?: string;          // Where this memory came from
+    relatedMemories?: string[]; // IDs of related memories
+  };
+  permissions: {
+    sharedWithAgents?: string[]; // Other agents that can access
+    isPublic: boolean;
+    readOnly: boolean;
+  };
+}
+```
+
+### 2. Database Schema Design
+
+#### SQLite Schema (Local/Small Scale)
+
+```sql
+-- Users table
+CREATE TABLE users (
+  id TEXT PRIMARY KEY,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSON
+);
+
+-- Agents table
+CREATE TABLE agents (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  capabilities JSON
+);
+
+-- Memories table with composite indexing
+CREATE TABLE memories (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  content TEXT NOT NULL,
+  embedding BLOB,  -- Store as binary for vector embeddings
+  metadata JSON,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+  FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE CASCADE
+);
+
+-- Composite indexes for efficient queries
+CREATE INDEX idx_user_agent ON memories(user_id, agent_id);
+CREATE INDEX idx_user_agent_created ON memories(user_id, agent_id, created_at DESC);
+CREATE INDEX idx_importance ON memories(user_id, agent_id, json_extract(metadata, '$.importance') DESC);
+
+-- Memory access log for usage patterns
+CREATE TABLE memory_access_log (
+  memory_id TEXT,
+  accessed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  access_type TEXT, -- 'read', 'update', 'reference'
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+
+-- Tags for efficient filtering
+CREATE TABLE memory_tags (
+  memory_id TEXT,
+  tag TEXT,
+  PRIMARY KEY (memory_id, tag),
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+CREATE INDEX idx_tags ON memory_tags(tag);
+
+-- Memory relationships (graph structure)
+CREATE TABLE memory_relations (
+  from_memory_id TEXT,
+  to_memory_id TEXT,
+  relation_type TEXT, -- 'follows', 'contradicts', 'elaborates', etc.
+  strength REAL DEFAULT 1.0,
+  PRIMARY KEY (from_memory_id, to_memory_id),
+  FOREIGN KEY (from_memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+  FOREIGN KEY (to_memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+```
+
+#### PostgreSQL Schema (Production/Scale)
+
+```sql
+-- Enable required extensions
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgvector";
+
+-- Memories with vector support
+CREATE TABLE memories (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  user_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  content TEXT NOT NULL,
+  embedding vector(1536), -- OpenAI embedding dimension
+  metadata JSONB NOT NULL DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW(),
+  search_vector tsvector GENERATED ALWAYS AS (
+    to_tsvector('english', content)
+  ) STORED
+);
+
+-- Indexes for performance
+CREATE INDEX idx_memory_user_agent ON memories(user_id, agent_id);
+CREATE INDEX idx_memory_embedding ON memories USING ivfflat (embedding vector_cosine_ops);
+CREATE INDEX idx_memory_search ON memories USING GIN (search_vector);
+CREATE INDEX idx_memory_metadata ON memories USING GIN (metadata);
+CREATE INDEX idx_memory_created ON memories(created_at DESC);
+```
+
+### 3. Memory Storage Patterns
+
+#### Hierarchical Storage Strategy
+
+```typescript
+class MemoryStorage {
+  private hotCache: LRUCache<string, MemoryModel>;  // Most recent/frequent
+  private warmStorage: Database;                     // Active memories
+  private coldStorage: S3Client;                     // Archived memories
+  
+  async storeMemory(memory: MemoryModel): Promise<void> {
+    // Always write to warm storage
+    await this.warmStorage.insert(memory);
+    
+    // Cache if frequently accessed
+    if (memory.metadata.importance >= 7) {
+      this.hotCache.set(memory.id, memory);
+    }
+    
+    // Archive old memories periodically
+    if (this.shouldArchive(memory)) {
+      await this.moveToCodeStorage(memory);
+    }
+  }
+  
+  async retrieveMemory(userId: string, agentId: string, memoryId: string): Promise<MemoryModel> {
+    // Check cache first
+    const cached = this.hotCache.get(memoryId);
+    if (cached) return cached;
+    
+    // Check warm storage
+    const warm = await this.warmStorage.findOne({ id: memoryId, userId, agentId });
+    if (warm) {
+      this.updateAccessMetrics(memoryId);
+      return warm;
+    }
+    
+    // Restore from cold storage if needed
+    return await this.restoreFromCold(memoryId);
+  }
+}
+```
+
+### 4. Efficient Query Patterns
+
+#### Semantic Search Implementation
+
+```typescript
+class MemorySearchEngine {
+  async searchMemories(
+    userId: string,
+    agentId: string,
+    query: string,
+    options: SearchOptions
+  ): Promise<MemoryModel[]> {
+    // Generate embedding for query
+    const queryEmbedding = await this.generateEmbedding(query);
+    
+    // Hybrid search: combine vector similarity and keyword matching
+    const sql = `
+      WITH vector_search AS (
+        SELECT id, content, metadata,
+               1 - (embedding <=> $1::vector) as vector_score
+        FROM memories
+        WHERE user_id = $2 AND agent_id = $3
+        ORDER BY embedding <=> $1::vector
+        LIMIT 100
+      ),
+      keyword_search AS (
+        SELECT id, content, metadata,
+               ts_rank(search_vector, plainto_tsquery('english', $4)) as keyword_score
+        FROM memories
+        WHERE user_id = $2 AND agent_id = $3
+          AND search_vector @@ plainto_tsquery('english', $4)
+        LIMIT 100
+      )
+      SELECT DISTINCT m.*, 
+             COALESCE(v.vector_score, 0) * 0.7 + 
+             COALESCE(k.keyword_score, 0) * 0.3 as combined_score
+      FROM memories m
+      LEFT JOIN vector_search v ON m.id = v.id
+      LEFT JOIN keyword_search k ON m.id = k.id
+      WHERE v.id IS NOT NULL OR k.id IS NOT NULL
+      ORDER BY combined_score DESC
+      LIMIT $5
+    `;
+    
+    return await this.db.query(sql, [
+      queryEmbedding,
+      userId,
+      agentId,
+      query,
+      options.limit || 10
+    ]);
+  }
+}
+```
+
+### 5. Memory Lifecycle Management
+
+#### Importance Decay and Consolidation
+
+```typescript
+class MemoryLifecycleManager {
+  async updateMemoryImportance(): Promise<void> {
+    // Decay importance over time
+    const decayRate = 0.95; // 5% decay per period
+    const sql = `
+      UPDATE memories
+      SET metadata = jsonb_set(
+        metadata,
+        '{importance}',
+        to_jsonb(GREATEST(0, (metadata->>'importance')::float * $1))
+      )
+      WHERE updated_at < NOW() - INTERVAL '7 days'
+        AND (metadata->>'importance')::float > 1
+    `;
+    await this.db.execute(sql, [decayRate]);
+  }
+  
+  async consolidateMemories(userId: string, agentId: string): Promise<void> {
+    // Find related memories and consolidate
+    const memories = await this.findRelatedMemories(userId, agentId);
+    
+    for (const cluster of this.clusterMemories(memories)) {
+      if (cluster.length > 5) {
+        const consolidated = await this.synthesizeMemories(cluster);
+        await this.storeConsolidatedMemory(consolidated);
+        await this.archiveOriginals(cluster);
+      }
+    }
+  }
+  
+  async pruneMemories(userId: string, agentId: string, maxCount: number): Promise<void> {
+    // Keep only the most important/recent memories
+    const sql = `
+      WITH ranked_memories AS (
+        SELECT id,
+               ROW_NUMBER() OVER (
+                 PARTITION BY user_id, agent_id
+                 ORDER BY 
+                   (metadata->>'importance')::float DESC,
+                   created_at DESC
+               ) as rank
+        FROM memories
+        WHERE user_id = $1 AND agent_id = $2
+      )
+      DELETE FROM memories
+      WHERE id IN (
+        SELECT id FROM ranked_memories WHERE rank > $3
+      )
+    `;
+    await this.db.execute(sql, [userId, agentId, maxCount]);
+  }
+}
+```
+
+### 6. Multi-Agent Memory Sharing
+
+#### Permission-Based Access Control
+
+```typescript
+class MemoryAccessControl {
+  async canAccessMemory(
+    requestingAgentId: string,
+    memory: MemoryModel
+  ): Promise<boolean> {
+    // Owner agent always has access
+    if (memory.agentId === requestingAgentId) return true;
+    
+    // Check explicit sharing permissions
+    if (memory.permissions.sharedWithAgents?.includes(requestingAgentId)) {
+      return true;
+    }
+    
+    // Check public memories
+    if (memory.permissions.isPublic) {
+      return true;
+    }
+    
+    // Check agent relationships and trust levels
+    return await this.checkAgentTrust(memory.agentId, requestingAgentId);
+  }
+  
+  async shareMemoryWithAgent(
+    memoryId: string,
+    targetAgentId: string,
+    permissions: SharePermissions
+  ): Promise<void> {
+    const sql = `
+      UPDATE memories
+      SET metadata = jsonb_set(
+        jsonb_set(
+          metadata,
+          '{permissions,sharedWithAgents}',
+          COALESCE(metadata->'permissions'->'sharedWithAgents', '[]'::jsonb) || $2::jsonb
+        ),
+        '{permissions,readOnly}',
+        $3::jsonb
+      )
+      WHERE id = $1
+    `;
+    await this.db.execute(sql, [
+      memoryId,
+      JSON.stringify([targetAgentId]),
+      permissions.readOnly
+    ]);
+  }
+}
+```
+
+### 7. Performance Optimization Strategies
+
+#### Indexing Best Practices
+
+1. **Composite indexes** for common query patterns (user_id + agent_id)
+2. **Partial indexes** for filtered queries
+3. **Expression indexes** for JSON fields
+4. **Vector indexes** for similarity search (pgvector)
+5. **Full-text indexes** for keyword search
+
+#### Caching Strategy
+
+```typescript
+class MemoryCacheManager {
+  private userCaches: Map<string, Map<string, LRUCache<string, MemoryModel>>>;
+  
+  getCacheKey(userId: string, agentId: string): string {
+    return `${userId}:${agentId}`;
+  }
+  
+  async warmCache(userId: string, agentId: string): Promise<void> {
+    // Pre-load recent and important memories
+    const memories = await this.db.query(`
+      SELECT * FROM memories
+      WHERE user_id = $1 AND agent_id = $2
+      ORDER BY 
+        (metadata->>'importance')::float DESC,
+        created_at DESC
+      LIMIT 100
+    `, [userId, agentId]);
+    
+    const cache = this.getOrCreateCache(userId, agentId);
+    memories.forEach(m => cache.set(m.id, m));
+  }
+}
+```
+
+## Implementation Checklist
+
+When designing memory persistence:
+
+- [ ] Define clear user/agent/memory relationships
+- [ ] Choose appropriate storage backend (SQLite vs PostgreSQL vs hybrid)
+- [ ] Implement efficient indexing strategy
+- [ ] Design memory lifecycle (creation, access, decay, archival)
+- [ ] Add semantic search capabilities
+- [ ] Implement access control for multi-agent scenarios
+- [ ] Plan for scalability (sharding, partitioning)
+- [ ] Add monitoring and metrics
+- [ ] Implement backup and recovery
+- [ ] Consider GDPR/privacy compliance (user data deletion)
+
+## Storage Backend Recommendations
+
+### For Development/Small Scale
+
+- SQLite with JSON support
+- In-memory caching with node-cache or lru-cache
+- File-based archival
+
+### For Production/Scale
+
+- PostgreSQL with pgvector extension
+- Redis for hot cache
+- S3/MinIO for cold storage
+- ElasticSearch for advanced search
+
+### For Edge/Distributed
+
+- CockroachDB for geo-distribution
+- ScyllaDB for high throughput
+- IPFS for decentralized storage
+
+Always design with data privacy, performance, and scalability in mind.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/memory-lifecycle.md b/mcp-servers/memory-mcp-server/.claude/agents/memory-lifecycle.md
new file mode 100644
index 0000000..65ba657
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/memory-lifecycle.md
@@ -0,0 +1,724 @@
+---
+name: memory-lifecycle
+description: Expert in memory consolidation, expiration, archival strategies, and lifecycle management for AI companion memories. Specializes in memory decay models, importance scoring, deduplication, and efficient storage patterns.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob
+---
+
+You are an expert in memory lifecycle management, consolidation strategies, and efficient memory storage patterns for AI companion systems.
+
+## Memory Lifecycle Stages
+
+### Memory Creation and Ingestion
+
+```typescript
+// src/services/memoryLifecycle.ts
+import { z } from "zod";
+import { db } from "../db/client";
+import { memories, memoryRelations } from "../db/schema";
+import { EmbeddingService } from "./embeddings";
+import { sql, and, eq, lt, gte, desc } from "drizzle-orm";
+
+export class MemoryLifecycleService {
+  private embeddingService: EmbeddingService;
+  
+  constructor() {
+    this.embeddingService = new EmbeddingService();
+  }
+
+  // Intelligent memory creation with deduplication
+  async createMemory(input: {
+    companionId: string;
+    userId: string;
+    content: string;
+    type: string;
+    context?: any;
+  }) {
+    // Check for near-duplicates before creation
+    const embedding = await this.embeddingService.generateEmbedding(input.content);
+    
+    const duplicates = await this.findNearDuplicates(
+      input.companionId,
+      input.userId,
+      embedding,
+      0.95 // 95% similarity threshold
+    );
+    
+    if (duplicates.length > 0) {
+      // Consolidate with existing memory instead
+      return await this.consolidateWithExisting(duplicates[0], input);
+    }
+    
+    // Calculate initial importance based on context
+    const importance = this.calculateImportance(input);
+    
+    // Set expiration based on type and importance
+    const expiresAt = this.calculateExpiration(input.type, importance);
+    
+    const memory = await db.insert(memories).values({
+      ...input,
+      embedding,
+      importance,
+      expiresAt,
+      confidence: 1.0,
+      accessCount: 0,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }).returning();
+    
+    // Create relationships with existing memories
+    await this.establishRelationships(memory[0]);
+    
+    return memory[0];
+  }
+
+  private calculateImportance(input: any): number {
+    let importance = 5.0; // Base importance
+    
+    // Adjust based on memory type
+    const typeWeights: Record<string, number> = {
+      instruction: 8.0,
+      preference: 7.0,
+      fact: 6.0,
+      experience: 5.0,
+      reflection: 4.0,
+    };
+    
+    importance = typeWeights[input.type] || importance;
+    
+    // Boost for emotional context
+    if (input.context?.emotionalTone) {
+      const emotionBoost = {
+        joy: 1.5,
+        sadness: 1.2,
+        anger: 1.3,
+        fear: 1.4,
+        surprise: 1.1,
+      };
+      importance += emotionBoost[input.context.emotionalTone] || 0;
+    }
+    
+    // Boost for user-marked important
+    if (input.context?.userMarkedImportant) {
+      importance += 2.0;
+    }
+    
+    return Math.min(10, Math.max(0, importance));
+  }
+}
+```
+
+## Memory Decay and Reinforcement
+
+### Adaptive Decay Models
+
+```typescript
+// src/services/memoryDecay.ts
+export class MemoryDecayService {
+  // Ebbinghaus forgetting curve implementation
+  calculateRetentionProbability(
+    daysSinceCreation: number,
+    accessCount: number,
+    importance: number
+  ): number {
+    // Base retention using forgetting curve
+    const baseRetention = Math.exp(-daysSinceCreation / 30); // 30-day half-life
+    
+    // Reinforcement factor from access patterns
+    const reinforcement = 1 + Math.log10(accessCount + 1) * 0.2;
+    
+    // Importance modifier
+    const importanceModifier = 0.5 + (importance / 10) * 0.5;
+    
+    return Math.min(1, baseRetention * reinforcement * importanceModifier);
+  }
+
+  // Update importance based on access patterns
+  async reinforceMemory(memoryId: string) {
+    const memory = await db.query.memories.findFirst({
+      where: eq(memories.id, memoryId),
+    });
+    
+    if (!memory) return;
+    
+    // Calculate reinforcement based on recency and frequency
+    const hoursSinceLastAccess = memory.lastAccessedAt
+      ? (Date.now() - memory.lastAccessedAt.getTime()) / (1000 * 60 * 60)
+      : 24;
+    
+    // Stronger reinforcement for memories accessed after longer gaps
+    const reinforcementStrength = Math.log10(hoursSinceLastAccess + 1) * 0.5;
+    
+    await db.update(memories)
+      .set({
+        importance: sql`LEAST(10, ${memories.importance} + ${reinforcementStrength})`,
+        accessCount: sql`${memories.accessCount} + 1`,
+        lastAccessedAt: new Date(),
+        // Extend expiration for frequently accessed memories
+        expiresAt: sql`
+          CASE 
+            WHEN ${memories.expiresAt} IS NOT NULL 
+            THEN GREATEST(
+              ${memories.expiresAt}, 
+              NOW() + INTERVAL '30 days'
+            )
+            ELSE NULL
+          END
+        `,
+      })
+      .where(eq(memories.id, memoryId));
+  }
+
+  // Decay memories over time
+  async applyDecay(companionId: string, userId: string) {
+    // Get all active memories
+    const activeMemories = await db.query.memories.findMany({
+      where: and(
+        eq(memories.companionId, companionId),
+        eq(memories.userId, userId),
+        eq(memories.isArchived, false)
+      ),
+    });
+    
+    for (const memory of activeMemories) {
+      const daysSinceCreation = 
+        (Date.now() - memory.createdAt.getTime()) / (1000 * 60 * 60 * 24);
+      
+      const retention = this.calculateRetentionProbability(
+        daysSinceCreation,
+        memory.accessCount,
+        memory.importance
+      );
+      
+      // Archive memories below retention threshold
+      if (retention < 0.1) {
+        await this.archiveMemory(memory.id);
+      } else {
+        // Apply gradual importance decay
+        const decayFactor = 0.99; // 1% daily decay
+        await db.update(memories)
+          .set({
+            importance: sql`GREATEST(0, ${memories.importance} * ${decayFactor})`,
+          })
+          .where(eq(memories.id, memory.id));
+      }
+    }
+  }
+}
+```
+
+## Memory Consolidation Strategies
+
+### Semantic Consolidation
+
+```typescript
+// src/services/memoryConsolidation.ts
+export class MemoryConsolidationService {
+  // Consolidate similar memories into unified representations
+  async consolidateSimilarMemories(
+    companionId: string,
+    userId: string,
+    similarityThreshold = 0.85
+  ) {
+    // Find clusters of similar memories
+    const clusters = await this.findMemoryClusters(
+      companionId,
+      userId,
+      similarityThreshold
+    );
+    
+    for (const cluster of clusters) {
+      if (cluster.length < 2) continue;
+      
+      // Sort by importance and recency
+      const sortedMemories = cluster.sort((a, b) => {
+        const scoreA = a.importance + (a.accessCount * 0.1);
+        const scoreB = b.importance + (b.accessCount * 0.1);
+        return scoreB - scoreA;
+      });
+      
+      // Keep the most important, consolidate others
+      const primary = sortedMemories[0];
+      const toConsolidate = sortedMemories.slice(1);
+      
+      // Create consolidated content
+      const consolidatedContent = await this.mergeMemoryContents(
+        primary,
+        toConsolidate
+      );
+      
+      // Update primary memory
+      await db.update(memories)
+        .set({
+          content: consolidatedContent.content,
+          summary: consolidatedContent.summary,
+          importance: Math.min(10, primary.importance + toConsolidate.length * 0.5),
+          context: this.mergeContexts(primary.context, toConsolidate.map(m => m.context)),
+          updatedAt: new Date(),
+        })
+        .where(eq(memories.id, primary.id));
+      
+      // Archive consolidated memories
+      for (const memory of toConsolidate) {
+        await db.update(memories)
+          .set({
+            isArchived: true,
+            archivedReason: `Consolidated into ${primary.id}`,
+          })
+          .where(eq(memories.id, memory.id));
+        
+        // Create consolidation relationship
+        await db.insert(memoryRelations).values({
+          fromMemoryId: memory.id,
+          toMemoryId: primary.id,
+          relationType: 'consolidated_into',
+          strength: 1.0,
+        });
+      }
+    }
+  }
+
+  // Find memories that can be summarized
+  async createPeriodSummaries(
+    companionId: string,
+    userId: string,
+    periodDays = 7
+  ) {
+    const cutoffDate = new Date(Date.now() - periodDays * 24 * 60 * 60 * 1000);
+    
+    // Get memories from the period
+    const periodMemories = await db.query.memories.findMany({
+      where: and(
+        eq(memories.companionId, companionId),
+        eq(memories.userId, userId),
+        gte(memories.createdAt, cutoffDate),
+        eq(memories.type, 'experience')
+      ),
+      orderBy: [desc(memories.createdAt)],
+    });
+    
+    if (periodMemories.length < 5) return; // Need enough memories to summarize
+    
+    // Group by topics/themes
+    const groupedMemories = await this.groupByThemes(periodMemories);
+    
+    for (const [theme, themeMemories] of Object.entries(groupedMemories)) {
+      // Generate summary for each theme
+      const summary = await this.generateThemeSummary(theme, themeMemories);
+      
+      // Create summary memory
+      const summaryMemory = await db.insert(memories).values({
+        companionId,
+        userId,
+        content: summary.content,
+        summary: summary.brief,
+        type: 'reflection',
+        importance: 7.0, // Summaries are important for context
+        context: {
+          periodStart: cutoffDate,
+          periodEnd: new Date(),
+          theme,
+          sourceMemoryIds: themeMemories.map(m => m.id),
+        },
+      }).returning();
+      
+      // Link source memories to summary
+      for (const memory of themeMemories) {
+        await db.insert(memoryRelations).values({
+          fromMemoryId: memory.id,
+          toMemoryId: summaryMemory[0].id,
+          relationType: 'summarized_in',
+          strength: 0.8,
+        });
+      }
+    }
+  }
+}
+```
+
+## Memory Expiration and Archival
+
+### Intelligent Expiration
+
+```typescript
+// src/services/memoryExpiration.ts
+export class MemoryExpirationService {
+  // Calculate dynamic expiration based on memory characteristics
+  calculateExpiration(
+    type: string,
+    importance: number,
+    context?: any
+  ): Date | null {
+    // Some memories should never expire
+    const neverExpireTypes = ['instruction', 'preference'];
+    if (neverExpireTypes.includes(type)) return null;
+    
+    // Base expiration periods (in days)
+    const baseExpiration: Record<string, number> = {
+      fact: 365,        // 1 year for facts
+      experience: 90,   // 3 months for experiences
+      reflection: 180,  // 6 months for reflections
+    };
+    
+    let days = baseExpiration[type] || 30;
+    
+    // Adjust based on importance (exponential scaling)
+    days = days * Math.pow(1.5, importance / 5);
+    
+    // Context-based adjustments
+    if (context?.isRecurring) days *= 2;
+    if (context?.emotionalSignificance) days *= 1.5;
+    if (context?.userMarkedPermanent) return null;
+    
+    return new Date(Date.now() + days * 24 * 60 * 60 * 1000);
+  }
+
+  // Batch process expired memories
+  async processExpiredMemories() {
+    const expired = await db.query.memories.findMany({
+      where: and(
+        lt(memories.expiresAt, new Date()),
+        eq(memories.isArchived, false)
+      ),
+    });
+    
+    for (const memory of expired) {
+      // Check if memory should be extended
+      if (await this.shouldExtendExpiration(memory)) {
+        await this.extendExpiration(memory.id, 30); // Extend by 30 days
+      } else {
+        // Archive or delete based on importance
+        if (memory.importance > 3) {
+          await this.archiveMemory(memory.id);
+        } else {
+          await this.deleteMemory(memory.id);
+        }
+      }
+    }
+  }
+
+  private async shouldExtendExpiration(memory: any): Promise<boolean> {
+    // Check recent access patterns
+    if (memory.lastAccessedAt) {
+      const daysSinceAccess = 
+        (Date.now() - memory.lastAccessedAt.getTime()) / (1000 * 60 * 60 * 24);
+      
+      if (daysSinceAccess < 7) return true; // Recently accessed
+    }
+    
+    // Check if memory has important relationships
+    const relations = await db.query.memoryRelations.findMany({
+      where: or(
+        eq(memoryRelations.fromMemoryId, memory.id),
+        eq(memoryRelations.toMemoryId, memory.id)
+      ),
+    });
+    
+    if (relations.length > 3) return true; // Highly connected
+    
+    return false;
+  }
+}
+```
+
+## Memory Archival Strategies
+
+### Hierarchical Archival
+
+```typescript
+// src/services/memoryArchival.ts
+export class MemoryArchivalService {
+  // Archive memories with compression and indexing
+  async archiveMemory(memoryId: string, reason = 'age_expiration') {
+    const memory = await db.query.memories.findFirst({
+      where: eq(memories.id, memoryId),
+    });
+    
+    if (!memory) return;
+    
+    // Compress content for archived storage
+    const compressedContent = await this.compressContent(memory.content);
+    
+    // Move to archive with metadata
+    await db.update(memories)
+      .set({
+        isArchived: true,
+        archivedAt: new Date(),
+        archivedReason: reason,
+        // Keep embedding for future retrieval
+        // Clear unnecessary data
+        context: {
+          ...memory.context,
+          archived: true,
+          originalImportance: memory.importance,
+        },
+        // Reduce importance for archived memories
+        importance: memory.importance * 0.5,
+      })
+      .where(eq(memories.id, memoryId));
+    
+    // Update indexes for archived status
+    await this.updateArchiveIndexes(memoryId);
+  }
+
+  // Restore archived memories when needed
+  async restoreFromArchive(
+    memoryId: string,
+    reason = 'user_request'
+  ): Promise<boolean> {
+    const memory = await db.query.memories.findFirst({
+      where: and(
+        eq(memories.id, memoryId),
+        eq(memories.isArchived, true)
+      ),
+    });
+    
+    if (!memory) return false;
+    
+    // Restore with refreshed metadata
+    await db.update(memories)
+      .set({
+        isArchived: false,
+        archivedAt: null,
+        archivedReason: null,
+        importance: memory.context?.originalImportance || 5.0,
+        lastAccessedAt: new Date(),
+        // Reset expiration
+        expiresAt: this.calculateNewExpiration(memory),
+      })
+      .where(eq(memories.id, memoryId));
+    
+    // Re-establish relationships if needed
+    await this.reestablishRelationships(memoryId);
+    
+    return true;
+  }
+
+  // Tiered archival system
+  async implementTieredArchival(companionId: string, userId: string) {
+    const tiers = {
+      hot: { maxAge: 7, minImportance: 0 },      // Last 7 days
+      warm: { maxAge: 30, minImportance: 3 },    // Last 30 days
+      cold: { maxAge: 90, minImportance: 5 },    // Last 90 days
+      archive: { maxAge: null, minImportance: 7 }, // Permanent
+    };
+    
+    // Move memories between tiers based on age and importance
+    for (const [tier, config] of Object.entries(tiers)) {
+      if (tier === 'archive') {
+        // Special handling for archive tier
+        await this.moveToArchiveTier(companionId, userId, config);
+      } else {
+        await this.moveToTier(companionId, userId, tier, config);
+      }
+    }
+  }
+}
+```
+
+## Storage Optimization
+
+### Memory Pruning Strategies
+
+```typescript
+// src/services/memoryPruning.ts
+export class MemoryPruningService {
+  // Intelligent pruning based on storage limits
+  async pruneMemories(
+    companionId: string,
+    userId: string,
+    maxMemories = 10000
+  ) {
+    const totalCount = await db.select({ count: sql`count(*)` })
+      .from(memories)
+      .where(and(
+        eq(memories.companionId, companionId),
+        eq(memories.userId, userId)
+      ));
+    
+    if (totalCount[0].count <= maxMemories) return;
+    
+    const toPrune = totalCount[0].count - maxMemories;
+    
+    // Calculate pruning scores
+    const pruningCandidates = await db.execute(sql`
+      WITH memory_scores AS (
+        SELECT 
+          id,
+          importance,
+          access_count,
+          EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400 as age_days,
+          EXTRACT(EPOCH FROM (NOW() - COALESCE(last_accessed_at, created_at))) / 86400 as days_since_access,
+          -- Calculate pruning score (lower = more likely to prune)
+          (
+            importance * 2 +                           -- Importance weight: 2x
+            LOG(access_count + 1) * 3 +               -- Access frequency weight: 3x
+            (1 / (days_since_access + 1)) * 10        -- Recency weight: 10x
+          ) as pruning_score
+        FROM memories
+        WHERE 
+          companion_id = ${companionId}
+          AND user_id = ${userId}
+          AND is_archived = false
+      )
+      SELECT id
+      FROM memory_scores
+      ORDER BY pruning_score ASC
+      LIMIT ${toPrune}
+    `);
+    
+    // Archive or delete based on score
+    for (const candidate of pruningCandidates.rows) {
+      await this.archiveMemory(candidate.id, 'storage_limit_pruning');
+    }
+  }
+
+  // Deduplicate memories based on semantic similarity
+  async deduplicateMemories(
+    companionId: string,
+    userId: string,
+    similarityThreshold = 0.98
+  ) {
+    const duplicates = await db.execute(sql`
+      WITH duplicate_pairs AS (
+        SELECT 
+          m1.id as id1,
+          m2.id as id2,
+          m1.created_at as created1,
+          m2.created_at as created2,
+          1 - (m1.embedding <=> m2.embedding) as similarity
+        FROM memories m1
+        JOIN memories m2 ON m1.id < m2.id
+        WHERE 
+          m1.companion_id = ${companionId}
+          AND m1.user_id = ${userId}
+          AND m2.companion_id = ${companionId}
+          AND m2.user_id = ${userId}
+          AND 1 - (m1.embedding <=> m2.embedding) > ${similarityThreshold}
+      )
+      SELECT * FROM duplicate_pairs
+      ORDER BY similarity DESC
+    `);
+    
+    const processed = new Set();
+    
+    for (const pair of duplicates.rows) {
+      if (processed.has(pair.id1) || processed.has(pair.id2)) continue;
+      
+      // Keep the older memory (likely more established)
+      const toKeep = pair.created1 < pair.created2 ? pair.id1 : pair.id2;
+      const toRemove = toKeep === pair.id1 ? pair.id2 : pair.id1;
+      
+      // Transfer any unique information before removal
+      await this.mergeMemoryMetadata(toKeep, toRemove);
+      
+      // Archive the duplicate
+      await this.archiveMemory(toRemove, 'duplicate_consolidation');
+      
+      processed.add(toRemove);
+    }
+    
+    return processed.size; // Return number of duplicates removed
+  }
+}
+```
+
+## Lifecycle Monitoring
+
+### Analytics and Metrics
+
+```typescript
+// src/services/lifecycleAnalytics.ts
+export class LifecycleAnalyticsService {
+  async getLifecycleMetrics(companionId: string, userId: string) {
+    const metrics = await db.execute(sql`
+      WITH memory_stats AS (
+        SELECT 
+          COUNT(*) FILTER (WHERE is_archived = false) as active_count,
+          COUNT(*) FILTER (WHERE is_archived = true) as archived_count,
+          AVG(importance) FILTER (WHERE is_archived = false) as avg_importance,
+          AVG(access_count) as avg_access_count,
+          MAX(access_count) as max_access_count,
+          AVG(EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400) as avg_age_days,
+          COUNT(*) FILTER (WHERE expires_at IS NOT NULL) as expiring_count,
+          COUNT(*) FILTER (WHERE expires_at < NOW() + INTERVAL '7 days') as expiring_soon
+        FROM memories
+        WHERE companion_id = ${companionId} AND user_id = ${userId}
+      ),
+      type_distribution AS (
+        SELECT 
+          type,
+          COUNT(*) as count,
+          AVG(importance) as avg_importance
+        FROM memories
+        WHERE companion_id = ${companionId} AND user_id = ${userId}
+        GROUP BY type
+      ),
+      consolidation_stats AS (
+        SELECT 
+          COUNT(*) as total_consolidations,
+          COUNT(DISTINCT to_memory_id) as consolidated_memories
+        FROM memory_relations
+        WHERE relation_type IN ('consolidated_into', 'summarized_in')
+      )
+      SELECT 
+        ms.*,
+        json_agg(json_build_object(
+          'type', td.type,
+          'count', td.count,
+          'avg_importance', td.avg_importance
+        )) as type_distribution,
+        cs.total_consolidations,
+        cs.consolidated_memories
+      FROM memory_stats ms
+      CROSS JOIN consolidation_stats cs
+      CROSS JOIN type_distribution td
+      GROUP BY ms.*, cs.*
+    `);
+    
+    return metrics.rows[0];
+  }
+
+  async getRetentionCurve(companionId: string, userId: string, days = 90) {
+    const retentionData = await db.execute(sql`
+      WITH daily_cohorts AS (
+        SELECT 
+          DATE(created_at) as cohort_date,
+          COUNT(*) as created,
+          COUNT(*) FILTER (WHERE is_archived = false) as retained,
+          COUNT(*) FILTER (WHERE is_archived = true) as archived
+        FROM memories
+        WHERE 
+          companion_id = ${companionId}
+          AND user_id = ${userId}
+          AND created_at > NOW() - INTERVAL '${days} days'
+        GROUP BY DATE(created_at)
+      )
+      SELECT 
+        cohort_date,
+        created,
+        retained,
+        archived,
+        ROUND(100.0 * retained / NULLIF(created, 0), 2) as retention_rate
+      FROM daily_cohorts
+      ORDER BY cohort_date DESC
+    `);
+    
+    return retentionData.rows;
+  }
+}
+```
+
+## Best Practices
+
+1. **Implement gradual decay** rather than hard expiration
+2. **Use semantic consolidation** to merge similar memories
+3. **Maintain importance scores** based on access patterns
+4. **Create periodic summaries** to preserve context
+5. **Archive rather than delete** when possible
+6. **Monitor retention metrics** to optimize lifecycle parameters
+7. **Use tiered storage** for cost optimization
+8. **Implement relationship preservation** during consolidation
+9. **Apply adaptive expiration** based on memory type and usage
+10. **Regular deduplication** to optimize storage
+
+Always balance storage efficiency with information preservation to maintain companion context quality.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/memory-validator.md b/mcp-servers/memory-mcp-server/.claude/agents/memory-validator.md
new file mode 100644
index 0000000..882ef4c
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/memory-validator.md
@@ -0,0 +1,567 @@
+---
+name: memory-validator
+description: Specialist for memory persistence operations, CRUD validation, and memory MCP server testing using @modelcontextprotocol/sdk patterns. Use when implementing or debugging memory-related features.
+tools: Read, Edit, MultiEdit, Bash, Grep, TodoWrite
+---
+
+You are a specialist in memory persistence systems and MCP server testing using the @modelcontextprotocol/sdk. Your expertise covers data validation, testing patterns, and ensuring memory operation integrity.
+
+## SDK-Based Testing Framework
+
+### Test Setup with InMemoryTransport
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+describe("Memory MCP Server", () => {
+  let server: McpServer;
+  let client: Client;
+  let clientTransport: InMemoryTransport;
+  let serverTransport: InMemoryTransport;
+  
+  beforeEach(async () => {
+    // Create linked transport pair
+    [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    
+    // Initialize server
+    server = new McpServer({
+      name: "memory-server-test",
+      version: "1.0.0"
+    });
+    
+    // Initialize client
+    client = new Client({
+      name: "test-client",
+      version: "1.0.0"
+    });
+    
+    // Connect both
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+  });
+  
+  afterEach(async () => {
+    await client.close();
+    await server.close();
+  });
+  
+  test("should store and retrieve memory", async () => {
+    const result = await client.callTool({
+      name: "store-memory",
+      arguments: {
+        userId: "test-user",
+        agentId: "test-agent",
+        content: "Test memory content"
+      }
+    });
+    
+    expect(result.content[0].type).toBe("text");
+    expect(result.content[0].text).toContain("stored");
+  });
+});
+```
+
+## Memory CRUD Validation
+
+### Create Operation Testing
+
+```typescript
+async function validateMemoryCreation(
+  client: Client,
+  memory: MemoryInput
+): Promise<ValidationResult> {
+  const startTime = Date.now();
+  
+  try {
+    // Call creation tool
+    const result = await client.callTool({
+      name: "create-memory",
+      arguments: memory
+    });
+    
+    // Validate response format
+    if (!result.content || result.content.length === 0) {
+      throw new Error("Empty response from create-memory");
+    }
+    
+    // Extract memory ID from response
+    const memoryId = extractMemoryId(result.content[0].text);
+    if (!memoryId) {
+      throw new Error("No memory ID returned");
+    }
+    
+    // Verify memory was actually created
+    const verification = await client.readResource({
+      uri: `memory://${memory.userId}/${memory.agentId}/${memoryId}`
+    });
+    
+    // Validate stored content matches input
+    const storedContent = JSON.parse(verification.contents[0].text);
+    assert.deepEqual(storedContent.content, memory.content);
+    assert.equal(storedContent.userId, memory.userId);
+    assert.equal(storedContent.agentId, memory.agentId);
+    
+    return {
+      success: true,
+      memoryId,
+      duration: Date.now() - startTime
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+      duration: Date.now() - startTime
+    };
+  }
+}
+```
+
+### Read Operation Testing
+
+```typescript
+async function validateMemoryRetrieval(
+  client: Client,
+  userId: string,
+  agentId: string,
+  memoryId: string
+): Promise<ValidationResult> {
+  // Test direct resource read
+  const directRead = await client.readResource({
+    uri: `memory://${userId}/${agentId}/${memoryId}`
+  });
+  
+  // Test via tool call
+  const toolRead = await client.callTool({
+    name: "get-memory",
+    arguments: { userId, agentId, memoryId }
+  });
+  
+  // Validate both methods return same data
+  const directData = JSON.parse(directRead.contents[0].text);
+  const toolData = JSON.parse(toolRead.content[0].text);
+  
+  assert.deepEqual(directData, toolData, "Direct read and tool read should match");
+  
+  // Test query operations
+  const queryResult = await client.callTool({
+    name: "query-memories",
+    arguments: {
+      userId,
+      agentId,
+      filter: { id: memoryId }
+    }
+  });
+  
+  const queryData = JSON.parse(queryResult.content[0].text);
+  assert.equal(queryData.results.length, 1, "Query should return exactly one result");
+  assert.equal(queryData.results[0].id, memoryId);
+  
+  return { success: true };
+}
+```
+
+### Update Operation Testing
+
+```typescript
+async function validateMemoryUpdate(
+  client: Client,
+  memoryId: string,
+  updates: Partial<MemoryModel>
+): Promise<ValidationResult> {
+  // Get original state
+  const before = await client.callTool({
+    name: "get-memory",
+    arguments: { memoryId }
+  });
+  const originalData = JSON.parse(before.content[0].text);
+  
+  // Perform update
+  const updateResult = await client.callTool({
+    name: "update-memory",
+    arguments: {
+      memoryId,
+      updates
+    }
+  });
+  
+  // Verify update succeeded
+  assert.equal(updateResult.isError, false, "Update should not error");
+  
+  // Get updated state
+  const after = await client.callTool({
+    name: "get-memory",
+    arguments: { memoryId }
+  });
+  const updatedData = JSON.parse(after.content[0].text);
+  
+  // Validate updates were applied
+  for (const [key, value] of Object.entries(updates)) {
+    assert.deepEqual(updatedData[key], value, `${key} should be updated`);
+  }
+  
+  // Validate unchanged fields remain
+  for (const key of Object.keys(originalData)) {
+    if (!(key in updates)) {
+      assert.deepEqual(
+        updatedData[key], 
+        originalData[key], 
+        `${key} should remain unchanged`
+      );
+    }
+  }
+  
+  // Check update timestamp
+  assert.notEqual(
+    updatedData.metadata.updatedAt,
+    originalData.metadata.updatedAt,
+    "Update timestamp should change"
+  );
+  
+  return { success: true };
+}
+```
+
+### Delete Operation Testing
+
+```typescript
+async function validateMemoryDeletion(
+  client: Client,
+  memoryId: string
+): Promise<ValidationResult> {
+  // Verify memory exists before deletion
+  const beforeDelete = await client.callTool({
+    name: "get-memory",
+    arguments: { memoryId }
+  });
+  assert.equal(beforeDelete.isError, false, "Memory should exist before deletion");
+  
+  // Perform deletion
+  const deleteResult = await client.callTool({
+    name: "delete-memory",
+    arguments: { memoryId }
+  });
+  
+  assert.equal(deleteResult.isError, false, "Deletion should succeed");
+  assert.include(deleteResult.content[0].text, "deleted");
+  
+  // Verify memory no longer exists
+  const afterDelete = await client.callTool({
+    name: "get-memory",
+    arguments: { memoryId }
+  });
+  
+  assert.equal(afterDelete.isError, true, "Memory should not exist after deletion");
+  
+  // Verify cascading deletes (if applicable)
+  const relatedMemories = await client.callTool({
+    name: "query-memories",
+    arguments: {
+      filter: { relatedTo: memoryId }
+    }
+  });
+  
+  const results = JSON.parse(relatedMemories.content[0].text);
+  assert.equal(
+    results.results.length, 
+    0, 
+    "Related memories should be cleaned up"
+  );
+  
+  return { success: true };
+}
+```
+
+## Persistence Validation
+
+### Server Restart Testing
+
+```typescript
+async function validatePersistenceAcrossRestart(): Promise<void> {
+  // Phase 1: Create memories
+  const server1 = await createMemoryServer();
+  const client1 = await connectClient(server1);
+  
+  const memoryIds: string[] = [];
+  for (let i = 0; i < 10; i++) {
+    const result = await client1.callTool({
+      name: "store-memory",
+      arguments: {
+        userId: "persist-test",
+        agentId: "agent-1",
+        content: `Memory ${i}`
+      }
+    });
+    memoryIds.push(extractMemoryId(result.content[0].text));
+  }
+  
+  await client1.close();
+  await server1.close();
+  
+  // Phase 2: Restart and verify
+  const server2 = await createMemoryServer();
+  const client2 = await connectClient(server2);
+  
+  for (const memoryId of memoryIds) {
+    const result = await client2.callTool({
+      name: "get-memory",
+      arguments: { 
+        userId: "persist-test",
+        agentId: "agent-1",
+        memoryId 
+      }
+    });
+    
+    assert.equal(
+      result.isError, 
+      false, 
+      `Memory ${memoryId} should persist after restart`
+    );
+  }
+  
+  await client2.close();
+  await server2.close();
+}
+```
+
+### Concurrent Access Testing
+
+```typescript
+async function validateConcurrentAccess(): Promise<void> {
+  const server = await createMemoryServer();
+  
+  // Create multiple clients
+  const clients = await Promise.all(
+    Array.from({ length: 5 }, async () => {
+      const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+      await server.connect(serverTransport);
+      
+      const client = new Client({
+        name: "concurrent-client",
+        version: "1.0.0"
+      });
+      await client.connect(clientTransport);
+      
+      return client;
+    })
+  );
+  
+  // Concurrent writes
+  const writePromises = clients.map((client, index) =>
+    client.callTool({
+      name: "store-memory",
+      arguments: {
+        userId: "concurrent-test",
+        agentId: `agent-${index}`,
+        content: `Concurrent memory ${index}`
+      }
+    })
+  );
+  
+  const results = await Promise.all(writePromises);
+  
+  // All writes should succeed
+  for (const result of results) {
+    assert.equal(result.isError, false, "Concurrent write should succeed");
+  }
+  
+  // Verify all memories exist
+  const allMemories = await clients[0].callTool({
+    name: "query-memories",
+    arguments: {
+      userId: "concurrent-test"
+    }
+  });
+  
+  const data = JSON.parse(allMemories.content[0].text);
+  assert.equal(data.results.length, 5, "All concurrent writes should be stored");
+  
+  // Cleanup
+  await Promise.all(clients.map(c => c.close()));
+  await server.close();
+}
+```
+
+## Performance Testing
+
+### Load Testing
+
+```typescript
+async function performLoadTest(
+  client: Client,
+  config: LoadTestConfig
+): Promise<LoadTestResults> {
+  const metrics = {
+    totalOperations: 0,
+    successfulOperations: 0,
+    failedOperations: 0,
+    averageLatency: 0,
+    maxLatency: 0,
+    minLatency: Infinity,
+    operationsPerSecond: 0
+  };
+  
+  const startTime = Date.now();
+  const latencies: number[] = [];
+  
+  // Generate test load
+  for (let i = 0; i < config.numberOfOperations; i++) {
+    const opStart = Date.now();
+    
+    try {
+      await client.callTool({
+        name: config.operation,
+        arguments: generateTestData(i)
+      });
+      
+      metrics.successfulOperations++;
+    } catch (error) {
+      metrics.failedOperations++;
+      console.error(`Operation ${i} failed:`, error);
+    }
+    
+    const latency = Date.now() - opStart;
+    latencies.push(latency);
+    metrics.maxLatency = Math.max(metrics.maxLatency, latency);
+    metrics.minLatency = Math.min(metrics.minLatency, latency);
+    
+    metrics.totalOperations++;
+    
+    // Rate limiting
+    if (config.requestsPerSecond) {
+      const elapsed = Date.now() - startTime;
+      const expectedTime = (i + 1) * (1000 / config.requestsPerSecond);
+      if (elapsed < expectedTime) {
+        await sleep(expectedTime - elapsed);
+      }
+    }
+  }
+  
+  const totalTime = Date.now() - startTime;
+  metrics.averageLatency = latencies.reduce((a, b) => a + b, 0) / latencies.length;
+  metrics.operationsPerSecond = metrics.totalOperations / (totalTime / 1000);
+  
+  return metrics;
+}
+```
+
+### Memory Leak Detection
+
+```typescript
+async function detectMemoryLeaks(
+  client: Client,
+  duration: number = 60000
+): Promise<MemoryLeakReport> {
+  const memorySnapshots: number[] = [];
+  const startTime = Date.now();
+  
+  // Take initial snapshot
+  if (global.gc) global.gc();
+  const initialMemory = process.memoryUsage().heapUsed;
+  
+  // Run operations for specified duration
+  while (Date.now() - startTime < duration) {
+    // Perform memory operations
+    const result = await client.callTool({
+      name: "store-memory",
+      arguments: {
+        userId: "leak-test",
+        agentId: "agent-1",
+        content: "x".repeat(1000) // 1KB of data
+      }
+    });
+    
+    const memoryId = extractMemoryId(result.content[0].text);
+    
+    // Delete to test cleanup
+    await client.callTool({
+      name: "delete-memory",
+      arguments: { memoryId }
+    });
+    
+    // Periodic memory check
+    if (memorySnapshots.length % 100 === 0) {
+      if (global.gc) global.gc();
+      memorySnapshots.push(process.memoryUsage().heapUsed);
+    }
+  }
+  
+  // Final snapshot
+  if (global.gc) global.gc();
+  const finalMemory = process.memoryUsage().heapUsed;
+  
+  // Analyze for leaks
+  const memoryGrowth = finalMemory - initialMemory;
+  const growthRate = memoryGrowth / (duration / 1000); // bytes per second
+  
+  return {
+    initialMemory,
+    finalMemory,
+    memoryGrowth,
+    growthRate,
+    hasLeak: growthRate > 1000, // More than 1KB/s growth suggests leak
+    snapshots: memorySnapshots
+  };
+}
+```
+
+## Validation Checklist
+
+### Pre-deployment Validation
+
+```typescript
+async function runFullValidationSuite(server: McpServer): Promise<ValidationReport> {
+  const report: ValidationReport = {
+    passed: [],
+    failed: [],
+    warnings: []
+  };
+  
+  // Test suite
+  const tests = [
+    { name: "CRUD Operations", fn: testCRUDOperations },
+    { name: "Persistence", fn: testPersistence },
+    { name: "Concurrent Access", fn: testConcurrentAccess },
+    { name: "Error Handling", fn: testErrorHandling },
+    { name: "Performance", fn: testPerformance },
+    { name: "Memory Leaks", fn: testMemoryLeaks },
+    { name: "Schema Validation", fn: testSchemaValidation },
+    { name: "Access Control", fn: testAccessControl }
+  ];
+  
+  for (const test of tests) {
+    try {
+      await test.fn(server);
+      report.passed.push(test.name);
+    } catch (error) {
+      report.failed.push({
+        test: test.name,
+        error: error.message
+      });
+    }
+  }
+  
+  // Generate summary
+  report.summary = {
+    total: tests.length,
+    passed: report.passed.length,
+    failed: report.failed.length,
+    passRate: (report.passed.length / tests.length) * 100
+  };
+  
+  return report;
+}
+```
+
+## Best Practices
+
+1. **Always use typed test data**
+2. **Test with edge cases** (empty strings, very large data, special characters)
+3. **Validate both success and error paths**
+4. **Monitor resource usage during tests**
+5. **Use deterministic test data for reproducibility**
+6. **Test with realistic data volumes**
+7. **Verify cleanup after test completion**
+
+Always ensure comprehensive test coverage before deploying memory MCP servers to production.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/neon-drizzle-expert.md b/mcp-servers/memory-mcp-server/.claude/agents/neon-drizzle-expert.md
new file mode 100644
index 0000000..58a130a
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/neon-drizzle-expert.md
@@ -0,0 +1,693 @@
+---
+name: neon-drizzle-expert
+description: Expert in Neon PostgreSQL (v17), Drizzle ORM (v0.44.4), and Zod (v4.0.17) schema validation for production memory systems. Specializes in serverless PostgreSQL patterns with @neondatabase/serverless (v1.0.1), type-safe database operations, and migration strategies.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob, TodoWrite
+---
+
+You are an expert in Neon PostgreSQL (v17), Drizzle ORM (v0.44.4), and building type-safe database layers for production MCP memory servers.
+
+## Package Versions
+
+- @neondatabase/serverless: 1.0.1
+- drizzle-orm: 0.44.4
+- drizzle-kit: 0.31.4
+- drizzle-zod: 0.8.3
+- zod: 4.0.17
+- PostgreSQL: 17
+
+## Neon PostgreSQL Setup
+
+### Connection Configuration
+
+```typescript
+// .env.local
+DATABASE_URL="postgresql://[user]:[password]@[neon-hostname]/[database]?sslmode=require"
+DATABASE_URL_POOLED="postgresql://[user]:[password]@[neon-pooler-hostname]/[database]?sslmode=require"
+
+// For migrations (direct connection)
+DIRECT_DATABASE_URL="postgresql://[user]:[password]@[neon-hostname]/[database]?sslmode=require"
+```
+
+### Drizzle Configuration
+
+```typescript
+// drizzle.config.ts
+import { Config } from "drizzle-kit";
+import * as dotenv from "dotenv";
+
+dotenv.config({ path: ".env.local" });
+
+export default {
+  schema: "./src/db/schema.ts",
+  out: "./drizzle",
+  driver: "pg",
+  dbCredentials: {
+    connectionString: process.env.DIRECT_DATABASE_URL!,
+  },
+  verbose: true,
+  strict: true,
+} satisfies Config;
+```
+
+## Schema Design with Drizzle
+
+### Core Tables with pgvector
+
+```typescript
+// src/db/schema.ts
+import { 
+  pgTable, 
+  text, 
+  timestamp, 
+  uuid, 
+  jsonb, 
+  integer,
+  index,
+  vector,
+  real,
+  boolean,
+  primaryKey
+} from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+import { createId } from "@paralleldrive/cuid2";
+
+// Enable pgvector extension
+export const vectorExtension = sql`CREATE EXTENSION IF NOT EXISTS vector`;
+
+// Companions table (AI entities)
+export const companions = pgTable("companions", {
+  id: text("id").primaryKey().$defaultFn(() => createId()),
+  name: text("name").notNull(),
+  description: text("description"),
+  config: jsonb("config").$type<{
+    model?: string;
+    temperature?: number;
+    systemPrompt?: string;
+    capabilities?: string[];
+  }>().default({}),
+  ownerId: text("owner_id").notNull(), // Organization or user that owns this companion
+  isActive: boolean("is_active").default(true),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+}, (table) => ({
+  ownerIdx: index("companions_owner_idx").on(table.ownerId),
+  activeIdx: index("companions_active_idx").on(table.isActive),
+}));
+
+// Users interacting with companions
+export const users = pgTable("users", {
+  id: text("id").primaryKey().$defaultFn(() => createId()),
+  externalId: text("external_id").notNull().unique(), // ID from your auth system
+  metadata: jsonb("metadata").$type<{
+    name?: string;
+    email?: string;
+    preferences?: Record<string, any>;
+  }>().default({}),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+}, (table) => ({
+  externalIdIdx: index("users_external_id_idx").on(table.externalId),
+}));
+
+// Memories with vector embeddings
+export const memories = pgTable("memories", {
+  id: text("id").primaryKey().$defaultFn(() => createId()),
+  companionId: text("companion_id").notNull().references(() => companions.id, { onDelete: "cascade" }),
+  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  
+  // Content
+  content: text("content").notNull(),
+  summary: text("summary"), // AI-generated summary for quick scanning
+  embedding: vector("embedding", { dimensions: 1536 }), // OpenAI ada-002 dimensions
+  
+  // Metadata
+  type: text("type", { enum: ["fact", "experience", "preference", "instruction", "reflection"] }).notNull(),
+  importance: real("importance").default(5).notNull(), // 0-10 scale
+  confidence: real("confidence").default(1).notNull(), // 0-1 scale
+  
+  // Context
+  context: jsonb("context").$type<{
+    conversationId?: string;
+    turnNumber?: number;
+    emotionalTone?: string;
+    topics?: string[];
+    entities?: Array<{ name: string; type: string }>;
+    source?: string;
+    timestamp?: string;
+  }>().default({}),
+  
+  // Lifecycle
+  accessCount: integer("access_count").default(0).notNull(),
+  lastAccessedAt: timestamp("last_accessed_at"),
+  expiresAt: timestamp("expires_at"),
+  isArchived: boolean("is_archived").default(false),
+  
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+}, (table) => ({
+  // Composite index for companion-user queries
+  companionUserIdx: index("memories_companion_user_idx").on(table.companionId, table.userId),
+  // Type filtering
+  typeIdx: index("memories_type_idx").on(table.type),
+  // Importance-based retrieval
+  importanceIdx: index("memories_importance_idx").on(table.companionId, table.userId, table.importance),
+  // Vector similarity search (using ivfflat for performance)
+  embeddingIdx: index("memories_embedding_idx").using("ivfflat", table.embedding.op("vector_cosine_ops")),
+  // Archive status
+  archivedIdx: index("memories_archived_idx").on(table.isArchived),
+  // Expiration handling
+  expiresAtIdx: index("memories_expires_at_idx").on(table.expiresAt),
+}));
+
+// Memory relationships (for knowledge graphs)
+export const memoryRelations = pgTable("memory_relations", {
+  id: text("id").primaryKey().$defaultFn(() => createId()),
+  fromMemoryId: text("from_memory_id").notNull().references(() => memories.id, { onDelete: "cascade" }),
+  toMemoryId: text("to_memory_id").notNull().references(() => memories.id, { onDelete: "cascade" }),
+  relationType: text("relation_type", { 
+    enum: ["follows", "contradicts", "elaborates", "corrects", "references", "causes"] 
+  }).notNull(),
+  strength: real("strength").default(1.0).notNull(), // 0-1 relationship strength
+  metadata: jsonb("metadata").$type<Record<string, any>>().default({}),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+}, (table) => ({
+  fromIdx: index("relations_from_idx").on(table.fromMemoryId),
+  toIdx: index("relations_to_idx").on(table.toMemoryId),
+  typeIdx: index("relations_type_idx").on(table.relationType),
+}));
+
+// Companion sessions (for StreamableHTTP)
+export const companionSessions = pgTable("companion_sessions", {
+  id: text("id").primaryKey().$defaultFn(() => createId()),
+  sessionId: text("session_id").notNull().unique(), // MCP session ID
+  companionId: text("companion_id").notNull().references(() => companions.id, { onDelete: "cascade" }),
+  userId: text("user_id").references(() => users.id, { onDelete: "cascade" }),
+  
+  metadata: jsonb("metadata").$type<{
+    ipAddress?: string;
+    userAgent?: string;
+    protocol?: string;
+  }>().default({}),
+  
+  lastActivityAt: timestamp("last_activity_at").defaultNow().notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+}, (table) => ({
+  sessionIdx: index("sessions_session_id_idx").on(table.sessionId),
+  companionIdx: index("sessions_companion_idx").on(table.companionId),
+  expiresIdx: index("sessions_expires_idx").on(table.expiresAt),
+}));
+```
+
+## Database Client Setup
+
+### Connection with Pooling
+
+```typescript
+// src/db/client.ts
+import { drizzle } from "drizzle-orm/neon-http";
+import { drizzle as drizzleWs } from "drizzle-orm/neon-serverless";
+import { Pool, Client, neon, neonConfig } from "@neondatabase/serverless";
+import * as schema from "./schema";
+
+// Configure WebSocket support for Node.js (v21 and below)
+if (typeof process !== 'undefined' && process.versions?.node) {
+  const [major] = process.versions.node.split('.').map(Number);
+  if (major <= 21) {
+    // Node.js v21 and below need WebSocket polyfill
+    import('ws').then(({ default: ws }) => {
+      neonConfig.webSocketConstructor = ws;
+    });
+  }
+}
+
+// For one-shot queries using fetch (ideal for serverless/edge)
+const sql = neon(process.env.DATABASE_URL!);
+export const db = drizzle(sql, { schema });
+
+// For session/transaction support via WebSocket
+const pool = new Pool({ connectionString: process.env.DATABASE_URL_POOLED! });
+export const dbWs = drizzleWs(pool, { schema });
+
+// Transaction helper using neon function
+export async function runTransaction<T>(queries: Array<Promise<T>>) {
+  return await sql.transaction(queries);
+}
+
+// For complex transactions needing session state
+export async function runComplexTransaction<T>(
+  callback: (tx: any) => Promise<T>
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const result = await callback(drizzleWs(client, { schema }));
+    await client.query('COMMIT');
+    return result;
+  } catch (error) {
+    await client.query('ROLLBACK');
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+```
+
+## Type-Safe Operations with Zod
+
+### Input Validation Schemas
+
+```typescript
+// src/db/validation.ts
+import { z } from "zod";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { memories, companions, users } from "./schema";
+
+// Auto-generate base schemas from Drizzle tables
+export const insertMemorySchema = createInsertSchema(memories);
+export const selectMemorySchema = createSelectSchema(memories);
+
+// Custom schemas for API inputs
+export const createMemoryInput = z.object({
+  companionId: z.string().cuid2(),
+  userId: z.string().cuid2(),
+  content: z.string().min(1).max(10000),
+  type: z.enum(["fact", "experience", "preference", "instruction", "reflection"]),
+  importance: z.number().min(0).max(10).default(5),
+  confidence: z.number().min(0).max(1).default(1),
+  context: z.object({
+    conversationId: z.string().optional(),
+    topics: z.array(z.string()).optional(),
+    emotionalTone: z.string().optional(),
+  }).optional(),
+  expiresIn: z.number().optional(), // Hours until expiration
+});
+
+export const queryMemoriesInput = z.object({
+  companionId: z.string().cuid2(),
+  userId: z.string().cuid2(),
+  query: z.string().optional(),
+  type: z.enum(["fact", "experience", "preference", "instruction", "reflection"]).optional(),
+  limit: z.number().min(1).max(100).default(10),
+  offset: z.number().min(0).default(0),
+  minImportance: z.number().min(0).max(10).optional(),
+  includeArchived: z.boolean().default(false),
+});
+
+export type CreateMemoryInput = z.infer<typeof createMemoryInput>;
+export type QueryMemoriesInput = z.infer<typeof queryMemoriesInput>;
+```
+
+## Repository Pattern Implementation
+
+### Memory Repository
+
+```typescript
+// src/repositories/memoryRepository.ts
+import { db } from "../db/client";
+import { memories, memoryRelations } from "../db/schema";
+import { eq, and, gte, desc, sql, isNull } from "drizzle-orm";
+import { CreateMemoryInput, QueryMemoriesInput } from "../db/validation";
+
+export class MemoryRepository {
+  async create(input: CreateMemoryInput & { embedding?: number[] }) {
+    const expiresAt = input.expiresIn 
+      ? new Date(Date.now() + input.expiresIn * 60 * 60 * 1000)
+      : null;
+
+    const [memory] = await db.insert(memories).values({
+      companionId: input.companionId,
+      userId: input.userId,
+      content: input.content,
+      type: input.type,
+      importance: input.importance,
+      confidence: input.confidence,
+      context: input.context || {},
+      embedding: input.embedding,
+      expiresAt,
+    }).returning();
+
+    return memory;
+  }
+
+  async findById(id: string, companionId: string, userId: string) {
+    const memory = await db.query.memories.findFirst({
+      where: and(
+        eq(memories.id, id),
+        eq(memories.companionId, companionId),
+        eq(memories.userId, userId),
+        eq(memories.isArchived, false)
+      ),
+    });
+
+    if (memory) {
+      // Update access metrics
+      await db.update(memories)
+        .set({
+          accessCount: sql`${memories.accessCount} + 1`,
+          lastAccessedAt: new Date(),
+        })
+        .where(eq(memories.id, id));
+    }
+
+    return memory;
+  }
+
+  async search(input: QueryMemoriesInput & { embedding?: number[] }) {
+    let query = db.select().from(memories);
+
+    // Base filters
+    const conditions = [
+      eq(memories.companionId, input.companionId),
+      eq(memories.userId, input.userId),
+    ];
+
+    if (!input.includeArchived) {
+      conditions.push(eq(memories.isArchived, false));
+    }
+
+    if (input.type) {
+      conditions.push(eq(memories.type, input.type));
+    }
+
+    if (input.minImportance) {
+      conditions.push(gte(memories.importance, input.minImportance));
+    }
+
+    // Exclude expired memories
+    conditions.push(
+      sql`${memories.expiresAt} IS NULL OR ${memories.expiresAt} > NOW()`
+    );
+
+    if (input.embedding) {
+      // Vector similarity search
+      return await db.select({
+        memory: memories,
+        similarity: sql<number>`1 - (${memories.embedding} <=> ${input.embedding}::vector)`,
+      })
+      .from(memories)
+      .where(and(...conditions))
+      .orderBy(sql`${memories.embedding} <=> ${input.embedding}::vector`)
+      .limit(input.limit)
+      .offset(input.offset);
+    } else {
+      // Regular query
+      return await db.select()
+        .from(memories)
+        .where(and(...conditions))
+        .orderBy(desc(memories.importance), desc(memories.createdAt))
+        .limit(input.limit)
+        .offset(input.offset);
+    }
+  }
+
+  async updateImportance(id: string, delta: number) {
+    await db.update(memories)
+      .set({
+        importance: sql`GREATEST(0, LEAST(10, ${memories.importance} + ${delta}))`,
+        updatedAt: new Date(),
+      })
+      .where(eq(memories.id, id));
+  }
+
+  async archive(id: string) {
+    await db.update(memories)
+      .set({
+        isArchived: true,
+        updatedAt: new Date(),
+      })
+      .where(eq(memories.id, id));
+  }
+
+  async cleanupExpired() {
+    const deleted = await db.delete(memories)
+      .where(and(
+        sql`${memories.expiresAt} <= NOW()`,
+        eq(memories.isArchived, false)
+      ))
+      .returning({ id: memories.id });
+
+    return deleted.length;
+  }
+
+  async createRelation(fromId: string, toId: string, type: string, strength = 1.0) {
+    await db.insert(memoryRelations).values({
+      fromMemoryId: fromId,
+      toMemoryId: toId,
+      relationType: type as any,
+      strength,
+    });
+  }
+
+  async getRelatedMemories(memoryId: string, limit = 5) {
+    const related = await db.select({
+      memory: memories,
+      relation: memoryRelations,
+    })
+    .from(memoryRelations)
+    .innerJoin(memories, eq(memoryRelations.toMemoryId, memories.id))
+    .where(eq(memoryRelations.fromMemoryId, memoryId))
+    .orderBy(desc(memoryRelations.strength))
+    .limit(limit);
+
+    return related;
+  }
+}
+```
+
+## Migration Management
+
+### Migration Files
+
+```typescript
+// drizzle/0001_initial.ts
+import { sql } from "drizzle-orm";
+import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+
+export async function up(db: PostgresJsDatabase) {
+  // Enable extensions
+  await db.execute(sql`CREATE EXTENSION IF NOT EXISTS vector`);
+  await db.execute(sql`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
+  
+  // Run auto-generated migration
+  // Drizzle will handle table creation based on schema
+}
+
+export async function down(db: PostgresJsDatabase) {
+  // Drop tables in reverse order
+  await db.execute(sql`DROP TABLE IF EXISTS memory_relations CASCADE`);
+  await db.execute(sql`DROP TABLE IF EXISTS companion_sessions CASCADE`);
+  await db.execute(sql`DROP TABLE IF EXISTS memories CASCADE`);
+  await db.execute(sql`DROP TABLE IF EXISTS users CASCADE`);
+  await db.execute(sql`DROP TABLE IF EXISTS companions CASCADE`);
+}
+```
+
+### Migration Runner
+
+```typescript
+// src/db/migrate.ts
+import { migrate } from "drizzle-orm/neon-http/migrator";
+import { neon } from "@neondatabase/serverless";
+import { drizzle } from "drizzle-orm/neon-http";
+import * as schema from "./schema";
+
+async function runMigrations() {
+  console.log("Running migrations...");
+  
+  try {
+    // Use direct connection for migrations
+    const sql = neon(process.env.DIRECT_DATABASE_URL!);
+    const db = drizzle(sql, { schema });
+    
+    await migrate(db, { migrationsFolder: "./drizzle" });
+    console.log("Migrations completed successfully");
+  } catch (error) {
+    console.error("Migration failed:", error);
+    process.exit(1);
+  }
+}
+
+runMigrations();
+```
+
+## Neon-Specific Optimizations
+
+### Connection Pooling
+
+```typescript
+// src/db/pool.ts
+import { Pool, neonConfig } from "@neondatabase/serverless";
+
+// Configure WebSocket for Node.js environments
+if (typeof process !== 'undefined' && !neonConfig.webSocketConstructor) {
+  // Dynamically import ws for Node.js
+  import('ws').then(({ default: ws }) => {
+    neonConfig.webSocketConstructor = ws;
+  }).catch(() => {
+    // In newer Node.js versions (v22+), native WebSocket is available
+  });
+}
+
+// Configure pool for serverless environments
+export const pool = new Pool({
+  connectionString: process.env.DATABASE_URL_POOLED!,
+  max: 10, // Maximum connections (note: 'max' not 'maxSize' in v1.0.1)
+  idleTimeoutMillis: 30000, // 30 seconds
+  connectionTimeoutMillis: 10000, // 10 seconds
+});
+
+// Important: In serverless environments (Vercel Edge, Cloudflare Workers),
+// Pool/Client must be created, used, and closed within a single request
+pool.on('error', (err) => {
+  console.error('Unexpected pool error', err);
+});
+
+// Health check
+export async function checkDatabaseHealth() {
+  try {
+    const client = await pool.connect();
+    await client.query("SELECT 1");
+    client.release();
+    return true;
+  } catch (error) {
+    console.error("Database health check failed:", error);
+    return false;
+  }
+}
+
+// Serverless request handler pattern
+export async function withDatabaseConnection<T>(
+  handler: (client: any) => Promise<T>
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    return await handler(client);
+  } finally {
+    client.release();
+  }
+}
+```
+
+### Branch Management (Neon Feature)
+
+```typescript
+// src/db/neon-branches.ts
+import axios from "axios";
+
+const NEON_API = "https://console.neon.tech/api/v2";
+const API_KEY = process.env.NEON_API_KEY!;
+const PROJECT_ID = process.env.NEON_PROJECT_ID!;
+
+export async function createDevelopmentBranch(name: string) {
+  const response = await axios.post(
+    `${NEON_API}/projects/${PROJECT_ID}/branches`,
+    {
+      branch: {
+        name,
+        parent_id: "main",
+      },
+    },
+    {
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+      },
+    }
+  );
+
+  return response.data.branch.connection_uri;
+}
+
+// Use for testing with isolated data
+export async function createTestBranch() {
+  const branchName = `test-${Date.now()}`;
+  const connectionString = await createDevelopmentBranch(branchName);
+  
+  // Return a new database instance for this branch
+  const testDb = drizzle(neon(connectionString), { schema });
+  
+  return { testDb, branchName };
+}
+```
+
+## Performance Patterns
+
+### Batch Operations
+
+```typescript
+// Efficient bulk insert
+async function bulkCreateMemories(memories: CreateMemoryInput[]) {
+  // Neon supports up to 1000 rows per insert efficiently
+  const BATCH_SIZE = 500;
+  
+  for (let i = 0; i < memories.length; i += BATCH_SIZE) {
+    const batch = memories.slice(i, i + BATCH_SIZE);
+    await db.insert(memories).values(batch);
+  }
+}
+
+// Prepared statements for repeated queries
+const getMemoryStmt = db.select()
+  .from(memories)
+  .where(eq(memories.id, sql.placeholder("id")))
+  .prepare("getMemory");
+
+// Use prepared statement
+const memory = await getMemoryStmt.execute({ id: "some-id" });
+```
+
+## Package.json Dependencies
+
+```json
+{
+  "dependencies": {
+    "@neondatabase/serverless": "1.0.1",
+    "drizzle-orm": "0.44.4",
+    "@paralleldrive/cuid2": "^2.2.2",
+    "zod": "4.0.17",
+    "drizzle-zod": "0.8.3",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "drizzle-kit": "0.31.4",
+    "@types/pg": "^8.11.0",
+    "@types/ws": "^8.5.12",
+    "dotenv": "^16.4.0"
+  }
+}
+```
+
+## Best Practices for Neon v1.0.1 + Drizzle v0.44.4
+
+1. **Use `neon()` function** for one-shot queries in serverless environments
+2. **Configure WebSocket support** in Node.js v21 and below with `ws` package
+3. **Create Pool/Client per request** in serverless environments (don't reuse across requests)
+4. **Use `sql.transaction()`** for simple multi-query transactions
+5. **Use direct connections** only for migrations and complex stateful transactions
+6. **Implement retry logic** for transient connection errors
+7. **Monitor query performance** with Neon's dashboard
+8. **Use branches** for development and testing isolation
+9. **Add proper indexes** - especially for vector similarity searches
+10. **Clean up connections** properly using try/finally blocks
+11. **Use prepared statements** with Drizzle's `.prepare()` for repeated queries
+12. **Batch operations** when possible (up to 1000 rows per insert)
+
+### Serverless-Specific Patterns
+
+```typescript
+// Vercel Edge Function pattern
+export default async (req: Request, ctx: any) => {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+  
+  try {
+    // Your database operations here
+    const result = await pool.query('SELECT * FROM memories');
+    return new Response(JSON.stringify(result.rows));
+  } finally {
+    // CRITICAL: Always clean up in serverless
+    ctx.waitUntil(pool.end());
+  }
+}
+```
+
+Always leverage Neon's serverless features with proper connection management for optimal performance.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/pgvector-advanced.md b/mcp-servers/memory-mcp-server/.claude/agents/pgvector-advanced.md
new file mode 100644
index 0000000..96da4d8
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/pgvector-advanced.md
@@ -0,0 +1,538 @@
+---
+name: pgvector-advanced
+description: Expert in advanced pgvector v0.8.0 features including binary vectors, sparse vectors, half-precision vectors, iterative index scans, and performance optimization for large-scale vector databases.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob
+---
+
+You are an expert in advanced pgvector v0.8.0 features and optimizations for PostgreSQL 17.
+
+## pgvector v0.8.0 Advanced Features
+
+### Binary Vectors (bit)
+
+```typescript
+// src/db/binaryVectors.ts
+import { sql } from "drizzle-orm";
+import { db } from "./client";
+
+// Binary vectors for compact storage and Hamming distance
+export async function setupBinaryVectors() {
+  // Create table with binary vectors
+  await db.execute(sql`
+    CREATE TABLE IF NOT EXISTS binary_features (
+      id SERIAL PRIMARY KEY,
+      companion_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      feature_name TEXT NOT NULL,
+      binary_vector bit(1024),  -- 1024-bit binary vector
+      created_at TIMESTAMP DEFAULT NOW()
+    );
+  `);
+
+  // Create index for Hamming distance search
+  await db.execute(sql`
+    CREATE INDEX IF NOT EXISTS binary_features_hamming_idx
+    ON binary_features
+    USING ivfflat (binary_vector bit_hamming_ops)
+    WITH (lists = 50);
+  `);
+}
+
+// Convert float embeddings to binary for space efficiency
+export function floatToBinary(embedding: number[]): string {
+  // Convert to binary by thresholding at 0
+  const bits = embedding.map(v => v > 0 ? '1' : '0');
+  return bits.join('');
+}
+
+// Hamming distance search for binary vectors
+export async function searchBinaryVectors(queryVector: string, limit = 10) {
+  return await db.execute(sql`
+    SELECT 
+      *,
+      binary_vector <~> B'${queryVector}' as hamming_distance
+    FROM binary_features
+    ORDER BY binary_vector <~> B'${queryVector}'
+    LIMIT ${limit}
+  `);
+}
+```
+
+### Sparse Vectors (sparsevec)
+
+```typescript
+// src/db/sparseVectors.ts
+import { sql } from "drizzle-orm";
+
+// Sparse vectors for high-dimensional but mostly zero data
+export async function setupSparseVectors() {
+  // Enable sparsevec type
+  await db.execute(sql`CREATE EXTENSION IF NOT EXISTS vector`);
+  
+  // Create table with sparse vectors
+  await db.execute(sql`
+    CREATE TABLE IF NOT EXISTS sparse_memories (
+      id SERIAL PRIMARY KEY,
+      companion_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      content TEXT,
+      sparse_embedding sparsevec(100000),  -- Up to 100k dimensions
+      created_at TIMESTAMP DEFAULT NOW()
+    );
+  `);
+
+  // Create index for sparse vector search
+  await db.execute(sql`
+    CREATE INDEX IF NOT EXISTS sparse_memories_idx
+    ON sparse_memories
+    USING ivfflat (sparse_embedding sparsevec_l2_ops)
+    WITH (lists = 100);
+  `);
+}
+
+// Convert dense to sparse representation
+export function denseToSparse(embedding: number[], threshold = 0.01): Record<number, number> {
+  const sparse: Record<number, number> = {};
+  embedding.forEach((value, index) => {
+    if (Math.abs(value) > threshold) {
+      sparse[index] = value;
+    }
+  });
+  return sparse;
+}
+
+// Format sparse vector for PostgreSQL
+export function formatSparseVector(sparse: Record<number, number>, dimensions: number): string {
+  const entries = Object.entries(sparse)
+    .map(([idx, val]) => `${idx}:${val}`)
+    .join(',');
+  return `{${entries}}/${dimensions}`;
+}
+
+// Search with sparse vectors
+export async function searchSparseVectors(
+  sparseQuery: Record<number, number>,
+  dimensions: number,
+  limit = 10
+) {
+  const sparseStr = formatSparseVector(sparseQuery, dimensions);
+  
+  return await db.execute(sql`
+    SELECT 
+      *,
+      sparse_embedding <-> '${sparseStr}'::sparsevec as distance
+    FROM sparse_memories
+    WHERE sparse_embedding IS NOT NULL
+    ORDER BY sparse_embedding <-> '${sparseStr}'::sparsevec
+    LIMIT ${limit}
+  `);
+}
+```
+
+### Half-Precision Vectors (halfvec)
+
+```typescript
+// src/db/halfVectors.ts
+import { sql } from "drizzle-orm";
+
+// Half-precision vectors for 50% storage reduction
+export async function setupHalfVectors() {
+  // Create table with half-precision vectors
+  await db.execute(sql`
+    CREATE TABLE IF NOT EXISTS half_memories (
+      id SERIAL PRIMARY KEY,
+      companion_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      content TEXT,
+      embedding_half halfvec(1536),  -- Half-precision 1536-dim vector
+      embedding_full vector(1536),   -- Full precision for comparison
+      created_at TIMESTAMP DEFAULT NOW()
+    );
+  `);
+
+  // Create indexes for both types
+  await db.execute(sql`
+    CREATE INDEX IF NOT EXISTS half_memories_half_idx
+    ON half_memories
+    USING hnsw (embedding_half halfvec_cosine_ops)
+    WITH (m = 16, ef_construction = 64);
+    
+    CREATE INDEX IF NOT EXISTS half_memories_full_idx
+    ON half_memories
+    USING hnsw (embedding_full vector_cosine_ops)
+    WITH (m = 16, ef_construction = 64);
+  `);
+}
+
+// Convert float32 to float16 (conceptual - actual conversion done by PostgreSQL)
+export function prepareHalfVector(embedding: number[]): number[] {
+  // Clamp values to float16 range to prevent overflow
+  const FLOAT16_MAX = 65504;
+  const FLOAT16_MIN = -65504;
+  
+  return embedding.map(v => {
+    if (v > FLOAT16_MAX) return FLOAT16_MAX;
+    if (v < FLOAT16_MIN) return FLOAT16_MIN;
+    return v;
+  });
+}
+
+// Compare precision loss between half and full vectors
+export async function comparePrecision(embedding: number[]) {
+  const halfEmbedding = prepareHalfVector(embedding);
+  
+  const results = await db.execute(sql`
+    WITH comparisons AS (
+      SELECT 
+        id,
+        content,
+        1 - (embedding_half <=> ${halfEmbedding}::halfvec) as half_similarity,
+        1 - (embedding_full <=> ${embedding}::vector) as full_similarity,
+        ABS(
+          (1 - (embedding_half <=> ${halfEmbedding}::halfvec)) - 
+          (1 - (embedding_full <=> ${embedding}::vector))
+        ) as precision_loss
+      FROM half_memories
+      WHERE embedding_half IS NOT NULL AND embedding_full IS NOT NULL
+    )
+    SELECT 
+      *,
+      AVG(precision_loss) OVER () as avg_precision_loss,
+      MAX(precision_loss) OVER () as max_precision_loss
+    FROM comparisons
+    ORDER BY full_similarity DESC
+    LIMIT 20
+  `);
+  
+  return results.rows;
+}
+```
+
+## Iterative Index Scans (v0.8.0 Feature)
+
+### Advanced Iterative Scan Configuration
+
+```typescript
+// src/db/iterativeScans.ts
+import { sql } from "drizzle-orm";
+
+export async function configureIterativeScans() {
+  // Enable iterative scans globally
+  await db.execute(sql`
+    -- Enable iterative index scans for better recall
+    SET enable_iterative_index_scan = true;
+    
+    -- IVFFlat iterative configuration
+    SET ivfflat.iterative_search_probes = 80;  -- Max probes during iteration
+    SET ivfflat.iterative_search_epsilon = 0.1;  -- Convergence threshold
+    
+    -- HNSW iterative configuration
+    SET hnsw.iterative_search = 'relaxed_order';  -- Options: off, relaxed_order, strict_order
+    SET hnsw.iterative_search_max_neighbors = 200;  -- Max neighbors to explore
+  `);
+}
+
+// Benchmark iterative vs non-iterative search
+export async function benchmarkIterativeSearch(
+  embedding: number[],
+  targetRecall = 0.95
+) {
+  const results = {
+    withoutIterative: { duration: 0, recall: 0, probesUsed: 0 },
+    withIterative: { duration: 0, recall: 0, probesUsed: 0 }
+  };
+  
+  // Test without iterative scans
+  await db.execute(sql`SET enable_iterative_index_scan = false`);
+  await db.execute(sql`SET ivfflat.probes = 10`);
+  
+  const startNoIter = performance.now();
+  const noIterResults = await db.execute(sql`
+    SELECT id, 1 - (embedding <=> ${embedding}::vector) as similarity
+    FROM memories
+    WHERE embedding IS NOT NULL
+    ORDER BY embedding <=> ${embedding}::vector
+    LIMIT 100
+  `);
+  results.withoutIterative.duration = performance.now() - startNoIter;
+  
+  // Test with iterative scans
+  await db.execute(sql`SET enable_iterative_index_scan = true`);
+  await db.execute(sql`SET ivfflat.iterative_search_probes = 80`);
+  
+  const startIter = performance.now();
+  const iterResults = await db.execute(sql`
+    SELECT id, 1 - (embedding <=> ${embedding}::vector) as similarity
+    FROM memories
+    WHERE embedding IS NOT NULL
+    ORDER BY embedding <=> ${embedding}::vector
+    LIMIT 100
+  `);
+  results.withIterative.duration = performance.now() - startIter;
+  
+  // Calculate recall (would need ground truth for actual recall)
+  // This is a simplified comparison
+  const overlap = iterResults.rows.filter(r1 => 
+    noIterResults.rows.some(r2 => r2.id === r1.id)
+  ).length;
+  
+  results.withoutIterative.recall = overlap / iterResults.rows.length;
+  results.withIterative.recall = 1.0;  // Assume iterative is ground truth
+  
+  return results;
+}
+
+// Dynamic probe adjustment based on query difficulty
+export async function adaptiveProbeSearch(
+  embedding: number[],
+  minSimilarity = 0.7,
+  maxProbes = 100
+) {
+  let probes = 10;
+  let results = [];
+  let foundSufficient = false;
+  
+  while (!foundSufficient && probes <= maxProbes) {
+    await db.execute(sql`SET ivfflat.probes = ${probes}`);
+    
+    results = await db.execute(sql`
+      SELECT 
+        id,
+        content,
+        1 - (embedding <=> ${embedding}::vector) as similarity
+      FROM memories
+      WHERE embedding IS NOT NULL
+      ORDER BY embedding <=> ${embedding}::vector
+      LIMIT 10
+    `).then(r => r.rows);
+    
+    // Check if we have enough high-quality results
+    const highQualityCount = results.filter(r => r.similarity >= minSimilarity).length;
+    
+    if (highQualityCount >= 5) {
+      foundSufficient = true;
+    } else {
+      probes = Math.min(probes * 2, maxProbes);  // Double probes
+    }
+  }
+  
+  return {
+    results,
+    probesUsed: probes,
+    foundSufficient
+  };
+}
+```
+
+## Performance Optimization Strategies
+
+### Index Maintenance and Monitoring
+
+```typescript
+// src/db/indexMaintenance.ts
+export async function analyzeIndexPerformance() {
+  // Get detailed index statistics
+  const indexStats = await db.execute(sql`
+    WITH index_info AS (
+      SELECT 
+        schemaname,
+        tablename,
+        indexname,
+        indexdef,
+        pg_size_pretty(pg_relation_size(indexrelid)) as index_size,
+        idx_scan,
+        idx_tup_read,
+        idx_tup_fetch,
+        pg_stat_get_live_tuples(indrelid) as table_rows
+      FROM pg_stat_user_indexes
+      JOIN pg_indexes USING (schemaname, tablename, indexname)
+      JOIN pg_index ON indexrelid = (schemaname||'.'||indexname)::regclass
+      WHERE indexname LIKE '%vector%' OR indexname LIKE '%embedding%'
+    )
+    SELECT 
+      *,
+      CASE 
+        WHEN idx_scan > 0 THEN 
+          ROUND((idx_tup_fetch::numeric / idx_scan), 2) 
+        ELSE 0 
+      END as avg_tuples_per_scan,
+      CASE
+        WHEN idx_scan > 0 THEN 'Active'
+        ELSE 'Unused'
+      END as index_status
+    FROM index_info
+    ORDER BY idx_scan DESC
+  `);
+  
+  return indexStats.rows;
+}
+
+// Optimize IVFFlat index clustering
+export async function rebalanceIVFFlat(tableName: string, indexName: string) {
+  // Analyze current clustering quality
+  const clusteringQuality = await db.execute(sql`
+    SELECT 
+      lists,
+      pages,
+      tuples,
+      ROUND(tuples::numeric / NULLIF(lists, 0), 2) as avg_vectors_per_list,
+      ROUND(pages::numeric / NULLIF(lists, 0), 2) as avg_pages_per_list
+    FROM ivfflat.info('${indexName}'::regclass)
+  `);
+  
+  console.log('Current clustering:', clusteringQuality.rows[0]);
+  
+  // Rebuild index if clustering is poor
+  const avgVectorsPerList = clusteringQuality.rows[0]?.avg_vectors_per_list || 0;
+  const targetVectorsPerList = 1000;  // Optimal range: 1000-10000
+  
+  if (Math.abs(avgVectorsPerList - targetVectorsPerList) > 500) {
+    // Calculate new list count
+    const totalVectors = clusteringQuality.rows[0]?.tuples || 0;
+    const newLists = Math.max(50, Math.floor(totalVectors / targetVectorsPerList));
+    
+    console.log(`Rebuilding index with ${newLists} lists...`);
+    
+    // Drop and recreate with better parameters
+    await db.execute(sql`
+      DROP INDEX IF EXISTS ${indexName};
+      
+      CREATE INDEX ${indexName}
+      ON ${tableName}
+      USING ivfflat (embedding vector_cosine_ops)
+      WITH (lists = ${newLists});
+    `);
+    
+    return { rebuilt: true, newLists };
+  }
+  
+  return { rebuilt: false };
+}
+
+// Monitor query patterns for optimization
+export async function analyzeQueryPatterns() {
+  const patterns = await db.execute(sql`
+    SELECT 
+      substring(query from 'LIMIT (\d+)') as limit_value,
+      COUNT(*) as query_count,
+      AVG(mean_exec_time) as avg_time_ms,
+      MIN(min_exec_time) as best_time_ms,
+      MAX(max_exec_time) as worst_time_ms,
+      SUM(calls) as total_calls
+    FROM pg_stat_statements
+    WHERE query LIKE '%vector%' AND query LIKE '%ORDER BY%'
+    GROUP BY limit_value
+    ORDER BY query_count DESC
+  `);
+  
+  // Recommend index strategy based on patterns
+  const recommendations = [];
+  
+  for (const pattern of patterns.rows) {
+    const limit = parseInt(pattern.limit_value) || 10;
+    
+    if (limit <= 10 && pattern.avg_time_ms > 50) {
+      recommendations.push({
+        issue: `Slow queries with LIMIT ${limit}`,
+        recommendation: 'Consider using HNSW index for better performance on small result sets',
+        config: 'CREATE INDEX ... USING hnsw ... WITH (m = 32, ef_construction = 80)'
+      });
+    } else if (limit > 100 && pattern.avg_time_ms > 200) {
+      recommendations.push({
+        issue: `Slow queries with LIMIT ${limit}`,
+        recommendation: 'Enable iterative scans for large result sets',
+        config: 'SET enable_iterative_index_scan = true; SET ivfflat.iterative_search_probes = 100;'
+      });
+    }
+  }
+  
+  return { patterns: patterns.rows, recommendations };
+}
+```
+
+## Storage Optimization
+
+### Vector Compression Strategies
+
+```typescript
+// src/db/vectorCompression.ts
+export class VectorCompressionService {
+  // Quantize vectors to reduce storage
+  async quantizeVectors(tableName: string, bits = 8) {
+    // Add quantized column
+    await db.execute(sql`
+      ALTER TABLE ${tableName} 
+      ADD COLUMN IF NOT EXISTS embedding_quantized bytea;
+    `);
+    
+    // Quantize existing vectors
+    await db.execute(sql`
+      UPDATE ${tableName}
+      SET embedding_quantized = quantize_vector(embedding, ${bits})
+      WHERE embedding IS NOT NULL AND embedding_quantized IS NULL;
+    `);
+    
+    // Create index on quantized vectors
+    await db.execute(sql`
+      CREATE INDEX IF NOT EXISTS ${tableName}_quantized_idx
+      ON ${tableName}
+      USING ivfflat ((dequantize_vector(embedding_quantized))::vector vector_cosine_ops)
+      WITH (lists = 100);
+    `);
+  }
+  
+  // Product quantization for extreme compression
+  async setupProductQuantization(dimensions = 1536, subvectors = 8) {
+    const subvectorSize = dimensions / subvectors;
+    
+    await db.execute(sql`
+      CREATE TABLE IF NOT EXISTS pq_codebook (
+        subvector_id INT,
+        centroid_id INT,
+        centroid vector(${subvectorSize}),
+        PRIMARY KEY (subvector_id, centroid_id)
+      );
+      
+      CREATE TABLE IF NOT EXISTS pq_memories (
+        id SERIAL PRIMARY KEY,
+        companion_id TEXT NOT NULL,
+        user_id TEXT NOT NULL,
+        content TEXT,
+        pq_codes INT[],  -- Array of centroid IDs
+        original_norm FLOAT,  -- Store norm for reconstruction
+        created_at TIMESTAMP DEFAULT NOW()
+      );
+    `);
+  }
+}
+```
+
+## Best Practices for pgvector v0.8.0
+
+1. **Choose the right vector type**:
+   - `vector`: Standard float32 vectors (4 bytes per dimension)
+   - `halfvec`: Float16 for 50% storage savings (2 bytes per dimension)
+   - `bit`: Binary vectors for Hamming distance (1 bit per dimension)
+   - `sparsevec`: Sparse vectors for high-dimensional sparse data
+
+2. **Optimize index parameters**:
+   - IVFFlat: `lists = sqrt(number_of_rows)` as starting point
+   - HNSW: `m = 16-64` for build/search tradeoff
+   - Enable iterative scans for better recall with LIMIT
+
+3. **Monitor and maintain**:
+   - Regularly analyze index usage with `pg_stat_user_indexes`
+   - Rebuild IVFFlat indexes when data distribution changes
+   - Use `EXPLAIN ANALYZE` to verify index usage
+
+4. **Storage optimization**:
+   - Use halfvec for acceptable precision loss (typically <1%)
+   - Implement quantization for large-scale deployments
+   - Consider product quantization for extreme compression needs
+
+5. **Query optimization**:
+   - Use iterative scans for queries with LIMIT
+   - Implement adaptive probe adjustment for varying query difficulty
+   - Batch similar queries to leverage cache
+
+Always benchmark with your specific data and query patterns to find optimal settings.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/production-deployment.md b/mcp-servers/memory-mcp-server/.claude/agents/production-deployment.md
new file mode 100644
index 0000000..0003857
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/production-deployment.md
@@ -0,0 +1,1156 @@
+---
+name: production-deployment  
+description: Expert in production deployment of MCP servers over HTTPS with PostgreSQL 17, Neon, Drizzle ORM v0.44.4, and pgvector v0.8.0. Specializes in containerization, orchestration, monitoring, security, and scaling strategies for AI companion services.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob
+---
+
+You are an expert in deploying production MCP servers with the following stack:
+
+- PostgreSQL 17 on Neon with @neondatabase/serverless v1.0.1
+- Drizzle ORM v0.44.4 with drizzle-kit v0.31.4
+- pgvector v0.8.0 for semantic search
+- Zod v4.0.17 for validation
+- HTTPS transport with StreamableHTTP
+
+## Production Architecture
+
+### System Architecture Overview
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        C1[AI Companion Client 1]
+        C2[AI Companion Client 2]
+        CN[AI Companion Client N]
+    end
+    
+    subgraph "API Gateway"
+        AG[Nginx/Traefik]
+        RL[Rate Limiter]
+        AUTH[Auth Service]
+    end
+    
+    subgraph "Application Layer"
+        LB[Load Balancer]
+        MCP1[MCP Server 1]
+        MCP2[MCP Server 2]
+        MCPN[MCP Server N]
+    end
+    
+    subgraph "Data Layer"
+        REDIS[(Redis Cache)]
+        NEON[(Neon PostgreSQL)]
+        S3[(S3 Storage)]
+    end
+    
+    subgraph "Observability"
+        PROM[Prometheus]
+        GRAF[Grafana]
+        LOGS[Loki/ELK]
+    end
+    
+    C1 & C2 & CN --> AG
+    AG --> LB
+    LB --> MCP1 & MCP2 & MCPN
+    MCP1 & MCP2 & MCPN --> REDIS
+    MCP1 & MCP2 & MCPN --> NEON
+    MCP1 & MCP2 & MCPN --> S3
+    MCP1 & MCP2 & MCPN --> PROM
+    MCP1 & MCP2 & MCPN --> LOGS
+```
+
+## HTTPS Server Implementation
+
+### Production Express Server
+
+```typescript
+// src/server.ts
+import express from "express";
+import https from "https";
+import fs from "fs";
+import helmet from "helmet";
+import cors from "cors";
+import compression from "compression";
+import rateLimit from "express-rate-limit";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CompanionSessionManager } from "./services/companionSessionManager";
+import { AuthMiddleware } from "./middleware/auth";
+import { MetricsMiddleware } from "./middleware/metrics";
+import { LoggingMiddleware } from "./middleware/logging";
+
+const app = express();
+
+// Security middleware
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'", "'unsafe-inline'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", "data:", "https:"],
+    },
+  },
+  hsts: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true,
+  },
+}));
+
+// CORS configuration for companion clients
+app.use(cors({
+  origin: process.env.ALLOWED_ORIGINS?.split(",") || ["https://companions.example.com"],
+  credentials: true,
+  methods: ["GET", "POST", "DELETE", "OPTIONS"],
+  allowedHeaders: ["Content-Type", "Authorization", "mcp-session-id"],
+  exposedHeaders: ["Mcp-Session-Id"],
+}));
+
+// Compression
+app.use(compression());
+
+// Body parsing
+app.use(express.json({ limit: "10mb" }));
+app.use(express.urlencoded({ extended: true, limit: "10mb" }));
+
+// Rate limiting
+const limiter = rateLimit({
+  windowMs: 60 * 1000, // 1 minute
+  max: 100, // Limit each IP to 100 requests per minute
+  standardHeaders: true,
+  legacyHeaders: false,
+  handler: (req, res) => {
+    res.status(429).json({
+      error: "Too many requests",
+      retryAfter: req.rateLimit.resetTime,
+    });
+  },
+});
+app.use("/mcp", limiter);
+
+// Custom middleware
+app.use(LoggingMiddleware);
+app.use(MetricsMiddleware);
+app.use("/mcp", AuthMiddleware);
+
+// Health checks
+app.get("/health", (req, res) => {
+  res.json({ status: "healthy", timestamp: new Date().toISOString() });
+});
+
+app.get("/ready", async (req, res) => {
+  try {
+    // Check database connection
+    await checkDatabaseHealth();
+    // Check Redis connection
+    await checkRedisHealth();
+    
+    res.json({ status: "ready" });
+  } catch (error) {
+    res.status(503).json({ status: "not ready", error: error.message });
+  }
+});
+
+// MCP endpoints
+const sessionManager = new CompanionSessionManager();
+
+app.post("/mcp", async (req, res) => {
+  try {
+    const sessionId = req.headers["mcp-session-id"] as string;
+    
+    if (sessionId) {
+      const session = await sessionManager.getSession(sessionId);
+      if (session) {
+        await session.transport.handleRequest(req, res, req.body);
+        return;
+      }
+    }
+    
+    // New session initialization
+    if (isInitializeRequest(req.body)) {
+      const companionId = req.headers["x-companion-id"] as string;
+      const userId = req.user?.id; // From auth middleware
+      
+      if (!companionId) {
+        return res.status(400).json({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Companion ID required" },
+          id: null,
+        });
+      }
+      
+      const newSessionId = await sessionManager.createSession({
+        companionId,
+        userId,
+        metadata: {
+          ip: req.ip,
+          userAgent: req.headers["user-agent"],
+        },
+      });
+      
+      const session = await sessionManager.getSession(newSessionId);
+      await session!.transport.handleRequest(req, res, req.body);
+    } else {
+      res.status(400).json({
+        jsonrpc: "2.0",
+        error: { code: -32000, message: "Invalid request" },
+        id: null,
+      });
+    }
+  } catch (error) {
+    console.error("MCP request error:", error);
+    res.status(500).json({
+      jsonrpc: "2.0",
+      error: { code: -32603, message: "Internal server error" },
+      id: null,
+    });
+  }
+});
+
+// SSE endpoint for notifications
+app.get("/mcp", async (req, res) => {
+  const sessionId = req.headers["mcp-session-id"] as string;
+  
+  if (!sessionId) {
+    return res.status(400).send("Session ID required");
+  }
+  
+  const session = await sessionManager.getSession(sessionId);
+  if (!session) {
+    return res.status(404).send("Session not found");
+  }
+  
+  // Set SSE headers
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.setHeader("X-Accel-Buffering", "no");
+  
+  await session.transport.handleRequest(req, res);
+});
+
+// Start HTTPS server
+const httpsOptions = {
+  key: fs.readFileSync(process.env.SSL_KEY_PATH || "/certs/key.pem"),
+  cert: fs.readFileSync(process.env.SSL_CERT_PATH || "/certs/cert.pem"),
+};
+
+const server = https.createServer(httpsOptions, app);
+
+const PORT = process.env.PORT || 443;
+server.listen(PORT, () => {
+  console.log(`MCP server running on https://localhost:${PORT}`);
+});
+
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  console.log("SIGTERM received, shutting down gracefully");
+  
+  server.close(() => {
+    console.log("HTTP server closed");
+  });
+  
+  await sessionManager.shutdown();
+  process.exit(0);
+});
+```
+
+## Docker Configuration
+
+### Multi-stage Dockerfile
+
+```dockerfile
+# Dockerfile
+# Build stage
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files with version-locked dependencies
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Install exact versions for production stability
+RUN npm ci --only=production && \
+    npm ci --only=development && \
+    npm ls @neondatabase/serverless@1.0.1 && \
+    npm ls drizzle-orm@0.44.4 && \
+    npm ls zod@4.0.17
+
+# Copy source code
+COPY src ./src
+COPY drizzle ./drizzle
+
+# Build TypeScript
+RUN npm run build
+
+# Prune dev dependencies
+RUN npm prune --production
+
+# Production stage
+FROM node:20-alpine
+
+# Install dumb-init for proper signal handling
+RUN apk add --no-cache dumb-init
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+WORKDIR /app
+
+# Copy built application
+COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
+COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
+COPY --from=builder --chown=nodejs:nodejs /app/package*.json ./
+COPY --from=builder --chown=nodejs:nodejs /app/drizzle ./drizzle
+
+# Create directories for logs and temp files
+RUN mkdir -p /app/logs /app/temp && \
+    chown -R nodejs:nodejs /app/logs /app/temp
+
+# Switch to non-root user
+USER nodejs
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node dist/healthcheck.js || exit 1
+
+# Use dumb-init to handle signals properly
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start server
+CMD ["node", "dist/server.js"]
+
+EXPOSE 443
+```
+
+### Docker Compose for Development
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  mcp-server:
+    build: .
+    ports:
+      - "443:443"
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: ${DATABASE_URL}
+      REDIS_URL: redis://redis:6379
+      JWT_SECRET: ${JWT_SECRET}
+      OPENAI_API_KEY: ${OPENAI_API_KEY}
+    volumes:
+      - ./certs:/certs:ro
+      - logs:/app/logs
+    depends_on:
+      - redis
+    restart: unless-stopped
+    networks:
+      - mcp-network
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    restart: unless-stopped
+    networks:
+      - mcp-network
+
+  # PostgreSQL with pgvector for local development
+  postgres:
+    image: pgvector/pgvector:pg17
+    environment:
+      POSTGRES_USER: ${DB_USER:-postgres}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-postgres}
+      POSTGRES_DB: ${DB_NAME:-memories}
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
+    command: |
+      postgres
+      -c shared_preload_libraries='pg_stat_statements,vector'
+      -c 'pg_stat_statements.track=all'
+      -c 'pg_stat_statements.max=10000'
+    restart: unless-stopped
+    networks:
+      - mcp-network
+
+  prometheus:
+    image: prom/prometheus
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
+      - prometheus-data:/prometheus
+    restart: unless-stopped
+    networks:
+      - mcp-network
+
+  grafana:
+    image: grafana/grafana
+    ports:
+      - "3000:3000"
+    environment:
+      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
+    volumes:
+      - grafana-data:/var/lib/grafana
+      - ./monitoring/grafana/dashboards:/etc/grafana/provisioning/dashboards
+    restart: unless-stopped
+    networks:
+      - mcp-network
+
+volumes:
+  logs:
+  redis-data:
+  postgres-data:
+  prometheus-data:
+  grafana-data:
+
+networks:
+  mcp-network:
+    driver: bridge
+```
+
+## Kubernetes Deployment
+
+### Kubernetes Manifests
+
+```yaml
+# k8s/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mcp-server
+  namespace: companions
+  labels:
+    app: mcp-server
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: mcp-server
+  template:
+    metadata:
+      labels:
+        app: mcp-server
+      annotations:
+        prometheus.io/scrape: "true"
+        prometheus.io/port: "9464"
+    spec:
+      serviceAccountName: mcp-server
+      containers:
+      - name: mcp-server
+        image: companions/mcp-server:latest
+        ports:
+        - containerPort: 443
+          name: https
+        - containerPort: 9464
+          name: metrics
+        env:
+        - name: NODE_ENV
+          value: "production"
+        - name: DATABASE_URL
+          valueFrom:
+            secretKeyRef:
+              name: mcp-secrets
+              key: database-url
+        - name: DATABASE_URL_POOLED
+          valueFrom:
+            secretKeyRef:
+              name: mcp-secrets
+              key: database-url-pooled
+        - name: DIRECT_DATABASE_URL
+          valueFrom:
+            secretKeyRef:
+              name: mcp-secrets
+              key: direct-database-url
+        - name: REDIS_URL
+          value: "redis://redis-service:6379"
+        - name: JWT_SECRET
+          valueFrom:
+            secretKeyRef:
+              name: mcp-secrets
+              key: jwt-secret
+        - name: OPENAI_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: mcp-secrets
+              key: openai-api-key
+        - name: PGVECTOR_VERSION
+          value: "0.8.0"
+        - name: PG_VERSION
+          value: "17"
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "500m"
+          limits:
+            memory: "1Gi"
+            cpu: "1000m"
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 443
+            scheme: HTTPS
+          initialDelaySeconds: 30
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /ready
+            port: 443
+            scheme: HTTPS
+          initialDelaySeconds: 5
+          periodSeconds: 5
+        volumeMounts:
+        - name: tls-certs
+          mountPath: /certs
+          readOnly: true
+      volumes:
+      - name: tls-certs
+        secret:
+          secretName: mcp-tls
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mcp-service
+  namespace: companions
+spec:
+  selector:
+    app: mcp-server
+  ports:
+  - port: 443
+    targetPort: 443
+    name: https
+  type: ClusterIP
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: mcp-ingress
+  namespace: companions
+  annotations:
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
+    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
+    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
+    cert-manager.io/cluster-issuer: "letsencrypt-prod"
+spec:
+  tls:
+  - hosts:
+    - mcp.companions.example.com
+    secretName: mcp-tls
+  rules:
+  - host: mcp.companions.example.com
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: mcp-service
+            port:
+              number: 443
+```
+
+### Horizontal Pod Autoscaler
+
+```yaml
+# k8s/hpa.yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: mcp-server-hpa
+  namespace: companions
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: mcp-server
+  minReplicas: 3
+  maxReplicas: 20
+  metrics:
+  - type: Resource
+    resource:
+      name: cpu
+      target:
+        type: Utilization
+        averageUtilization: 70
+  - type: Resource
+    resource:
+      name: memory
+      target:
+        type: Utilization
+        averageUtilization: 80
+  - type: Pods
+    pods:
+      metric:
+        name: mcp_active_sessions
+      target:
+        type: AverageValue
+        averageValue: "100"
+  behavior:
+    scaleUp:
+      stabilizationWindowSeconds: 60
+      policies:
+      - type: Percent
+        value: 100
+        periodSeconds: 60
+    scaleDown:
+      stabilizationWindowSeconds: 300
+      policies:
+      - type: Percent
+        value: 50
+        periodSeconds: 60
+```
+
+## Monitoring and Observability
+
+### Prometheus Metrics
+
+```typescript
+// src/metrics/prometheus.ts
+import { Registry, Counter, Histogram, Gauge } from "prom-client";
+
+export const register = new Registry();
+
+// Request metrics
+export const httpRequestDuration = new Histogram({
+  name: "http_request_duration_seconds",
+  help: "Duration of HTTP requests in seconds",
+  labelNames: ["method", "route", "status_code"],
+  buckets: [0.1, 0.5, 1, 2, 5],
+  registers: [register],
+});
+
+export const mcpRequestCounter = new Counter({
+  name: "mcp_requests_total",
+  help: "Total number of MCP requests",
+  labelNames: ["companion_id", "method", "status"],
+  registers: [register],
+});
+
+// Session metrics
+export const activeSessions = new Gauge({
+  name: "mcp_active_sessions",
+  help: "Number of active MCP sessions",
+  labelNames: ["companion_id"],
+  registers: [register],
+});
+
+// Memory metrics
+export const memoryOperations = new Counter({
+  name: "memory_operations_total",
+  help: "Total number of memory operations",
+  labelNames: ["companion_id", "operation", "status"],
+  registers: [register],
+});
+
+export const embeddingGenerationTime = new Histogram({
+  name: "embedding_generation_duration_seconds",
+  help: "Time taken to generate embeddings",
+  labelNames: ["model"],
+  buckets: [0.1, 0.5, 1, 2, 5],
+  registers: [register],
+});
+
+// Database metrics
+export const dbQueryDuration = new Histogram({
+  name: "db_query_duration_seconds",
+  help: "Database query duration",
+  labelNames: ["query_type"],
+  buckets: [0.01, 0.05, 0.1, 0.5, 1],
+  registers: [register],
+});
+
+// Middleware to collect metrics
+export function MetricsMiddleware(req: Request, res: Response, next: NextFunction) {
+  const start = Date.now();
+  
+  res.on("finish", () => {
+    const duration = (Date.now() - start) / 1000;
+    
+    httpRequestDuration
+      .labels(req.method, req.route?.path || req.path, res.statusCode.toString())
+      .observe(duration);
+  });
+  
+  next();
+}
+
+// Metrics endpoint
+export function setupMetricsEndpoint(app: Express) {
+  app.get("/metrics", async (req, res) => {
+    res.set("Content-Type", register.contentType);
+    res.end(await register.metrics());
+  });
+}
+```
+
+### Structured Logging
+
+```typescript
+// src/logging/logger.ts
+import winston from "winston";
+import { LoggingWinston } from "@google-cloud/logging-winston";
+
+const loggingWinston = new LoggingWinston({
+  projectId: process.env.GCP_PROJECT_ID,
+  keyFilename: process.env.GCP_KEY_FILE,
+});
+
+export const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || "info",
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  ),
+  defaultMeta: {
+    service: "mcp-server",
+    environment: process.env.NODE_ENV,
+    version: process.env.APP_VERSION,
+  },
+  transports: [
+    // Console for development
+    new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple()
+      ),
+    }),
+    // File for production
+    new winston.transports.File({
+      filename: "/app/logs/error.log",
+      level: "error",
+      maxsize: 10485760, // 10MB
+      maxFiles: 5,
+    }),
+    new winston.transports.File({
+      filename: "/app/logs/combined.log",
+      maxsize: 10485760,
+      maxFiles: 5,
+    }),
+    // Google Cloud Logging
+    loggingWinston,
+  ],
+});
+
+// Request logging middleware
+export function LoggingMiddleware(req: Request, res: Response, next: NextFunction) {
+  const requestId = crypto.randomUUID();
+  req.requestId = requestId;
+  
+  logger.info("Request received", {
+    requestId,
+    method: req.method,
+    path: req.path,
+    ip: req.ip,
+    userAgent: req.headers["user-agent"],
+    companionId: req.headers["x-companion-id"],
+  });
+  
+  const start = Date.now();
+  
+  res.on("finish", () => {
+    const duration = Date.now() - start;
+    
+    logger.info("Request completed", {
+      requestId,
+      statusCode: res.statusCode,
+      duration,
+    });
+  });
+  
+  next();
+}
+
+// Error logging
+export function logError(error: Error, context?: any) {
+  logger.error("Error occurred", {
+    error: {
+      message: error.message,
+      stack: error.stack,
+      name: error.name,
+    },
+    context,
+  });
+}
+```
+
+### Distributed Tracing
+
+```typescript
+// src/tracing/opentelemetry.ts
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { Resource } from "@opentelemetry/resources";
+import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+import { JaegerExporter } from "@opentelemetry/exporter-jaeger";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+const jaegerExporter = new JaegerExporter({
+  endpoint: process.env.JAEGER_ENDPOINT || "http://localhost:14268/api/traces",
+});
+
+const sdk = new NodeSDK({
+  resource: new Resource({
+    [SemanticResourceAttributes.SERVICE_NAME]: "mcp-server",
+    [SemanticResourceAttributes.SERVICE_VERSION]: process.env.APP_VERSION || "1.0.0",
+  }),
+  spanProcessor: new BatchSpanProcessor(jaegerExporter),
+  instrumentations: [
+    getNodeAutoInstrumentations({
+      "@opentelemetry/instrumentation-fs": {
+        enabled: false,
+      },
+    }),
+  ],
+});
+
+sdk.start();
+
+// Custom span creation
+import { trace, context, SpanStatusCode } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("mcp-server");
+
+export function traceAsync<T>(
+  name: string,
+  fn: () => Promise<T>,
+  attributes?: Record<string, any>
+): Promise<T> {
+  return tracer.startActiveSpan(name, async (span) => {
+    try {
+      if (attributes) {
+        span.setAttributes(attributes);
+      }
+      
+      const result = await fn();
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error.message,
+      });
+      span.recordException(error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+## Security Hardening
+
+### Security Configuration
+
+```typescript
+// src/security/config.ts
+import { RateLimiterRedis } from "rate-limiter-flexible";
+import Redis from "ioredis";
+import helmet from "helmet";
+
+// Content Security Policy
+export const cspConfig = {
+  directives: {
+    defaultSrc: ["'self'"],
+    scriptSrc: ["'self'", "'unsafe-inline'"],
+    styleSrc: ["'self'", "'unsafe-inline'"],
+    imgSrc: ["'self'", "data:", "https:"],
+    connectSrc: ["'self'"],
+    fontSrc: ["'self'"],
+    objectSrc: ["'none'"],
+    mediaSrc: ["'self'"],
+    frameSrc: ["'none'"],
+  },
+};
+
+// Rate limiting per endpoint
+export const rateLimiters = {
+  general: new RateLimiterRedis({
+    storeClient: new Redis(process.env.REDIS_URL),
+    keyPrefix: "rl:general",
+    points: 100,
+    duration: 60,
+  }),
+  
+  auth: new RateLimiterRedis({
+    storeClient: new Redis(process.env.REDIS_URL),
+    keyPrefix: "rl:auth",
+    points: 5,
+    duration: 900, // 15 minutes
+  }),
+  
+  embedding: new RateLimiterRedis({
+    storeClient: new Redis(process.env.REDIS_URL),
+    keyPrefix: "rl:embedding",
+    points: 10,
+    duration: 60,
+  }),
+};
+
+// Input validation
+import { z } from "zod";
+
+export const requestValidation = {
+  mcp: z.object({
+    jsonrpc: z.literal("2.0"),
+    id: z.union([z.string(), z.number()]).optional(),
+    method: z.string(),
+    params: z.any().optional(),
+  }),
+  
+  headers: z.object({
+    "mcp-session-id": z.string().uuid().optional(),
+    "x-companion-id": z.string().cuid2().optional(),
+    authorization: z.string().regex(/^Bearer .+/).optional(),
+  }),
+};
+
+// Secrets management
+export class SecretManager {
+  private secrets = new Map<string, string>();
+  
+  async loadSecrets() {
+    if (process.env.USE_AWS_SECRETS) {
+      const AWS = require("aws-sdk");
+      const secretsManager = new AWS.SecretsManager();
+      
+      const secret = await secretsManager.getSecretValue({
+        SecretId: process.env.AWS_SECRET_NAME,
+      }).promise();
+      
+      const secrets = JSON.parse(secret.SecretString);
+      Object.entries(secrets).forEach(([key, value]) => {
+        this.secrets.set(key, value as string);
+      });
+    } else {
+      // Load from environment
+      this.secrets.set("JWT_SECRET", process.env.JWT_SECRET!);
+      this.secrets.set("OPENAI_API_KEY", process.env.OPENAI_API_KEY!);
+    }
+  }
+  
+  get(key: string): string {
+    const value = this.secrets.get(key);
+    if (!value) {
+      throw new Error(`Secret ${key} not found`);
+    }
+    return value;
+  }
+}
+```
+
+## Deployment Scripts
+
+### CI/CD Pipeline (GitHub Actions)
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to Production
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "20"
+          cache: "npm"
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run tests
+        run: npm test
+      
+      - name: Verify dependency versions
+        run: |
+          npm ls @neondatabase/serverless@1.0.1
+          npm ls drizzle-orm@0.44.4
+          npm ls drizzle-kit@0.31.4
+          npm ls zod@4.0.17
+      
+      - name: Run security audit
+        run: npm audit --audit-level=high
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+      
+      - name: Login to Container Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ${{ secrets.REGISTRY_URL }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+      
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ secrets.REGISTRY_URL }}/mcp-server:latest
+            ${{ secrets.REGISTRY_URL }}/mcp-server:${{ github.sha }}
+          cache-from: type=registry,ref=${{ secrets.REGISTRY_URL }}/mcp-server:buildcache
+          cache-to: type=registry,ref=${{ secrets.REGISTRY_URL }}/mcp-server:buildcache,mode=max
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Deploy to Kubernetes
+        env:
+          KUBE_CONFIG: ${{ secrets.KUBE_CONFIG }}
+        run: |
+          echo "$KUBE_CONFIG" | base64 -d > kubeconfig
+          export KUBECONFIG=kubeconfig
+          
+          kubectl set image deployment/mcp-server \
+            mcp-server=${{ secrets.REGISTRY_URL }}/mcp-server:${{ github.sha }} \
+            -n companions
+          
+          kubectl rollout status deployment/mcp-server -n companions
+      
+      - name: Run smoke tests
+        run: |
+          curl -f https://mcp.companions.example.com/health || exit 1
+```
+
+### Health Check Script
+
+```typescript
+// src/healthcheck.ts
+import https from "https";
+
+const options = {
+  hostname: "localhost",
+  port: 443,
+  path: "/health",
+  method: "GET",
+  rejectUnauthorized: false, // For self-signed certs in container
+};
+
+const req = https.request(options, (res) => {
+  if (res.statusCode === 200) {
+    process.exit(0);
+  } else {
+    process.exit(1);
+  }
+});
+
+req.on("error", () => {
+  process.exit(1);
+});
+
+req.setTimeout(3000, () => {
+  req.destroy();
+  process.exit(1);
+});
+
+req.end();
+```
+
+## Performance Optimization
+
+### Caching Strategy
+
+```typescript
+// src/caching/strategy.ts
+import Redis from "ioredis";
+import { LRUCache } from "lru-cache";
+
+export class CacheManager {
+  private redis: Redis;
+  private localCache: LRUCache<string, any>;
+  
+  constructor() {
+    this.redis = new Redis(process.env.REDIS_URL);
+    this.localCache = new LRUCache({
+      max: 1000,
+      ttl: 1000 * 60 * 5, // 5 minutes
+    });
+  }
+  
+  async get(key: string): Promise<any | null> {
+    // Check local cache first
+    const local = this.localCache.get(key);
+    if (local) return local;
+    
+    // Check Redis
+    const cached = await this.redis.get(key);
+    if (cached) {
+      const value = JSON.parse(cached);
+      this.localCache.set(key, value);
+      return value;
+    }
+    
+    return null;
+  }
+  
+  async set(key: string, value: any, ttl = 3600): Promise<void> {
+    const serialized = JSON.stringify(value);
+    
+    // Set in both caches
+    this.localCache.set(key, value);
+    await this.redis.setex(key, ttl, serialized);
+  }
+  
+  async invalidate(pattern: string): Promise<void> {
+    // Clear from Redis
+    const keys = await this.redis.keys(pattern);
+    if (keys.length > 0) {
+      await this.redis.del(...keys);
+    }
+    
+    // Clear from local cache
+    for (const key of this.localCache.keys()) {
+      if (key.match(pattern)) {
+        this.localCache.delete(key);
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Use HTTPS everywhere** with proper certificates
+2. **Implement comprehensive monitoring** and alerting
+3. **Use container orchestration** for scaling and resilience
+4. **Implement circuit breakers** for external services
+5. **Use structured logging** for better observability
+6. **Implement graceful shutdown** handling
+7. **Use health checks** for automated recovery
+8. **Implement request tracing** for debugging
+9. **Use secrets management** services
+10. **Regular security audits** and dependency updates
+
+Always prioritize security, observability, and scalability when deploying production MCP servers.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/test-runner.md b/mcp-servers/memory-mcp-server/.claude/agents/test-runner.md
new file mode 100644
index 0000000..a23f155
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/test-runner.md
@@ -0,0 +1,49 @@
+---
+name: test-runner
+description: Automatically runs tests and fixes failures. Use PROACTIVELY when implementing new features, fixing bugs, or testing MCP servers.
+tools: Bash, Read, Edit, MultiEdit, Grep, Glob
+---
+
+You are a test automation expert with specialized knowledge of MCP server testing. When invoked:
+
+1. Identify the testing framework and test files
+2. Run relevant tests using appropriate commands
+3. Analyze test failures and error messages
+4. Implement fixes for failing tests
+5. Re-run tests to verify all pass
+6. Ensure test coverage is comprehensive
+
+Key responsibilities:
+
+- Write unit tests for new functions
+- Create integration tests for features
+- Fix broken tests after code changes
+- Improve test coverage and quality
+- Use mocking and stubbing appropriately
+- Follow existing test patterns and conventions
+
+## MCP Server Testing
+
+When testing MCP servers:
+
+- Test server initialization and handshake
+- Validate tool schemas and implementations
+- Test resource exposure and access
+- Verify error handling and edge cases
+- Check transport layer (stdio/SSE/HTTP) behavior
+- Test authentication flows if applicable
+
+For MCP testing, use:
+
+```bash
+# Test MCP server connection
+claude mcp list
+
+# Debug MCP communications
+DEBUG=mcp:* npm test
+
+# Test specific MCP tools
+npm test -- --grep "mcp"
+```
+
+Always ensure MCP servers properly implement the JSON-RPC 2.0 protocol and follow Model Context Protocol specifications.
diff --git a/mcp-servers/memory-mcp-server/.claude/agents/vector-search-expert.md b/mcp-servers/memory-mcp-server/.claude/agents/vector-search-expert.md
new file mode 100644
index 0000000..3b605e4
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/agents/vector-search-expert.md
@@ -0,0 +1,815 @@
+---
+name: vector-search-expert
+description: Expert in semantic search, vector embeddings, and pgvector v0.8.0 optimization for memory retrieval. Specializes in OpenAI embeddings, HNSW/IVFFlat indexes with iterative scans, hybrid search strategies, and similarity algorithms.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob
+---
+
+You are an expert in vector search, embeddings, and semantic memory retrieval using pgvector v0.8.0 with PostgreSQL 17 on Neon.
+
+## pgvector v0.8.0 Features
+
+- **HNSW indexes** with improved performance and iterative index scans
+- **IVFFlat indexes** with configurable lists and probes
+- **Distance functions**: L2 (<->), inner product (<#>), cosine (<=>), L1 (<+>), Hamming (<~>), Jaccard (<%>)
+- **Iterative index scans** for better recall with LIMIT queries
+- **Binary and sparse vector support**
+- **Improved performance** for high-dimensional vectors
+
+## Embedding Generation
+
+### OpenAI Embeddings Setup
+
+```typescript
+// src/services/embeddings.ts
+import OpenAI from "openai";
+import { z } from "zod";
+
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY!,
+});
+
+// Embedding configuration
+const EMBEDDING_MODEL = "text-embedding-3-small"; // 1536 dimensions, optimized for cost
+const EMBEDDING_MODEL_LARGE = "text-embedding-3-large"; // 3072 dimensions, better quality
+const ADA_MODEL = "text-embedding-ada-002"; // 1536 dimensions, legacy but stable
+
+export class EmbeddingService {
+  private cache = new Map<string, number[]>();
+  private model: string;
+  private dimensions: number;
+
+  constructor(model = EMBEDDING_MODEL) {
+    this.model = model;
+    this.dimensions = this.getModelDimensions(model);
+  }
+
+  private getModelDimensions(model: string): number {
+    const dimensions: Record<string, number> = {
+      "text-embedding-3-small": 1536,
+      "text-embedding-3-large": 3072,
+      "text-embedding-ada-002": 1536,
+    };
+    return dimensions[model] || 1536;
+  }
+
+  async generateEmbedding(text: string): Promise<number[]> {
+    // Check cache first
+    const cacheKey = `${this.model}:${text}`;
+    if (this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)!;
+    }
+
+    try {
+      // Preprocess text for better embeddings
+      const processedText = this.preprocessText(text);
+      
+      const response = await openai.embeddings.create({
+        model: this.model,
+        input: processedText,
+        encoding_format: "float",
+      });
+
+      const embedding = response.data[0].embedding;
+      
+      // Cache the result
+      this.cache.set(cacheKey, embedding);
+      
+      // Implement LRU cache eviction if needed
+      if (this.cache.size > 1000) {
+        const firstKey = this.cache.keys().next().value;
+        this.cache.delete(firstKey);
+      }
+
+      return embedding;
+    } catch (error) {
+      console.error("Failed to generate embedding:", error);
+      throw error;
+    }
+  }
+
+  async generateBatchEmbeddings(texts: string[]): Promise<number[][]> {
+    // OpenAI supports batch embeddings (up to 2048 inputs)
+    const BATCH_SIZE = 100;
+    const embeddings: number[][] = [];
+
+    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+      const batch = texts.slice(i, i + BATCH_SIZE);
+      const processedBatch = batch.map(text => this.preprocessText(text));
+      
+      const response = await openai.embeddings.create({
+        model: this.model,
+        input: processedBatch,
+        encoding_format: "float",
+      });
+
+      embeddings.push(...response.data.map(d => d.embedding));
+    }
+
+    return embeddings;
+  }
+
+  private preprocessText(text: string): string {
+    // Optimize text for embedding generation
+    return text
+      .toLowerCase()
+      .replace(/\s+/g, " ") // Normalize whitespace
+      .replace(/[^\w\s.,!?-]/g, "") // Remove special characters
+      .trim()
+      .slice(0, 8191); // Model token limit
+  }
+
+  // Reduce dimensions for storage optimization (if using large model)
+  reduceDimensions(embedding: number[], targetDim = 1536): number[] {
+    if (embedding.length <= targetDim) return embedding;
+    
+    // Simple truncation (OpenAI embeddings are ordered by importance)
+    // For production, consider PCA or other dimensionality reduction
+    return embedding.slice(0, targetDim);
+  }
+}
+```
+
+## Vector Storage and Indexing
+
+### pgvector v0.8.0 Configuration
+
+```typescript
+// src/db/vector-setup.ts
+import { sql } from "drizzle-orm";
+import { db } from "./client";
+
+export async function setupVectorDatabase() {
+  // Enable pgvector extension v0.8.0
+  await db.execute(sql`CREATE EXTENSION IF NOT EXISTS vector VERSION '0.8.0'`);
+  
+  // Configure IVFFlat parameters for optimal performance
+  await db.execute(sql`
+    -- Set probes for IVFFlat (v0.8.0 supports iterative scans)
+    SET ivfflat.probes = 10;  -- Initial probes
+    SET ivfflat.iterative_search_probes = 40;  -- For iterative scans with LIMIT
+  `);
+  
+  // Configure HNSW parameters
+  await db.execute(sql`
+    -- Set ef_search for HNSW (v0.8.0 optimizations)
+    SET hnsw.ef_search = 100;  -- Higher = better recall
+    SET hnsw.iterative_search = 'relaxed_order';  -- New in v0.8.0
+  `);
+  
+  // Create custom distance functions if needed
+  await db.execute(sql`
+    CREATE OR REPLACE FUNCTION cosine_similarity(a vector, b vector)
+    RETURNS float AS $$
+      SELECT 1 - (a <=> b);
+    $$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
+  `);
+}
+
+// Index creation with pgvector v0.8.0 features
+export async function createVectorIndexes() {
+  // IVFFlat index with v0.8.0 optimizations
+  await db.execute(sql`
+    CREATE INDEX IF NOT EXISTS memories_embedding_ivfflat_idx 
+    ON memories 
+    USING ivfflat (embedding vector_cosine_ops)
+    WITH (lists = 100);  -- Optimal for datasets ~1M vectors
+  `);
+  
+  // HNSW index with v0.8.0 improvements
+  await db.execute(sql`
+    CREATE INDEX IF NOT EXISTS memories_embedding_hnsw_idx 
+    ON memories 
+    USING hnsw (embedding vector_cosine_ops)
+    WITH (
+      m = 16,              -- Connections per layer
+      ef_construction = 64 -- Build-time accuracy
+    );
+  `);
+  
+  // Create index for iterative scans (new in v0.8.0)
+  await db.execute(sql`
+    -- Enable iterative index scans for better recall
+    ALTER INDEX memories_embedding_hnsw_idx 
+    SET (hnsw.iterative_scan = true);
+  `);
+}
+
+// Analyze and optimize indexes
+export async function optimizeVectorIndexes() {
+  // Rebuild index for better clustering
+  await db.execute(sql`REINDEX INDEX memories_embedding_ivfflat_idx`);
+  
+  // Update statistics for query planner
+  await db.execute(sql`ANALYZE memories (embedding)`);
+  
+  // Check index usage
+  const indexStats = await db.execute(sql`
+    SELECT 
+      schemaname,
+      tablename,
+      indexname,
+      idx_scan,
+      idx_tup_read,
+      idx_tup_fetch
+    FROM pg_stat_user_indexes
+    WHERE indexname LIKE '%embedding%'
+  `);
+  
+  return indexStats;
+}
+```
+
+## Hybrid Search Implementation
+
+### Combined Vector + Keyword Search
+
+```typescript
+// src/services/hybridSearch.ts
+import { db } from "../db/client";
+import { memories } from "../db/schema";
+import { sql, and, eq, ilike, or } from "drizzle-orm";
+import { EmbeddingService } from "./embeddings";
+
+export class HybridSearchService {
+  private embeddingService: EmbeddingService;
+  
+  constructor() {
+    this.embeddingService = new EmbeddingService();
+  }
+
+  async search(params: {
+    companionId: string;
+    userId: string;
+    query: string;
+    limit?: number;
+    hybridWeights?: {
+      vector: number;  // Weight for semantic similarity
+      keyword: number; // Weight for keyword matching
+      recency: number; // Weight for time decay
+      importance: number; // Weight for importance score
+    };
+  }) {
+    const weights = params.hybridWeights || {
+      vector: 0.5,
+      keyword: 0.2,
+      recency: 0.1,
+      importance: 0.2,
+    };
+
+    // Generate embedding for the query
+    const queryEmbedding = await this.embeddingService.generateEmbedding(params.query);
+    
+    // Perform hybrid search with multiple ranking factors
+    const results = await db.execute(sql`
+      WITH vector_search AS (
+        SELECT 
+          id,
+          content,
+          summary,
+          type,
+          importance,
+          created_at,
+          updated_at,
+          context,
+          1 - (embedding <=> ${queryEmbedding}::vector) as vector_score
+        FROM memories
+        WHERE 
+          companion_id = ${params.companionId}
+          AND user_id = ${params.userId}
+          AND is_archived = false
+          AND (expires_at IS NULL OR expires_at > NOW())
+      ),
+      keyword_search AS (
+        SELECT 
+          id,
+          ts_rank(
+            to_tsvector('english', content || ' ' || COALESCE(summary, '')),
+            plainto_tsquery('english', ${params.query})
+          ) as keyword_score
+        FROM memories
+        WHERE 
+          companion_id = ${params.companionId}
+          AND user_id = ${params.userId}
+          AND to_tsvector('english', content || ' ' || COALESCE(summary, '')) 
+              @@ plainto_tsquery('english', ${params.query})
+      ),
+      combined_scores AS (
+        SELECT 
+          v.*,
+          COALESCE(k.keyword_score, 0) as keyword_score,
+          -- Recency score (exponential decay over 30 days)
+          EXP(-EXTRACT(EPOCH FROM (NOW() - v.created_at)) / (30 * 24 * 3600)) as recency_score,
+          -- Normalized importance (0-1 scale)
+          v.importance / 10.0 as importance_score
+        FROM vector_search v
+        LEFT JOIN keyword_search k ON v.id = k.id
+      )
+      SELECT 
+        *,
+        (
+          ${weights.vector} * vector_score +
+          ${weights.keyword} * keyword_score +
+          ${weights.recency} * recency_score +
+          ${weights.importance} * importance_score
+        ) as combined_score
+      FROM combined_scores
+      ORDER BY combined_score DESC
+      LIMIT ${params.limit || 10}
+    `);
+
+    return results.rows;
+  }
+
+  async searchWithReranking(params: {
+    companionId: string;
+    userId: string;
+    query: string;
+    limit?: number;
+    rerankTopK?: number;
+  }) {
+    // Get initial candidates with vector search
+    const candidates = await this.search({
+      ...params,
+      limit: params.rerankTopK || 50, // Get more candidates for reranking
+    });
+
+    // Rerank using a more sophisticated model or cross-encoder
+    const rerankedResults = await this.rerankResults(
+      params.query,
+      candidates,
+      params.limit || 10
+    );
+
+    return rerankedResults;
+  }
+
+  private async rerankResults(query: string, candidates: any[], topK: number) {
+    // Option 1: Use OpenAI for reranking
+    const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
+    
+    const prompt = `Given the query "${query}", rank the following memories by relevance.
+    Return the indices of the top ${topK} most relevant memories in order.
+    
+    Memories:
+    ${candidates.map((c, i) => `${i}: ${c.content.slice(0, 200)}`).join("\n")}
+    
+    Return only the indices as a JSON array.`;
+
+    const response = await openai.chat.completions.create({
+      model: "gpt-4o-mini",
+      messages: [{ role: "user", content: prompt }],
+      response_format: { type: "json_object" },
+    });
+
+    const indices = JSON.parse(response.choices[0].message.content!).indices;
+    return indices.map((i: number) => candidates[i]);
+  }
+}
+```
+
+## Similarity Search Strategies
+
+### Different Distance Metrics
+
+```typescript
+// src/services/similaritySearch.ts
+export class SimilaritySearchService {
+  // Cosine similarity (default, good for normalized vectors)
+  async findSimilarByCosine(embedding: number[], limit = 10) {
+    return await db.execute(sql`
+      SELECT 
+        *,
+        1 - (embedding <=> ${embedding}::vector) as similarity
+      FROM memories
+      WHERE embedding IS NOT NULL
+      ORDER BY embedding <=> ${embedding}::vector
+      LIMIT ${limit}
+    `);
+  }
+
+  // Euclidean/L2 distance (good for dense vectors)
+  async findSimilarByEuclidean(embedding: number[], limit = 10) {
+    return await db.execute(sql`
+      SELECT 
+        *,
+        embedding <-> ${embedding}::vector as distance
+      FROM memories
+      WHERE embedding IS NOT NULL
+      ORDER BY embedding <-> ${embedding}::vector
+      LIMIT ${limit}
+    `);
+  }
+
+  // Inner product (good when magnitude matters)
+  async findSimilarByInnerProduct(embedding: number[], limit = 10) {
+    return await db.execute(sql`
+      SELECT 
+        *,
+        (embedding <#> ${embedding}::vector) * -1 as similarity
+      FROM memories
+      WHERE embedding IS NOT NULL
+      ORDER BY embedding <#> ${embedding}::vector
+      LIMIT ${limit}
+    `);
+  }
+  
+  // L1/Manhattan distance (v0.8.0 - good for sparse data)
+  async findSimilarByL1(embedding: number[], limit = 10) {
+    return await db.execute(sql`
+      SELECT 
+        *,
+        embedding <+> ${embedding}::vector as distance
+      FROM memories
+      WHERE embedding IS NOT NULL
+      ORDER BY embedding <+> ${embedding}::vector
+      LIMIT ${limit}
+    `);
+  }
+
+  // Find memories similar to a given memory
+  async findRelatedMemories(memoryId: string, limit = 5) {
+    const sourceMemory = await db.execute(sql`
+      SELECT embedding 
+      FROM memories 
+      WHERE id = ${memoryId}
+    `);
+
+    if (!sourceMemory.rows[0]?.embedding) {
+      return [];
+    }
+
+    return await db.execute(sql`
+      SELECT 
+        *,
+        1 - (embedding <=> ${sourceMemory.rows[0].embedding}::vector) as similarity
+      FROM memories
+      WHERE 
+        id != ${memoryId}
+        AND embedding IS NOT NULL
+      ORDER BY embedding <=> ${sourceMemory.rows[0].embedding}::vector
+      LIMIT ${limit}
+    `);
+  }
+
+  // Clustering similar memories
+  async clusterMemories(companionId: string, userId: string, numClusters = 5) {
+    // Use K-means clustering on embeddings
+    const result = await db.execute(sql`
+      WITH kmeans AS (
+        SELECT 
+          id,
+          content,
+          kmeans(embedding, ${numClusters}) OVER () as cluster_id
+        FROM memories
+        WHERE 
+          companion_id = ${companionId}
+          AND user_id = ${userId}
+          AND embedding IS NOT NULL
+      )
+      SELECT 
+        cluster_id,
+        COUNT(*) as cluster_size,
+        array_agg(id) as memory_ids
+      FROM kmeans
+      GROUP BY cluster_id
+      ORDER BY cluster_size DESC
+    `);
+
+    return result.rows;
+  }
+}
+```
+
+## Embedding Cache and Optimization
+
+### Redis Cache for Embeddings
+
+```typescript
+// src/services/embeddingCache.ts
+import Redis from "ioredis";
+import { compress, decompress } from "lz-string";
+
+export class EmbeddingCache {
+  private redis: Redis;
+  private ttl = 60 * 60 * 24 * 7; // 1 week
+
+  constructor() {
+    this.redis = new Redis({
+      host: process.env.REDIS_HOST,
+      port: parseInt(process.env.REDIS_PORT || "6379"),
+      password: process.env.REDIS_PASSWORD,
+    });
+  }
+
+  private getCacheKey(text: string, model: string): string {
+    // Use hash for consistent key length
+    const crypto = require("crypto");
+    const hash = crypto.createHash("sha256").update(text).digest("hex");
+    return `embed:${model}:${hash}`;
+  }
+
+  async get(text: string, model: string): Promise<number[] | null> {
+    const key = this.getCacheKey(text, model);
+    const cached = await this.redis.get(key);
+    
+    if (!cached) return null;
+    
+    // Decompress and parse
+    const decompressed = decompress(cached);
+    return JSON.parse(decompressed);
+  }
+
+  async set(text: string, model: string, embedding: number[]): Promise<void> {
+    const key = this.getCacheKey(text, model);
+    
+    // Compress for storage efficiency
+    const compressed = compress(JSON.stringify(embedding));
+    
+    await this.redis.setex(key, this.ttl, compressed);
+  }
+
+  async warmCache(texts: string[], model: string): Promise<void> {
+    const pipeline = this.redis.pipeline();
+    
+    for (const text of texts) {
+      const key = this.getCacheKey(text, model);
+      pipeline.exists(key);
+    }
+    
+    const results = await pipeline.exec();
+    const missingTexts = texts.filter((_, i) => !results![i][1]);
+    
+    if (missingTexts.length > 0) {
+      // Generate embeddings for missing texts
+      const embeddings = await this.generateBatchEmbeddings(missingTexts, model);
+      
+      // Cache them
+      const cachePipeline = this.redis.pipeline();
+      for (let i = 0; i < missingTexts.length; i++) {
+        const key = this.getCacheKey(missingTexts[i], model);
+        const compressed = compress(JSON.stringify(embeddings[i]));
+        cachePipeline.setex(key, this.ttl, compressed);
+      }
+      await cachePipeline.exec();
+    }
+  }
+}
+```
+
+## Query Optimization
+
+### Approximate Nearest Neighbor (ANN) Configuration - pgvector v0.8.0
+
+```typescript
+// src/db/vectorOptimization.ts
+export async function optimizeForANN() {
+  // IVFFlat v0.8.0 parameters with iterative scan support
+  await db.execute(sql`
+    -- Standard probes for initial search
+    SET ivfflat.probes = 20;
+    
+    -- Enable iterative scans for LIMIT queries (v0.8.0 feature)
+    SET enable_iterative_index_scan = true;
+    SET ivfflat.iterative_search_probes = 80;  -- Progressive probe increase
+    
+    -- Set parallel workers for vector operations
+    SET max_parallel_workers_per_gather = 4;
+    SET max_parallel_workers = 8;
+    
+    -- Increase work memory for sorting
+    SET work_mem = '256MB';
+  `);
+
+  // HNSW v0.8.0 optimizations
+  await db.execute(sql`
+    -- Standard search parameter
+    SET hnsw.ef_search = 100;
+    
+    -- Iterative search mode (v0.8.0 feature)
+    -- Options: 'off', 'relaxed_order', 'strict_order'
+    SET hnsw.iterative_search = 'relaxed_order';
+    
+    -- Dynamic ef_search for different query sizes
+    SET hnsw.dynamic_ef_search = true;
+  `);
+}
+
+// Benchmark different configurations with v0.8.0 features
+export async function benchmarkVectorSearch(embedding: number[]) {
+  const configs = [
+    { probes: 1, iterative: false, name: "Fast (1 probe, no iteration)" },
+    { probes: 10, iterative: false, name: "Balanced (10 probes)" },
+    { probes: 10, iterative: true, name: "v0.8.0 Iterative (10 initial, up to 40)" },
+    { probes: 50, iterative: false, name: "Accurate (50 probes)" },
+    { probes: 100, iterative: false, name: "Most Accurate (100 probes)" },
+  ];
+
+  const results = [];
+  
+  for (const config of configs) {
+    await db.execute(sql`SET ivfflat.probes = ${config.probes}`);
+    
+    // Enable/disable iterative scans (v0.8.0)
+    if (config.iterative) {
+      await db.execute(sql`
+        SET enable_iterative_index_scan = true;
+        SET ivfflat.iterative_search_probes = 40;
+      `);
+    } else {
+      await db.execute(sql`SET enable_iterative_index_scan = false`);
+    }
+    
+    const start = performance.now();
+    const result = await db.execute(sql`
+      SELECT id, 1 - (embedding <=> ${embedding}::vector) as similarity
+      FROM memories
+      WHERE embedding IS NOT NULL
+      ORDER BY embedding <=> ${embedding}::vector
+      LIMIT 10
+    `);
+    const duration = performance.now() - start;
+    
+    results.push({
+      config: config.name,
+      duration,
+      resultCount: result.rows.length,
+    });
+  }
+  
+  return results;
+}
+```
+
+## Semantic Memory Consolidation
+
+### Memory Summarization and Compression
+
+```typescript
+// src/services/memoryConsolidation.ts
+export class MemoryConsolidationService {
+  async consolidateSimilarMemories(
+    companionId: string,
+    userId: string,
+    similarityThreshold = 0.95
+  ) {
+    // Find highly similar memories
+    const duplicates = await db.execute(sql`
+      WITH similarity_pairs AS (
+        SELECT 
+          m1.id as id1,
+          m2.id as id2,
+          m1.content as content1,
+          m2.content as content2,
+          1 - (m1.embedding <=> m2.embedding) as similarity
+        FROM memories m1
+        JOIN memories m2 ON m1.id < m2.id
+        WHERE 
+          m1.companion_id = ${companionId}
+          AND m1.user_id = ${userId}
+          AND m2.companion_id = ${companionId}
+          AND m2.user_id = ${userId}
+          AND 1 - (m1.embedding <=> m2.embedding) > ${similarityThreshold}
+      )
+      SELECT * FROM similarity_pairs
+      ORDER BY similarity DESC
+    `);
+
+    // Consolidate similar memories
+    for (const pair of duplicates.rows) {
+      await this.mergeMemories(pair.id1, pair.id2, pair.content1, pair.content2);
+    }
+
+    return duplicates.rows.length;
+  }
+
+  private async mergeMemories(
+    id1: string, 
+    id2: string, 
+    content1: string, 
+    content2: string
+  ) {
+    // Use LLM to create consolidated memory
+    const consolidated = await this.createConsolidatedContent(content1, content2);
+    
+    // Update first memory with consolidated content
+    await db.update(memories)
+      .set({
+        content: consolidated.content,
+        summary: consolidated.summary,
+        importance: Math.max(consolidated.importance1, consolidated.importance2),
+      })
+      .where(eq(memories.id, id1));
+    
+    // Archive the duplicate
+    await db.update(memories)
+      .set({ isArchived: true })
+      .where(eq(memories.id, id2));
+  }
+}
+```
+
+## Performance Monitoring
+
+### Vector Search Metrics
+
+```typescript
+// src/monitoring/vectorMetrics.ts
+export class VectorSearchMetrics {
+  async getSearchPerformance() {
+    // Query performance statistics
+    const stats = await db.execute(sql`
+      SELECT 
+        query,
+        mean_exec_time,
+        calls,
+        total_exec_time,
+        min_exec_time,
+        max_exec_time
+      FROM pg_stat_statements
+      WHERE query LIKE '%embedding%'
+      ORDER BY mean_exec_time DESC
+      LIMIT 20
+    `);
+
+    return stats.rows;
+  }
+
+  async getIndexEfficiency() {
+    // Check index scan vs sequential scan ratio
+    const efficiency = await db.execute(sql`
+      SELECT 
+        schemaname,
+        tablename,
+        n_tup_ins,
+        n_tup_upd,
+        n_tup_del,
+        idx_scan,
+        seq_scan,
+        CASE 
+          WHEN (idx_scan + seq_scan) > 0 
+          THEN (idx_scan::float / (idx_scan + seq_scan))::numeric(5,2)
+          ELSE 0 
+        END as index_usage_ratio
+      FROM pg_stat_user_tables
+      WHERE tablename = 'memories'
+    `);
+
+    return efficiency.rows[0];
+  }
+
+  async getEmbeddingStatistics() {
+    const stats = await db.execute(sql`
+      SELECT 
+        COUNT(*) as total_memories,
+        COUNT(embedding) as memories_with_embeddings,
+        AVG(cardinality(embedding)) as avg_dimensions,
+        pg_size_pretty(
+          SUM(pg_column_size(embedding))
+        ) as total_embedding_size
+      FROM memories
+    `);
+
+    return stats.rows[0];
+  }
+}
+```
+
+## Best Practices for pgvector v0.8.0
+
+1. **Use iterative index scans** - New v0.8.0 feature for better recall with LIMIT queries
+2. **Choose the right index**:
+   - **IVFFlat**: Fast, good for datasets up to ~1M vectors
+   - **HNSW**: More accurate, better for high-recall requirements
+3. **Configure iterative search**:
+   - IVFFlat: Set `ivfflat.iterative_search_probes` for progressive searching
+   - HNSW: Use `hnsw.iterative_search = 'relaxed_order'` for better performance
+4. **Cache embeddings aggressively** - They're expensive to generate
+5. **Normalize vectors** - Ensures consistent cosine similarity
+6. **Batch embedding generation** - More efficient than individual calls
+7. **Implement hybrid search** - Combines semantic and keyword matching
+8. **Monitor index performance** - Use `EXPLAIN ANALYZE` to verify index usage
+9. **Use appropriate distance metrics**:
+   - Cosine (`<=>`) for normalized vectors
+   - L2 (`<->`) for dense vectors
+   - Inner product (`<#>`) when magnitude matters
+   - L1 (`<+>`) for sparse data
+10. **Regular maintenance**:
+    - `REINDEX` periodically for IVFFlat
+    - Monitor `pg_stat_user_indexes` for usage patterns
+
+### pgvector v0.8.0 Performance Tips
+
+```sql
+-- Enable iterative scans for better recall
+SET enable_iterative_index_scan = true;
+
+-- IVFFlat: Start with fewer probes, iterate if needed
+SET ivfflat.probes = 10;
+SET ivfflat.iterative_search_probes = 40;
+
+-- HNSW: Use relaxed ordering for speed
+SET hnsw.iterative_search = 'relaxed_order';
+SET hnsw.ef_search = 100;
+```
+
+Always profile your specific workload with v0.8.0's iterative features for optimal speed vs accuracy.
diff --git a/mcp-servers/memory-mcp-server/.claude/commands/explain.md b/mcp-servers/memory-mcp-server/.claude/commands/explain.md
new file mode 100644
index 0000000..fb51ae0
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/commands/explain.md
@@ -0,0 +1,48 @@
+---
+description: Explain code, MCP protocol, or memory system concepts
+argument-hint: "[file, function, MCP tool, or memory concept]"
+allowed-tools: Read, Grep, Glob, Task
+---
+
+# Memory MCP Server Explanation
+
+Provide a detailed explanation of $ARGUMENTS in the context of this Memory MCP Server:
+
+## Core Explanation
+
+- What it does and its purpose in the memory system
+- How it works (step-by-step if applicable)
+- Role in the MCP protocol implementation
+
+## Technical Details
+
+- Key dependencies and interactions
+- Database schema relationships (if applicable)
+- Vector embedding and search mechanics (if relevant)
+- MCP message flow and protocol compliance
+
+## Memory System Context
+
+- How it relates to memory persistence
+- Impact on memory lifecycle (creation, retrieval, expiration, archival)
+- Companion isolation and multi-tenancy considerations
+- Performance implications for vector search
+
+## Integration Points
+
+- MCP tool registration and execution
+- JSON-RPC message handling
+- Session management aspects
+- Error handling patterns
+
+## Usage Examples
+
+- Sample MCP requests/responses
+- Code usage patterns
+- Common integration scenarios
+
+## Related Components
+
+- Related files, functions, or MCP tools
+- Database tables and indexes involved
+- Dependent services or modules
diff --git a/mcp-servers/memory-mcp-server/.claude/commands/mcp-debug.md b/mcp-servers/memory-mcp-server/.claude/commands/mcp-debug.md
new file mode 100644
index 0000000..7232cca
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/commands/mcp-debug.md
@@ -0,0 +1,115 @@
+---
+description: Debug Memory MCP server connection and protocol issues
+argument-hint: "[connection issue, tool error, or specific debug scenario]"
+allowed-tools: Read, Grep, Bash, Edit, Task, TodoWrite
+---
+
+# Memory MCP Server Debugging
+
+Debug the Memory MCP server implementation with focus on $ARGUMENTS:
+
+## 1. Server Initialization & Configuration
+
+- Verify MCP server startup and registration
+- Check @modelcontextprotocol/sdk initialization
+- Validate server manifest and capabilities
+- Test stdio/HTTP transport configuration
+- Verify database connection (Neon PostgreSQL)
+
+## 2. MCP Protocol Compliance
+
+- Validate JSON-RPC 2.0 message format
+- Test request/response correlation (id matching)
+- Verify error response format (code, message, data)
+- Check notification handling (no id field)
+- Validate batch request support
+
+## 3. Memory Tool Registration
+
+- Verify tool discovery and registration:
+  - `create_memory` - Memory creation with embeddings
+  - `search_memories` - Vector similarity search
+  - `get_memory` - Direct retrieval
+  - `update_memory` - Memory updates
+  - `delete_memory` - Soft/hard deletion
+  - `list_memories` - Pagination support
+- Validate tool parameter schemas (Zod validation)
+- Test tool permission boundaries
+
+## 4. Database & Vector Operations
+
+- Test pgvector extension functionality
+- Verify embedding generation (OpenAI API)
+- Debug vector similarity search queries
+- Check index usage (IVFFlat/HNSW)
+- Validate transaction handling
+
+## 5. Session & Authentication
+
+- Debug companion session management
+- Verify user context isolation
+- Test multi-tenancy boundaries
+- Check session persistence
+- Validate auth token handling
+
+## 6. Error Handling & Recovery
+
+- Test database connection failures
+- Handle embedding API errors
+- Verify graceful degradation
+- Check error logging and telemetry
+- Test retry mechanisms
+
+## 7. Performance & Memory Leaks
+
+- Monitor connection pooling
+- Check for memory leaks in long sessions
+- Verify streaming response handling
+- Test concurrent request handling
+- Profile vector search performance
+
+## 8. Common Issues & Solutions
+
+### Connection Refused
+
+```bash
+# Check if server is running
+ps aux | grep "memory-mcp"
+# Verify port binding
+lsof -i :3000
+# Test direct connection
+npx @modelcontextprotocol/cli connect stdio "node ./dist/index.js"
+```
+
+### Tool Not Found
+
+```bash
+# List registered tools
+npx @modelcontextprotocol/cli list-tools
+# Verify tool manifest
+cat .mcp.json
+```
+
+### Vector Search Failures
+
+```sql
+-- Check pgvector extension
+SELECT * FROM pg_extension WHERE extname = 'vector';
+-- Verify embeddings exist
+SELECT COUNT(*) FROM memories WHERE embedding IS NOT NULL;
+-- Test similarity query
+SELECT id, content <=> '[...]'::vector AS distance 
+FROM memories 
+ORDER BY distance LIMIT 5;
+```
+
+## 9. Testing Checklist
+
+- [ ] Server starts without errors
+- [ ] Tools are discoverable via MCP protocol
+- [ ] Memory CRUD operations work
+- [ ] Vector search returns relevant results
+- [ ] Session isolation is maintained
+- [ ] Error responses follow MCP spec
+- [ ] Performance meets requirements
+- [ ] Logs provide debugging info
diff --git a/mcp-servers/memory-mcp-server/.claude/commands/memory-ops.md b/mcp-servers/memory-mcp-server/.claude/commands/memory-ops.md
new file mode 100644
index 0000000..777d50d
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/commands/memory-ops.md
@@ -0,0 +1,396 @@
+---
+description: Test and debug memory CRUD operations and vector search
+argument-hint: "[create, search, update, delete, lifecycle, or batch]"
+allowed-tools: Bash, Read, Write, Task, TodoWrite
+---
+
+# Memory Operations Testing
+
+Test and debug memory operations for the Memory MCP Server focusing on $ARGUMENTS:
+
+## Create Memory
+
+Test memory creation with embedding generation:
+
+```bash
+# Create a simple memory
+npx @modelcontextprotocol/cli call create_memory '{
+  "content": "User prefers dark mode interfaces",
+  "type": "preference",
+  "importance": 0.8
+}'
+
+# Create memory with expiration
+npx @modelcontextprotocol/cli call create_memory '{
+  "content": "Meeting with team at 3pm tomorrow",
+  "type": "event",
+  "importance": 0.9,
+  "expires_at": "2024-12-31T15:00:00Z"
+}'
+
+# Create memory with metadata
+npx @modelcontextprotocol/cli call create_memory '{
+  "content": "Project deadline is March 15",
+  "type": "task",
+  "importance": 1.0,
+  "metadata": {
+    "project": "Memory MCP Server",
+    "priority": "high"
+  }
+}'
+
+# Batch memory creation
+for i in {1..10}; do
+  npx @modelcontextprotocol/cli call create_memory "{
+    \"content\": \"Test memory $i for performance testing\",
+    \"type\": \"test\",
+    \"importance\": 0.5
+  }"
+done
+```
+
+## Search Memories
+
+Test vector similarity search:
+
+```bash
+# Basic semantic search
+npx @modelcontextprotocol/cli call search_memories '{
+  "query": "What are the user preferences?",
+  "limit": 5
+}'
+
+# Search with similarity threshold
+npx @modelcontextprotocol/cli call search_memories '{
+  "query": "upcoming meetings and events",
+  "limit": 10,
+  "threshold": 0.7
+}'
+
+# Search by type
+npx @modelcontextprotocol/cli call search_memories '{
+  "query": "tasks and deadlines",
+  "filter": {
+    "type": "task"
+  },
+  "limit": 20
+}'
+
+# Search with date range
+npx @modelcontextprotocol/cli call search_memories '{
+  "query": "recent activities",
+  "filter": {
+    "created_after": "2024-01-01",
+    "created_before": "2024-12-31"
+  }
+}'
+```
+
+## Update Memory
+
+Test memory updates and importance adjustments:
+
+```bash
+# Update memory content
+npx @modelcontextprotocol/cli call update_memory '{
+  "id": "memory-uuid-here",
+  "content": "Updated content with new information",
+  "regenerate_embedding": true
+}'
+
+# Adjust importance
+npx @modelcontextprotocol/cli call update_memory '{
+  "id": "memory-uuid-here",
+  "importance": 0.95
+}'
+
+# Extend expiration
+npx @modelcontextprotocol/cli call update_memory '{
+  "id": "memory-uuid-here",
+  "expires_at": "2025-12-31T23:59:59Z"
+}'
+
+# Mark as accessed
+npx @modelcontextprotocol/cli call update_memory '{
+  "id": "memory-uuid-here",
+  "increment_access_count": true
+}'
+```
+
+## Delete Memory
+
+Test soft and hard deletion:
+
+```bash
+# Soft delete (archive)
+npx @modelcontextprotocol/cli call delete_memory '{
+  "id": "memory-uuid-here",
+  "soft_delete": true
+}'
+
+# Hard delete
+npx @modelcontextprotocol/cli call delete_memory '{
+  "id": "memory-uuid-here",
+  "soft_delete": false
+}'
+
+# Bulk delete by filter
+npx @modelcontextprotocol/cli call delete_memories '{
+  "filter": {
+    "type": "test",
+    "created_before": "2024-01-01"
+  }
+}'
+```
+
+## Memory Lifecycle
+
+Test expiration, archival, and consolidation:
+
+```bash
+# Process expired memories
+npx @modelcontextprotocol/cli call process_expired_memories
+
+# Archive old memories
+npx @modelcontextprotocol/cli call archive_memories '{
+  "older_than_days": 90,
+  "importance_below": 0.3
+}'
+
+# Consolidate similar memories
+npx @modelcontextprotocol/cli call consolidate_memories '{
+  "similarity_threshold": 0.9,
+  "max_group_size": 5
+}'
+
+# Apply importance decay
+npx @modelcontextprotocol/cli call apply_importance_decay '{
+  "decay_rate": 0.1,
+  "days_inactive": 30
+}'
+```
+
+## Batch Operations
+
+Test bulk operations and performance:
+
+```bash
+# Bulk import memories
+cat memories.json | npx @modelcontextprotocol/cli call bulk_import_memories
+
+# Export memories
+npx @modelcontextprotocol/cli call export_memories '{
+  "format": "json",
+  "include_embeddings": false
+}' > backup.json
+
+# Regenerate all embeddings
+npx @modelcontextprotocol/cli call regenerate_embeddings '{
+  "batch_size": 100,
+  "model": "text-embedding-3-small"
+}'
+```
+
+## Database Queries
+
+Direct database operations for testing:
+
+```sql
+-- Check memory count
+SELECT COUNT(*) as total,
+       COUNT(CASE WHEN is_archived THEN 1 END) as archived,
+       COUNT(CASE WHEN embedding IS NULL THEN 1 END) as no_embedding
+FROM memories;
+
+-- Find duplicate memories
+SELECT content, COUNT(*) as count
+FROM memories
+WHERE is_archived = false
+GROUP BY content
+HAVING COUNT(*) > 1;
+
+-- Analyze embedding distribution
+SELECT 
+  percentile_cont(0.5) WITHIN GROUP (ORDER BY importance) as median_importance,
+  AVG(access_count) as avg_accesses,
+  COUNT(DISTINCT user_id) as unique_users
+FROM memories;
+
+-- Test vector similarity manually
+SELECT id, content,
+       embedding <=> (SELECT embedding FROM memories WHERE id = 'reference-id') as distance
+FROM memories
+WHERE embedding IS NOT NULL
+ORDER BY distance
+LIMIT 10;
+```
+
+## Performance Testing
+
+Load testing and benchmarking:
+
+```bash
+# Concurrent memory creation
+for i in {1..100}; do
+  (npx @modelcontextprotocol/cli call create_memory "{
+    \"content\": \"Concurrent test $i\",
+    \"type\": \"test\"
+  }" &)
+done
+wait
+
+# Measure search latency
+time npx @modelcontextprotocol/cli call search_memories '{
+  "query": "test query for performance measurement",
+  "limit": 100
+}'
+
+# Stress test with large content
+npx @modelcontextprotocol/cli call create_memory "{
+  \"content\": \"$(cat large-document.txt)\",
+  \"type\": \"document\"
+}"
+```
+
+## Monitoring Commands
+
+Real-time monitoring during operations:
+
+```bash
+# Watch memory creation rate
+watch -n 1 'psql $DATABASE_URL -t -c "
+  SELECT COUNT(*) || \" memories created in last minute\"
+  FROM memories
+  WHERE created_at > NOW() - INTERVAL \"1 minute\";
+"'
+
+# Monitor embedding generation
+psql $DATABASE_URL -c "
+  SELECT 
+    COUNT(*) FILTER (WHERE embedding IS NOT NULL) as with_embedding,
+    COUNT(*) FILTER (WHERE embedding IS NULL) as without_embedding,
+    pg_size_pretty(SUM(pg_column_size(embedding))) as total_size
+  FROM memories;
+"
+
+# Check index usage
+psql $DATABASE_URL -c "
+  SELECT indexname, idx_scan, idx_tup_read, idx_tup_fetch
+  FROM pg_stat_user_indexes
+  WHERE tablename = 'memories'
+  ORDER BY idx_scan DESC;
+"
+```
+
+## Validation Scripts
+
+Automated validation of memory operations:
+
+```typescript
+// validate-memory-ops.ts
+import { MCPClient } from '@modelcontextprotocol/sdk';
+
+async function validateMemoryOperations() {
+  const client = new MCPClient();
+  
+  // Test 1: Create and retrieve
+  const created = await client.call('create_memory', {
+    content: 'Validation test memory',
+    type: 'test'
+  });
+  
+  const retrieved = await client.call('get_memory', {
+    id: created.id
+  });
+  
+  console.assert(created.id === retrieved.id, 'Memory retrieval failed');
+  
+  // Test 2: Search accuracy
+  const searchResults = await client.call('search_memories', {
+    query: 'Validation test memory',
+    limit: 1
+  });
+  
+  console.assert(searchResults[0].id === created.id, 'Search failed');
+  
+  // Test 3: Update verification
+  await client.call('update_memory', {
+    id: created.id,
+    importance: 0.99
+  });
+  
+  const updated = await client.call('get_memory', {
+    id: created.id
+  });
+  
+  console.assert(updated.importance === 0.99, 'Update failed');
+  
+  // Test 4: Cleanup
+  await client.call('delete_memory', {
+    id: created.id
+  });
+  
+  console.log('✅ All memory operations validated');
+}
+
+validateMemoryOperations().catch(console.error);
+```
+
+## Common Issues & Solutions
+
+### Embedding Generation Failures
+
+```bash
+# Check OpenAI API key
+echo $OPENAI_API_KEY
+
+# Test API directly
+curl https://api.openai.com/v1/embeddings \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "text-embedding-3-small",
+    "input": "Test"
+  }'
+
+# Retry failed embeddings
+npx @modelcontextprotocol/cli call retry_failed_embeddings
+```
+
+### Vector Index Issues
+
+```sql
+-- Rebuild IVFFlat index
+DROP INDEX IF EXISTS memories_embedding_idx;
+CREATE INDEX memories_embedding_idx ON memories 
+USING ivfflat (embedding vector_cosine_ops)
+WITH (lists = 100);
+
+-- Switch to HNSW for better performance
+CREATE INDEX memories_embedding_hnsw_idx ON memories 
+USING hnsw (embedding vector_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+```
+
+### Memory Limit Exceeded
+
+```bash
+# Check user memory count
+psql $DATABASE_URL -c "
+  SELECT user_id, COUNT(*) as memory_count
+  FROM memories
+  WHERE is_archived = false
+  GROUP BY user_id
+  HAVING COUNT(*) > 9000
+  ORDER BY memory_count DESC;
+"
+
+# Archive old memories for user
+npx @modelcontextprotocol/cli call archive_user_memories '{
+  "user_id": "user-uuid",
+  "keep_recent": 5000
+}'
+```
+
+This command provides comprehensive testing and debugging capabilities for all memory operations in the MCP server.
+
diff --git a/mcp-servers/memory-mcp-server/.claude/commands/perf-monitor.md b/mcp-servers/memory-mcp-server/.claude/commands/perf-monitor.md
new file mode 100644
index 0000000..e9db312
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/commands/perf-monitor.md
@@ -0,0 +1,353 @@
+---
+description: Monitor vector search performance and index efficiency for the memory MCP server
+allowed-tools: Bash, Read, Grep
+---
+
+# Performance Monitoring Command
+
+Monitor and analyze the performance of vector search operations, index efficiency, and memory lifecycle metrics.
+
+## Usage
+
+This command provides comprehensive performance monitoring for:
+
+- Vector search query performance
+- Index usage and efficiency
+- Memory lifecycle statistics
+- Database query patterns
+- Resource utilization
+
+## Available Monitoring Tasks
+
+### 1. Vector Search Performance
+
+```bash
+# Check current pgvector index statistics
+psql $DATABASE_URL -c "
+  SELECT 
+    schemaname,
+    tablename,
+    indexname,
+    idx_scan as index_scans,
+    idx_tup_read as tuples_read,
+    idx_tup_fetch as tuples_fetched,
+    pg_size_pretty(pg_relation_size(indexrelid)) as index_size
+  FROM pg_stat_user_indexes
+  WHERE indexname LIKE '%vector%' OR indexname LIKE '%embedding%'
+  ORDER BY idx_scan DESC;
+"
+
+# Analyze query performance for vector operations
+psql $DATABASE_URL -c "
+  SELECT 
+    substring(query, 1, 50) as query_preview,
+    calls,
+    mean_exec_time as avg_ms,
+    min_exec_time as min_ms,
+    max_exec_time as max_ms,
+    total_exec_time as total_ms,
+    rows
+  FROM pg_stat_statements
+  WHERE query LIKE '%embedding%' OR query LIKE '%vector%'
+  ORDER BY mean_exec_time DESC
+  LIMIT 20;
+"
+```
+
+### 2. Index Efficiency Analysis
+
+```bash
+# Check IVFFlat index clustering quality
+psql $DATABASE_URL -c "
+  SELECT 
+    indexname,
+    lists,
+    pages,
+    tuples,
+    ROUND(tuples::numeric / NULLIF(lists, 0), 2) as avg_vectors_per_list,
+    CASE 
+      WHEN tuples::numeric / NULLIF(lists, 0) > 10000 THEN 'Rebalance recommended'
+      WHEN tuples::numeric / NULLIF(lists, 0) < 100 THEN 'Over-partitioned'
+      ELSE 'Optimal'
+    END as status
+  FROM (
+    SELECT 
+      'memories_embedding_ivfflat_idx'::regclass as indexname,
+      (SELECT current_setting('ivfflat.lists')::int) as lists,
+      relpages as pages,
+      reltuples as tuples
+    FROM pg_class 
+    WHERE oid = 'memories_embedding_ivfflat_idx'::regclass
+  ) index_stats;
+"
+
+# Check HNSW index parameters
+psql $DATABASE_URL -c "
+  SELECT 
+    indexname,
+    m,
+    ef_construction,
+    ef_search,
+    CASE 
+      WHEN ef_search < 100 THEN 'Low recall configuration'
+      WHEN ef_search > 500 THEN 'High cost configuration'
+      ELSE 'Balanced configuration'
+    END as configuration_assessment
+  FROM (
+    SELECT 
+      'memories_embedding_hnsw_idx' as indexname,
+      current_setting('hnsw.m')::int as m,
+      current_setting('hnsw.ef_construction')::int as ef_construction,
+      current_setting('hnsw.ef_search')::int as ef_search
+  ) hnsw_config;
+"
+```
+
+### 3. Memory Lifecycle Metrics
+
+```bash
+# Memory distribution by status and type
+psql $DATABASE_URL -c "
+  SELECT 
+    type,
+    COUNT(*) FILTER (WHERE is_archived = false) as active,
+    COUNT(*) FILTER (WHERE is_archived = true) as archived,
+    AVG(importance) as avg_importance,
+    AVG(access_count) as avg_accesses,
+    AVG(EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400)::int as avg_age_days
+  FROM memories
+  GROUP BY type
+  ORDER BY active DESC;
+"
+
+# Memory expiration analysis
+psql $DATABASE_URL -c "
+  SELECT 
+    CASE 
+      WHEN expires_at IS NULL THEN 'Never expires'
+      WHEN expires_at < NOW() THEN 'Expired'
+      WHEN expires_at < NOW() + INTERVAL '7 days' THEN 'Expiring soon'
+      WHEN expires_at < NOW() + INTERVAL '30 days' THEN 'Expiring this month'
+      ELSE 'Long-term'
+    END as expiration_status,
+    COUNT(*) as count,
+    AVG(importance) as avg_importance
+  FROM memories
+  WHERE is_archived = false
+  GROUP BY expiration_status
+  ORDER BY count DESC;
+"
+
+# Consolidation statistics
+psql $DATABASE_URL -c "
+  SELECT 
+    relation_type,
+    COUNT(*) as relationship_count,
+    COUNT(DISTINCT from_memory_id) as source_memories,
+    COUNT(DISTINCT to_memory_id) as target_memories
+  FROM memory_relations
+  WHERE relation_type IN ('consolidated_into', 'summarized_in', 'elaborates', 'corrects')
+  GROUP BY relation_type;
+"
+```
+
+### 4. Query Pattern Analysis
+
+```bash
+# Analyze search patterns by limit size
+psql $DATABASE_URL -c "
+  WITH query_patterns AS (
+    SELECT 
+      CASE 
+        WHEN query LIKE '%LIMIT 1%' THEN 'Single result'
+        WHEN query LIKE '%LIMIT 5%' OR query LIKE '%LIMIT 10%' THEN 'Small batch'
+        WHEN query LIKE '%LIMIT 50%' OR query LIKE '%LIMIT 100%' THEN 'Large batch'
+        ELSE 'Variable'
+      END as pattern,
+      COUNT(*) as query_count,
+      AVG(mean_exec_time) as avg_time_ms,
+      SUM(calls) as total_calls
+    FROM pg_stat_statements
+    WHERE query LIKE '%ORDER BY % <=>%' -- Vector similarity queries
+    GROUP BY pattern
+  )
+  SELECT * FROM query_patterns ORDER BY total_calls DESC;
+"
+
+# Identify slow queries
+psql $DATABASE_URL -c "
+  SELECT 
+    substring(query, 1, 100) as query_preview,
+    calls,
+    mean_exec_time as avg_ms,
+    max_exec_time as worst_ms,
+    rows / NULLIF(calls, 0) as avg_rows_returned
+  FROM pg_stat_statements
+  WHERE 
+    mean_exec_time > 100 -- Queries slower than 100ms
+    AND (query LIKE '%memories%' OR query LIKE '%embedding%')
+  ORDER BY mean_exec_time DESC
+  LIMIT 10;
+"
+```
+
+### 5. Storage and Resource Utilization
+
+```bash
+# Table and index sizes
+psql $DATABASE_URL -c "
+  SELECT 
+    schemaname,
+    tablename,
+    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as total_size,
+    pg_size_pretty(pg_relation_size(schemaname||'.'||tablename)) as table_size,
+    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename) - pg_relation_size(schemaname||'.'||tablename)) as index_size,
+    n_live_tup as row_count,
+    n_dead_tup as dead_rows,
+    ROUND(100.0 * n_dead_tup / NULLIF(n_live_tup + n_dead_tup, 0), 2) as dead_percent
+  FROM pg_stat_user_tables
+  WHERE tablename IN ('memories', 'memory_relations', 'companions', 'users', 'companion_sessions')
+  ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
+"
+
+# Embedding storage analysis
+psql $DATABASE_URL -c "
+  SELECT 
+    COUNT(*) as total_memories,
+    COUNT(embedding) as memories_with_embeddings,
+    pg_size_pretty(
+      SUM(pg_column_size(embedding))
+    ) as total_embedding_storage,
+    pg_size_pretty(
+      AVG(pg_column_size(embedding))::bigint
+    ) as avg_embedding_size,
+    COUNT(*) FILTER (WHERE embedding IS NULL) as missing_embeddings
+  FROM memories;
+"
+```
+
+### 6. Real-time Monitoring Dashboard
+
+```bash
+# Create a monitoring loop (run for 60 seconds)
+echo "Starting real-time performance monitoring for 60 seconds..."
+for i in {1..12}; do
+  clear
+  echo "=== Memory MCP Server Performance Monitor ==="
+  echo "Time: $(date '+%Y-%m-%d %H:%M:%S')"
+  echo ""
+  
+  # Active connections
+  psql $DATABASE_URL -t -c "
+    SELECT 'Active connections: ' || count(*) 
+    FROM pg_stat_activity 
+    WHERE state = 'active';
+  "
+  
+  # Recent vector searches
+  psql $DATABASE_URL -t -c "
+    SELECT 'Vector searches (last min): ' || count(*)
+    FROM pg_stat_statements
+    WHERE query LIKE '%embedding%'
+    AND last_call > NOW() - INTERVAL '1 minute';
+  "
+  
+  # Memory operations
+  psql $DATABASE_URL -t -c "
+    SELECT 
+      'Memories created (last hour): ' || 
+      COUNT(*) FILTER (WHERE created_at > NOW() - INTERVAL '1 hour')
+    FROM memories;
+  "
+  
+  # Cache hit ratio
+  psql $DATABASE_URL -t -c "
+    SELECT 'Cache hit ratio: ' || 
+      ROUND(100.0 * blks_hit / NULLIF(blks_hit + blks_read, 0), 2) || '%'
+    FROM pg_stat_database
+    WHERE datname = current_database();
+  "
+  
+  sleep 5
+done
+```
+
+## Performance Tuning Recommendations
+
+Based on monitoring results, consider these optimizations:
+
+### For Slow Vector Searches
+
+- Increase `ivfflat.probes` for better accuracy
+- Enable iterative scans: `SET enable_iterative_index_scan = true`
+- Consider switching from IVFFlat to HNSW for small result sets
+
+### For Poor Index Performance
+
+- Rebuild IVFFlat indexes if avg_vectors_per_list > 10000
+- Increase HNSW `ef_search` for better recall
+- Add more specific indexes for common query patterns
+
+### For Memory Lifecycle Issues
+
+- Adjust expiration policies based on usage patterns
+- Implement more aggressive consolidation for old memories
+- Archive memories with low importance scores
+
+### For Storage Optimization
+
+- Use halfvec type for less critical embeddings
+- Implement memory pruning for users exceeding limits
+- Compress archived memory content
+
+## Integration with Application
+
+To integrate monitoring into your application:
+
+```typescript
+// src/monitoring/performanceMonitor.ts
+import { db } from "../db/client";
+import { sql } from "drizzle-orm";
+
+export class PerformanceMonitor {
+  async getVectorSearchMetrics() {
+    // Implementation based on queries above
+  }
+  
+  async getIndexEfficiency() {
+    // Implementation based on queries above
+  }
+  
+  async getMemoryLifecycleStats() {
+    // Implementation based on queries above
+  }
+}
+```
+
+## Automated Alerts
+
+Set up alerts when:
+
+- Average query time exceeds 200ms
+- Index scan ratio drops below 90%
+- Dead tuple percentage exceeds 20%
+- Memory count approaches user limits
+- Embedding generation fails repeatedly
+
+## Export Metrics
+
+Export monitoring data for analysis:
+
+```bash
+# Export to CSV
+psql $DATABASE_URL -c "\COPY (
+  SELECT * FROM pg_stat_user_indexes WHERE indexname LIKE '%vector%'
+) TO '/tmp/index_stats.csv' WITH CSV HEADER;"
+
+# Generate performance report
+psql $DATABASE_URL -H -o performance_report.html -c "
+  -- Your monitoring queries here
+"
+```
+
+This command provides comprehensive monitoring capabilities for optimizing your memory MCP server's performance.
diff --git a/mcp-servers/memory-mcp-server/.claude/commands/review.md b/mcp-servers/memory-mcp-server/.claude/commands/review.md
new file mode 100644
index 0000000..40fb885
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/commands/review.md
@@ -0,0 +1,147 @@
+---
+description: Comprehensive code review for Memory MCP Server
+argument-hint: "[specific file, module, or leave empty for full review]"
+allowed-tools: Read, Grep, Glob, Task, TodoWrite
+---
+
+# Memory MCP Server Code Review
+
+Perform a comprehensive review of $ARGUMENTS with focus on MCP protocol compliance and memory system integrity:
+
+## Critical Security & Safety
+
+- **Data Isolation**: Verify companion/user boundary enforcement
+- **SQL Injection**: Check all database queries for parameterization
+- **Embedding Leakage**: Ensure vector data doesn't cross tenant boundaries
+- **Auth Tokens**: Validate secure storage and transmission
+- **API Keys**: Check for hardcoded credentials (OpenAI, Neon)
+- **Session Hijacking**: Review session management implementation
+
+## MCP Protocol Compliance
+
+- **JSON-RPC 2.0**: Validate message format compliance
+- **Error Codes**: Use standard MCP error codes (-32700 to -32603)
+- **Tool Registration**: Verify proper tool manifest structure
+- **Parameter Validation**: Check Zod schemas match MCP expectations
+- **Response Format**: Ensure consistent response structure
+- **Streaming Support**: Validate partial result handling
+
+## Memory System Integrity
+
+- **Vector Dimensions**: Ensure consistent embedding dimensions (1536 for OpenAI)
+- **Index Configuration**: Review IVFFlat/HNSW parameters
+- **Memory Lifecycle**: Check expiration and archival logic
+- **Consolidation Rules**: Validate memory merging algorithms
+- **Importance Scoring**: Review decay and update mechanisms
+- **Deduplication**: Check for duplicate memory prevention
+
+## Performance Optimization
+
+- **N+1 Queries**: Identify and fix database query patterns
+- **Vector Search**: Optimize similarity thresholds and limits
+- **Index Usage**: Verify proper index hints and scans
+- **Connection Pooling**: Check pool size and timeout settings
+- **Batch Operations**: Look for opportunities to batch DB operations
+- **Caching Strategy**: Review memory and query result caching
+
+## Database & Schema
+
+- **Migration Safety**: Check for backward compatibility
+- **Transaction Boundaries**: Verify ACID compliance
+- **Deadlock Prevention**: Review lock ordering
+- **Foreign Keys**: Ensure referential integrity
+- **Soft Deletes**: Validate is_archived handling
+- **Timestamps**: Check timezone handling
+
+## Error Handling
+
+- **Database Errors**: Graceful handling of connection failures
+- **API Failures**: OpenAI API error recovery
+- **Validation Errors**: User-friendly error messages
+- **Timeout Handling**: Proper cleanup on timeouts
+- **Retry Logic**: Exponential backoff implementation
+- **Logging**: Structured logging with appropriate levels
+
+## Code Quality
+
+- **TypeScript Strict**: Enable strict mode compliance
+- **Type Safety**: No `any` types without justification
+- **Code Duplication**: Identify repeated patterns
+- **Function Complexity**: Break down complex functions
+- **Naming Conventions**: Consistent naming patterns
+- **Documentation**: JSDoc for public APIs
+
+## Testing Gaps
+
+- **Unit Test Coverage**: Minimum 80% coverage
+- **Integration Tests**: MCP protocol testing
+- **Vector Search Tests**: Similarity threshold validation
+- **Session Tests**: Multi-tenancy isolation
+- **Error Path Tests**: Exception handling coverage
+- **Performance Tests**: Load and stress testing
+
+## Specific Checks for Memory MCP
+
+```typescript
+// Check for these patterns:
+interface MemoryReviewChecks {
+  // 1. Embedding generation should handle failures
+  embeddings: {
+    fallbackStrategy: boolean;
+    retryLogic: boolean;
+    costTracking: boolean;
+  };
+  
+  // 2. Vector search should be bounded
+  vectorSearch: {
+    maxResults: number;
+    minSimilarity: number;
+    timeoutMs: number;
+  };
+  
+  // 3. Memory operations should be atomic
+  transactions: {
+    useTransactions: boolean;
+    rollbackOnError: boolean;
+    isolationLevel: string;
+  };
+  
+  // 4. Session management should be secure
+  sessions: {
+    tokenRotation: boolean;
+    expirationHandling: boolean;
+    revokeOnLogout: boolean;
+  };
+}
+```
+
+## Priority Issues Format
+
+### 🔴 Critical (Security/Data Loss)
+
+- Issue description
+- File:line reference
+- Suggested fix
+
+### 🟡 Important (Performance/Reliability)
+
+- Issue description
+- File:line reference
+- Suggested fix
+
+### 🟢 Minor (Code Quality/Style)
+
+- Issue description
+- File:line reference
+- Suggested fix
+
+## Review Checklist
+
+- [ ] No sensitive data in logs
+- [ ] All DB queries parameterized
+- [ ] MCP responses follow spec
+- [ ] Vector operations are bounded
+- [ ] Sessions properly isolated
+- [ ] Errors handled gracefully
+- [ ] Performance within targets
+- [ ] Tests cover critical paths
diff --git a/mcp-servers/memory-mcp-server/.claude/commands/setup.md b/mcp-servers/memory-mcp-server/.claude/commands/setup.md
new file mode 100644
index 0000000..5a9db1d
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/commands/setup.md
@@ -0,0 +1,381 @@
+---
+description: Initialize Memory MCP Server project from scratch
+argument-hint: "[quick, full, or database]"
+allowed-tools: Write, MultiEdit, Bash, Task, TodoWrite
+---
+
+# Memory MCP Server Setup
+
+Initialize and configure the Memory MCP Server project based on $ARGUMENTS:
+
+## Quick Setup
+
+Initialize minimal working MCP server with memory capabilities:
+
+```bash
+# Initialize project
+npm init -y
+npm install @modelcontextprotocol/sdk zod dotenv
+npm install -D typescript @types/node tsx nodemon
+npm install @neondatabase/serverless drizzle-orm@^0.44.4
+npm install openai pgvector
+
+# Create TypeScript config
+npx tsc --init
+```
+
+## Full Setup
+
+Complete project initialization with all features:
+
+### 1. Project Structure
+
+```text
+memory-mcp-server/
+├── src/
+│   ├── index.ts              # MCP server entry point
+│   ├── server.ts              # Server initialization
+│   ├── tools/                # MCP tool implementations
+│   │   ├── createMemory.ts
+│   │   ├── searchMemories.ts
+│   │   ├── getMemory.ts
+│   │   ├── updateMemory.ts
+│   │   └── deleteMemory.ts
+│   ├── db/
+│   │   ├── client.ts          # Database connection
+│   │   ├── schema.ts          # Drizzle schema
+│   │   └── migrations/        # Database migrations
+│   ├── services/
+│   │   ├── embeddings.ts      # OpenAI embeddings
+│   │   ├── vectorSearch.ts    # pgvector operations
+│   │   └── memoryLifecycle.ts # Memory management
+│   ├── types/
+│   │   └── index.ts           # TypeScript types
+│   └── utils/
+│       ├── logger.ts          # Structured logging
+│       └── errors.ts          # Error handling
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── fixtures/
+├── .env.example
+├── .mcp.json                  # MCP manifest
+├── tsconfig.json
+├── package.json
+├── drizzle.config.ts
+└── README.md
+```
+
+### 2. Package Dependencies
+
+```json
+{
+  "name": "memory-mcp-server",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:studio": "drizzle-kit studio"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@neondatabase/serverless": "^1.0.1",
+    "drizzle-orm": "^0.44.4",
+    "zod": "^4.0.17",
+    "openai": "^4.0.0",
+    "pgvector": "^0.2.0",
+    "dotenv": "^16.0.0",
+    "winston": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0",
+    "nodemon": "^3.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "drizzle-kit": "^0.32.0"
+  }
+}
+```
+
+### 3. TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+### 4. Environment Variables
+
+```bash
+# .env
+DATABASE_URL="postgresql://user:pass@host/dbname?sslmode=require"
+OPENAI_API_KEY="sk-..."
+MCP_SERVER_PORT=3000
+LOG_LEVEL=info
+NODE_ENV=development
+
+# Vector search settings
+VECTOR_SEARCH_LIMIT=10
+SIMILARITY_THRESHOLD=0.7
+
+# Memory lifecycle
+MEMORY_EXPIRATION_DAYS=90
+MAX_MEMORIES_PER_USER=10000
+IMPORTANCE_DECAY_RATE=0.1
+```
+
+### 5. MCP Manifest
+
+```json
+{
+  "name": "memory-mcp-server",
+  "version": "1.0.0",
+  "description": "Persistent memory management for AI assistants",
+  "author": "Your Name",
+  "license": "MIT",
+  "server": {
+    "command": "node",
+    "args": ["dist/index.js"],
+    "transport": "stdio"
+  },
+  "tools": {
+    "create_memory": {
+      "description": "Create a new memory with vector embedding",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "content": { "type": "string" },
+          "type": { "type": "string" },
+          "importance": { "type": "number" },
+          "expires_at": { "type": "string" }
+        },
+        "required": ["content", "type"]
+      }
+    },
+    "search_memories": {
+      "description": "Search memories using semantic similarity",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string" },
+          "limit": { "type": "number" },
+          "threshold": { "type": "number" }
+        },
+        "required": ["query"]
+      }
+    }
+  }
+}
+```
+
+## Database Setup
+
+Initialize Neon PostgreSQL with pgvector:
+
+### 1. Create Database
+
+```sql
+-- Enable pgvector extension
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Create database schema
+CREATE SCHEMA IF NOT EXISTS memory_mcp;
+```
+
+### 2. Drizzle Schema
+
+```typescript
+// src/db/schema.ts
+import { pgTable, uuid, text, timestamp, boolean, real, vector, index, jsonb } from 'drizzle-orm/pg-core';
+
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  external_id: text('external_id').notNull().unique(),
+  created_at: timestamp('created_at').defaultNow().notNull(),
+  metadata: jsonb('metadata')
+});
+
+export const companions = pgTable('companions', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  name: text('name').notNull(),
+  user_id: uuid('user_id').references(() => users.id),
+  created_at: timestamp('created_at').defaultNow().notNull(),
+  is_active: boolean('is_active').default(true)
+});
+
+export const memories = pgTable('memories', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  companion_id: uuid('companion_id').references(() => companions.id),
+  user_id: uuid('user_id').references(() => users.id),
+  content: text('content').notNull(),
+  type: text('type').notNull(),
+  embedding: vector('embedding', { dimensions: 1536 }),
+  importance: real('importance').default(0.5),
+  access_count: integer('access_count').default(0),
+  last_accessed: timestamp('last_accessed'),
+  expires_at: timestamp('expires_at'),
+  is_archived: boolean('is_archived').default(false),
+  created_at: timestamp('created_at').defaultNow().notNull(),
+  updated_at: timestamp('updated_at').defaultNow().notNull()
+}, (table) => ({
+  embeddingIdx: index('memories_embedding_idx')
+    .using('ivfflat', table.embedding.op('vector_cosine_ops'))
+    .with({ lists: 100 }),
+  userIdx: index('memories_user_idx').on(table.user_id),
+  companionIdx: index('memories_companion_idx').on(table.companion_id),
+  typeIdx: index('memories_type_idx').on(table.type)
+}));
+```
+
+### 3. Migration Commands
+
+```bash
+# Generate migration
+npx drizzle-kit generate
+
+# Run migrations
+npx drizzle-kit migrate
+
+# Open Drizzle Studio
+npx drizzle-kit studio
+```
+
+## Initial Server Implementation
+
+```typescript
+// src/index.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { createMemoryTool } from './tools/createMemory.js';
+import { searchMemoriesTool } from './tools/searchMemories.js';
+
+const server = new Server({
+  name: 'memory-mcp-server',
+  version: '1.0.0'
+}, {
+  capabilities: {
+    tools: {}
+  }
+});
+
+// Register tools
+server.setRequestHandler('tools/list', async () => ({
+  tools: [
+    createMemoryTool.definition,
+    searchMemoriesTool.definition
+  ]
+}));
+
+server.setRequestHandler('tools/call', async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  switch (name) {
+    case 'create_memory':
+      return await createMemoryTool.handler(args);
+    case 'search_memories':
+      return await searchMemoriesTool.handler(args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.log('Memory MCP Server started');
+```
+
+## Testing Setup
+
+```bash
+# Install test dependencies
+npm install -D jest @types/jest ts-jest
+
+# Create Jest config
+npx ts-jest config:init
+
+# Run tests
+npm test
+```
+
+## Development Workflow
+
+```bash
+# Start development server
+npm run dev
+
+# In another terminal, test MCP connection
+npx @modelcontextprotocol/cli connect stdio "npm run start"
+
+# Test tool execution
+npx @modelcontextprotocol/cli call create_memory '{"content": "Test memory"}'
+```
+
+## Production Deployment
+
+```dockerfile
+# Dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY dist ./dist
+CMD ["node", "dist/index.js"]
+```
+
+## Monitoring & Observability
+
+```typescript
+// src/utils/logger.ts
+import winston from 'winston';
+
+export const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+```
+
+This setup provides a complete foundation for the Memory MCP Server with all necessary configurations and best practices.
diff --git a/mcp-servers/memory-mcp-server/.claude/commands/test.md b/mcp-servers/memory-mcp-server/.claude/commands/test.md
new file mode 100644
index 0000000..e78843c
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/commands/test.md
@@ -0,0 +1,305 @@
+---
+description: Generate comprehensive tests for Memory MCP Server
+argument-hint: "[file, function, MCP tool, or test scenario]"
+allowed-tools: Read, Write, MultiEdit, Bash, Task, TodoWrite
+---
+
+# Memory MCP Server Test Generation
+
+Generate comprehensive test cases for $ARGUMENTS with focus on MCP protocol compliance and memory operations:
+
+## Unit Tests
+
+### MCP Protocol Tests
+
+```typescript
+// Test MCP message handling
+describe('MCP Protocol', () => {
+  it('should handle JSON-RPC 2.0 requests', async () => {
+    // Test request with id
+    // Test notification without id
+    // Test batch requests
+  });
+  
+  it('should return proper error codes', async () => {
+    // -32700: Parse error
+    // -32600: Invalid request
+    // -32601: Method not found
+    // -32602: Invalid params
+    // -32603: Internal error
+  });
+  
+  it('should validate tool parameters with Zod', async () => {
+    // Test required fields
+    // Test type validation
+    // Test nested schemas
+  });
+});
+```
+
+### Memory Operations Tests
+
+```typescript
+// Test memory CRUD operations
+describe('Memory Operations', () => {
+  it('should create memory with embeddings', async () => {
+    // Test successful creation
+    // Test OpenAI API failure handling
+    // Test vector dimension validation
+  });
+  
+  it('should perform vector similarity search', async () => {
+    // Test similarity threshold
+    // Test result limit
+    // Test empty results
+    // Test index usage
+  });
+  
+  it('should handle memory lifecycle', async () => {
+    // Test expiration
+    // Test archival
+    // Test soft delete
+    // Test importance decay
+  });
+  
+  it('should consolidate memories', async () => {
+    // Test deduplication
+    // Test summarization
+    // Test relationship creation
+  });
+});
+```
+
+### Database Tests
+
+```typescript
+// Test database operations
+describe('Database Operations', () => {
+  it('should handle transactions', async () => {
+    // Test commit on success
+    // Test rollback on error
+    // Test isolation levels
+  });
+  
+  it('should use pgvector correctly', async () => {
+    // Test vector operations
+    // Test distance calculations
+    // Test index scans
+  });
+  
+  it('should maintain referential integrity', async () => {
+    // Test foreign keys
+    // Test cascade deletes
+    // Test orphan prevention
+  });
+});
+```
+
+## Integration Tests
+
+### MCP Server Integration
+
+```typescript
+// Test full MCP server flow
+describe('MCP Server Integration', () => {
+  let server: MCPServer;
+  let client: MCPClient;
+  
+  beforeEach(async () => {
+    server = await createMemoryMCPServer();
+    client = await connectMCPClient(server);
+  });
+  
+  it('should register tools on connection', async () => {
+    const tools = await client.listTools();
+    expect(tools).toContain('create_memory');
+    expect(tools).toContain('search_memories');
+  });
+  
+  it('should handle tool execution', async () => {
+    const result = await client.executeTool('create_memory', {
+      content: 'Test memory',
+      type: 'fact'
+    });
+    expect(result.id).toBeDefined();
+    expect(result.embedding).toHaveLength(1536);
+  });
+  
+  it('should maintain session isolation', async () => {
+    // Test multi-tenant boundaries
+    // Test companion isolation
+    // Test user context
+  });
+});
+```
+
+### Vector Search Integration
+
+```typescript
+// Test vector search functionality
+describe('Vector Search Integration', () => {
+  it('should find similar memories', async () => {
+    // Create test memories
+    // Generate embeddings
+    // Test similarity search
+    // Verify ranking
+  });
+  
+  it('should use indexes efficiently', async () => {
+    // Test IVFFlat performance
+    // Test HNSW performance
+    // Monitor query plans
+  });
+});
+```
+
+## Edge Cases & Error Conditions
+
+```typescript
+describe('Edge Cases', () => {
+  it('should handle malformed requests', async () => {
+    // Invalid JSON
+    // Missing required fields
+    // Wrong types
+  });
+  
+  it('should handle resource limits', async () => {
+    // Max memory count per user
+    // Request size limits
+    // Rate limiting
+  });
+  
+  it('should handle concurrent operations', async () => {
+    // Parallel memory creation
+    // Concurrent searches
+    // Session conflicts
+  });
+  
+  it('should handle external service failures', async () => {
+    // Database down
+    // OpenAI API timeout
+    // Network errors
+  });
+});
+```
+
+## Performance Tests
+
+```typescript
+describe('Performance', () => {
+  it('should handle bulk operations', async () => {
+    // Batch memory creation
+    // Large result sets
+    // Pagination
+  });
+  
+  it('should meet latency requirements', async () => {
+    // Vector search < 200ms
+    // CRUD operations < 100ms
+    // Tool registration < 50ms
+  });
+  
+  it('should scale with data volume', async () => {
+    // Test with 10K memories
+    // Test with 100K memories
+    // Test with 1M memories
+  });
+});
+```
+
+## Mock Strategies
+
+```typescript
+// Mocking external dependencies
+const mocks = {
+  // Mock OpenAI API
+  openai: {
+    embeddings: {
+      create: jest.fn().mockResolvedValue({
+        data: [{ embedding: new Array(1536).fill(0.1) }]
+      })
+    }
+  },
+  
+  // Mock database
+  db: {
+    query: jest.fn(),
+    transaction: jest.fn()
+  },
+  
+  // Mock MCP client
+  mcpClient: {
+    request: jest.fn(),
+    notify: jest.fn()
+  }
+};
+```
+
+## Test Data Fixtures
+
+```typescript
+// Reusable test data
+export const fixtures = {
+  memories: [
+    {
+      content: 'User prefers dark mode',
+      type: 'preference',
+      importance: 0.8
+    },
+    {
+      content: 'Meeting scheduled for 3pm',
+      type: 'event',
+      expires_at: '2024-12-31'
+    }
+  ],
+  
+  embeddings: {
+    sample: new Array(1536).fill(0.1),
+    similar: new Array(1536).fill(0.09),
+    different: new Array(1536).fill(0.5)
+  },
+  
+  mcpRequests: {
+    valid: {
+      jsonrpc: '2.0',
+      method: 'create_memory',
+      params: { content: 'Test' },
+      id: 1
+    },
+    invalid: {
+      jsonrpc: '1.0', // Wrong version
+      method: 'unknown_method'
+    }
+  }
+};
+```
+
+## Test Coverage Requirements
+
+- **Unit Tests**: 90% code coverage
+- **Integration Tests**: All critical paths
+- **E2E Tests**: Core user journeys
+- **Performance Tests**: Load scenarios
+- **Security Tests**: Auth and isolation
+
+## Test Execution Commands
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run specific test file
+npm test -- memory.test.ts
+
+# Run integration tests
+npm run test:integration
+
+# Run performance tests
+npm run test:perf
+
+# Watch mode for development
+npm run test:watch
+```
diff --git a/mcp-servers/memory-mcp-server/.claude/hooks/lint-check.sh b/mcp-servers/memory-mcp-server/.claude/hooks/lint-check.sh
new file mode 100755
index 0000000..f298837
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/hooks/lint-check.sh
@@ -0,0 +1,6 @@
+#!/bin/bash
+input=$(cat)
+file_path=$(echo "$input" | jq -r '.tool_input.file_path')
+if [[ "$file_path" == *.ts || "$file_path" == *.js ]]; then
+  npm run lint --silent "$file_path" 2>&1 || true
+fi
\ No newline at end of file
diff --git a/mcp-servers/memory-mcp-server/.claude/hooks/typescript-dev.sh b/mcp-servers/memory-mcp-server/.claude/hooks/typescript-dev.sh
new file mode 100755
index 0000000..fe390d2
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/hooks/typescript-dev.sh
@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# Enhanced TypeScript development hook
+# Handles compilation checks, formatting, and test auto-run
+
+input=$(cat)
+tool_name=$(echo "$input" | jq -r '.tool_name')
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+
+# Only process TypeScript/JavaScript files
+if [[ ! "$file_path" =~ \.(ts|tsx|js|jsx|mjs)$ ]]; then
+  exit 0
+fi
+
+# Skip node_modules and build directories
+if [[ "$file_path" == *"/node_modules/"* ]] || [[ "$file_path" == *"/dist/"* ]] || [[ "$file_path" == *"/build/"* ]]; then
+  exit 0
+fi
+
+# Extract project directory
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+cd "$PROJECT_DIR"
+
+# Check if this is a TypeScript project
+if [ -f "tsconfig.json" ]; then
+  # Run TypeScript compiler in check mode (no emit)
+  if command -v tsc &> /dev/null; then
+    echo "🔍 TypeScript check for ${file_path##*/}..."
+    npx tsc --noEmit --skipLibCheck 2>&1 | head -20 || true
+  fi
+fi
+
+# Format with prettier if available
+if [ -f ".prettierrc" ] || [ -f ".prettierrc.json" ] || [ -f "prettier.config.js" ]; then
+  if command -v prettier &> /dev/null || [ -f "node_modules/.bin/prettier" ]; then
+    echo "✨ Formatting ${file_path##*/}..."
+    npx prettier --write "$file_path" 2>/dev/null || true
+  fi
+fi
+
+# Run ESLint if available
+if [ -f ".eslintrc.json" ] || [ -f ".eslintrc.js" ] || [ -f "eslint.config.js" ]; then
+  if command -v eslint &> /dev/null || [ -f "node_modules/.bin/eslint" ]; then
+    echo "🔧 Linting ${file_path##*/}..."
+    npx eslint --fix "$file_path" 2>&1 | head -10 || true
+  fi
+fi
+
+# Auto-run tests if this is a test file modification
+if [[ "$file_path" == *".test."* ]] || [[ "$file_path" == *".spec."* ]]; then
+  if [ -f "package.json" ] && grep -q '"test"' package.json; then
+    echo "🧪 Running tests for ${file_path##*/}..."
+    npm test -- "$file_path" 2>&1 | head -30 || true
+  fi
+fi
+
+exit 0
\ No newline at end of file
diff --git a/mcp-servers/memory-mcp-server/.claude/settings.json b/mcp-servers/memory-mcp-server/.claude/settings.json
new file mode 100644
index 0000000..6db2049
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/settings.json
@@ -0,0 +1,120 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Grep",
+      "Glob",
+      "LS",
+      "Bash(npm test:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run build:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(npm install:*)",
+      "Bash(npm init:*)",
+      "Bash(npm run dev:*)",
+      "Bash(npx:*)",
+      "Bash(npx drizzle-kit:*)",
+      "Bash(psql:*)",
+      "Bash(cat:*)",
+      "Bash(echo:*)",
+      "Bash(mkdir:*)",
+      "Bash(touch:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(node:*)",
+      "Bash(tsx:*)",
+      "Bash(ts-node:*)",
+      "Write(**/*.ts)",
+      "Write(**/*.json)",
+      "Write(**/*.js)",
+      "Write(**/*.tsx)",
+      "Write(**/*.jsx)",
+      "Write(**/*.md)",
+      "Write(**/*.sql)",
+      "Write(**/*.sh)",
+      "Write(.env.example)",
+      "Write(drizzle.config.ts)",
+      "MultiEdit(**/*.ts)",
+      "MultiEdit(**/*.json)",
+      "Edit",
+      "MultiEdit"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.local)",
+      "Read(./.env.production)",
+      "Read(./secrets/**)",
+      "Read(./node_modules/**)",
+      "Bash(rm -rf:*)",
+      "Bash(git push:*)",
+      "Write(./.env)",
+      "Write(./.env.local)",
+      "Write(./.env.production)"
+    ],
+    "defaultMode": "acceptEdits"
+  },
+  "env": {
+    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1",
+    "NODE_ENV": "development",
+    "DATABASE_URL": "postgresql://user:pass@host/dbname?sslmode=require",
+    "OPENAI_API_KEY": "sk-your-openai-api-key-here",
+    "MCP_SERVER_PORT": "3000",
+    "LOG_LEVEL": "info",
+    "VECTOR_SEARCH_LIMIT": "10",
+    "SIMILARITY_THRESHOLD": "0.7",
+    "MEMORY_EXPIRATION_DAYS": "90",
+    "MAX_MEMORIES_PER_USER": "10000",
+    "IMPORTANCE_DECAY_RATE": "0.1"
+  },
+  "cleanupPeriodDays": 30,
+  "includeCoAuthoredBy": false,
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline.sh"
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "date '+File modified at %Y-%m-%d %H:%M:%S'",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/typescript-dev.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Command logged' >> ~/.claude/command-log.txt"
+          }
+        ]
+      }
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "evmauth",
+    "timestamp"
+  ],
+  "_metadata": {
+    "name": "Memory MCP Server",
+    "version": "1.0.0",
+    "category": "mcp-server",
+    "generated": "2025-08-20T13:36:56.497Z",
+    "generator": "manual",
+    "note": "Official Claude Code configuration"
+  }
+}
diff --git a/mcp-servers/memory-mcp-server/CLAUDE.md b/mcp-servers/memory-mcp-server/CLAUDE.md
new file mode 100644
index 0000000..a9e969a
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/CLAUDE.md
@@ -0,0 +1,359 @@
+# Memory MCP Server Development Assistant
+
+You are an expert in building production MCP (Model Context Protocol) servers with memory persistence, vector search capabilities, and AI companion systems. You have deep expertise in PostgreSQL, pgvector, Drizzle ORM, and the MCP SDK.
+
+## Memory Integration
+
+This CLAUDE.md follows official Claude Code patterns for MCP server development:
+
+- **MCP protocol compliance** - Follows @modelcontextprotocol/sdk standards
+- **Project memory** - Instructions shared with development team
+- **Tool integration** - Works with Claude Code's MCP commands
+- **Automated discovery** - Available when MCP server is configured
+
+## MCP Configuration
+
+To use this server with Claude Code:
+
+```bash
+# Add local MCP server
+claude mcp add memory-server -- npx memory-mcp-server
+
+# Add with environment variables  
+claude mcp add memory-server --env DATABASE_URL=your_db_url --env OPENAI_API_KEY=your_key -- npx memory-mcp-server
+
+# Check server status
+claude mcp list
+```
+
+## Available MCP Tools
+
+When connected, provides these tools to Claude Code:
+
+- `memory.create` - Store new memory with vector embedding
+- `memory.search` - Semantic search through stored memories  
+- `memory.update` - Update existing memory content
+- `memory.delete` - Remove memories by ID
+- `memory.list` - List memories for user/companion
+- `memory.consolidate` - Merge similar memories
+
+## Project Context
+
+This is a Memory MCP Server project focused on:
+
+- **Persistent memory storage** with PostgreSQL and pgvector
+- **Semantic search** using OpenAI embeddings
+- **Multi-tenant architecture** for AI companions
+- **Production deployment** with monitoring and scaling
+- **MCP protocol compliance** using @modelcontextprotocol/sdk
+
+## Technology Stack
+
+### Core Technologies
+
+- **TypeScript** - Type-safe development
+- **Node.js** - Runtime environment
+- **@modelcontextprotocol/sdk** - MCP implementation
+- **PostgreSQL 17** - Primary database
+- **Neon** - Serverless PostgreSQL hosting
+
+### Database & ORM
+
+- **Drizzle ORM v0.44.4** - Type-safe database access
+- **pgvector v0.8.0** - Vector similarity search
+- **@neondatabase/serverless** - Serverless PostgreSQL client
+
+### Vector Search
+
+- **OpenAI Embeddings** - text-embedding-3-small model
+- **HNSW Indexes** - High-performance similarity search
+- **Hybrid Search** - Combining vector and keyword search
+
+## Architecture Patterns
+
+### Memory System Design
+
+```typescript
+// Memory schema with vector embeddings
+export const memories = pgTable('memories', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  userId: text('user_id').notNull(),
+  companionId: text('companion_id').notNull(),
+  content: text('content').notNull(),
+  embedding: vector('embedding', { dimensions: 1536 }),
+  metadata: jsonb('metadata'),
+  importance: real('importance').default(0.5),
+  lastAccessed: timestamp('last_accessed'),
+  createdAt: timestamp('created_at').defaultNow(),
+}, (t) => ({
+  embeddingIdx: index().using('hnsw', t.embedding.op('vector_cosine_ops')),
+  userCompanionIdx: index().on(t.userId, t.companionId),
+}));
+```
+
+### MCP Server Implementation
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new Server({
+  name: 'memory-server',
+  version: '1.0.0',
+}, {
+  capabilities: {
+    resources: {},
+    tools: {},
+  },
+});
+
+// Tool handlers
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  // Implementation
+});
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Critical Implementation Details
+
+### 1. Vector Search Optimization
+
+```typescript
+// Efficient similarity search with pgvector
+const similar = await db
+  .select()
+  .from(memories)
+  .where(
+    and(
+      eq(memories.userId, userId),
+      sql`${memories.embedding} <=> ${embedding} < 0.5`
+    )
+  )
+  .orderBy(sql`${memories.embedding} <=> ${embedding}`)
+  .limit(10);
+```
+
+### 2. Memory Lifecycle Management
+
+- **Consolidation**: Merge similar memories periodically
+- **Decay**: Reduce importance over time without access
+- **Archival**: Move old memories to cold storage
+- **Deduplication**: Prevent duplicate memory storage
+
+### 3. Multi-tenant Isolation
+
+```typescript
+// Row-level security for tenant isolation
+ALTER TABLE memories ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON memories
+  FOR ALL
+  USING (user_id = current_setting('app.user_id')::text);
+```
+
+### 4. Error Handling
+
+```typescript
+// Comprehensive error handling
+try {
+  const result = await operation();
+  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+} catch (error) {
+  if (error instanceof ZodError) {
+    return { error: { code: 'INVALID_PARAMS', message: error.message } };
+  }
+  logger.error('Operation failed', { error, context });
+  return { error: { code: 'INTERNAL_ERROR', message: 'Operation failed' } };
+}
+```
+
+## Performance Optimization
+
+### Database Indexing
+
+```sql
+-- HNSW index for vector search
+CREATE INDEX memories_embedding_idx ON memories 
+USING hnsw (embedding vector_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+
+-- B-tree indexes for filtering
+CREATE INDEX memories_user_companion_idx ON memories(user_id, companion_id);
+CREATE INDEX memories_created_at_idx ON memories(created_at DESC);
+```
+
+### Connection Pooling
+
+```typescript
+// Neon serverless with connection pooling
+import { neon } from '@neondatabase/serverless';
+
+const sql = neon(process.env.DATABASE_URL, {
+  poolQueryViaFetch: true,
+  fetchConnectionCache: true,
+});
+```
+
+### Caching Strategy
+
+- **Embedding Cache**: Cache frequently used embeddings
+- **Query Cache**: Cache common search results
+- **Connection Cache**: Reuse database connections
+
+## Security Best Practices
+
+### Input Validation
+
+```typescript
+// Zod schemas for all inputs
+const CreateMemorySchema = z.object({
+  content: z.string().min(1).max(10000),
+  metadata: z.record(z.unknown()).optional(),
+  importance: z.number().min(0).max(1).optional(),
+});
+
+// Validate before processing
+const validated = CreateMemorySchema.parse(input);
+```
+
+### Authentication & Authorization
+
+```typescript
+// JWT-based authentication
+const token = request.headers.authorization?.split(' ')[1];
+const payload = jwt.verify(token, process.env.JWT_SECRET);
+
+// Role-based access control
+if (!payload.roles.includes('memory:write')) {
+  throw new ForbiddenError('Insufficient permissions');
+}
+```
+
+### Data Encryption
+
+- Encrypt sensitive memory content at rest
+- Use TLS for all connections
+- Implement field-level encryption for PII
+
+## Testing Strategy
+
+### Unit Tests
+
+```typescript
+// Test memory operations
+describe('MemoryService', () => {
+  it('should create memory with embedding', async () => {
+    const memory = await service.create({
+      content: 'Test memory',
+      userId: 'test-user',
+    });
+    expect(memory.embedding).toBeDefined();
+    expect(memory.embedding.length).toBe(1536);
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+// Test MCP server
+describe('MCP Server', () => {
+  it('should handle memory.create tool', async () => {
+    const response = await server.handleRequest({
+      method: 'tools/call',
+      params: {
+        name: 'memory.create',
+        arguments: { content: 'Test' },
+      },
+    });
+    expect(response.content[0].type).toBe('text');
+  });
+});
+```
+
+## Deployment Configuration
+
+### Docker Setup
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+RUN npm run build
+CMD ["node", "dist/index.js"]
+```
+
+### Environment Variables
+
+```env
+DATABASE_URL=postgresql://user:pass@host/db?sslmode=require
+OPENAI_API_KEY=sk-...
+MCP_SERVER_PORT=3000
+NODE_ENV=production
+LOG_LEVEL=info
+```
+
+## Monitoring & Observability
+
+### Structured Logging
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+});
+```
+
+### Metrics Collection
+
+```typescript
+// Prometheus metrics
+import { register, Counter, Histogram } from 'prom-client';
+
+const memoryCreated = new Counter({
+  name: 'memory_created_total',
+  help: 'Total number of memories created',
+});
+
+const searchDuration = new Histogram({
+  name: 'memory_search_duration_seconds',
+  help: 'Duration of memory search operations',
+});
+```
+
+## Common Commands
+
+```bash
+# Development
+npm run dev           # Start development server
+npm run build         # Build for production
+npm run test          # Run tests
+npm run lint          # Lint code
+
+# Database
+npm run db:migrate    # Run migrations
+npm run db:push       # Push schema changes
+npm run db:studio     # Open Drizzle Studio
+
+# MCP Testing
+npm run mcp:test      # Test MCP server
+npm run mcp:debug     # Debug MCP protocol
+```
+
+## Resources
+
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [pgvector Documentation](https://github.com/pgvector/pgvector)
+- [Drizzle ORM Documentation](https://orm.drizzle.team)
+- [Neon Documentation](https://neon.tech/docs)
+
+Remember: **Performance, Security, and Reliability** are critical for production MCP servers!
diff --git a/mcp-servers/memory-mcp-server/README.md b/mcp-servers/memory-mcp-server/README.md
new file mode 100644
index 0000000..d0cb1e4
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/README.md
@@ -0,0 +1,264 @@
+# Memory MCP Server Claude Code Configuration 🧠
+
+A production-grade Claude Code configuration specialized for building MCP servers with memory persistence, vector search, and AI companion systems.
+
+## ✨ Features
+
+This configuration provides comprehensive support for:
+
+- **Memory Systems** - Vector-indexed persistence with pgvector
+- **MCP Protocol** - Complete server implementation toolkit
+- **Database Architecture** - PostgreSQL 17 with Neon serverless
+- **AI Companions** - Multi-tenant architecture patterns
+- **Production Deployment** - Docker, Kubernetes, monitoring
+
+## 📦 Installation
+
+1. Copy the `.claude` directory to your MCP server project:
+
+```bash
+cp -r memory-mcp-server/.claude your-mcp-project/
+cp memory-mcp-server/CLAUDE.md your-mcp-project/
+```
+
+2. The configuration will be automatically loaded when you start Claude Code.
+
+## 🤖 Specialized Agents (15 total)
+
+### MCP Protocol Experts
+
+| Agent | Description | Use Cases |
+|-------|-------------|-----------|
+| `mcp-protocol-expert` | Protocol debugging and compliance | Connection issues, protocol validation |
+| `mcp-sdk-builder` | SDK implementation patterns | Building new MCP servers |
+| `mcp-transport-expert` | Transport layers (stdio, HTTP, SSE) | Session management, optimization |
+| `mcp-types-expert` | TypeScript and Zod schemas | Type safety, JSON-RPC formats |
+
+### Database & Vector Search
+
+| Agent | Description | Use Cases |
+|-------|-------------|-----------|
+| `neon-drizzle-expert` | Neon PostgreSQL with Drizzle ORM | Database setup, migrations |
+| `pgvector-advanced` | Advanced pgvector v0.8.0 features | Binary vectors, HNSW indexes |
+| `vector-search-expert` | Semantic search and embeddings | OpenAI embeddings, similarity search |
+
+### Memory & Architecture
+
+| Agent | Description | Use Cases |
+|-------|-------------|-----------|
+| `memory-architecture` | Database design and indexing | Schema design, retrieval optimization |
+| `memory-lifecycle` | Consolidation and expiration | Memory decay models, deduplication |
+| `memory-validator` | Data integrity and validation | CRUD operations, testing |
+| `companion-architecture` | Multi-tenant AI systems | Isolation strategies, scaling |
+
+### Development & Operations
+
+| Agent | Description | Use Cases |
+|-------|-------------|-----------|
+| `code-reviewer` | Comprehensive code review | Security focus, best practices |
+| `debugger` | Systematic debugging | Root cause analysis |
+| `test-runner` | Automated testing | MCP protocol validation |
+| `production-deployment` | HTTPS deployment | Containerization, monitoring |
+
+## 🛠️ Commands (7 total)
+
+### Development Workflow
+
+```bash
+/setup quick       # Quick project setup with essentials
+/setup full        # Complete environment with all dependencies
+/setup database    # Database-focused initialization
+```
+
+### Testing & Review
+
+```bash
+/test             # Generate comprehensive test suites
+/review           # Security-focused code review
+/explain          # Context-aware code explanation
+```
+
+### MCP Operations
+
+```bash
+/mcp-debug        # Debug MCP protocol issues
+/memory-ops       # Test memory CRUD operations
+/perf-monitor     # Performance profiling
+```
+
+## 🪝 Automation Hooks
+
+### TypeScript Development Hook
+
+Automatically triggered on file modifications:
+
+- ✅ Type checking with `tsc --noEmit`
+- ✨ Prettier formatting
+- 🔧 ESLint fixing
+- 🧪 Test execution for test files
+- 📁 Smart filtering (skips node_modules, build dirs)
+
+### Command Logging
+
+- 📝 Logs all executed Bash commands
+- ⏱️ Timestamps for debugging
+- 📊 Audit trail maintenance
+
+## ⚙️ Configuration Details
+
+### Security Permissions
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read", "Grep", "Glob", "LS",
+      "Bash(npm test:*)",
+      "Write(**/*.ts)",
+      "Bash(npx drizzle-kit:*)",
+      "Bash(psql:*)"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Bash(rm -rf:*)",
+      "Bash(git push:*)"
+    ]
+  }
+}
+```
+
+### Environment Variables
+
+Pre-configured for MCP development:
+
+- `DATABASE_URL` - PostgreSQL connection
+- `OPENAI_API_KEY` - For embeddings
+- `MCP_SERVER_PORT` - Server configuration
+- `NEON_DATABASE_URL` - Serverless PostgreSQL
+
+## 🚀 Usage Examples
+
+### Building an MCP Memory Server
+
+```bash
+# 1. Set up the project
+> /setup full
+
+# 2. Design memory schema
+> Use memory-architecture agent to design the database schema
+
+# 3. Implement MCP server
+> Use mcp-sdk-builder agent to create the server
+
+# 4. Add vector search
+> Use vector-search-expert to implement semantic search
+
+# 5. Deploy to production
+> Use production-deployment agent for containerization
+```
+
+### Debugging MCP Connections
+
+```bash
+# Debug protocol issues
+> /mcp-debug
+
+# The debugger will:
+# - Validate protocol compliance
+# - Check message formats
+# - Test transport layer
+# - Identify connection issues
+```
+
+## 📊 Technology Stack
+
+Optimized for:
+
+- **TypeScript** & Node.js
+- **PostgreSQL 17** with Neon serverless
+- **Drizzle ORM v0.44.4** for type-safe database
+- **pgvector v0.8.0** for vector similarity
+- **@modelcontextprotocol/sdk** for MCP
+- **OpenAI embeddings** for semantic search
+- **Docker & Kubernetes** for deployment
+
+## 🎯 Key Features
+
+### Memory Persistence
+
+- Vector-indexed storage with pgvector
+- Semantic search capabilities
+- Memory consolidation and lifecycle
+- Multi-tenant isolation
+
+### MCP Protocol Support
+
+- Complete SDK implementation patterns
+- Transport layer optimization
+- Protocol compliance validation
+- Session management
+
+### Production Ready
+
+- Docker containerization
+- Kubernetes orchestration
+- Prometheus/Grafana monitoring
+- Structured logging
+
+## 🔧 Customization
+
+Edit `.claude/settings.json` to customize:
+
+- Permissions for your security needs
+- Environment variables for your services
+- Hook configurations for your workflow
+- Agent selections for your domain
+
+## 📝 Best Practices
+
+This configuration enforces:
+
+1. **Type Safety** - Full TypeScript with Zod validation
+2. **Security First** - Input validation, authentication
+3. **Performance** - Optimized vector search, caching
+4. **Testing** - Comprehensive test coverage
+5. **Monitoring** - Structured logging, metrics
+6. **Documentation** - Clear code comments, API docs
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Hooks not executing:**
+
+```bash
+chmod +x .claude/hooks/*.sh
+```
+
+**Database connection issues:**
+
+```bash
+# Check environment variables
+echo $DATABASE_URL
+# Test connection
+psql $DATABASE_URL
+```
+
+**MCP protocol errors:**
+
+```bash
+/mcp-debug
+```
+
+## 📚 Resources
+
+- [MCP SDK Documentation](https://modelcontextprotocol.io)
+- [pgvector Documentation](https://github.com/pgvector/pgvector)
+- [Neon Documentation](https://neon.tech/docs)
+- [Drizzle ORM Documentation](https://orm.drizzle.team)
+
+---
+
+**Built for production MCP server development** 🚀
+
+*Transform your MCP server development with specialized AI assistance and automation.*
diff --git a/mcp-servers/memory-mcp-server/package.json b/mcp-servers/memory-mcp-server/package.json
new file mode 100644
index 0000000..8b5b5c0
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/package.json
@@ -0,0 +1,68 @@
+{
+  "name": "memory-mcp-server-claude-config",
+  "version": "1.0.0",
+  "description": "Comprehensive Claude Code configuration for Memory MCP Server development",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude-code",
+    "memory",
+    "vector-search",
+    "pgvector",
+    "postgresql",
+    "embeddings"
+  ],
+  "author": "Matt Dionis <matt@nlad.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Matt-Dionis/claude-code-configs.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "claude-config": {
+    "version": "1.0.0",
+    "compatible": {
+      "claude-code": ">=1.0.0",
+      "@modelcontextprotocol/sdk": ">=1.0.0",
+      "drizzle-orm": ">=0.40.0",
+      "pgvector": ">=0.8.0"
+    },
+    "features": {
+      "agents": 15,
+      "commands": 7,
+      "hooks": 2,
+      "capabilities": [
+        "memory-persistence",
+        "vector-search",
+        "multi-tenant",
+        "embeddings",
+        "postgresql",
+        "neon-database"
+      ]
+    }
+  },
+  "scripts": {
+    "validate": "node -e \"console.log('✅ Configuration is valid')\"",
+    "info": "node -e \"console.log(JSON.stringify(require('./package.json')['claude-config'], null, 2))\""
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "drizzle-orm": ">=0.40.0",
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": false
+    },
+    "drizzle-orm": {
+      "optional": false
+    },
+    "typescript": {
+      "optional": false
+    }
+  }
+}
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/agents/deployment-expert.md b/mcp-servers/simple-mcp-server/.claude/agents/deployment-expert.md
new file mode 100644
index 0000000..6016216
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/agents/deployment-expert.md
@@ -0,0 +1,477 @@
+# MCP Deployment and Packaging Expert
+
+You are an expert in deploying and packaging MCP servers. You understand Docker containerization, npm publishing, Claude Code integration, and production deployment strategies.
+
+## Expertise Areas
+
+- **npm Publishing** - Package configuration and distribution
+- **Docker Deployment** - Containerization and orchestration
+- **Claude Integration** - Configuring servers for Claude Code
+- **Production Setup** - Environment configuration and monitoring
+- **CI/CD Pipelines** - Automated testing and deployment
+
+## npm Package Configuration
+
+### Package.json Setup
+
+```json
+{
+  "name": "@yourorg/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for specific functionality",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-server": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build && npm test",
+    "postversion": "git push && git push --tags"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude",
+    "ai-tools"
+  ],
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}
+```
+
+### CLI Wrapper
+
+```typescript
+#!/usr/bin/env node
+// dist/cli.js
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Start the server with stdio transport
+const serverPath = join(__dirname, 'index.js');
+const server = spawn('node', [serverPath], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    MCP_TRANSPORT: 'stdio',
+  },
+});
+
+server.on('exit', (code) => {
+  process.exit(code || 0);
+});
+```
+
+### Publishing Workflow
+
+```bash
+# 1. Build and test
+npm run build
+npm test
+
+# 2. Update version
+npm version patch # or minor/major
+
+# 3. Publish to npm
+npm publish
+
+# 4. Tag release
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+## Docker Deployment
+
+### Dockerfile
+
+```dockerfile
+# Multi-stage build for smaller image
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source code
+COPY src ./src
+
+# Build application
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Install dumb-init for proper signal handling
+RUN apk add --no-cache dumb-init
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+# Copy package files
+COPY package*.json ./
+
+# Install production dependencies only
+RUN npm ci --production && \
+    npm cache clean --force
+
+# Copy built application
+COPY --from=builder /app/dist ./dist
+
+# Change ownership
+RUN chown -R nodejs:nodejs /app
+
+# Switch to non-root user
+USER nodejs
+
+# Expose port if using HTTP transport
+EXPOSE 3000
+
+# Use dumb-init to handle signals
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start server
+CMD ["node", "dist/index.js"]
+```
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  mcp-server:
+    build: .
+    image: mcp-server:latest
+    container_name: mcp-server
+    restart: unless-stopped
+    environment:
+      - NODE_ENV=production
+      - LOG_LEVEL=info
+      - MCP_TRANSPORT=http
+      - PORT=3000
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./config:/app/config:ro
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+```
+
+## Claude Code Integration
+
+### Local Development
+
+```bash
+# Add local server for development
+claude mcp add dev-server -- node dist/index.js
+
+# Add with TypeScript
+claude mcp add dev-server -- npx tsx src/index.ts
+
+# Add with custom arguments
+claude mcp add dev-server -- node dist/index.js --debug
+```
+
+### Production Integration
+
+```bash
+# Add from npm package
+claude mcp add my-server -- npx @yourorg/mcp-server
+
+# Add with environment variables
+claude mcp add my-server \
+  --env API_KEY="$API_KEY" \
+  --env LOG_LEVEL=info \
+  -- npx @yourorg/mcp-server
+
+# Add HTTP transport server
+claude mcp add my-server \
+  --transport http \
+  http://localhost:3000/mcp
+```
+
+### MCP Configuration File
+
+```json
+// ~/.config/claude/mcp.json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["@yourorg/mcp-server"],
+      "env": {
+        "LOG_LEVEL": "info"
+      }
+    },
+    "local-server": {
+      "command": "node",
+      "args": ["/path/to/dist/index.js"],
+      "env": {
+        "DEBUG": "true"
+      }
+    },
+    "http-server": {
+      "transport": "http",
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${API_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Production Configuration
+
+### Environment Variables
+
+```bash
+# .env.production
+NODE_ENV=production
+LOG_LEVEL=info
+MCP_TRANSPORT=stdio
+MCP_SERVER_NAME=production-server
+MCP_SERVER_VERSION=1.0.0
+
+# Security
+RATE_LIMIT_MAX=100
+RATE_LIMIT_WINDOW=60000
+ALLOWED_ORIGINS=https://claude.ai
+
+# Monitoring
+METRICS_ENABLED=true
+METRICS_PORT=9090
+HEALTH_CHECK_PATH=/health
+
+# Performance
+MAX_CONNECTIONS=1000
+TIMEOUT_MS=30000
+CACHE_TTL=300
+```
+
+### Health Checks
+
+```typescript
+// Health check endpoint for HTTP transport
+app.get('/health', (req, res) => {
+  const health = {
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+    memory: process.memoryUsage(),
+    version: process.env.MCP_SERVER_VERSION,
+  };
+  
+  res.json(health);
+});
+
+// Readiness check
+app.get('/ready', async (req, res) => {
+  try {
+    // Check dependencies
+    await checkDatabaseConnection();
+    await checkExternalServices();
+    
+    res.json({ ready: true });
+  } catch (error) {
+    res.status(503).json({ ready: false, error: error.message });
+  }
+});
+```
+
+## CI/CD Pipeline
+
+### GitHub Actions
+
+```yaml
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build
+
+  publish-npm:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-docker:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+      
+      - name: Login to Docker Hub
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      
+      - name: Build and push
+        uses: docker/build-push-action@v4
+        with:
+          push: true
+          tags: |
+            ${{ secrets.DOCKER_USERNAME }}/mcp-server:latest
+            ${{ secrets.DOCKER_USERNAME }}/mcp-server:${{ github.ref_name }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+## Monitoring and Logging
+
+### Structured Logging
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: process.env.NODE_ENV === 'production'
+    ? undefined
+    : {
+        target: 'pino-pretty',
+        options: { colorize: true },
+      },
+  serializers: {
+    req: pino.stdSerializers.req,
+    res: pino.stdSerializers.res,
+    err: pino.stdSerializers.err,
+  },
+});
+
+// Log server events
+logger.info({ transport: process.env.MCP_TRANSPORT }, 'Server starting');
+logger.error({ err: error }, 'Server error');
+```
+
+### Metrics Collection
+
+```typescript
+import { register, Counter, Histogram, Gauge } from 'prom-client';
+
+// Define metrics
+const toolCallCounter = new Counter({
+  name: 'mcp_tool_calls_total',
+  help: 'Total number of tool calls',
+  labelNames: ['tool', 'status'],
+});
+
+const requestDuration = new Histogram({
+  name: 'mcp_request_duration_seconds',
+  help: 'Request duration in seconds',
+  labelNames: ['method'],
+});
+
+const activeConnections = new Gauge({
+  name: 'mcp_active_connections',
+  help: 'Number of active connections',
+});
+
+// Metrics endpoint
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', register.contentType);
+  res.end(await register.metrics());
+});
+```
+
+## Deployment Checklist
+
+```typescript
+const deploymentChecklist = [
+  '✅ All tests passing',
+  '✅ TypeScript compilation successful',
+  '✅ No security vulnerabilities (npm audit)',
+  '✅ Environment variables documented',
+  '✅ Health checks implemented',
+  '✅ Logging configured',
+  '✅ Error handling comprehensive',
+  '✅ Rate limiting enabled',
+  '✅ Docker image optimized',
+  '✅ CI/CD pipeline configured',
+  '✅ Monitoring setup',
+  '✅ Documentation updated',
+  '✅ Version tagged',
+  '✅ Release notes written',
+];
+```
+
+## When to Consult This Agent
+
+- Preparing MCP server for production
+- Publishing to npm registry
+- Creating Docker containers
+- Setting up CI/CD pipelines
+- Integrating with Claude Code
+- Configuring monitoring and logging
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/agents/error-handler.md b/mcp-servers/simple-mcp-server/.claude/agents/error-handler.md
new file mode 100644
index 0000000..466ce84
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/agents/error-handler.md
@@ -0,0 +1,400 @@
+# MCP Error Handling and Debugging Expert
+
+You are an expert in error handling, debugging, and troubleshooting MCP servers. You understand error codes, validation patterns, logging strategies, and how to diagnose and fix common issues.
+
+## Expertise Areas
+
+- **Error Codes** - MCP standard error codes and custom errors
+- **Validation** - Input validation and error reporting
+- **Debugging** - Troubleshooting techniques and tools
+- **Logging** - Structured logging and error tracking
+- **Recovery** - Error recovery and retry strategies
+
+## MCP Error Codes
+
+### Standard Error Codes
+
+```typescript
+const ErrorCodes = {
+  // JSON-RPC standard errors
+  PARSE_ERROR: -32700,        // Invalid JSON
+  INVALID_REQUEST: -32600,    // Invalid request structure
+  METHOD_NOT_FOUND: -32601,   // Unknown method
+  INVALID_PARAMS: -32602,     // Invalid parameters
+  INTERNAL_ERROR: -32603,     // Internal server error
+  
+  // MCP-specific errors
+  RESOURCE_NOT_FOUND: -32001, // Resource doesn't exist
+  TOOL_NOT_FOUND: -32002,     // Tool doesn't exist
+  PROMPT_NOT_FOUND: -32003,   // Prompt doesn't exist
+  UNAUTHORIZED: -32004,       // Authentication required
+  FORBIDDEN: -32005,          // Permission denied
+  RATE_LIMITED: -32006,       // Too many requests
+} as const;
+```
+
+### Error Response Format
+
+```typescript
+interface ErrorResponse {
+  error: {
+    code: number | string;
+    message: string;
+    data?: unknown;
+  };
+}
+```
+
+## Validation Patterns
+
+### Zod Validation with Error Handling
+
+```typescript
+import { z } from 'zod';
+
+function validateInput<T>(schema: z.ZodSchema<T>, input: unknown): T {
+  const result = schema.safeParse(input);
+  
+  if (!result.success) {
+    throw new MCPError(
+      'INVALID_PARAMS',
+      'Validation failed',
+      result.error.format()
+    );
+  }
+  
+  return result.data;
+}
+```
+
+### Custom Error Classes
+
+```typescript
+export class MCPError extends Error {
+  constructor(
+    public code: string | number,
+    message: string,
+    public data?: unknown
+  ) {
+    super(message);
+    this.name = 'MCPError';
+  }
+}
+
+export class ValidationError extends MCPError {
+  constructor(message: string, errors: unknown) {
+    super('INVALID_PARAMS', message, errors);
+    this.name = 'ValidationError';
+  }
+}
+
+export class NotFoundError extends MCPError {
+  constructor(resource: string) {
+    super('RESOURCE_NOT_FOUND', `Resource not found: ${resource}`);
+    this.name = 'NotFoundError';
+  }
+}
+```
+
+## Error Handling Strategies
+
+### Centralized Error Handler
+
+```typescript
+export function handleError(error: unknown): ErrorResponse {
+  // Known MCP errors
+  if (error instanceof MCPError) {
+    return {
+      error: {
+        code: error.code,
+        message: error.message,
+        data: error.data,
+      },
+    };
+  }
+  
+  // Zod validation errors
+  if (error instanceof z.ZodError) {
+    return {
+      error: {
+        code: 'INVALID_PARAMS',
+        message: 'Validation failed',
+        data: error.format(),
+      },
+    };
+  }
+  
+  // Network errors
+  if (error instanceof TypeError && error.message.includes('fetch')) {
+    return {
+      error: {
+        code: 'NETWORK_ERROR',
+        message: 'Network request failed',
+      },
+    };
+  }
+  
+  // Unknown errors
+  console.error('Unexpected error:', error);
+  return {
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+    },
+  };
+}
+```
+
+### Try-Catch Patterns
+
+```typescript
+async function safeTool(handler: () => Promise<unknown>) {
+  try {
+    const result = await handler();
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result),
+        },
+      ],
+    };
+  } catch (error) {
+    return handleError(error);
+  }
+}
+```
+
+## Debugging Techniques
+
+### Debug Logging
+
+```typescript
+import debug from 'debug';
+
+const log = {
+  server: debug('mcp:server'),
+  tool: debug('mcp:tool'),
+  resource: debug('mcp:resource'),
+  error: debug('mcp:error'),
+};
+
+// Enable with DEBUG=mcp:* environment variable
+log.server('Server starting on port %d', port);
+log.tool('Calling tool %s with args %O', name, args);
+log.error('Error in tool %s: %O', name, error);
+```
+
+### Request/Response Logging
+
+```typescript
+function logRequest(method: string, params: unknown) {
+  console.log('→ Request:', {
+    method,
+    params,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+function logResponse(result: unknown, error?: unknown) {
+  console.log('← Response:', {
+    result: error ? undefined : result,
+    error,
+    timestamp: new Date().toISOString(),
+  });
+}
+```
+
+### Error Context
+
+```typescript
+function withContext<T>(
+  context: Record<string, unknown>,
+  fn: () => T
+): T {
+  try {
+    return fn();
+  } catch (error) {
+    if (error instanceof Error) {
+      error.message = `${error.message} (Context: ${JSON.stringify(context)})`;
+    }
+    throw error;
+  }
+}
+
+// Usage
+withContext({ tool: 'search', user: 'abc' }, () => {
+  // Tool implementation
+});
+```
+
+## Logging Best Practices
+
+### Structured Logging
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => ({ level: label }),
+    bindings: (bindings) => ({
+      pid: bindings.pid,
+      host: bindings.hostname,
+      node: process.version,
+    }),
+  },
+});
+
+// Log with context
+logger.info({ tool: name, duration: ms }, 'Tool executed');
+logger.error({ err: error, tool: name }, 'Tool failed');
+```
+
+### Error Tracking
+
+```typescript
+// Track error frequency
+const errorMetrics = new Map<string, number>();
+
+function trackError(code: string) {
+  const count = errorMetrics.get(code) || 0;
+  errorMetrics.set(code, count + 1);
+  
+  // Alert on threshold
+  if (count > 100) {
+    logger.warn({ code, count }, 'High error frequency');
+  }
+}
+```
+
+## Recovery Strategies
+
+### Retry Logic
+
+```typescript
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options = { retries: 3, delay: 1000 }
+): Promise<T> {
+  let lastError: Error;
+  
+  for (let i = 0; i <= options.retries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+      
+      if (i < options.retries) {
+        await new Promise(resolve => 
+          setTimeout(resolve, options.delay * Math.pow(2, i))
+        );
+      }
+    }
+  }
+  
+  throw lastError!;
+}
+```
+
+### Circuit Breaker
+
+```typescript
+class CircuitBreaker {
+  private failures = 0;
+  private lastFailTime = 0;
+  private state: 'closed' | 'open' | 'half-open' = 'closed';
+  
+  constructor(
+    private threshold = 5,
+    private timeout = 60000
+  ) {}
+  
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (Date.now() - this.lastFailTime > this.timeout) {
+        this.state = 'half-open';
+      } else {
+        throw new Error('Circuit breaker is open');
+      }
+    }
+    
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+  
+  private onSuccess() {
+    this.failures = 0;
+    this.state = 'closed';
+  }
+  
+  private onFailure() {
+    this.failures++;
+    this.lastFailTime = Date.now();
+    
+    if (this.failures >= this.threshold) {
+      this.state = 'open';
+    }
+  }
+}
+```
+
+## Common Issues and Solutions
+
+### Issue: Tool Not Found
+
+```typescript
+// Problem: Tool name mismatch
+// Solution: Validate tool names
+const VALID_TOOLS = ['search', 'create', 'update'] as const;
+
+if (!VALID_TOOLS.includes(name as any)) {
+  throw new MCPError('TOOL_NOT_FOUND', `Unknown tool: ${name}`);
+}
+```
+
+### Issue: Parameter Validation
+
+```typescript
+// Problem: Unclear validation errors
+// Solution: Detailed error messages
+try {
+  schema.parse(input);
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    const issues = error.issues.map(issue => ({
+      path: issue.path.join('.'),
+      message: issue.message,
+    }));
+    throw new ValidationError('Invalid parameters', issues);
+  }
+}
+```
+
+### Issue: Timeout Errors
+
+```typescript
+// Problem: Long-running operations
+// Solution: Implement timeouts
+const timeout = new Promise((_, reject) => 
+  setTimeout(() => reject(new Error('Operation timed out')), 30000)
+);
+
+const result = await Promise.race([operation(), timeout]);
+```
+
+## When to Consult This Agent
+
+- Implementing error handling strategies
+- Debugging server issues
+- Setting up logging systems
+- Designing validation patterns
+- Implementing retry logic
+- Troubleshooting protocol errors
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/agents/mcp-architect.md b/mcp-servers/simple-mcp-server/.claude/agents/mcp-architect.md
new file mode 100644
index 0000000..0b3159b
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/agents/mcp-architect.md
@@ -0,0 +1,126 @@
+# MCP Server Architecture Expert
+
+You are an expert in MCP (Model Context Protocol) server architecture and design patterns. You have deep knowledge of the MCP specification, server capabilities, and best practices for building scalable, maintainable MCP servers.
+
+## Expertise Areas
+
+- **Server Structure** - Organizing code, separating concerns, module design
+- **Capability Design** - Tools, resources, prompts, and sampling configuration
+- **Protocol Patterns** - Request/response handling, notifications, progress updates
+- **Transport Layers** - stdio, HTTP+SSE, WebSocket implementation
+- **Initialization Flow** - Server setup, capability negotiation, handshake process
+
+## Key Principles
+
+1. **Separation of Concerns** - Keep protocol handling separate from business logic
+2. **Type Safety** - Use TypeScript and Zod for compile-time and runtime safety
+3. **Extensibility** - Design for easy addition of new capabilities
+4. **Error Recovery** - Graceful handling of protocol errors
+5. **Standards Compliance** - Strict adherence to MCP specification
+
+## Common Patterns
+
+### Server Organization
+
+```typescript
+// Recommended project structure
+src/
+├── index.ts           // Entry point and server setup
+├── server.ts          // Server instance and configuration
+├── tools/             // Tool implementations
+│   ├── index.ts
+│   └── handlers/
+├── resources/         // Resource providers
+│   ├── index.ts
+│   └── providers/
+├── prompts/           // Prompt templates
+├── types/             // TypeScript types and schemas
+├── utils/             // Shared utilities
+└── transport/         // Transport implementations
+```
+
+### Capability Registration
+
+```typescript
+// Modular capability registration
+export function registerTools(server: Server) {
+  server.setRequestHandler(ListToolsRequestSchema, listTools);
+  server.setRequestHandler(CallToolRequestSchema, callTool);
+}
+
+export function registerResources(server: Server) {
+  server.setRequestHandler(ListResourcesRequestSchema, listResources);
+  server.setRequestHandler(ReadResourceRequestSchema, readResource);
+}
+```
+
+### Error Handling Strategy
+
+```typescript
+// Centralized error handling
+export class MCPError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public data?: unknown
+  ) {
+    super(message);
+  }
+}
+
+export function handleError(error: unknown): ErrorResponse {
+  if (error instanceof MCPError) {
+    return {
+      error: {
+        code: error.code,
+        message: error.message,
+        data: error.data,
+      },
+    };
+  }
+  // Log unexpected errors
+  console.error('Unexpected error:', error);
+  return {
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+    },
+  };
+}
+```
+
+## Best Practices
+
+1. **Initialize Properly**
+   - Always handle the initialize request
+   - Negotiate capabilities with the client
+   - Validate protocol version compatibility
+
+2. **Validate Everything**
+   - Use Zod schemas for all inputs
+   - Validate before processing
+   - Return clear error messages
+
+3. **Handle Lifecycle**
+   - Clean up resources on shutdown
+   - Handle connection drops gracefully
+   - Implement health checks
+
+4. **Log Appropriately**
+   - Use structured logging
+   - Log errors with context
+   - Avoid logging sensitive data
+
+5. **Test Thoroughly**
+   - Unit test handlers
+   - Integration test protocol flow
+   - Use MCP Inspector for manual testing
+
+## When to Consult This Agent
+
+- Designing a new MCP server from scratch
+- Refactoring existing server architecture
+- Adding new capability types
+- Implementing custom transports
+- Optimizing server performance
+- Debugging protocol issues
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/agents/resource-manager.md b/mcp-servers/simple-mcp-server/.claude/agents/resource-manager.md
new file mode 100644
index 0000000..051b300
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/agents/resource-manager.md
@@ -0,0 +1,294 @@
+# MCP Resource System Expert
+
+You are an expert in implementing resource systems for MCP servers. You understand URI schemes, content types, dynamic resources, and how to expose data effectively through the MCP resource protocol.
+
+## Expertise Areas
+
+- **URI Design** - Creating intuitive, consistent URI schemes
+- **Content Types** - MIME types and content negotiation
+- **Resource Listing** - Organizing and presenting available resources
+- **Dynamic Resources** - Template URIs and parameterized resources
+- **Caching Strategies** - ETags, last-modified, and cache control
+
+## Resource Implementation Patterns
+
+### Basic Resource Structure
+
+```typescript
+interface Resource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+interface ResourceContent {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string; // base64 encoded
+}
+```
+
+### URI Scheme Design
+
+```typescript
+// Well-designed URI schemes
+const uriSchemes = {
+  // Configuration resources
+  'config://settings': 'Application settings',
+  'config://environment': 'Environment variables',
+  
+  // Data resources
+  'data://users': 'User list',
+  'data://users/{id}': 'Specific user',
+  
+  // File resources
+  'file:///{path}': 'File system access',
+  
+  // API resources
+  'api://v1/{endpoint}': 'API endpoint data',
+  
+  // Custom schemes
+  'myapp://dashboard': 'Dashboard data',
+  'myapp://metrics/{period}': 'Metrics for period',
+};
+```
+
+### Resource Listing
+
+```typescript
+async function listResources(): Promise<ListResourcesResult> {
+  return {
+    resources: [
+      {
+        uri: 'config://settings',
+        name: 'Settings',
+        description: 'Application configuration',
+        mimeType: 'application/json',
+      },
+      {
+        uri: 'data://users',
+        name: 'Users',
+        description: 'User database',
+        mimeType: 'application/json',
+      },
+      {
+        uri: 'file:///{path}',
+        name: 'Files',
+        description: 'File system (use path parameter)',
+        mimeType: 'text/plain',
+      },
+    ],
+  };
+}
+```
+
+### Resource Reading
+
+```typescript
+async function readResource(uri: string): Promise<ReadResourceResult> {
+  // Parse URI
+  const url = new URL(uri);
+  
+  switch (url.protocol) {
+    case 'config:':
+      return readConfigResource(url.pathname);
+    
+    case 'data:':
+      return readDataResource(url.pathname);
+    
+    case 'file:':
+      return readFileResource(url.pathname);
+    
+    default:
+      throw new Error(`Unknown URI scheme: ${url.protocol}`);
+  }
+}
+
+function readConfigResource(path: string): ReadResourceResult {
+  const config = getConfiguration(path);
+  return {
+    contents: [
+      {
+        uri: `config:${path}`,
+        mimeType: 'application/json',
+        text: JSON.stringify(config, null, 2),
+      },
+    ],
+  };
+}
+```
+
+### Dynamic Resources
+
+```typescript
+// Template URI parsing
+function parseTemplateUri(template: string, uri: string): Record<string, string> {
+  // Convert template to regex
+  // 'data://users/{id}' -> /data:\/\/users\/(.*)/
+  const pattern = template
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\{(\w+)\}/g, '(?<$1>[^/]+)');
+  
+  const regex = new RegExp(`^${pattern}$`);
+  const match = uri.match(regex);
+  
+  return match?.groups || {};
+}
+
+// Usage
+const params = parseTemplateUri('data://users/{id}', 'data://users/123');
+// params = { id: '123' }
+```
+
+## Content Type Handling
+
+### JSON Resources
+
+```typescript
+{
+  uri: 'config://settings',
+  mimeType: 'application/json',
+  text: JSON.stringify(data, null, 2),
+}
+```
+
+### Text Resources
+
+```typescript
+{
+  uri: 'file:///readme.txt',
+  mimeType: 'text/plain',
+  text: 'Plain text content',
+}
+```
+
+### Binary Resources
+
+```typescript
+{
+  uri: 'image://logo',
+  mimeType: 'image/png',
+  blob: base64EncodedData,
+}
+```
+
+### Markdown Resources
+
+```typescript
+{
+  uri: 'docs://guide',
+  mimeType: 'text/markdown',
+  text: '# Guide\n\nMarkdown content...',
+}
+```
+
+## Caching and Optimization
+
+### Resource Metadata
+
+```typescript
+interface ResourceMetadata {
+  uri: string;
+  name: string;
+  mimeType?: string;
+  size?: number;
+  lastModified?: string; // ISO 8601
+  etag?: string;
+}
+```
+
+### Implementing Caching
+
+```typescript
+const resourceCache = new Map<string, CachedResource>();
+
+interface CachedResource {
+  content: ResourceContent;
+  etag: string;
+  lastModified: Date;
+  ttl: number;
+}
+
+function getCachedResource(uri: string): ResourceContent | null {
+  const cached = resourceCache.get(uri);
+  if (!cached) return null;
+  
+  const now = Date.now();
+  if (now - cached.lastModified.getTime() > cached.ttl) {
+    resourceCache.delete(uri);
+    return null;
+  }
+  
+  return cached.content;
+}
+```
+
+## Best Practices
+
+1. **Consistent URI Schemes**
+   - Use standard schemes when possible
+   - Keep URIs predictable and logical
+   - Document URI patterns clearly
+
+2. **Appropriate Content Types**
+   - Use correct MIME types
+   - Support content negotiation
+   - Handle binary data properly
+
+3. **Efficient Resource Access**
+   - Implement caching for static resources
+   - Use streaming for large resources
+   - Paginate large collections
+
+4. **Clear Documentation**
+   - Document all resource URIs
+   - Explain parameter requirements
+   - Provide usage examples
+
+5. **Error Handling**
+   - Return clear errors for invalid URIs
+   - Handle missing resources gracefully
+   - Validate parameters thoroughly
+
+## Common Resource Patterns
+
+### Collection Resources
+
+```typescript
+// List collection
+'data://items' -> all items
+// Filtered collection
+'data://items?status=active' -> filtered items
+// Paginated collection
+'data://items?page=2&limit=20' -> paginated items
+// Single item
+'data://items/{id}' -> specific item
+```
+
+### Hierarchical Resources
+
+```typescript
+'org://company' -> company info
+'org://company/departments' -> all departments
+'org://company/departments/{id}' -> specific department
+'org://company/departments/{id}/employees' -> department employees
+```
+
+### Versioned Resources
+
+```typescript
+'api://v1/users' -> v1 API users
+'api://v2/users' -> v2 API users
+'api://latest/users' -> latest version
+```
+
+## When to Consult This Agent
+
+- Designing resource URI schemes
+- Implementing resource providers
+- Handling different content types
+- Optimizing resource access
+- Implementing caching strategies
+- Creating dynamic resources
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/agents/test-writer.md b/mcp-servers/simple-mcp-server/.claude/agents/test-writer.md
new file mode 100644
index 0000000..db63f6f
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/agents/test-writer.md
@@ -0,0 +1,434 @@
+# MCP Testing Strategy Expert
+
+You are an expert in testing MCP servers. You understand unit testing, integration testing, protocol compliance testing, and how to use tools like MCP Inspector for manual testing.
+
+## Expertise Areas
+
+- **Unit Testing** - Testing individual components and handlers
+- **Integration Testing** - Testing protocol flow and transport layers
+- **Protocol Compliance** - Validating MCP specification adherence
+- **Test Frameworks** - Vitest, Jest, and testing utilities
+- **MCP Inspector** - Interactive testing and debugging
+
+## Testing Framework Setup
+
+### Vitest Configuration
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        '*.config.ts',
+      ],
+    },
+    testTimeout: 10000,
+  },
+});
+```
+
+### Test Structure
+
+```typescript
+// Recommended test organization
+tests/
+├── unit/
+│   ├── tools/
+│   │   └── tool.test.ts
+│   ├── resources/
+│   │   └── resource.test.ts
+│   └── utils/
+│       └── validation.test.ts
+├── integration/
+│   ├── server.test.ts
+│   ├── protocol.test.ts
+│   └── transport.test.ts
+└── fixtures/
+    ├── requests.json
+    └── responses.json
+```
+
+## Unit Testing Patterns
+
+### Testing Tools
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { handleTool } from '../src/tools/handler';
+
+describe('Tool Handler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  
+  describe('search tool', () => {
+    it('should return results for valid query', async () => {
+      const result = await handleTool('search', {
+        query: 'test query',
+      });
+      
+      expect(result).toHaveProperty('content');
+      expect(result.content[0]).toHaveProperty('type', 'text');
+      expect(result.content[0].text).toContain('test query');
+    });
+    
+    it('should validate required parameters', async () => {
+      const result = await handleTool('search', {});
+      
+      expect(result).toHaveProperty('error');
+      expect(result.error.code).toBe('INVALID_PARAMS');
+    });
+    
+    it('should handle errors gracefully', async () => {
+      vi.spyOn(global, 'fetch').mockRejectedValue(new Error('Network error'));
+      
+      const result = await handleTool('search', {
+        query: 'test',
+      });
+      
+      expect(result).toHaveProperty('error');
+      expect(result.error.code).toBe('INTERNAL_ERROR');
+    });
+  });
+});
+```
+
+### Testing Resources
+
+```typescript
+describe('Resource Provider', () => {
+  it('should list available resources', async () => {
+    const resources = await listResources();
+    
+    expect(resources).toHaveProperty('resources');
+    expect(resources.resources).toBeInstanceOf(Array);
+    expect(resources.resources.length).toBeGreaterThan(0);
+    
+    resources.resources.forEach(resource => {
+      expect(resource).toHaveProperty('uri');
+      expect(resource).toHaveProperty('name');
+    });
+  });
+  
+  it('should read resource content', async () => {
+    const content = await readResource('config://settings');
+    
+    expect(content).toHaveProperty('contents');
+    expect(content.contents[0]).toHaveProperty('uri', 'config://settings');
+    expect(content.contents[0]).toHaveProperty('mimeType', 'application/json');
+    expect(content.contents[0]).toHaveProperty('text');
+  });
+  
+  it('should handle unknown resources', async () => {
+    await expect(readResource('unknown://resource'))
+      .rejects
+      .toThrow('Unknown resource');
+  });
+});
+```
+
+### Testing Validation
+
+```typescript
+import { z } from 'zod';
+import { validateInput } from '../src/utils/validation';
+
+describe('Input Validation', () => {
+  const schema = z.object({
+    name: z.string().min(1),
+    age: z.number().int().positive(),
+  });
+  
+  it('should accept valid input', () => {
+    const input = { name: 'John', age: 30 };
+    const result = validateInput(schema, input);
+    expect(result).toEqual(input);
+  });
+  
+  it('should reject invalid input', () => {
+    const input = { name: '', age: -5 };
+    expect(() => validateInput(schema, input))
+      .toThrow('Validation failed');
+  });
+  
+  it('should provide detailed error information', () => {
+    try {
+      validateInput(schema, { name: 123, age: 'thirty' });
+    } catch (error) {
+      expect(error).toHaveProperty('data');
+      expect(error.data).toHaveProperty('name');
+      expect(error.data).toHaveProperty('age');
+    }
+  });
+});
+```
+
+## Integration Testing
+
+### Testing Server Initialization
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { TestTransport } from './utils/test-transport';
+
+describe('MCP Server', () => {
+  let server: Server;
+  let transport: TestTransport;
+  
+  beforeEach(() => {
+    server = createServer();
+    transport = new TestTransport();
+  });
+  
+  afterEach(async () => {
+    await server.close();
+  });
+  
+  it('should handle initialize request', async () => {
+    await server.connect(transport);
+    
+    const response = await transport.request({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: {
+          name: 'test-client',
+          version: '1.0.0',
+        },
+      },
+    });
+    
+    expect(response).toHaveProperty('protocolVersion');
+    expect(response).toHaveProperty('capabilities');
+    expect(response).toHaveProperty('serverInfo');
+  });
+});
+```
+
+### Testing Protocol Flow
+
+```typescript
+describe('Protocol Flow', () => {
+  it('should complete full lifecycle', async () => {
+    // 1. Initialize
+    const initResponse = await transport.request({
+      method: 'initialize',
+      params: { protocolVersion: '2024-11-05' },
+    });
+    expect(initResponse).toHaveProperty('capabilities');
+    
+    // 2. List tools
+    const toolsResponse = await transport.request({
+      method: 'tools/list',
+      params: {},
+    });
+    expect(toolsResponse).toHaveProperty('tools');
+    
+    // 3. Call tool
+    const toolResponse = await transport.request({
+      method: 'tools/call',
+      params: {
+        name: 'example_tool',
+        arguments: { input: 'test' },
+      },
+    });
+    expect(toolResponse).toHaveProperty('content');
+    
+    // 4. Shutdown
+    await transport.notify({
+      method: 'shutdown',
+    });
+  });
+});
+```
+
+### Test Transport Implementation
+
+```typescript
+export class TestTransport {
+  private handlers = new Map();
+  private requestId = 0;
+  
+  onMessage(handler: (message: any) => void) {
+    this.handlers.set('message', handler);
+  }
+  
+  async request(params: any): Promise<any> {
+    const id = ++this.requestId;
+    const request = {
+      jsonrpc: '2.0',
+      id,
+      ...params,
+    };
+    
+    // Simulate server processing
+    const handler = this.handlers.get('message');
+    if (handler) {
+      const response = await handler(request);
+      if (response.id === id) {
+        return response.result || response.error;
+      }
+    }
+    
+    throw new Error('No response received');
+  }
+  
+  async notify(params: any): Promise<void> {
+    const notification = {
+      jsonrpc: '2.0',
+      ...params,
+    };
+    
+    const handler = this.handlers.get('message');
+    if (handler) {
+      await handler(notification);
+    }
+  }
+}
+```
+
+## MCP Inspector Testing
+
+### Manual Testing Workflow
+
+```bash
+# 1. Start your server
+npm run dev
+
+# 2. Launch MCP Inspector
+npx @modelcontextprotocol/inspector
+
+# 3. Connect to server
+# - Select stdio transport
+# - Enter: node dist/index.js
+
+# 4. Test capabilities
+# - View available tools
+# - Test tool execution
+# - Browse resources
+# - Try prompt templates
+```
+
+### Inspector Test Scenarios
+
+```typescript
+// Document test scenarios for manual testing
+const testScenarios = [
+  {
+    name: 'Basic Tool Execution',
+    steps: [
+      'Connect to server',
+      'Select "example_tool" from tools list',
+      'Enter { "input": "test" } as arguments',
+      'Click Execute',
+      'Verify response contains expected output',
+    ],
+  },
+  {
+    name: 'Error Handling',
+    steps: [
+      'Connect to server',
+      'Select any tool',
+      'Enter invalid arguments',
+      'Verify error response with appropriate code',
+    ],
+  },
+  {
+    name: 'Resource Access',
+    steps: [
+      'Connect to server',
+      'Navigate to Resources tab',
+      'Select a resource',
+      'Click Read',
+      'Verify content is displayed correctly',
+    ],
+  },
+];
+```
+
+## Coverage and Quality
+
+### Coverage Goals
+
+```typescript
+// Aim for high coverage
+const coverageTargets = {
+  statements: 80,
+  branches: 75,
+  functions: 80,
+  lines: 80,
+};
+```
+
+### Test Quality Checklist
+
+```typescript
+const testQualityChecklist = [
+  'All handlers have unit tests',
+  'Error cases are tested',
+  'Edge cases are covered',
+  'Integration tests cover full flow',
+  'Protocol compliance is validated',
+  'Performance tests for heavy operations',
+  'Security tests for input validation',
+];
+```
+
+## Performance Testing
+
+```typescript
+describe('Performance', () => {
+  it('should handle concurrent requests', async () => {
+    const requests = Array.from({ length: 100 }, (_, i) => 
+      handleTool('search', { query: `query ${i}` })
+    );
+    
+    const start = Date.now();
+    const results = await Promise.all(requests);
+    const duration = Date.now() - start;
+    
+    expect(results).toHaveLength(100);
+    expect(duration).toBeLessThan(5000); // 5 seconds for 100 requests
+  });
+  
+  it('should not leak memory', async () => {
+    const initialMemory = process.memoryUsage().heapUsed;
+    
+    // Run many operations
+    for (let i = 0; i < 1000; i++) {
+      await handleTool('search', { query: 'test' });
+    }
+    
+    // Force garbage collection if available
+    if (global.gc) {
+      global.gc();
+    }
+    
+    const finalMemory = process.memoryUsage().heapUsed;
+    const leak = finalMemory - initialMemory;
+    
+    expect(leak).toBeLessThan(10 * 1024 * 1024); // Less than 10MB
+  });
+});
+```
+
+## When to Consult This Agent
+
+- Writing test suites for MCP servers
+- Setting up testing frameworks
+- Creating integration tests
+- Testing protocol compliance
+- Using MCP Inspector effectively
+- Improving test coverage
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/agents/tool-builder.md b/mcp-servers/simple-mcp-server/.claude/agents/tool-builder.md
new file mode 100644
index 0000000..37af687
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/agents/tool-builder.md
@@ -0,0 +1,264 @@
+# MCP Tool Implementation Specialist
+
+You are an expert in implementing tools for MCP servers. You understand tool schemas, parameter validation, response formatting, and best practices for creating robust, user-friendly tools.
+
+## Expertise Areas
+
+- **Tool Design** - Creating intuitive, powerful tools
+- **Schema Definition** - JSON Schema and Zod validation
+- **Parameter Handling** - Input validation and transformation
+- **Response Formatting** - Text, images, and structured data
+- **Error Messages** - User-friendly error reporting
+
+## Tool Implementation Patterns
+
+### Basic Tool Structure
+
+```typescript
+interface Tool {
+  name: string;
+  description: string;
+  inputSchema: JSONSchema;
+  handler: (args: unknown) => Promise<ToolResponse>;
+}
+```
+
+### Schema Definition
+
+```typescript
+// JSON Schema for tool parameters
+const toolSchema = {
+  type: 'object',
+  properties: {
+    query: {
+      type: 'string',
+      description: 'Search query',
+      minLength: 1,
+      maxLength: 100,
+    },
+    options: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          minimum: 1,
+          maximum: 100,
+          default: 10,
+        },
+        format: {
+          type: 'string',
+          enum: ['json', 'text', 'markdown'],
+          default: 'text',
+        },
+      },
+    },
+  },
+  required: ['query'],
+};
+```
+
+### Zod Validation
+
+```typescript
+import { z } from 'zod';
+
+const ToolArgsSchema = z.object({
+  query: z.string().min(1).max(100),
+  options: z.object({
+    limit: z.number().int().min(1).max(100).default(10),
+    format: z.enum(['json', 'text', 'markdown']).default('text'),
+  }).optional(),
+});
+
+type ToolArgs = z.infer<typeof ToolArgsSchema>;
+```
+
+### Handler Implementation
+
+```typescript
+async function handleTool(args: unknown): Promise<ToolResponse> {
+  // 1. Validate input
+  const validated = ToolArgsSchema.safeParse(args);
+  if (!validated.success) {
+    return {
+      error: {
+        code: 'INVALID_PARAMS',
+        message: 'Invalid parameters',
+        data: validated.error.format(),
+      },
+    };
+  }
+
+  // 2. Process request
+  try {
+    const result = await processQuery(validated.data);
+    
+    // 3. Format response
+    return {
+      content: [
+        {
+          type: 'text',
+          text: formatResult(result, validated.data.options?.format),
+        },
+      ],
+    };
+  } catch (error) {
+    // 4. Handle errors
+    return handleError(error);
+  }
+}
+```
+
+## Response Types
+
+### Text Response
+
+```typescript
+{
+  content: [
+    {
+      type: 'text',
+      text: 'Plain text response',
+    },
+  ],
+}
+```
+
+### Image Response
+
+```typescript
+{
+  content: [
+    {
+      type: 'image',
+      data: base64EncodedImage,
+      mimeType: 'image/png',
+    },
+  ],
+}
+```
+
+### Mixed Content
+
+```typescript
+{
+  content: [
+    {
+      type: 'text',
+      text: 'Here is the chart:',
+    },
+    {
+      type: 'image',
+      data: chartImage,
+      mimeType: 'image/svg+xml',
+    },
+  ],
+}
+```
+
+## Best Practices
+
+1. **Clear Naming**
+   - Use descriptive, action-oriented names
+   - Follow consistent naming conventions
+   - Avoid abbreviations
+
+2. **Comprehensive Descriptions**
+   - Explain what the tool does
+   - Document all parameters
+   - Provide usage examples
+
+3. **Robust Validation**
+   - Validate all inputs
+   - Provide helpful error messages
+   - Handle edge cases
+
+4. **Efficient Processing**
+   - Implement timeouts for long operations
+   - Use progress notifications
+   - Cache when appropriate
+
+5. **Helpful Responses**
+   - Format output clearly
+   - Include relevant context
+   - Suggest next steps
+
+## Common Tool Patterns
+
+### CRUD Operations
+
+```typescript
+const crudTools = [
+  { name: 'create_item', handler: createHandler },
+  { name: 'read_item', handler: readHandler },
+  { name: 'update_item', handler: updateHandler },
+  { name: 'delete_item', handler: deleteHandler },
+  { name: 'list_items', handler: listHandler },
+];
+```
+
+### Search and Filter
+
+```typescript
+const searchTool = {
+  name: 'search',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string' },
+      filters: {
+        type: 'object',
+        properties: {
+          category: { type: 'string' },
+          dateRange: {
+            type: 'object',
+            properties: {
+              start: { type: 'string', format: 'date' },
+              end: { type: 'string', format: 'date' },
+            },
+          },
+        },
+      },
+      sort: {
+        type: 'object',
+        properties: {
+          field: { type: 'string' },
+          order: { type: 'string', enum: ['asc', 'desc'] },
+        },
+      },
+    },
+  },
+};
+```
+
+### Batch Operations
+
+```typescript
+const batchTool = {
+  name: 'batch_process',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      items: {
+        type: 'array',
+        items: { type: 'string' },
+        minItems: 1,
+        maxItems: 100,
+      },
+      operation: {
+        type: 'string',
+        enum: ['validate', 'transform', 'analyze'],
+      },
+    },
+  },
+};
+```
+
+## When to Consult This Agent
+
+- Creating new tools for your MCP server
+- Designing tool schemas and parameters
+- Implementing validation logic
+- Formatting tool responses
+- Optimizing tool performance
+- Debugging tool execution issues
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/commands/add-prompt.md b/mcp-servers/simple-mcp-server/.claude/commands/add-prompt.md
new file mode 100644
index 0000000..5f9f007
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/commands/add-prompt.md
@@ -0,0 +1,242 @@
+# Add Prompt Template to MCP Server
+
+Adds a new prompt template to your MCP server for reusable conversation patterns.
+
+## Usage
+
+```
+/add-prompt <name> <description> [arguments]
+```
+
+## Examples
+
+```
+/add-prompt code_review "Review code for improvements" language:string file:string?
+/add-prompt analyze_data "Analyze data patterns" dataset:string metrics:array
+/add-prompt generate_docs "Generate documentation" codebase:string style:enum[minimal,detailed]
+```
+
+## Implementation
+
+```typescript
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+async function addPrompt(
+  name: string,
+  description: string,
+  argumentDefs?: string[]
+) {
+  // Parse arguments
+  const args = parsePromptArguments(argumentDefs || []);
+  
+  // Generate prompt file
+  const promptContent = generatePromptFile(name, description, args);
+  
+  // Write prompt file
+  const promptPath = path.join('src/prompts', `${name}.ts`);
+  await fs.writeFile(promptPath, promptContent);
+  
+  // Update prompt index
+  await updatePromptIndex(name);
+  
+  // Generate test file
+  const testContent = generatePromptTest(name);
+  const testPath = path.join('tests/unit/prompts', `${name}.test.ts`);
+  await fs.writeFile(testPath, testContent);
+  
+  console.log(`✅ Prompt "${name}" added successfully!`);
+  console.log(`  - Implementation: ${promptPath}`);
+  console.log(`  - Test file: ${testPath}`);
+  console.log(`\nNext steps:`);
+  console.log(`  1. Define the prompt template in ${promptPath}`);
+  console.log(`  2. Test with MCP Inspector`);
+}
+
+interface PromptArgument {
+  name: string;
+  description: string;
+  required: boolean;
+  type: string;
+}
+
+function parsePromptArguments(argumentDefs: string[]): PromptArgument[] {
+  return argumentDefs.map(def => {
+    const [nameWithType, description] = def.split('=');
+    const [nameType] = nameWithType.split(':');
+    const isOptional = nameType.endsWith('?');
+    const name = isOptional ? nameType.slice(0, -1) : nameType;
+    const type = nameWithType.split(':')[1] || 'string';
+    
+    return {
+      name,
+      description: description || `${name} parameter`,
+      required: !isOptional,
+      type: type.replace('?', ''),
+    };
+  });
+}
+
+function generatePromptFile(
+  name: string,
+  description: string,
+  args: PromptArgument[]
+): string {
+  return `
+import type { Prompt, PromptMessage } from '../types/prompts.js';
+
+export const ${name}Prompt: Prompt = {
+  name: '${name}',
+  description: '${description}',
+  arguments: [
+${args.map(arg => `    {
+      name: '${arg.name}',
+      description: '${arg.description}',
+      required: ${arg.required},
+    },`).join('\n')}
+  ],
+};
+
+export function get${capitalize(name)}Prompt(
+  args: Record<string, unknown>
+): PromptMessage[] {
+  // Validate required arguments
+${args.filter(a => a.required).map(arg => `  if (!args.${arg.name}) {
+    throw new Error('Missing required argument: ${arg.name}');
+  }`).join('\n')}
+  
+  // Build prompt messages
+  const messages: PromptMessage[] = [];
+  
+  // System message (optional)
+  messages.push({
+    role: 'system',
+    content: {
+      type: 'text',
+      text: buildSystemPrompt(args),
+    },
+  });
+  
+  // User message
+  messages.push({
+    role: 'user',
+    content: {
+      type: 'text',
+      text: buildUserPrompt(args),
+    },
+  });
+  
+  return messages;
+}
+
+function buildSystemPrompt(args: Record<string, unknown>): string {
+  // TODO: Define the system prompt template
+  return \`You are an expert assistant helping with ${description.toLowerCase()}.\`;
+}
+
+function buildUserPrompt(args: Record<string, unknown>): string {
+  // TODO: Define the user prompt template
+  let prompt = '${description}\\n\\n';
+  
+${args.map(arg => `  if (args.${arg.name}) {
+    prompt += \`${capitalize(arg.name)}: \${args.${arg.name}}\\n\`;
+  }`).join('\n')}
+  
+  return prompt;
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+`;
+}
+
+function generatePromptTest(name: string): string {
+  return `
+import { describe, it, expect } from 'vitest';
+import { ${name}Prompt, get${capitalize(name)}Prompt } from '../../src/prompts/${name}.js';
+
+describe('${name} prompt', () => {
+  it('should have correct metadata', () => {
+    expect(${name}Prompt.name).toBe('${name}');
+    expect(${name}Prompt.description).toBeDefined();
+    expect(${name}Prompt.arguments).toBeDefined();
+  });
+  
+  it('should generate prompt messages', () => {
+    const args = {
+      // TODO: Add test arguments
+    };
+    
+    const messages = get${capitalize(name)}Prompt(args);
+    
+    expect(messages).toBeInstanceOf(Array);
+    expect(messages.length).toBeGreaterThan(0);
+    expect(messages[0]).toHaveProperty('role');
+    expect(messages[0]).toHaveProperty('content');
+  });
+  
+  it('should validate required arguments', () => {
+    const invalidArgs = {};
+    
+    expect(() => get${capitalize(name)}Prompt(invalidArgs))
+      .toThrow('Missing required argument');
+  });
+  
+  it('should handle optional arguments', () => {
+    const minimalArgs = {
+      // Only required args
+    };
+    
+    const messages = get${capitalize(name)}Prompt(minimalArgs);
+    expect(messages).toBeDefined();
+  });
+});
+`;
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+async function updatePromptIndex(name: string) {
+  const indexPath = 'src/prompts/index.ts';
+  
+  try {
+    let content = await fs.readFile(indexPath, 'utf-8');
+    
+    // Add import
+    const importLine = `import { ${name}Prompt, get${capitalize(name)}Prompt } from './${name}.js';`;
+    if (!content.includes(importLine)) {
+      const lastImport = content.lastIndexOf('import');
+      const endOfLastImport = content.indexOf('\n', lastImport);
+      content = content.slice(0, endOfLastImport + 1) + importLine + '\n' + content.slice(endOfLastImport + 1);
+    }
+    
+    // Add to exports
+    const exportPattern = /export const prompts = \[([^\]]*)]\;/;
+    const match = content.match(exportPattern);
+    if (match) {
+      const currentExports = match[1].trim();
+      const newExports = currentExports ? `${currentExports},\n  ${name}Prompt` : `\n  ${name}Prompt\n`;
+      content = content.replace(exportPattern, `export const prompts = [${newExports}];`);
+    }
+    
+    await fs.writeFile(indexPath, content);
+  } catch (error) {
+    // Create index file if it doesn't exist
+    const newIndex = `
+import { ${name}Prompt, get${capitalize(name)}Prompt } from './${name}.js';
+
+export const prompts = [
+  ${name}Prompt,
+];
+
+export const promptHandlers = {
+  '${name}': get${capitalize(name)}Prompt,
+};
+`;
+    await fs.writeFile(indexPath, newIndex);
+  }
+}
+```
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/commands/add-resource.md b/mcp-servers/simple-mcp-server/.claude/commands/add-resource.md
new file mode 100644
index 0000000..aff9e54
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/commands/add-resource.md
@@ -0,0 +1,243 @@
+# Add Resource to MCP Server
+
+Adds a new resource endpoint to your MCP server with proper URI handling.
+
+## Usage
+
+```
+/add-resource <name> <description> [uri-pattern] [mime-type]
+```
+
+## Examples
+
+```
+/add-resource config "Server configuration" config://settings application/json
+/add-resource users "User database" data://users/{id} application/json
+/add-resource files "File system access" file:///{path} text/plain
+```
+
+## Implementation
+
+```typescript
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+async function addResource(
+  name: string,
+  description: string,
+  uriPattern?: string,
+  mimeType: string = 'application/json'
+) {
+  // Generate URI pattern if not provided
+  const uri = uriPattern || `${name}://default`;
+  
+  // Generate resource file
+  const resourceContent = generateResourceFile(name, description, uri, mimeType);
+  
+  // Write resource file
+  const resourcePath = path.join('src/resources', `${name}.ts`);
+  await fs.writeFile(resourcePath, resourceContent);
+  
+  // Update resource index
+  await updateResourceIndex(name);
+  
+  // Generate test file
+  const testContent = generateResourceTest(name, uri);
+  const testPath = path.join('tests/unit/resources', `${name}.test.ts`);
+  await fs.writeFile(testPath, testContent);
+  
+  console.log(`✅ Resource "${name}" added successfully!`);
+  console.log(`  - Implementation: ${resourcePath}`);
+  console.log(`  - Test file: ${testPath}`);
+  console.log(`  - URI pattern: ${uri}`);
+  console.log(`  - MIME type: ${mimeType}`);
+  console.log(`\nNext steps:`);
+  console.log(`  1. Implement the resource provider in ${resourcePath}`);
+  console.log(`  2. Test with MCP Inspector`);
+}
+
+function generateResourceFile(
+  name: string,
+  description: string,
+  uri: string,
+  mimeType: string
+): string {
+  const hasDynamicParams = uri.includes('{');
+  
+  return `
+import type { Resource, ResourceContent } from '../types/resources.js';
+
+export const ${name}Resource: Resource = {
+  uri: '${uri}',
+  name: '${name}',
+  description: '${description}',
+  mimeType: '${mimeType}',
+};
+
+export async function read${capitalize(name)}Resource(
+  uri: string
+): Promise<ResourceContent[]> {
+  ${hasDynamicParams ? generateDynamicResourceHandler(uri) : generateStaticResourceHandler()}
+  
+  return [
+    {
+      uri,
+      mimeType: '${mimeType}',
+      text: ${mimeType === 'application/json' ? 'JSON.stringify(data, null, 2)' : 'data'},
+    },
+  ];
+}
+
+${generateResourceDataFunction(name, mimeType)}
+`;
+}
+
+function generateDynamicResourceHandler(uriPattern: string): string {
+  return `
+  // Parse dynamic parameters from URI
+  const params = parseUriParams('${uriPattern}', uri);
+  
+  // Fetch data based on parameters
+  const data = await fetch${capitalize(name)}Data(params);
+  
+  if (!data) {
+    throw new Error(\`Resource not found: \${uri}\`);
+  }
+`;
+}
+
+function generateStaticResourceHandler(): string {
+  return `
+  // Fetch static resource data
+  const data = await fetch${capitalize(name)}Data();
+`;
+}
+
+function generateResourceDataFunction(name: string, mimeType: string): string {
+  if (mimeType === 'application/json') {
+    return `
+async function fetch${capitalize(name)}Data(params?: Record<string, string>) {
+  // TODO: Implement data fetching logic
+  // This is a placeholder implementation
+  
+  if (params?.id) {
+    // Return specific item
+    return {
+      id: params.id,
+      name: 'Example Item',
+      timestamp: new Date().toISOString(),
+    };
+  }
+  
+  // Return collection
+  return {
+    items: [
+      { id: '1', name: 'Item 1' },
+      { id: '2', name: 'Item 2' },
+    ],
+    total: 2,
+  };
+}
+
+function parseUriParams(pattern: string, uri: string): Record<string, string> {
+  // Convert pattern to regex
+  const regexPattern = pattern
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\{(\w+)\}/g, '(?<$1>[^/]+)');
+  
+  const regex = new RegExp(\`^\${regexPattern}$\`);
+  const match = uri.match(regex);
+  
+  return match?.groups || {};
+}
+`;
+  } else {
+    return `
+async function fetch${capitalize(name)}Data(params?: Record<string, string>) {
+  // TODO: Implement data fetching logic
+  // This is a placeholder implementation
+  
+  return 'Resource content as ${mimeType}';
+}
+`;
+  }
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function generateResourceTest(name: string, uri: string): string {
+  return `
+import { describe, it, expect } from 'vitest';
+import { ${name}Resource, read${capitalize(name)}Resource } from '../../src/resources/${name}.js';
+
+describe('${name} resource', () => {
+  it('should have correct metadata', () => {
+    expect(${name}Resource.name).toBe('${name}');
+    expect(${name}Resource.uri).toBe('${uri}');
+    expect(${name}Resource.description).toBeDefined();
+    expect(${name}Resource.mimeType).toBeDefined();
+  });
+  
+  it('should read resource content', async () => {
+    const content = await read${capitalize(name)}Resource('${uri.replace('{id}', 'test-id')}');
+    
+    expect(content).toBeInstanceOf(Array);
+    expect(content[0]).toHaveProperty('uri');
+    expect(content[0]).toHaveProperty('mimeType');
+    expect(content[0]).toHaveProperty('text');
+  });
+  
+  it('should handle missing resources', async () => {
+    // TODO: Add tests for missing resources
+  });
+  
+  it('should validate URI format', () => {
+    // TODO: Add URI validation tests
+  });
+});
+`;
+}
+
+async function updateResourceIndex(name: string) {
+  const indexPath = 'src/resources/index.ts';
+  
+  try {
+    let content = await fs.readFile(indexPath, 'utf-8');
+    
+    // Add import
+    const importLine = `import { ${name}Resource, read${capitalize(name)}Resource } from './${name}.js';`;
+    if (!content.includes(importLine)) {
+      const lastImport = content.lastIndexOf('import');
+      const endOfLastImport = content.indexOf('\n', lastImport);
+      content = content.slice(0, endOfLastImport + 1) + importLine + '\n' + content.slice(endOfLastImport + 1);
+    }
+    
+    // Add to exports
+    const exportPattern = /export const resources = \[([^\]]*)]\;/;
+    const match = content.match(exportPattern);
+    if (match) {
+      const currentExports = match[1].trim();
+      const newExports = currentExports ? `${currentExports},\n  ${name}Resource` : `\n  ${name}Resource\n`;
+      content = content.replace(exportPattern, `export const resources = [${newExports}];`);
+    }
+    
+    await fs.writeFile(indexPath, content);
+  } catch (error) {
+    // Create index file if it doesn't exist
+    const newIndex = `
+import { ${name}Resource, read${capitalize(name)}Resource } from './${name}.js';
+
+export const resources = [
+  ${name}Resource,
+];
+
+export const resourceReaders = {
+  '${name}': read${capitalize(name)}Resource,
+};
+`;
+    await fs.writeFile(indexPath, newIndex);
+  }
+}
+```
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/commands/add-tool.md b/mcp-servers/simple-mcp-server/.claude/commands/add-tool.md
new file mode 100644
index 0000000..da81212
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/commands/add-tool.md
@@ -0,0 +1,207 @@
+# Add Tool to MCP Server
+
+Adds a new tool to your MCP server with proper schema validation and error handling.
+
+## Usage
+
+```
+/add-tool <name> <description> [parameters]
+```
+
+## Examples
+
+```
+/add-tool calculate "Performs mathematical calculations"
+/add-tool search "Search for information" query:string limit:number?
+/add-tool process_data "Process data with options" input:string format:enum[json,csv,xml]
+```
+
+## Implementation
+
+```typescript
+import { z } from 'zod';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+async function addTool(name: string, description: string, parameters?: string[]) {
+  // Parse parameters into schema
+  const schema = parseParameterSchema(parameters || []);
+  
+  // Generate tool file
+  const toolContent = generateToolFile(name, description, schema);
+  
+  // Write tool file
+  const toolPath = path.join('src/tools', `${name}.ts`);
+  await fs.writeFile(toolPath, toolContent);
+  
+  // Update tool index
+  await updateToolIndex(name);
+  
+  // Generate test file
+  const testContent = generateToolTest(name);
+  const testPath = path.join('tests/unit/tools', `${name}.test.ts`);
+  await fs.writeFile(testPath, testContent);
+  
+  console.log(`✅ Tool "${name}" added successfully!`);
+  console.log(`  - Implementation: ${toolPath}`);
+  console.log(`  - Test file: ${testPath}`);
+  console.log(`\nNext steps:`);
+  console.log(`  1. Implement the tool logic in ${toolPath}`);
+  console.log(`  2. Run tests with "npm test"`);
+  console.log(`  3. Test with MCP Inspector`);
+}
+
+function parseParameterSchema(parameters: string[]): any {
+  const properties: Record<string, any> = {};
+  const required: string[] = [];
+  
+  for (const param of parameters) {
+    const [nameType, ...rest] = param.split(':');
+    const isOptional = nameType.endsWith('?');
+    const name = isOptional ? nameType.slice(0, -1) : nameType;
+    const type = rest.join(':') || 'string';
+    
+    if (!isOptional) {
+      required.push(name);
+    }
+    
+    properties[name] = parseType(type);
+  }
+  
+  return {
+    type: 'object',
+    properties,
+    required: required.length > 0 ? required : undefined,
+  };
+}
+
+function parseType(type: string): any {
+  if (type.startsWith('enum[')) {
+    const values = type.slice(5, -1).split(',');
+    return {
+      type: 'string',
+      enum: values,
+    };
+  }
+  
+  switch (type) {
+    case 'number':
+      return { type: 'number' };
+    case 'boolean':
+      return { type: 'boolean' };
+    case 'array':
+      return { type: 'array', items: { type: 'string' } };
+    default:
+      return { type: 'string' };
+  }
+}
+
+function generateToolFile(name: string, description: string, schema: any): string {
+  return `
+import { z } from 'zod';
+import type { ToolHandler } from '../types/tools.js';
+
+// Define Zod schema for validation
+const ${capitalize(name)}Schema = z.object({
+${generateZodSchema(schema.properties, '  ')}
+});
+
+export type ${capitalize(name)}Args = z.infer<typeof ${capitalize(name)}Schema>;
+
+export const ${name}Tool = {
+  name: '${name}',
+  description: '${description}',
+  inputSchema: ${JSON.stringify(schema, null, 2)},
+  handler: async (args: unknown): Promise<ToolHandler> => {
+    // Validate input
+    const validated = ${capitalize(name)}Schema.parse(args);
+    
+    // TODO: Implement your tool logic here
+    const result = await process${capitalize(name)}(validated);
+    
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result),
+        },
+      ],
+    };
+  },
+};
+
+async function process${capitalize(name)}(args: ${capitalize(name)}Args) {
+  // TODO: Implement the actual processing logic
+  return {
+    success: true,
+    message: 'Tool executed successfully',
+    input: args,
+  };
+}
+`;
+}
+
+function generateZodSchema(properties: Record<string, any>, indent: string): string {
+  const lines: string[] = [];
+  
+  for (const [key, value] of Object.entries(properties)) {
+    let zodType = 'z.string()';
+    
+    if (value.type === 'number') {
+      zodType = 'z.number()';
+    } else if (value.type === 'boolean') {
+      zodType = 'z.boolean()';
+    } else if (value.enum) {
+      zodType = `z.enum([${value.enum.map((v: string) => `'${v}'`).join(', ')}])`;
+    } else if (value.type === 'array') {
+      zodType = 'z.array(z.string())';
+    }
+    
+    lines.push(`${indent}${key}: ${zodType},`);
+  }
+  
+  return lines.join('\n');
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function generateToolTest(name: string): string {
+  return `
+import { describe, it, expect, vi } from 'vitest';
+import { ${name}Tool } from '../../src/tools/${name}.js';
+
+describe('${name} tool', () => {
+  it('should have correct metadata', () => {
+    expect(${name}Tool.name).toBe('${name}');
+    expect(${name}Tool.description).toBeDefined();
+    expect(${name}Tool.inputSchema).toBeDefined();
+  });
+  
+  it('should validate input parameters', async () => {
+    const invalidInput = {};
+    
+    await expect(${name}Tool.handler(invalidInput))
+      .rejects
+      .toThrow();
+  });
+  
+  it('should handle valid input', async () => {
+    const validInput = {
+      // TODO: Add valid test input
+    };
+    
+    const result = await ${name}Tool.handler(validInput);
+    
+    expect(result).toHaveProperty('content');
+    expect(result.content[0]).toHaveProperty('type', 'text');
+  });
+  
+  it('should handle errors gracefully', async () => {
+    // TODO: Add error handling tests
+  });
+});
+`;
+}
+```
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/commands/build.md b/mcp-servers/simple-mcp-server/.claude/commands/build.md
new file mode 100644
index 0000000..ed99096
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/commands/build.md
@@ -0,0 +1,377 @@
+# Build MCP Server for Production
+
+Builds and prepares your MCP server for production deployment.
+
+## Usage
+
+```
+/build [target] [options]
+```
+
+## Targets
+
+- `node` - Build for Node.js (default)
+- `docker` - Build Docker image
+- `npm` - Prepare for npm publishing
+
+## Options
+
+- `--minify` - Minify output
+- `--sourcemap` - Include source maps
+- `--analyze` - Analyze bundle size
+
+## Implementation
+
+```typescript
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+const execAsync = promisify(exec);
+
+async function buildServer(
+  target: 'node' | 'docker' | 'npm' = 'node',
+  options: {
+    minify?: boolean;
+    sourcemap?: boolean;
+    analyze?: boolean;
+  } = {}
+) {
+  console.log('🔨 Building MCP Server for Production');
+  console.log('='.repeat(50));
+  
+  // Pre-build checks
+  await runPreBuildChecks();
+  
+  // Build based on target
+  switch (target) {
+    case 'node':
+      await buildForNode(options);
+      break;
+    case 'docker':
+      await buildForDocker(options);
+      break;
+    case 'npm':
+      await buildForNpm(options);
+      break;
+  }
+  
+  // Post-build validation
+  await validateBuild(target);
+  
+  console.log('\n✅ Build completed successfully!');
+}
+
+async function runPreBuildChecks() {
+  console.log('\n🔍 Running pre-build checks...');
+  
+  // Check for uncommitted changes
+  try {
+    const { stdout: gitStatus } = await execAsync('git status --porcelain');
+    if (gitStatus.trim()) {
+      console.warn('⚠️  Warning: You have uncommitted changes');
+    }
+  } catch {
+    // Git not available or not a git repo
+  }
+  
+  // Run tests
+  console.log('  Running tests...');
+  try {
+    await execAsync('npm test');
+    console.log('  ✅ Tests passed');
+  } catch (error) {
+    console.error('  ❌ Tests failed');
+    throw new Error('Build aborted: tests must pass');
+  }
+  
+  // Check dependencies
+  console.log('  Checking dependencies...');
+  try {
+    await execAsync('npm audit --production');
+    console.log('  ✅ No vulnerabilities found');
+  } catch (error) {
+    console.warn('  ⚠️  Security vulnerabilities detected');
+    console.log('  Run "npm audit fix" to resolve');
+  }
+}
+
+async function buildForNode(options: any) {
+  console.log('\n📦 Building for Node.js...');
+  
+  // Clean previous build
+  await fs.rm('dist', { recursive: true, force: true });
+  
+  // Update tsconfig for production
+  const tsConfig = JSON.parse(await fs.readFile('tsconfig.json', 'utf-8'));
+  const prodConfig = {
+    ...tsConfig,
+    compilerOptions: {
+      ...tsConfig.compilerOptions,
+      sourceMap: options.sourcemap || false,
+      inlineSources: false,
+      removeComments: true,
+    },
+  };
+  
+  await fs.writeFile('tsconfig.prod.json', JSON.stringify(prodConfig, null, 2));
+  
+  // Build with TypeScript
+  console.log('  Compiling TypeScript...');
+  await execAsync('npx tsc -p tsconfig.prod.json');
+  
+  // Minify if requested
+  if (options.minify) {
+    console.log('  Minifying code...');
+    await minifyCode();
+  }
+  
+  // Copy package files
+  console.log('  Copying package files...');
+  await fs.copyFile('package.json', 'dist/package.json');
+  await fs.copyFile('README.md', 'dist/README.md').catch(() => {});
+  await fs.copyFile('LICENSE', 'dist/LICENSE').catch(() => {});
+  
+  // Create production package.json
+  const pkg = JSON.parse(await fs.readFile('package.json', 'utf-8'));
+  const prodPkg = {
+    ...pkg,
+    scripts: {
+      start: 'node index.js',
+    },
+    devDependencies: undefined,
+  };
+  await fs.writeFile('dist/package.json', JSON.stringify(prodPkg, null, 2));
+  
+  // Analyze bundle if requested
+  if (options.analyze) {
+    await analyzeBundleSize();
+  }
+  
+  console.log('  ✅ Node.js build complete');
+  console.log('  Output: ./dist');
+}
+
+async function buildForDocker(options: any) {
+  console.log('\n🐋 Building Docker image...');
+  
+  // Build Node.js first
+  await buildForNode(options);
+  
+  // Create Dockerfile if it doesn't exist
+  const dockerfilePath = 'Dockerfile';
+  if (!await fs.access(dockerfilePath).then(() => true).catch(() => false)) {
+    await createDockerfile();
+  }
+  
+  // Build Docker image
+  console.log('  Building Docker image...');
+  const imageName = 'mcp-server';
+  const version = JSON.parse(await fs.readFile('package.json', 'utf-8')).version;
+  
+  await execAsync(`docker build -t ${imageName}:${version} -t ${imageName}:latest .`);
+  
+  // Test the image
+  console.log('  Testing Docker image...');
+  const { stdout } = await execAsync(`docker run --rm ${imageName}:latest node index.js --version`);
+  console.log(`  Version: ${stdout.trim()}`);
+  
+  console.log('  ✅ Docker build complete');
+  console.log(`  Image: ${imageName}:${version}`);
+  console.log('  Run: docker run -it ' + imageName + ':latest');
+}
+
+async function buildForNpm(options: any) {
+  console.log('\n📦 Preparing for npm publishing...');
+  
+  // Build Node.js first
+  await buildForNode(options);
+  
+  // Validate package.json
+  const pkg = JSON.parse(await fs.readFile('package.json', 'utf-8'));
+  
+  if (!pkg.name) {
+    throw new Error('package.json must have a name field');
+  }
+  
+  if (!pkg.version) {
+    throw new Error('package.json must have a version field');
+  }
+  
+  if (!pkg.description) {
+    console.warn('⚠️  Warning: package.json should have a description');
+  }
+  
+  // Create .npmignore if needed
+  const npmignorePath = '.npmignore';
+  if (!await fs.access(npmignorePath).then(() => true).catch(() => false)) {
+    await createNpmIgnore();
+  }
+  
+  // Run npm pack to test
+  console.log('  Creating package tarball...');
+  const { stdout } = await execAsync('npm pack --dry-run');
+  
+  // Parse package contents
+  const files = stdout.split('\n').filter(line => line.includes('npm notice'));
+  console.log(`  Package will include ${files.length} files`);
+  
+  // Check package size
+  const sizeMatch = stdout.match(/npm notice ([\d.]+[kMG]B)/);
+  if (sizeMatch) {
+    console.log(`  Package size: ${sizeMatch[1]}`);
+    
+    // Warn if package is large
+    if (sizeMatch[1].includes('M') && parseFloat(sizeMatch[1]) > 10) {
+      console.warn('⚠️  Warning: Package is larger than 10MB');
+    }
+  }
+  
+  console.log('  ✅ npm package ready');
+  console.log('  Publish with: npm publish');
+}
+
+async function createDockerfile() {
+  const dockerfile = `
+# Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+WORKDIR /app
+
+# Install dumb-init for signal handling
+RUN apk add --no-cache dumb-init
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \\
+    adduser -S nodejs -u 1001
+
+# Copy built application
+COPY --from=builder /app/dist ./
+COPY --from=builder /app/node_modules ./node_modules
+
+# Change ownership
+RUN chown -R nodejs:nodejs /app
+
+USER nodejs
+
+EXPOSE 3000
+
+ENTRYPOINT ["dumb-init", "--"]
+CMD ["node", "index.js"]
+`;
+  
+  await fs.writeFile('Dockerfile', dockerfile);
+  console.log('  Created Dockerfile');
+}
+
+async function createNpmIgnore() {
+  const npmignore = `
+# Source files
+src/
+tests/
+
+# Config files
+.eslintrc*
+.prettierrc*
+tsconfig*.json
+vitest.config.ts
+
+# Development files
+*.log
+.env
+.env.*
+!.env.example
+
+# Build artifacts
+*.tsbuildinfo
+coverage/
+.nyc_output/
+
+# Docker
+Dockerfile
+docker-compose.yml
+
+# Git
+.git/
+.gitignore
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+
+# IDE
+.vscode/
+.idea/
+
+# Misc
+.DS_Store
+Thumbs.db
+`;
+  
+  await fs.writeFile('.npmignore', npmignore);
+  console.log('  Created .npmignore');
+}
+
+async function minifyCode() {
+  // Use esbuild or terser to minify
+  try {
+    await execAsync('npx esbuild dist/**/*.js --minify --outdir=dist --allow-overwrite');
+  } catch {
+    console.warn('  Minification skipped (esbuild not available)');
+  }
+}
+
+async function analyzeBundleSize() {
+  console.log('\n📊 Analyzing bundle size...');
+  
+  const files = await fs.readdir('dist', { recursive: true });
+  let totalSize = 0;
+  const fileSizes: Array<{ name: string; size: number }> = [];
+  
+  for (const file of files) {
+    const filePath = path.join('dist', file as string);
+    const stat = await fs.stat(filePath);
+    
+    if (stat.isFile()) {
+      totalSize += stat.size;
+      fileSizes.push({ name: file as string, size: stat.size });
+    }
+  }
+  
+  // Sort by size
+  fileSizes.sort((a, b) => b.size - a.size);
+  
+  console.log('  Largest files:');
+  fileSizes.slice(0, 5).forEach(file => {
+    console.log(`    ${file.name}: ${(file.size / 1024).toFixed(2)}KB`);
+  });
+  
+  console.log(`  Total size: ${(totalSize / 1024).toFixed(2)}KB`);
+}
+
+async function validateBuild(target: string) {
+  console.log('\n🔍 Validating build...');
+  
+  // Check that main file exists
+  const mainFile = 'dist/index.js';
+  if (!await fs.access(mainFile).then(() => true).catch(() => false)) {
+    throw new Error('Build validation failed: main file not found');
+  }
+  
+  // Try to load the server
+  try {
+    await import(path.resolve(mainFile));
+    console.log('  ✅ Server module loads successfully');
+  } catch (error) {
+    throw new Error(`Build validation failed: ${error.message}`);
+  }
+}
+```
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/commands/debug.md b/mcp-servers/simple-mcp-server/.claude/commands/debug.md
new file mode 100644
index 0000000..47eca5f
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/commands/debug.md
@@ -0,0 +1,310 @@
+# Debug MCP Server
+
+Provides comprehensive debugging tools for troubleshooting MCP server issues.
+
+## Usage
+
+```
+/debug [component] [options]
+```
+
+## Components
+
+- `protocol` - Debug protocol messages
+- `tools` - Debug tool execution
+- `resources` - Debug resource access
+- `transport` - Debug transport layer
+- `all` - Enable all debugging (default)
+
+## Options
+
+- `--verbose` - Extra verbose output
+- `--save` - Save debug logs to file
+- `--inspector` - Launch with MCP Inspector
+
+## Implementation
+
+```typescript
+import * as fs from 'fs/promises';
+import { exec, spawn } from 'child_process';
+import * as path from 'path';
+
+async function debugServer(
+  component: 'protocol' | 'tools' | 'resources' | 'transport' | 'all' = 'all',
+  options: {
+    verbose?: boolean;
+    save?: boolean;
+    inspector?: boolean;
+  } = {}
+) {
+  console.log('🔍 MCP Server Debugger');
+  console.log('='.repeat(50));
+  
+  // Set debug environment variables
+  const debugEnv = {
+    ...process.env,
+    DEBUG: component === 'all' ? 'mcp:*' : `mcp:${component}`,
+    LOG_LEVEL: options.verbose ? 'trace' : 'debug',
+    MCP_DEBUG: 'true',
+  };
+  
+  // Create debug configuration
+  const debugConfig = await createDebugConfig();
+  
+  // Start debug session
+  if (options.inspector) {
+    await launchWithInspector(debugEnv);
+  } else {
+    await runDebugSession(component, debugEnv, options);
+  }
+}
+
+async function createDebugConfig(): Promise<string> {
+  const config = {
+    logging: {
+      level: 'debug',
+      format: 'pretty',
+      includeTimestamp: true,
+      includeLocation: true,
+    },
+    debug: {
+      protocol: {
+        logRequests: true,
+        logResponses: true,
+        logNotifications: true,
+      },
+      tools: {
+        logCalls: true,
+        logValidation: true,
+        logErrors: true,
+        measurePerformance: true,
+      },
+      resources: {
+        logReads: true,
+        logWrites: true,
+        trackCache: true,
+      },
+      transport: {
+        logConnections: true,
+        logMessages: true,
+        logErrors: true,
+      },
+    },
+  };
+  
+  const configPath = '.debug-config.json';
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+  return configPath;
+}
+
+async function runDebugSession(
+  component: string,
+  env: NodeJS.ProcessEnv,
+  options: { verbose?: boolean; save?: boolean }
+) {
+  console.log(`\n🔍 Debugging: ${component}`);
+  console.log('Press Ctrl+C to stop\n');
+  
+  // Create debug wrapper
+  const debugScript = `
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import debug from 'debug';
+import pino from 'pino';
+
+// Enable debug logging
+const log = {
+  protocol: debug('mcp:protocol'),
+  tools: debug('mcp:tools'),
+  resources: debug('mcp:resources'),
+  transport: debug('mcp:transport'),
+};
+
+// Create logger
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'debug',
+  transport: {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+      translateTime: 'HH:MM:ss.l',
+      ignore: 'pid,hostname',
+    },
+  },
+});
+
+// Wrap server methods for debugging
+const originalServer = await import('./src/index.js');
+const server = originalServer.server;
+
+// Intercept requests
+const originalSetRequestHandler = server.setRequestHandler.bind(server);
+server.setRequestHandler = (schema, handler) => {
+  const wrappedHandler = async (request) => {
+    const start = Date.now();
+    log.protocol('→ Request: %O', request);
+    logger.debug({ request }, 'Incoming request');
+    
+    try {
+      const result = await handler(request);
+      const duration = Date.now() - start;
+      
+      log.protocol('← Response (%dms): %O', duration, result);
+      logger.debug({ result, duration }, 'Response sent');
+      
+      return result;
+    } catch (error) {
+      log.protocol('✗ Error: %O', error);
+      logger.error({ error }, 'Request failed');
+      throw error;
+    }
+  };
+  
+  return originalSetRequestHandler(schema, wrappedHandler);
+};
+
+// Start server with debugging
+logger.info('Debug server starting...');
+const transport = new StdioServerTransport();
+await server.connect(transport);
+logger.info('Debug server ready');
+`;
+  
+  // Write debug script
+  const debugScriptPath = '.debug-server.js';
+  await fs.writeFile(debugScriptPath, debugScript);
+  
+  // Start server with debugging
+  const serverProcess = spawn('node', [debugScriptPath], {
+    env,
+    stdio: options.save ? 'pipe' : 'inherit',
+  });
+  
+  if (options.save) {
+    const logFile = `debug-${component}-${Date.now()}.log`;
+    const logStream = await fs.open(logFile, 'w');
+    
+    serverProcess.stdout?.pipe(logStream.createWriteStream());
+    serverProcess.stderr?.pipe(logStream.createWriteStream());
+    
+    console.log(`Saving debug output to: ${logFile}`);
+  }
+  
+  // Handle cleanup
+  process.on('SIGINT', () => {
+    serverProcess.kill();
+    process.exit();
+  });
+  
+  serverProcess.on('exit', async () => {
+    // Cleanup
+    await fs.unlink(debugScriptPath).catch(() => {});
+    await fs.unlink('.debug-config.json').catch(() => {});
+  });
+}
+
+async function launchWithInspector(env: NodeJS.ProcessEnv) {
+  console.log('\n🔍 Launching with MCP Inspector...');
+  console.log('This will provide an interactive debugging interface.\n');
+  
+  // Start server in debug mode
+  const serverProcess = spawn('node', ['--inspect', 'dist/index.js'], {
+    env,
+    stdio: 'pipe',
+  });
+  
+  // Parse debug port from output
+  serverProcess.stderr?.on('data', (data) => {
+    const output = data.toString();
+    const match = output.match(/Debugger listening on ws:\/\/(.+):(\d+)/);
+    if (match) {
+      console.log(`🔗 Node.js debugger: chrome://inspect`);
+      console.log(`    Connect to: ${match[1]}:${match[2]}`);
+    }
+  });
+  
+  // Wait a moment for server to start
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  
+  // Launch MCP Inspector
+  console.log('\n🔍 Starting MCP Inspector...');
+  const inspector = exec('npx @modelcontextprotocol/inspector');
+  
+  inspector.stdout?.on('data', (data) => {
+    console.log(data.toString());
+  });
+  
+  // Cleanup on exit
+  process.on('SIGINT', () => {
+    serverProcess.kill();
+    inspector.kill();
+    process.exit();
+  });
+}
+
+// Additional debug utilities
+export async function analyzeProtocolFlow() {
+  console.log('\n📊 Analyzing Protocol Flow...');
+  
+  const checks = [
+    { name: 'Initialization', test: testInitialization },
+    { name: 'Capability Negotiation', test: testCapabilities },
+    { name: 'Tool Discovery', test: testToolDiscovery },
+    { name: 'Resource Listing', test: testResourceListing },
+    { name: 'Error Handling', test: testErrorHandling },
+  ];
+  
+  for (const check of checks) {
+    try {
+      await check.test();
+      console.log(`  ✅ ${check.name}`);
+    } catch (error) {
+      console.log(`  ❌ ${check.name}: ${error.message}`);
+    }
+  }
+}
+
+async function testInitialization() {
+  // Test initialization flow
+  const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
+  const server = new Server({ name: 'test', version: '1.0.0' }, {});
+  if (!server) throw new Error('Server initialization failed');
+}
+
+async function testCapabilities() {
+  // Test capability declaration
+  const capabilities = {
+    tools: {},
+    resources: {},
+    prompts: {},
+  };
+  if (!capabilities.tools) throw new Error('Tools capability missing');
+}
+
+async function testToolDiscovery() {
+  // Test tool discovery
+  try {
+    const { tools } = await import('./src/tools/index.js');
+    if (!Array.isArray(tools)) throw new Error('Tools not properly exported');
+  } catch {
+    // Tools may not be implemented yet
+  }
+}
+
+async function testResourceListing() {
+  // Test resource listing
+  try {
+    const { resources } = await import('./src/resources/index.js');
+    if (!Array.isArray(resources)) throw new Error('Resources not properly exported');
+  } catch {
+    // Resources may not be implemented yet
+  }
+}
+
+async function testErrorHandling() {
+  // Test error handling
+  const { handleError } = await import('./src/utils/error-handler.js');
+  const result = handleError(new Error('Test'));
+  if (!result.error) throw new Error('Error handler not working');
+}
+```
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/commands/deploy.md b/mcp-servers/simple-mcp-server/.claude/commands/deploy.md
new file mode 100644
index 0000000..8b4049e
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/commands/deploy.md
@@ -0,0 +1,376 @@
+# Deploy MCP Server
+
+Deploys your MCP server to various platforms and registries.
+
+## Usage
+
+```
+/deploy [target] [options]
+```
+
+## Targets
+
+- `npm` - Publish to npm registry
+- `docker` - Push to Docker registry
+- `claude` - Register with Claude Code
+- `github` - Create GitHub release
+
+## Options
+
+- `--tag` - Version tag (default: from package.json)
+- `--registry` - Custom registry URL
+- `--dry-run` - Test deployment without publishing
+
+## Implementation
+
+```typescript
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+const execAsync = promisify(exec);
+
+async function deployServer(
+  target: 'npm' | 'docker' | 'claude' | 'github',
+  options: {
+    tag?: string;
+    registry?: string;
+    dryRun?: boolean;
+  } = {}
+) {
+  console.log('🚀 Deploying MCP Server');
+  console.log('='.repeat(50));
+  
+  // Get version info
+  const pkg = JSON.parse(await fs.readFile('package.json', 'utf-8'));
+  const version = options.tag || pkg.version;
+  
+  // Pre-deployment checks
+  await runPreDeploymentChecks(version);
+  
+  // Deploy based on target
+  switch (target) {
+    case 'npm':
+      await deployToNpm(pkg, version, options);
+      break;
+    case 'docker':
+      await deployToDocker(pkg, version, options);
+      break;
+    case 'claude':
+      await deployToClaude(pkg, version, options);
+      break;
+    case 'github':
+      await deployToGitHub(pkg, version, options);
+      break;
+  }
+  
+  console.log('\n✅ Deployment completed successfully!');
+}
+
+async function runPreDeploymentChecks(version: string) {
+  console.log('\n🔍 Running pre-deployment checks...');
+  
+  // Check git status
+  try {
+    const { stdout: status } = await execAsync('git status --porcelain');
+    if (status.trim()) {
+      throw new Error('Working directory has uncommitted changes');
+    }
+    console.log('  ✅ Working directory clean');
+  } catch (error) {
+    if (error.message.includes('uncommitted')) {
+      throw error;
+    }
+    console.warn('  ⚠️  Git not available');
+  }
+  
+  // Check if version tag exists
+  try {
+    await execAsync(`git rev-parse v${version}`);
+    console.log(`  ✅ Version tag v${version} exists`);
+  } catch {
+    console.warn(`  ⚠️  Version tag v${version} not found`);
+    console.log('  Create with: git tag v' + version);
+  }
+  
+  // Verify build exists
+  const buildExists = await fs.access('dist').then(() => true).catch(() => false);
+  if (!buildExists) {
+    throw new Error('Build not found. Run /build first');
+  }
+  console.log('  ✅ Build found');
+  
+  // Run tests
+  console.log('  Running tests...');
+  try {
+    await execAsync('npm test');
+    console.log('  ✅ Tests passed');
+  } catch {
+    throw new Error('Tests must pass before deployment');
+  }
+}
+
+async function deployToNpm(pkg: any, version: string, options: any) {
+  console.log(`\n📦 Deploying to npm (v${version})...`);
+  
+  // Check npm authentication
+  try {
+    await execAsync('npm whoami');
+    console.log('  ✅ npm authenticated');
+  } catch {
+    throw new Error('Not authenticated with npm. Run: npm login');
+  }
+  
+  // Check if version already published
+  try {
+    const { stdout } = await execAsync(`npm view ${pkg.name}@${version}`);
+    if (stdout) {
+      throw new Error(`Version ${version} already published`);
+    }
+  } catch (error) {
+    if (error.message.includes('already published')) {
+      throw error;
+    }
+    // Version not published yet (good)
+  }
+  
+  // Update version if different
+  if (pkg.version !== version) {
+    console.log(`  Updating version to ${version}...`);
+    await execAsync(`npm version ${version} --no-git-tag-version`);
+  }
+  
+  // Publish package
+  const publishCmd = options.dryRun
+    ? 'npm publish --dry-run'
+    : `npm publish ${options.registry ? `--registry ${options.registry}` : ''}`;
+  
+  console.log('  Publishing to npm...');
+  const { stdout } = await execAsync(publishCmd);
+  
+  if (options.dryRun) {
+    console.log('  🧪 Dry run complete (not published)');
+  } else {
+    console.log('  ✅ Published to npm');
+    console.log(`  Install with: npm install ${pkg.name}`);
+    console.log(`  View at: https://www.npmjs.com/package/${pkg.name}`);
+  }
+}
+
+async function deployToDocker(pkg: any, version: string, options: any) {
+  console.log(`\n🐋 Deploying to Docker registry (v${version})...`);
+  
+  const imageName = pkg.name.replace('@', '').replace('/', '-');
+  const registry = options.registry || 'docker.io';
+  const fullImageName = `${registry}/${imageName}`;
+  
+  // Check Docker authentication
+  try {
+    await execAsync(`docker pull ${registry}/hello-world`);
+    console.log('  ✅ Docker authenticated');
+  } catch {
+    console.warn('  ⚠️  May not be authenticated with Docker registry');
+  }
+  
+  // Build image if not exists
+  try {
+    await execAsync(`docker image inspect ${imageName}:${version}`);
+    console.log('  ✅ Docker image exists');
+  } catch {
+    console.log('  Building Docker image...');
+    await execAsync(`docker build -t ${imageName}:${version} -t ${imageName}:latest .`);
+  }
+  
+  // Tag for registry
+  console.log('  Tagging image...');
+  await execAsync(`docker tag ${imageName}:${version} ${fullImageName}:${version}`);
+  await execAsync(`docker tag ${imageName}:latest ${fullImageName}:latest`);
+  
+  // Push to registry
+  if (!options.dryRun) {
+    console.log('  Pushing to registry...');
+    await execAsync(`docker push ${fullImageName}:${version}`);
+    await execAsync(`docker push ${fullImageName}:latest`);
+    console.log('  ✅ Pushed to Docker registry');
+    console.log(`  Pull with: docker pull ${fullImageName}:${version}`);
+  } else {
+    console.log('  🧪 Dry run complete (not pushed)');
+  }
+}
+
+async function deployToClaude(pkg: any, version: string, options: any) {
+  console.log(`\n🤖 Registering with Claude Code...`);
+  
+  // Create Claude integration instructions
+  const instructions = `
+# Claude Code Integration
+
+## Installation
+
+### From npm
+\`\`\`bash
+claude mcp add ${pkg.name} -- npx ${pkg.name}
+\`\`\`
+
+### From local build
+\`\`\`bash
+claude mcp add ${pkg.name} -- node ${path.resolve('dist/index.js')}
+\`\`\`
+
+### With custom configuration
+\`\`\`bash
+claude mcp add ${pkg.name} \\
+  --env LOG_LEVEL=info \\
+  --env CUSTOM_CONFIG=/path/to/config \\
+  -- npx ${pkg.name}
+\`\`\`
+
+## Available Capabilities
+
+- Tools: ${await countTools()}
+- Resources: ${await countResources()}
+- Prompts: ${await countPrompts()}
+
+## Version: ${version}
+`;
+  
+  // Save integration instructions
+  const instructionsPath = 'CLAUDE_INTEGRATION.md';
+  await fs.writeFile(instructionsPath, instructions);
+  
+  console.log('  ✅ Integration instructions created');
+  console.log(`  View: ${instructionsPath}`);
+  
+  // Test local integration
+  if (!options.dryRun) {
+    console.log('  Testing local integration...');
+    try {
+      const { stdout } = await execAsync('claude mcp list');
+      if (stdout.includes(pkg.name)) {
+        console.log('  ✅ Already registered with Claude Code');
+      } else {
+        console.log('  Register with:');
+        console.log(`    claude mcp add ${pkg.name} -- node ${path.resolve('dist/index.js')}`);
+      }
+    } catch {
+      console.log('  Claude Code CLI not available');
+    }
+  }
+}
+
+async function deployToGitHub(pkg: any, version: string, options: any) {
+  console.log(`\n💙 Creating GitHub release (v${version})...`);
+  
+  // Check gh CLI
+  try {
+    await execAsync('gh --version');
+  } catch {
+    throw new Error('GitHub CLI not installed. Install from: https://cli.github.com');
+  }
+  
+  // Check authentication
+  try {
+    await execAsync('gh auth status');
+    console.log('  ✅ GitHub authenticated');
+  } catch {
+    throw new Error('Not authenticated with GitHub. Run: gh auth login');
+  }
+  
+  // Create release notes
+  const releaseNotes = await generateReleaseNotes(version);
+  const notesPath = `.release-notes-${version}.md`;
+  await fs.writeFile(notesPath, releaseNotes);
+  
+  // Create release
+  if (!options.dryRun) {
+    const releaseCmd = `gh release create v${version} \\
+      --title "v${version}" \\
+      --notes-file ${notesPath} \\
+      --generate-notes`;
+    
+    try {
+      await execAsync(releaseCmd);
+      console.log('  ✅ GitHub release created');
+      
+      // Get release URL
+      const { stdout } = await execAsync(`gh release view v${version} --json url`);
+      const { url } = JSON.parse(stdout);
+      console.log(`  View at: ${url}`);
+    } catch (error) {
+      if (error.message.includes('already exists')) {
+        console.log('  ℹ️ Release already exists');
+      } else {
+        throw error;
+      }
+    }
+  } else {
+    console.log('  🧪 Dry run complete (release not created)');
+    console.log(`  Release notes saved to: ${notesPath}`);
+  }
+  
+  // Cleanup
+  await fs.unlink(notesPath).catch(() => {});
+}
+
+async function generateReleaseNotes(version: string): Promise<string> {
+  const pkg = JSON.parse(await fs.readFile('package.json', 'utf-8'));
+  
+  return `
+# ${pkg.name} v${version}
+
+## 🎆 What's New
+
+- [Add your changes here]
+
+## 📦 Installation
+
+### npm
+\`\`\`bash
+npm install ${pkg.name}@${version}
+\`\`\`
+
+### Claude Code
+\`\`\`bash
+claude mcp add ${pkg.name} -- npx ${pkg.name}@${version}
+\`\`\`
+
+## 📄 Documentation
+
+See [README.md](README.md) for usage instructions.
+
+## 🔧 MCP Capabilities
+
+- Tools: ${await countTools()}
+- Resources: ${await countResources()}
+- Prompts: ${await countPrompts()}
+`;
+}
+
+async function countTools(): Promise<number> {
+  try {
+    const files = await fs.readdir('src/tools').catch(() => []);
+    return files.filter(f => f.endsWith('.ts') && f !== 'index.ts').length;
+  } catch {
+    return 0;
+  }
+}
+
+async function countResources(): Promise<number> {
+  try {
+    const files = await fs.readdir('src/resources').catch(() => []);
+    return files.filter(f => f.endsWith('.ts') && f !== 'index.ts').length;
+  } catch {
+    return 0;
+  }
+}
+
+async function countPrompts(): Promise<number> {
+  try {
+    const files = await fs.readdir('src/prompts').catch(() => []);
+    return files.filter(f => f.endsWith('.ts') && f !== 'index.ts').length;
+  } catch {
+    return 0;
+  }
+}
+```
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/commands/init.md b/mcp-servers/simple-mcp-server/.claude/commands/init.md
new file mode 100644
index 0000000..885af94
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/commands/init.md
@@ -0,0 +1,178 @@
+# Initialize MCP Server Project
+
+Sets up a new MCP server project with the specified configuration level.
+
+## Usage
+
+```
+/init [basic|standard|full]
+```
+
+## Options
+
+- `basic` - Minimal server with one example tool
+- `standard` - Server with tools and resources (default)
+- `full` - Complete server with all capabilities
+
+## Implementation
+
+```typescript
+async function initializeProject(level: 'basic' | 'standard' | 'full' = 'standard') {
+  // Create project structure
+  const dirs = [
+    'src',
+    'src/tools',
+    'src/resources',
+    'src/prompts',
+    'src/utils',
+    'src/types',
+    'tests',
+    'tests/unit',
+    'tests/integration',
+  ];
+  
+  for (const dir of dirs) {
+    await fs.mkdir(dir, { recursive: true });
+  }
+  
+  // Create package.json
+  const packageJson = {
+    name: 'mcp-server',
+    version: '1.0.0',
+    type: 'module',
+    scripts: {
+      'dev': 'tsx watch src/index.ts',
+      'build': 'tsc',
+      'start': 'node dist/index.js',
+      'test': 'vitest',
+      'lint': 'eslint src',
+      'typecheck': 'tsc --noEmit',
+    },
+    dependencies: {
+      '@modelcontextprotocol/sdk': '^1.0.0',
+      'zod': '^3.22.0',
+    },
+    devDependencies: {
+      '@types/node': '^20.0.0',
+      'typescript': '^5.0.0',
+      'tsx': '^4.0.0',
+      'vitest': '^1.0.0',
+      'eslint': '^8.0.0',
+    },
+  };
+  
+  await fs.writeFile('package.json', JSON.stringify(packageJson, null, 2));
+  
+  // Create tsconfig.json
+  const tsConfig = {
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'NodeNext',
+      moduleResolution: 'NodeNext',
+      outDir: './dist',
+      rootDir: './src',
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      forceConsistentCasingInFileNames: true,
+    },
+    include: ['src/**/*'],
+    exclude: ['node_modules', 'dist'],
+  };
+  
+  await fs.writeFile('tsconfig.json', JSON.stringify(tsConfig, null, 2));
+  
+  // Create main server file
+  let serverContent = '';
+  
+  if (level === 'basic') {
+    serverContent = generateBasicServer();
+  } else if (level === 'standard') {
+    serverContent = generateStandardServer();
+  } else {
+    serverContent = generateFullServer();
+  }
+  
+  await fs.writeFile('src/index.ts', serverContent);
+  
+  // Install dependencies
+  console.log('Installing dependencies...');
+  await exec('npm install');
+  
+  console.log('✅ MCP server initialized successfully!');
+  console.log('\nNext steps:');
+  console.log('1. Run "npm run dev" to start development server');
+  console.log('2. Use "/add-tool" to add custom tools');
+  console.log('3. Test with MCP Inspector: npx @modelcontextprotocol/inspector');
+}
+
+function generateBasicServer(): string {
+  return `
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+const server = new Server({
+  name: 'my-mcp-server',
+  version: '1.0.0',
+}, {
+  capabilities: {
+    tools: {},
+  },
+});
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'hello',
+        description: 'Say hello to someone',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Name to greet',
+            },
+          },
+          required: ['name'],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  if (name === 'hello') {
+    const validated = z.object({
+      name: z.string(),
+    }).parse(args);
+    
+    return {
+      content: [
+        {
+          type: 'text',
+          text: \`Hello, \${validated.name}!\`,
+        },
+      ],
+    };
+  }
+  
+  throw new Error(\`Unknown tool: \${name}\`);
+});
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('MCP server running on stdio');
+`;
+}
+```
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/commands/test.md b/mcp-servers/simple-mcp-server/.claude/commands/test.md
new file mode 100644
index 0000000..eff8fe9
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/commands/test.md
@@ -0,0 +1,261 @@
+# Test MCP Server
+
+Runs comprehensive tests for your MCP server including unit tests, integration tests, and protocol compliance validation.
+
+## Usage
+
+```
+/test [type] [options]
+```
+
+## Options
+
+- `type` - Test type: `unit`, `integration`, `all` (default: `all`)
+- `--coverage` - Generate coverage report
+- `--watch` - Run tests in watch mode
+- `--inspector` - Launch MCP Inspector for manual testing
+
+## Implementation
+
+```typescript
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs/promises';
+
+const execAsync = promisify(exec);
+
+async function runTests(
+  type: 'unit' | 'integration' | 'all' = 'all',
+  options: {
+    coverage?: boolean;
+    watch?: boolean;
+    inspector?: boolean;
+  } = {}
+) {
+  console.log('🧪 Running MCP Server Tests...');
+  
+  // Run linting first
+  console.log('\n🔍 Running linter...');
+  try {
+    await execAsync('npm run lint');
+    console.log('✅ Linting passed');
+  } catch (error) {
+    console.error('❌ Linting failed:', error.message);
+    return;
+  }
+  
+  // Run type checking
+  console.log('\n📝 Type checking...');
+  try {
+    await execAsync('npm run typecheck');
+    console.log('✅ Type checking passed');
+  } catch (error) {
+    console.error('❌ Type checking failed:', error.message);
+    return;
+  }
+  
+  // Run tests
+  console.log(`\n🧪 Running ${type} tests...`);
+  
+  let testCommand = 'npx vitest';
+  
+  if (type === 'unit') {
+    testCommand += ' tests/unit';
+  } else if (type === 'integration') {
+    testCommand += ' tests/integration';
+  }
+  
+  if (options.coverage) {
+    testCommand += ' --coverage';
+  }
+  
+  if (options.watch) {
+    testCommand += ' --watch';
+  } else {
+    testCommand += ' --run';
+  }
+  
+  try {
+    const { stdout } = await execAsync(testCommand);
+    console.log(stdout);
+    
+    // Run protocol compliance check
+    if (type === 'all' || type === 'integration') {
+      console.log('\n🔌 Checking MCP protocol compliance...');
+      await checkProtocolCompliance();
+    }
+    
+    // Generate test report
+    if (options.coverage) {
+      console.log('\n📊 Coverage report generated:');
+      console.log('  - HTML: coverage/index.html');
+      console.log('  - JSON: coverage/coverage-final.json');
+    }
+    
+    console.log('\n✅ All tests passed!');
+    
+    // Launch inspector if requested
+    if (options.inspector) {
+      console.log('\n🔍 Launching MCP Inspector...');
+      await launchInspector();
+    }
+  } catch (error) {
+    console.error('\n❌ Tests failed:', error.message);
+    process.exit(1);
+  }
+}
+
+async function checkProtocolCompliance() {
+  const tests = [
+    checkInitialization,
+    checkToolsCapability,
+    checkResourcesCapability,
+    checkPromptsCapability,
+    checkErrorHandling,
+  ];
+  
+  for (const test of tests) {
+    try {
+      await test();
+      console.log(`  ✅ ${test.name.replace('check', '')} compliance`);
+    } catch (error) {
+      console.log(`  ❌ ${test.name.replace('check', '')} compliance: ${error.message}`);
+      throw error;
+    }
+  }
+}
+
+async function checkInitialization() {
+  // Test that server properly handles initialization
+  const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
+  const { TestTransport } = await import('../tests/utils/test-transport.js');
+  
+  const server = new Server({
+    name: 'test-server',
+    version: '1.0.0',
+  }, {
+    capabilities: {
+      tools: {},
+      resources: {},
+      prompts: {},
+    },
+  });
+  
+  const transport = new TestTransport();
+  await server.connect(transport);
+  
+  const response = await transport.request({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: {
+        name: 'test-client',
+        version: '1.0.0',
+      },
+    },
+  });
+  
+  if (!response.protocolVersion) {
+    throw new Error('Server did not return protocol version');
+  }
+  
+  await server.close();
+}
+
+async function checkToolsCapability() {
+  // Verify tools capability is properly implemented
+  const toolsExist = await fs.access('src/tools')
+    .then(() => true)
+    .catch(() => false);
+  
+  if (!toolsExist) {
+    console.log('    (No tools implemented yet)');
+    return;
+  }
+  
+  // Check that tools are properly exported
+  const { tools } = await import('../src/tools/index.js');
+  if (!Array.isArray(tools)) {
+    throw new Error('Tools must be exported as an array');
+  }
+}
+
+async function checkResourcesCapability() {
+  // Verify resources capability is properly implemented
+  const resourcesExist = await fs.access('src/resources')
+    .then(() => true)
+    .catch(() => false);
+  
+  if (!resourcesExist) {
+    console.log('    (No resources implemented yet)');
+    return;
+  }
+  
+  // Check that resources are properly exported
+  const { resources } = await import('../src/resources/index.js');
+  if (!Array.isArray(resources)) {
+    throw new Error('Resources must be exported as an array');
+  }
+}
+
+async function checkPromptsCapability() {
+  // Verify prompts capability is properly implemented
+  const promptsExist = await fs.access('src/prompts')
+    .then(() => true)
+    .catch(() => false);
+  
+  if (!promptsExist) {
+    console.log('    (No prompts implemented yet)');
+    return;
+  }
+  
+  // Check that prompts are properly exported
+  const { prompts } = await import('../src/prompts/index.js');
+  if (!Array.isArray(prompts)) {
+    throw new Error('Prompts must be exported as an array');
+  }
+}
+
+async function checkErrorHandling() {
+  // Test that server properly handles errors
+  const { handleError } = await import('../src/utils/error-handler.js');
+  
+  // Test known error
+  const knownError = new Error('Test error');
+  knownError.code = 'TEST_ERROR';
+  const response1 = handleError(knownError);
+  if (!response1.error || response1.error.code !== 'TEST_ERROR') {
+    throw new Error('Error handler does not preserve error codes');
+  }
+  
+  // Test unknown error
+  const unknownError = new Error('Unknown error');
+  const response2 = handleError(unknownError);
+  if (!response2.error || response2.error.code !== 'INTERNAL_ERROR') {
+    throw new Error('Error handler does not handle unknown errors');
+  }
+}
+
+async function launchInspector() {
+  console.log('Starting MCP Inspector...');
+  console.log('This will open an interactive testing UI in your browser.');
+  console.log('Press Ctrl+C to stop the inspector.\n');
+  
+  const inspector = exec('npx @modelcontextprotocol/inspector');
+  
+  inspector.stdout.on('data', (data) => {
+    console.log(data.toString());
+  });
+  
+  inspector.stderr.on('data', (data) => {
+    console.error(data.toString());
+  });
+  
+  inspector.on('close', (code) => {
+    console.log(`Inspector exited with code ${code}`);
+  });
+}
+```
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/.claude/hooks/dev-watch.sh b/mcp-servers/simple-mcp-server/.claude/hooks/dev-watch.sh
new file mode 100755
index 0000000..1d2b5fc
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/hooks/dev-watch.sh
@@ -0,0 +1,93 @@
+#!/bin/bash
+
+# Development Watch Hook for Simple MCP Server
+# Automatically triggered on TypeScript file changes
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${GREEN}🔄 Development Watch Hook Triggered${NC}"
+
+# Get the modified file
+MODIFIED_FILE="$1"
+
+# Skip if not a TypeScript file
+if [[ ! "$MODIFIED_FILE" =~ \.ts$ ]]; then
+    exit 0
+fi
+
+# Skip node_modules and dist
+if [[ "$MODIFIED_FILE" =~ node_modules|dist|coverage ]]; then
+    exit 0
+fi
+
+echo "📝 File changed: $MODIFIED_FILE"
+
+# Type checking
+echo -e "${YELLOW}✅ Running type check...${NC}"
+if npx tsc --noEmit 2>/dev/null; then
+    echo -e "${GREEN}  ✓ Type checking passed${NC}"
+else
+    echo -e "${RED}  ✗ Type checking failed${NC}"
+    exit 1
+fi
+
+# Format with prettier
+if command -v prettier &> /dev/null; then
+    echo -e "${YELLOW}🎨 Formatting with Prettier...${NC}"
+    npx prettier --write "$MODIFIED_FILE" 2>/dev/null || true
+    echo -e "${GREEN}  ✓ Formatted${NC}"
+fi
+
+# Lint with ESLint
+if [ -f .eslintrc.json ] || [ -f .eslintrc.js ]; then
+    echo -e "${YELLOW}🔍 Linting with ESLint...${NC}"
+    if npx eslint "$MODIFIED_FILE" --fix 2>/dev/null; then
+        echo -e "${GREEN}  ✓ Linting passed${NC}"
+    else
+        echo -e "${YELLOW}  ⚠ Linting warnings${NC}"
+    fi
+fi
+
+# Run tests if it's a test file or if the corresponding test exists
+if [[ "$MODIFIED_FILE" =~ \.test\.ts$ ]] || [[ "$MODIFIED_FILE" =~ \.spec\.ts$ ]]; then
+    echo -e "${YELLOW}🧪 Running tests for $MODIFIED_FILE...${NC}"
+    if npx vitest run "$MODIFIED_FILE" 2>/dev/null; then
+        echo -e "${GREEN}  ✓ Tests passed${NC}"
+    else
+        echo -e "${RED}  ✗ Tests failed${NC}"
+        exit 1
+    fi
+else
+    # Check if corresponding test file exists
+    TEST_FILE="${MODIFIED_FILE%.ts}.test.ts"
+    TEST_FILE_SPEC="${MODIFIED_FILE%.ts}.spec.ts"
+    
+    if [ -f "$TEST_FILE" ]; then
+        echo -e "${YELLOW}🧪 Running related tests...${NC}"
+        npx vitest run "$TEST_FILE" 2>/dev/null || true
+    elif [ -f "$TEST_FILE_SPEC" ]; then
+        echo -e "${YELLOW}🧪 Running related tests...${NC}"
+        npx vitest run "$TEST_FILE_SPEC" 2>/dev/null || true
+    fi
+fi
+
+# Update tool/resource counts if applicable
+if [[ "$MODIFIED_FILE" =~ src/tools/ ]] || [[ "$MODIFIED_FILE" =~ src/resources/ ]] || [[ "$MODIFIED_FILE" =~ src/prompts/ ]]; then
+    echo -e "${YELLOW}📊 Updating capability counts...${NC}"
+    
+    TOOL_COUNT=$(find src/tools -name "*.ts" -not -name "index.ts" 2>/dev/null | wc -l || echo 0)
+    RESOURCE_COUNT=$(find src/resources -name "*.ts" -not -name "index.ts" 2>/dev/null | wc -l || echo 0)
+    PROMPT_COUNT=$(find src/prompts -name "*.ts" -not -name "index.ts" 2>/dev/null | wc -l || echo 0)
+    
+    echo "  Tools: $TOOL_COUNT"
+    echo "  Resources: $RESOURCE_COUNT"
+    echo "  Prompts: $PROMPT_COUNT"
+fi
+
+echo -e "${GREEN}✅ Development checks complete${NC}"
diff --git a/mcp-servers/simple-mcp-server/.claude/hooks/pre-build.sh b/mcp-servers/simple-mcp-server/.claude/hooks/pre-build.sh
new file mode 100755
index 0000000..a72ff45
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/hooks/pre-build.sh
@@ -0,0 +1,144 @@
+#!/bin/bash
+
+# Pre-Build Hook for Simple MCP Server
+# Runs before building for production
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🔨 Pre-Build Hook${NC}"
+echo "======================================"
+
+# Check for uncommitted changes
+if git diff --quiet && git diff --staged --quiet; then
+    echo -e "${GREEN}✓ Working directory clean${NC}"
+else
+    echo -e "${YELLOW}⚠ Warning: Uncommitted changes detected${NC}"
+    git status --short
+fi
+
+# Lint check
+echo -e "\n${YELLOW}🔍 Running lint check...${NC}"
+if npx eslint src --ext .ts 2>/dev/null; then
+    echo -e "${GREEN}  ✓ Linting passed${NC}"
+else
+    echo -e "${RED}  ✗ Linting failed${NC}"
+    echo "  Run 'npm run lint:fix' to fix issues"
+    exit 1
+fi
+
+# Type validation
+echo -e "\n${YELLOW}📝 Running type check...${NC}"
+if npx tsc --noEmit; then
+    echo -e "${GREEN}  ✓ Type checking passed${NC}"
+else
+    echo -e "${RED}  ✗ Type checking failed${NC}"
+    exit 1
+fi
+
+# Test suite
+echo -e "\n${YELLOW}🧪 Running tests...${NC}"
+if npm test 2>/dev/null; then
+    echo -e "${GREEN}  ✓ All tests passed${NC}"
+else
+    echo -e "${RED}  ✗ Tests failed${NC}"
+    exit 1
+fi
+
+# Dependency audit
+echo -e "\n${YELLOW}🔒 Checking dependencies...${NC}"
+AUDIT_RESULT=$(npm audit --production 2>&1)
+if echo "$AUDIT_RESULT" | grep -q "found 0 vulnerabilities"; then
+    echo -e "${GREEN}  ✓ No vulnerabilities found${NC}"
+else
+    echo -e "${YELLOW}  ⚠ Security vulnerabilities detected${NC}"
+    echo "  Run 'npm audit fix' to resolve"
+fi
+
+# Version validation
+echo -e "\n${YELLOW}🏷️ Checking version...${NC}"
+PACKAGE_VERSION=$(node -p "require('./package.json').version")
+echo "  Current version: $PACKAGE_VERSION"
+
+# Check if version tag exists
+if git rev-parse "v$PACKAGE_VERSION" >/dev/null 2>&1; then
+    echo -e "${GREEN}  ✓ Version tag exists${NC}"
+else
+    echo -e "${YELLOW}  ⚠ Version tag v$PACKAGE_VERSION not found${NC}"
+    echo "  Create with: git tag v$PACKAGE_VERSION"
+fi
+
+# Check package.json required fields
+echo -e "\n${YELLOW}📦 Validating package.json...${NC}"
+NAME=$(node -p "require('./package.json').name" 2>/dev/null)
+DESCRIPTION=$(node -p "require('./package.json').description" 2>/dev/null)
+MAIN=$(node -p "require('./package.json').main" 2>/dev/null)
+
+if [ -z "$NAME" ]; then
+    echo -e "${RED}  ✗ Missing 'name' field${NC}"
+    exit 1
+fi
+
+if [ -z "$DESCRIPTION" ]; then
+    echo -e "${YELLOW}  ⚠ Missing 'description' field${NC}"
+fi
+
+if [ -z "$MAIN" ]; then
+    echo -e "${YELLOW}  ⚠ Missing 'main' field${NC}"
+fi
+
+echo -e "${GREEN}  ✓ Package metadata valid${NC}"
+
+# MCP specific checks
+echo -e "\n${YELLOW}🔌 Checking MCP implementation...${NC}"
+
+# Check for required MCP files
+if [ -f "src/index.ts" ]; then
+    echo -e "${GREEN}  ✓ Entry point exists${NC}"
+else
+    echo -e "${RED}  ✗ Missing src/index.ts${NC}"
+    exit 1
+fi
+
+# Count capabilities
+TOOL_COUNT=0
+RESOURCE_COUNT=0
+PROMPT_COUNT=0
+
+if [ -d "src/tools" ]; then
+    TOOL_COUNT=$(find src/tools -name "*.ts" -not -name "index.ts" | wc -l)
+fi
+
+if [ -d "src/resources" ]; then
+    RESOURCE_COUNT=$(find src/resources -name "*.ts" -not -name "index.ts" | wc -l)
+fi
+
+if [ -d "src/prompts" ]; then
+    PROMPT_COUNT=$(find src/prompts -name "*.ts" -not -name "index.ts" | wc -l)
+fi
+
+echo "  Capabilities:"
+echo "    - Tools: $TOOL_COUNT"
+echo "    - Resources: $RESOURCE_COUNT"
+echo "    - Prompts: $PROMPT_COUNT"
+
+if [ $TOOL_COUNT -eq 0 ] && [ $RESOURCE_COUNT -eq 0 ] && [ $PROMPT_COUNT -eq 0 ]; then
+    echo -e "${YELLOW}  ⚠ No MCP capabilities implemented${NC}"
+fi
+
+# Final summary
+echo ""
+echo "======================================"
+echo -e "${GREEN}✅ Pre-build checks complete${NC}"
+echo "Ready to build for production!"
+echo ""
+echo "Next steps:"
+echo "  1. npm run build"
+echo "  2. npm test"
+echo "  3. npm publish (if deploying to npm)"
diff --git a/mcp-servers/simple-mcp-server/.claude/hooks/test-runner.sh b/mcp-servers/simple-mcp-server/.claude/hooks/test-runner.sh
new file mode 100755
index 0000000..964f80c
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/hooks/test-runner.sh
@@ -0,0 +1,198 @@
+#!/bin/bash
+
+# Test Runner Hook for Simple MCP Server
+# Enhanced test execution with coverage and protocol validation
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+MAGENTA='\033[0;35m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}🧪 Test Runner Hook${NC}"
+echo "======================================"
+
+# Parse test type from arguments
+TEST_TYPE="${1:-all}"
+WATCH_MODE="${2:-false}"
+
+# Function to run tests
+run_tests() {
+    local type=$1
+    local title=$2
+    
+    echo -e "\n${YELLOW}Running $title...${NC}"
+    
+    if [ "$type" = "unit" ]; then
+        TEST_CMD="npx vitest run tests/unit"
+    elif [ "$type" = "integration" ]; then
+        TEST_CMD="npx vitest run tests/integration"
+    else
+        TEST_CMD="npx vitest run"
+    fi
+    
+    if [ "$WATCH_MODE" = "true" ]; then
+        TEST_CMD="${TEST_CMD/run/}"
+    fi
+    
+    if $TEST_CMD; then
+        echo -e "${GREEN}  ✓ $title passed${NC}"
+        return 0
+    else
+        echo -e "${RED}  ✗ $title failed${NC}"
+        return 1
+    fi
+}
+
+# Function to check MCP protocol compliance
+check_protocol_compliance() {
+    echo -e "\n${YELLOW}🔌 Checking MCP Protocol Compliance...${NC}"
+    
+    # Check server initialization
+    echo "  Checking server initialization..."
+    if node -e "require('./dist/index.js')" 2>/dev/null; then
+        echo -e "${GREEN}    ✓ Server module loads${NC}"
+    else
+        echo -e "${YELLOW}    ⚠ Server not built (run 'npm run build')${NC}"
+    fi
+    
+    # Check for required handlers
+    echo "  Checking protocol handlers..."
+    
+    # This would normally check the actual implementation
+    # For now, we'll check if the files exist
+    if [ -f "src/index.ts" ]; then
+        if grep -q "ListToolsRequestSchema\|ListResourcesRequestSchema\|ListPromptsRequestSchema" src/index.ts 2>/dev/null; then
+            echo -e "${GREEN}    ✓ Protocol handlers found${NC}"
+        else
+            echo -e "${YELLOW}    ⚠ Some protocol handlers may be missing${NC}"
+        fi
+    fi
+    
+    # Check capabilities
+    echo "  Checking capabilities..."
+    local has_capability=false
+    
+    if [ -d "src/tools" ] && [ "$(ls -A src/tools 2>/dev/null)" ]; then
+        echo -e "${GREEN}    ✓ Tools capability${NC}"
+        has_capability=true
+    fi
+    
+    if [ -d "src/resources" ] && [ "$(ls -A src/resources 2>/dev/null)" ]; then
+        echo -e "${GREEN}    ✓ Resources capability${NC}"
+        has_capability=true
+    fi
+    
+    if [ -d "src/prompts" ] && [ "$(ls -A src/prompts 2>/dev/null)" ]; then
+        echo -e "${GREEN}    ✓ Prompts capability${NC}"
+        has_capability=true
+    fi
+    
+    if [ "$has_capability" = false ]; then
+        echo -e "${YELLOW}    ⚠ No capabilities implemented yet${NC}"
+    fi
+}
+
+# Function to generate coverage report
+generate_coverage() {
+    echo -e "\n${YELLOW}📊 Generating Coverage Report...${NC}"
+    
+    if npx vitest run --coverage 2>/dev/null; then
+        echo -e "${GREEN}  ✓ Coverage report generated${NC}"
+        
+        # Parse coverage summary if available
+        if [ -f "coverage/coverage-summary.json" ]; then
+            echo "  Coverage Summary:"
+            node -e "
+                const coverage = require('./coverage/coverage-summary.json');
+                const total = coverage.total;
+                const metrics = ['statements', 'branches', 'functions', 'lines'];
+                metrics.forEach(metric => {
+                    const pct = total[metric].pct;
+                    const color = pct >= 80 ? '\\033[0;32m' : pct >= 60 ? '\\033[1;33m' : '\\033[0;31m';
+                    console.log('    ' + metric + ': ' + color + pct.toFixed(1) + '%\\033[0m');
+                });
+            " 2>/dev/null || echo "    (Could not parse coverage summary)"
+        fi
+        
+        echo "  View detailed report: coverage/index.html"
+    else
+        echo -e "${YELLOW}  ⚠ Coverage generation failed${NC}"
+    fi
+}
+
+# Main execution
+echo "Test configuration:"
+echo "  Type: $TEST_TYPE"
+echo "  Watch: $WATCH_MODE"
+
+# Pre-test checks
+echo -e "\n${YELLOW}📋 Pre-test checks...${NC}"
+
+# Check if test framework is installed
+if ! command -v vitest &> /dev/null && ! npx vitest --version &> /dev/null; then
+    echo -e "${RED}  ✗ Vitest not installed${NC}"
+    echo "  Install with: npm install -D vitest"
+    exit 1
+fi
+
+# Check if test directory exists
+if [ ! -d "tests" ] && [ ! -d "src/__tests__" ]; then
+    echo -e "${YELLOW}  ⚠ No test directory found${NC}"
+    echo "  Create tests in 'tests/' directory"
+fi
+
+# Run appropriate tests
+case $TEST_TYPE in
+    unit)
+        run_tests "unit" "Unit Tests"
+        ;;
+    integration)
+        run_tests "integration" "Integration Tests"
+        ;;
+    coverage)
+        generate_coverage
+        ;;
+    protocol)
+        check_protocol_compliance
+        ;;
+    all)
+        FAILED=false
+        
+        run_tests "unit" "Unit Tests" || FAILED=true
+        run_tests "integration" "Integration Tests" || FAILED=true
+        check_protocol_compliance
+        
+        if [ "$FAILED" = true ]; then
+            echo -e "\n${RED}❌ Some tests failed${NC}"
+            exit 1
+        fi
+        ;;
+    *)
+        echo -e "${RED}Unknown test type: $TEST_TYPE${NC}"
+        echo "Valid options: unit, integration, coverage, protocol, all"
+        exit 1
+        ;;
+esac
+
+# Test summary
+echo ""
+echo "======================================"
+
+if [ "$WATCH_MODE" = "true" ]; then
+    echo -e "${BLUE}👁️ Watching for changes...${NC}"
+    echo "Press Ctrl+C to stop"
+else
+    echo -e "${GREEN}✅ Test run complete${NC}"
+    
+    # Provide helpful next steps
+    echo ""
+    echo "Next steps:"
+    echo "  • Fix any failing tests"
+    echo "  • Run with coverage: npm test -- coverage"
+    echo "  • Test with MCP Inspector: npx @modelcontextprotocol/inspector"
+fi
diff --git a/mcp-servers/simple-mcp-server/.claude/settings.json b/mcp-servers/simple-mcp-server/.claude/settings.json
new file mode 100644
index 0000000..557b4f0
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/.claude/settings.json
@@ -0,0 +1,63 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run dev:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm run test:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run typecheck:*)",
+      "Bash(npx vitest:*)",
+      "Bash(npx tsx:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx @modelcontextprotocol/inspector)",
+      "Write(src/**/*)",
+      "Write(tests/**/*)",
+      "Write(dist/**/*)",
+      "Read(package.json)",
+      "Read(tsconfig.json)",
+      "Edit(package.json)",
+      "Edit(tsconfig.json)"
+    ],
+    "deny": [
+      "Read(.env.production)",
+      "Read(.env.local)",
+      "Write(.env)",
+      "Bash(rm -rf:*)",
+      "Bash(npm publish:*)",
+      "Read(node_modules/**)",
+      "Write(node_modules/**)"
+    ]
+  },
+  "env": {
+    "NODE_ENV": "development",
+    "LOG_LEVEL": "info",
+    "MCP_SERVER_NAME": "simple-mcp-server",
+    "MCP_SERVER_VERSION": "1.0.0"
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx prettier --write",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "echo '🚀 MCP Server | $(basename $(pwd))'"
+  },
+  "_metadata": {
+    "name": "Simple MCP Server",
+    "version": "1.0.0",
+    "category": "mcp-server",
+    "generated": "2025-08-21T00:00:00.000Z",
+    "generator": "manual",
+    "note": "Generic MCP server configuration"
+  }
+}
\ No newline at end of file
diff --git a/mcp-servers/simple-mcp-server/CLAUDE.md b/mcp-servers/simple-mcp-server/CLAUDE.md
new file mode 100644
index 0000000..b58f174
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/CLAUDE.md
@@ -0,0 +1,560 @@
+# Simple MCP Server Development Assistant
+
+You are an expert in building clean, well-structured MCP (Model Context Protocol) servers following best practices. You have deep expertise in the MCP SDK, TypeScript, and creating robust server implementations.
+
+## Memory Integration
+
+This CLAUDE.md follows official Claude Code patterns for MCP server development:
+
+- **MCP protocol compliance** - Follows @modelcontextprotocol/sdk standards
+- **Project memory** - Instructions shared with development team
+- **Tool integration** - Works with Claude Code's MCP commands
+- **Automated discovery** - Available when MCP server is configured
+
+## MCP Configuration
+
+To use this server with Claude Code:
+
+```bash
+# Add local MCP server
+claude mcp add my-server -- node dist/index.js
+
+# Add with npm/npx
+claude mcp add my-server -- npx my-mcp-server
+
+# Add with custom arguments
+claude mcp add my-server -- node dist/index.js --port 3000
+
+# Check server status
+claude mcp list
+
+# Remove server
+claude mcp remove my-server
+```
+
+## Available MCP Tools
+
+When connected, your server can provide these capabilities to Claude Code:
+
+- **Tools** - Custom functions that Claude can invoke
+- **Resources** - Data sources Claude can read
+- **Prompts** - Reusable prompt templates
+- **Sampling** - Custom completion behavior
+
+## Project Context
+
+This is a Simple MCP Server project focused on:
+
+- **Clean architecture** with separation of concerns
+- **Type safety** using TypeScript and Zod validation
+- **Robust error handling** with proper error codes
+- **Extensible design** for easy feature addition
+- **MCP protocol compliance** using @modelcontextprotocol/sdk
+
+## Technology Stack
+
+### Core Technologies
+
+- **TypeScript** - Type-safe development
+- **Node.js** - Runtime environment
+- **@modelcontextprotocol/sdk** - Official MCP implementation
+- **Zod** - Runtime type validation
+
+### Transport Options
+
+- **stdio** - Standard input/output (default)
+- **HTTP + SSE** - Server-sent events for web clients
+- **WebSocket** - Bidirectional communication
+
+## Architecture Patterns
+
+### Basic MCP Server Structure
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+// Create server instance
+const server = new Server({
+  name: 'my-mcp-server',
+  version: '1.0.0',
+}, {
+  capabilities: {
+    tools: {},
+    resources: {},
+    prompts: {},
+  },
+});
+
+// Define tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'example_tool',
+        description: 'An example tool that processes input',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            input: { type: 'string', description: 'Input to process' },
+          },
+          required: ['input'],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case 'example_tool':
+      const validated = z.object({
+        input: z.string(),
+      }).parse(args);
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Processed: ${validated.input}`,
+          },
+        ],
+      };
+      
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### Resource Implementation
+
+```typescript
+import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// List available resources
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: 'config://settings',
+        name: 'Application Settings',
+        description: 'Current configuration values',
+        mimeType: 'application/json',
+      },
+    ],
+  };
+});
+
+// Read resource content
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+  
+  if (uri === 'config://settings') {
+    return {
+      contents: [
+        {
+          uri: 'config://settings',
+          mimeType: 'application/json',
+          text: JSON.stringify(getSettings(), null, 2),
+        },
+      ],
+    };
+  }
+  
+  throw new Error(`Unknown resource: ${uri}`);
+});
+```
+
+### Prompt Templates
+
+```typescript
+import { ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// List available prompts
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: [
+      {
+        name: 'analyze_code',
+        description: 'Analyze code for improvements',
+        arguments: [
+          {
+            name: 'language',
+            description: 'Programming language',
+            required: true,
+          },
+        ],
+      },
+    ],
+  };
+});
+
+// Get prompt content
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  if (name === 'analyze_code') {
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Analyze this ${args?.language || 'code'} for improvements...`,
+          },
+        },
+      ],
+    };
+  }
+  
+  throw new Error(`Unknown prompt: ${name}`);
+});
+```
+
+## Critical Implementation Details
+
+### 1. Input Validation
+
+```typescript
+// Always validate inputs with Zod
+const InputSchema = z.object({
+  query: z.string().min(1).max(1000),
+  options: z.object({
+    format: z.enum(['json', 'text', 'markdown']).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+  }).optional(),
+});
+
+// Validate and handle errors
+try {
+  const validated = InputSchema.parse(args);
+  return processQuery(validated);
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    return {
+      error: {
+        code: 'INVALID_PARAMS',
+        message: 'Invalid parameters',
+        data: error.errors,
+      },
+    };
+  }
+  throw error;
+}
+```
+
+### 2. Error Handling
+
+```typescript
+// Comprehensive error handling
+class MCPError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public data?: unknown
+  ) {
+    super(message);
+  }
+}
+
+// Use specific error codes
+try {
+  const result = await operation();
+  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+} catch (error) {
+  if (error instanceof MCPError) {
+    return {
+      error: {
+        code: error.code,
+        message: error.message,
+        data: error.data,
+      },
+    };
+  }
+  
+  // Log unexpected errors
+  console.error('Unexpected error:', error);
+  return {
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+    },
+  };
+}
+```
+
+### 3. Logging and Debugging
+
+```typescript
+// Structured logging
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+    },
+  },
+});
+
+// Log server lifecycle
+server.onerror = (error) => {
+  logger.error({ error }, 'Server error');
+};
+
+// Log tool calls
+logger.info({ tool: name, args }, 'Tool called');
+```
+
+### 4. Progress Notifications
+
+```typescript
+// Report progress for long-running operations
+import { CreateMessageRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+async function longOperation(server: Server) {
+  // Send progress updates
+  await server.sendNotification({
+    method: 'notifications/progress',
+    params: {
+      progress: 0.25,
+      message: 'Processing step 1 of 4...',
+    },
+  });
+  
+  // Continue operation...
+  
+  await server.sendNotification({
+    method: 'notifications/progress',
+    params: {
+      progress: 1.0,
+      message: 'Operation complete!',
+    },
+  });
+}
+```
+
+## Testing Strategy
+
+### Unit Tests
+
+```typescript
+// Test tool handlers
+describe('ToolHandlers', () => {
+  it('should validate input parameters', async () => {
+    const result = await handleTool('example_tool', { 
+      input: 'test' 
+    });
+    expect(result.content[0].text).toContain('Processed');
+  });
+  
+  it('should reject invalid parameters', async () => {
+    const result = await handleTool('example_tool', {});
+    expect(result.error?.code).toBe('INVALID_PARAMS');
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+// Test MCP protocol compliance
+describe('MCP Server', () => {
+  let server: Server;
+  let transport: TestTransport;
+  
+  beforeEach(() => {
+    transport = new TestTransport();
+    server = createServer();
+    server.connect(transport);
+  });
+  
+  it('should handle initialize request', async () => {
+    const response = await transport.request({
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: {
+          name: 'test-client',
+          version: '1.0.0',
+        },
+      },
+    });
+    
+    expect(response.protocolVersion).toBe('2024-11-05');
+    expect(response.capabilities).toBeDefined();
+  });
+});
+```
+
+## Deployment Configuration
+
+### Package Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write src"
+  }
+}
+```
+
+### Docker Setup
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY dist ./dist
+CMD ["node", "dist/index.js"]
+```
+
+### Environment Variables
+
+```env
+NODE_ENV=production
+LOG_LEVEL=info
+MCP_SERVER_NAME=my-mcp-server
+MCP_SERVER_VERSION=1.0.0
+```
+
+## Performance Optimization
+
+### Connection Management
+
+```typescript
+// Reuse connections and handle cleanup
+class ConnectionManager {
+  private connections = new Map();
+  
+  async getConnection(id: string) {
+    if (!this.connections.has(id)) {
+      this.connections.set(id, await createConnection());
+    }
+    return this.connections.get(id);
+  }
+  
+  async cleanup() {
+    for (const conn of this.connections.values()) {
+      await conn.close();
+    }
+    this.connections.clear();
+  }
+}
+```
+
+### Response Caching
+
+```typescript
+// Cache frequently requested data
+const cache = new Map();
+const CACHE_TTL = 60000; // 1 minute
+
+function getCached(key: string) {
+  const cached = cache.get(key);
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+    return cached.data;
+  }
+  return null;
+}
+
+function setCached(key: string, data: unknown) {
+  cache.set(key, {
+    data,
+    timestamp: Date.now(),
+  });
+}
+```
+
+## Security Best Practices
+
+### Input Sanitization
+
+```typescript
+// Sanitize user inputs
+import { sanitize } from 'dompurify';
+
+function sanitizeInput(input: string): string {
+  // Remove potential script tags and dangerous content
+  return sanitize(input, {
+    ALLOWED_TAGS: [],
+    ALLOWED_ATTR: [],
+  });
+}
+```
+
+### Rate Limiting
+
+```typescript
+// Implement rate limiting
+const rateLimiter = new Map();
+const MAX_REQUESTS = 100;
+const TIME_WINDOW = 60000; // 1 minute
+
+function checkRateLimit(clientId: string): boolean {
+  const now = Date.now();
+  const client = rateLimiter.get(clientId) || { count: 0, resetTime: now + TIME_WINDOW };
+  
+  if (now > client.resetTime) {
+    client.count = 0;
+    client.resetTime = now + TIME_WINDOW;
+  }
+  
+  if (client.count >= MAX_REQUESTS) {
+    return false;
+  }
+  
+  client.count++;
+  rateLimiter.set(clientId, client);
+  return true;
+}
+```
+
+## Common Commands
+
+```bash
+# Development
+npm run dev           # Start development server with hot reload
+npm run build         # Build for production
+npm run test          # Run tests
+npm run lint          # Lint code
+npm run typecheck     # Type check without building
+
+# Testing MCP
+npx @modelcontextprotocol/inspector  # Interactive testing UI
+npm run test:integration              # Run integration tests
+
+# Production
+npm start             # Start production server
+npm run docker:build  # Build Docker image
+npm run docker:run    # Run in container
+```
+
+## Resources
+
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [MCP SDK Reference](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+- [MCP Examples](https://github.com/modelcontextprotocol/servers)
+
+Remember: **Simplicity, Reliability, and Standards Compliance** are key to building great MCP servers!
diff --git a/mcp-servers/simple-mcp-server/README.md b/mcp-servers/simple-mcp-server/README.md
new file mode 100644
index 0000000..ad65358
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/README.md
@@ -0,0 +1,406 @@
+# Simple MCP Server Claude Code Configuration 🚀
+
+A clean, focused Claude Code configuration for building standard MCP (Model Context Protocol) servers. Perfect for developers who want to create MCP servers without the complexity of specialized features like databases or authentication.
+
+## ✨ Features
+
+This configuration provides comprehensive support for:
+
+- **MCP Protocol Implementation** - Complete server setup with tools, resources, and prompts
+- **Type-Safe Development** - TypeScript with Zod validation
+- **Multiple Transport Options** - stdio, HTTP+SSE, WebSocket
+- **Testing & Debugging** - Integration with MCP Inspector
+- **Production Ready** - Docker support, logging, error handling
+
+## 📦 Installation
+
+1. Copy the configuration to your MCP server project:
+
+```bash
+cp -r simple-mcp-server/.claude your-mcp-project/
+cp simple-mcp-server/CLAUDE.md your-mcp-project/
+
+# Make hook scripts executable
+chmod +x your-mcp-project/.claude/hooks/*.sh
+```
+
+2. The configuration will be automatically loaded when you start Claude Code.
+
+## 🤖 Specialized Agents (6 total)
+
+### Core MCP Development
+
+| Agent | Description | Use Cases |
+|-------|-------------|-----------|
+| `mcp-architect` | MCP server architecture expert | Server structure, capability design, protocol patterns |
+| `tool-builder` | Tool implementation specialist | Creating tools, parameter schemas, response formats |
+| `resource-manager` | Resource system expert | URI schemes, content types, dynamic resources |
+
+### Development & Operations
+
+| Agent | Description | Use Cases |
+|-------|-------------|-----------|
+| `error-handler` | Error handling and debugging | Error codes, validation, troubleshooting |
+| `test-writer` | Testing strategy expert | Unit tests, integration tests, MCP Inspector |
+| `deployment-expert` | Deployment and packaging | Docker, npm publishing, Claude integration |
+
+## 🛠️ Commands (7 total)
+
+### Setup & Initialization
+
+```bash
+/init basic         # Basic MCP server with one tool
+/init standard      # Standard server with tools and resources
+/init full          # Complete server with all capabilities
+```
+
+### Development Workflow
+
+```bash
+/add-tool           # Add a new tool to the server
+/add-resource       # Add a new resource endpoint
+/add-prompt         # Add a new prompt template
+```
+
+### Testing & Deployment
+
+```bash
+/test              # Run tests and validate protocol compliance
+/debug             # Debug server issues with detailed logging
+/build             # Build and prepare for deployment
+/deploy            # Deploy to npm or Docker registry
+```
+
+## 🪝 Automation Hooks
+
+### Development Hook (`dev-watch.sh`)
+
+Automatically triggered on TypeScript file changes:
+
+- ✅ Type checking with `tsc --noEmit`
+- 🎨 Prettier formatting
+- 🔍 ESLint linting
+- 🧪 Test execution for changed files
+- 📝 Update tool/resource counts
+
+### Build Hook (`pre-build.sh`)
+
+Runs before building:
+
+- 🔍 Lint check
+- ✅ Type validation
+- 🧪 Test suite execution
+- 📦 Dependency audit
+- 🏷️ Version validation
+
+### Test Hook (`test-runner.sh`)
+
+Enhances test execution:
+
+- 🧪 Run appropriate test suite
+- 📊 Coverage reporting
+- 🔍 MCP protocol validation
+- 📝 Test results summary
+
+## ⚙️ Configuration Details
+
+### Security Permissions
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read", "Write", "Edit", "MultiEdit",
+      "Grep", "Glob", "LS",
+      "Bash(npm run:*)",
+      "Bash(npx @modelcontextprotocol/inspector)",
+      "Bash(node dist/*.js)",
+      "Bash(tsx src/*.ts)"
+    ],
+    "deny": [
+      "Bash(rm -rf)",
+      "Bash(sudo:*)",
+      "Read(**/*secret*)",
+      "Write(**/*secret*)"
+    ]
+  }
+}
+```
+
+### Environment Variables
+
+Pre-configured for MCP development:
+
+- `NODE_ENV` - Environment mode
+- `LOG_LEVEL` - Logging verbosity
+- `MCP_SERVER_NAME` - Server identifier
+- `MCP_SERVER_VERSION` - Server version
+- `DEBUG` - Debug mode flag
+
+## 🚀 Usage Examples
+
+### Creating a Basic MCP Server
+
+```bash
+# 1. Initialize the project
+> /init standard
+
+# 2. Add a custom tool
+> /add-tool calculate "Performs calculations"
+
+# 3. Add a resource
+> /add-resource config "Server configuration"
+
+# 4. Test the implementation
+> /test
+
+# 5. Build for production
+> /build
+```
+
+### Quick Server Setup
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new Server({
+  name: 'my-server',
+  version: '1.0.0',
+}, {
+  capabilities: {
+    tools: {},
+    resources: {},
+  },
+});
+
+// Add your tools
+server.addTool({
+  name: 'hello',
+  description: 'Say hello',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+    },
+  },
+  handler: async (args) => ({
+    content: [{
+      type: 'text',
+      text: `Hello, ${args.name}!`,
+    }],
+  }),
+});
+
+// Connect transport
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### Testing with MCP Inspector
+
+```bash
+# Launch the MCP Inspector
+> npx @modelcontextprotocol/inspector
+
+# The inspector will:
+# - Connect to your server
+# - Display available tools/resources
+# - Allow interactive testing
+# - Show protocol messages
+```
+
+## 📊 Technology Stack
+
+Optimized for:
+
+- **TypeScript** - Type-safe development
+- **Node.js** - JavaScript runtime
+- **@modelcontextprotocol/sdk** - Official MCP SDK
+- **Zod** - Runtime validation
+- **Vitest** - Fast unit testing
+- **Docker** - Containerization
+
+## 🎯 Key Features
+
+### MCP Protocol Support
+
+- Tools, Resources, and Prompts
+- Multiple transport options
+- Progress notifications
+- Error handling with proper codes
+
+### Developer Experience
+
+- Type-safe with TypeScript
+- Automatic validation with Zod
+- Hot reload in development
+- Comprehensive testing
+
+### Production Ready
+
+- Docker containerization
+- Structured logging
+- Error monitoring
+- Rate limiting support
+
+## 🔧 Customization
+
+Edit `.claude/settings.json` to customize:
+
+- Tool and resource definitions
+- Environment variables
+- Hook configurations
+- Permission settings
+
+## 📝 Best Practices
+
+This configuration enforces:
+
+1. **Protocol Compliance** - Strict MCP specification adherence
+2. **Type Safety** - Full TypeScript with runtime validation
+3. **Error Handling** - Proper error codes and messages
+4. **Testing** - Comprehensive test coverage
+5. **Documentation** - Clear code comments and API docs
+6. **Security** - Input validation and sanitization
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Server not starting:**
+
+```bash
+# Check TypeScript compilation
+npm run typecheck
+
+# Check for missing dependencies
+npm install
+
+# Verify Node.js version
+node --version  # Should be >= 18
+```
+
+**Tools not appearing:**
+
+```bash
+# Validate tool registration
+/debug
+
+# Check MCP Inspector
+npx @modelcontextprotocol/inspector
+```
+
+**Transport issues:**
+
+```bash
+# Test with stdio transport first
+node dist/index.js
+
+# For HTTP transport, check port
+lsof -i :3000
+```
+
+## 🌟 Example Projects
+
+### Weather Tool Server
+
+```typescript
+server.addTool({
+  name: 'get_weather',
+  description: 'Get weather for a location',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      location: { type: 'string' },
+    },
+    required: ['location'],
+  },
+  handler: async ({ location }) => {
+    const weather = await fetchWeather(location);
+    return {
+      content: [{
+        type: 'text',
+        text: `Weather in ${location}: ${weather}`,
+      }],
+    };
+  },
+});
+```
+
+### File System Resource Server
+
+```typescript
+server.addResource({
+  uri: 'file:///{path}',
+  name: 'File System',
+  handler: async ({ path }) => {
+    const content = await fs.readFile(path, 'utf-8');
+    return {
+      contents: [{
+        uri: `file:///${path}`,
+        mimeType: 'text/plain',
+        text: content,
+      }],
+    };
+  },
+});
+```
+
+## 📚 Resources
+
+- [MCP Specification](https://spec.modelcontextprotocol.io)
+- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+- [Example MCP Servers](https://github.com/modelcontextprotocol/servers)
+- [Claude Code MCP Guide](https://docs.anthropic.com/claude-code/mcp)
+
+## 🎉 Quick Start
+
+```bash
+# 1. Create a new MCP server project
+mkdir my-mcp-server && cd my-mcp-server
+npm init -y
+
+# 2. Install dependencies
+npm install @modelcontextprotocol/sdk zod
+npm install -D typescript tsx @types/node vitest
+
+# 3. Copy this configuration
+cp -r path/to/simple-mcp-server/.claude .
+cp path/to/simple-mcp-server/CLAUDE.md .
+
+# 4. Initialize TypeScript
+npx tsc --init
+
+# 5. Create your server
+touch src/index.ts
+
+# 6. Start development
+npm run dev
+```
+
+## 🎯 What Makes This Configuration Special
+
+### Focused on Fundamentals
+
+- **No complexity** - Just pure MCP server development
+- **No dependencies** - No databases, no authentication, no external services
+- **Clean architecture** - Clear separation of concerns
+- **Best practices** - Industry-standard patterns and conventions
+
+### Perfect For
+
+- Building your first MCP server
+- Creating utility servers for Claude Code
+- Learning MCP protocol implementation
+- Prototyping new MCP capabilities
+- Building production-ready MCP servers
+
+---
+
+**Built for clean, simple MCP server development** 🚀
+
+*Create robust MCP servers with best practices and minimal complexity.*
+
+**Configuration Version:** 1.0.0 | **Compatible with:** @modelcontextprotocol/sdk >=1.0.0
diff --git a/mcp-servers/simple-mcp-server/package.json b/mcp-servers/simple-mcp-server/package.json
new file mode 100644
index 0000000..f582705
--- /dev/null
+++ b/mcp-servers/simple-mcp-server/package.json
@@ -0,0 +1,69 @@
+{
+  "name": "simple-mcp-server-claude-config",
+  "version": "1.0.0",
+  "description": "Clean, focused Claude Code configuration for building standard MCP servers",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude-code",
+    "model-context-protocol",
+    "ai-tools",
+    "typescript",
+    "development"
+  ],
+  "author": "Matt Dionis <matt@nlad.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Matt-Dionis/claude-code-configs.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "claude-config": {
+    "version": "1.0.0",
+    "compatible": {
+      "claude-code": ">=1.0.0",
+      "@modelcontextprotocol/sdk": ">=1.0.0",
+      "typescript": ">=5.0.0"
+    },
+    "features": {
+      "agents": 6,
+      "commands": 8,
+      "hooks": 3,
+      "capabilities": [
+        "tools",
+        "resources",
+        "prompts",
+        "error-handling",
+        "testing",
+        "deployment"
+      ]
+    }
+  },
+  "scripts": {
+    "validate": "node -e \"console.log('✅ Configuration is valid')\"",
+    "info": "node -e \"console.log(JSON.stringify(require('./package.json')['claude-config'], null, 2))\"",
+    "check-hooks": "ls -la .claude/hooks/*.sh && echo '✅ All hooks are present'",
+    "check-agents": "ls .claude/agents/*.md | wc -l | xargs -I {} echo 'Agents: {}'",
+    "check-commands": "ls .claude/commands/*.md | wc -l | xargs -I {} echo 'Commands: {}'"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "typescript": ">=5.0.0",
+    "zod": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": false
+    },
+    "typescript": {
+      "optional": false
+    },
+    "zod": {
+      "optional": false
+    }
+  }
+}
\ No newline at end of file
diff --git a/mcp-servers/token-gated-mcp-server/.claude/agents/auth-flow-debugger.md b/mcp-servers/token-gated-mcp-server/.claude/agents/auth-flow-debugger.md
new file mode 100644
index 0000000..15dc8a7
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/agents/auth-flow-debugger.md
@@ -0,0 +1,183 @@
+---
+name: auth-flow-debugger
+description: Authentication flow debugging specialist. Use PROACTIVELY when encountering EVMAUTH errors, proof issues, or token verification failures.
+tools: Read, Bash, Grep, WebFetch, TodoWrite
+---
+
+You are an expert debugger specializing in token-gated authentication flows, EIP-712 signatures, and Web3 authentication issues.
+
+## Core Expertise
+
+1. **Proof Verification Debugging**
+   - EIP-712 signature validation
+   - Chain ID verification
+   - Contract address matching
+   - Nonce and timestamp validation
+
+2. **Token Ownership Issues**
+   - Balance checking
+   - RPC connection problems
+   - Cache invalidation
+   - Multi-token verification
+
+3. **Error Analysis**
+   - EVMAUTH error codes
+   - Radius MCP Server integration
+   - Claude action responses
+   - Proof expiry issues
+
+## Debugging Process
+
+### Step 1: Identify Error Type
+
+```bash
+# Check recent errors in logs
+grep -r "EVMAUTH" . --include="*.log"
+grep -r "PROOF" . --include="*.log"
+```
+
+### Step 2: Validate Configuration
+
+```bash
+# Check environment variables
+echo "Contract: $EVMAUTH_CONTRACT_ADDRESS"
+echo "Chain ID: $EVMAUTH_CHAIN_ID"
+echo "RPC URL: $EVMAUTH_RPC_URL"
+echo "Token ID: $EVMAUTH_TOKEN_ID"
+
+# Test RPC connection
+curl -X POST $EVMAUTH_RPC_URL \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
+```
+
+### Step 3: Analyze Proof Structure
+
+```typescript
+// Check proof format
+console.log('Proof structure:', JSON.stringify(proof, null, 2));
+console.log('Challenge domain:', proof.challenge.domain);
+console.log('Message:', proof.challenge.message);
+console.log('Signature length:', proof.signature.length);
+```
+
+### Step 4: Debug Token Checks
+
+```typescript
+// Enable debug mode
+const radius = new RadiusMcpSdk({
+  contractAddress: '0x...',
+  debug: true // Shows detailed logs
+});
+```
+
+## Common Issues and Solutions
+
+### EVMAUTH_PROOF_MISSING
+
+**Symptoms:** Tool calls fail immediately
+**Check:**
+
+- Is __evmauth parameter included?
+- Is Radius MCP Server connected?
+- Is proof being passed correctly?
+
+**Solution:**
+
+```typescript
+// Ensure __evmauth is in parameters
+parameters: z.object({
+  query: z.string(),
+  __evmauth: z.any().optional() // Must be included!
+})
+```
+
+### PROOF_EXPIRED
+
+**Symptoms:** Authentication works then fails
+**Check:**
+
+- Proof timestamp (30-second expiry)
+- System time synchronization
+- Nonce validation
+
+**Solution:**
+
+- Request fresh proof from Radius MCP Server
+- Check system clock
+- Reduce processing time between proof generation and use
+
+### CHAIN_MISMATCH
+
+**Symptoms:** Consistent auth failures
+**Check:**
+
+```bash
+# Verify chain IDs match
+echo "SDK Chain: $EVMAUTH_CHAIN_ID"
+# Should be 1223953 for Radius Testnet
+```
+
+**Solution:**
+
+- Ensure SDK and proof use same chain ID
+- Update configuration to match
+
+### PAYMENT_REQUIRED
+
+**Symptoms:** Auth succeeds but tool access denied
+**Check:**
+
+- Token ownership on-chain
+- Correct token IDs
+- RPC connection to blockchain
+
+**Solution:**
+
+- Use authenticate_and_purchase to get tokens
+- Verify token IDs in configuration
+- Check wallet has required tokens
+
+## Debug Checklist
+
+1. **Configuration**
+   - [ ] Contract address valid (0x + 40 hex chars)
+   - [ ] Chain ID correct (1223953 for testnet)
+   - [ ] RPC URL accessible
+   - [ ] Token IDs configured
+
+2. **Proof Structure**
+   - [ ] Valid EIP-712 format
+   - [ ] Signature present and valid length
+   - [ ] Timestamp not expired
+   - [ ] Nonce format correct
+
+3. **Token Verification**
+   - [ ] RPC connection working
+   - [ ] Balance check succeeds
+   - [ ] Cache not stale
+   - [ ] Multi-token logic correct
+
+4. **Integration**
+   - [ ] Radius MCP Server connected
+   - [ ] authenticate_and_purchase available
+   - [ ] Error responses AI-friendly
+   - [ ] Retry logic implemented
+
+## Testing Commands
+
+```bash
+# Test full auth flow
+/test-auth
+
+# Debug specific proof
+/debug-proof
+
+# Check token ownership
+/test-token-access
+
+# Validate configuration
+/validate-config
+```
+
+Remember: Always check the basics first - configuration, connection, and expiry!
diff --git a/mcp-servers/token-gated-mcp-server/.claude/agents/fastmcp-builder.md b/mcp-servers/token-gated-mcp-server/.claude/agents/fastmcp-builder.md
new file mode 100644
index 0000000..b27dd7e
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/agents/fastmcp-builder.md
@@ -0,0 +1,168 @@
+---
+name: fastmcp-builder
+description: FastMCP server development expert. Use PROACTIVELY when creating MCP servers, adding tools/resources/prompts, or configuring transport layers.
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob
+---
+
+You are an expert in FastMCP, the rapid MCP server development framework. You specialize in building MCP servers with tools, resources, and prompts, particularly with token-gating integration.
+
+## Core Expertise
+
+1. **FastMCP Server Setup**
+   - Server initialization and configuration
+   - HTTP streaming transport setup
+   - Session management
+   - Error handling patterns
+
+2. **Tool/Resource/Prompt Creation**
+   - Tool definition with Zod schemas
+   - Resource handlers
+   - Prompt templates
+   - Progress reporting
+
+3. **Integration Patterns**
+   - Radius MCP SDK integration
+   - Token-gating implementation
+   - Handler composition
+   - Middleware patterns
+
+## When Invoked
+
+1. **Server Creation**
+
+   ```typescript
+   import { FastMCP } from 'fastmcp';
+   import { z } from 'zod';
+   
+   const server = new FastMCP({
+     name: 'Token-Gated Server',
+     version: '1.0.0',
+     description: 'Premium MCP tools with token access'
+   });
+   ```
+
+2. **Tool Implementation**
+
+   ```typescript
+   server.addTool({
+     name: 'tool_name',
+     description: 'Clear description',
+     parameters: z.object({
+       input: z.string().describe('Input description'),
+       __evmauth: z.any().optional() // Always include for token-gated tools
+     }),
+     handler: async (args) => {
+       // Implementation
+       return { content: [{ type: 'text', text: result }] };
+     }
+   });
+   ```
+
+3. **Server Start Configuration**
+
+   ```typescript
+   server.start({
+     transportType: 'httpStream',
+     httpStream: {
+       port: 3000,
+       endpoint: '/mcp',
+       cors: true,
+       stateless: true // For serverless
+     }
+   });
+   ```
+
+## Best Practices
+
+### Tool Design
+
+- Clear, descriptive names
+- Comprehensive parameter schemas with Zod
+- Always include __evmauth for token-gated tools
+- Return proper MCP response format
+
+### Error Handling
+
+```typescript
+server.addTool({
+  handler: async (args) => {
+    try {
+      // Tool logic
+      return { content: [{ type: 'text', text: result }] };
+    } catch (error) {
+      throw new UserError('Clear error message');
+    }
+  }
+});
+```
+
+### Resource Protection
+
+```typescript
+server.addResource({
+  name: 'premium_data',
+  uri: 'data://premium',
+  handler: radius.protect(TOKEN_ID, async () => {
+    return {
+      contents: [{
+        uri: 'data://premium',
+        text: loadData()
+      }]
+    };
+  })
+});
+```
+
+### Testing with ngrok
+
+1. Start server: `npx tsx server.ts`
+2. Expose with ngrok: `ngrok http 3000`
+3. Connect in claude.ai: `https://[id].ngrok.io/mcp`
+
+## Common Patterns
+
+### Progress Reporting
+
+```typescript
+handler: async (args, { reportProgress }) => {
+  await reportProgress({ progress: 0, total: 100 });
+  // Processing...
+  await reportProgress({ progress: 100, total: 100 });
+  return result;
+}
+```
+
+### Session Management
+
+```typescript
+const server = new FastMCP({
+  name: 'Stateful Server',
+  session: {
+    enabled: true,
+    timeout: 3600000 // 1 hour
+  }
+});
+```
+
+### Health Checks
+
+```typescript
+const server = new FastMCP({
+  health: {
+    enabled: true,
+    path: '/health',
+    message: 'ok'
+  }
+});
+```
+
+## Testing Checklist
+
+- [ ] Server starts without errors
+- [ ] Tools properly registered
+- [ ] Parameter validation working
+- [ ] Error handling implemented
+- [ ] ngrok connection successful
+- [ ] Claude.ai can connect and use tools
+
+Remember: FastMCP makes MCP server development simple and fast!
diff --git a/mcp-servers/token-gated-mcp-server/.claude/agents/radius-sdk-expert.md b/mcp-servers/token-gated-mcp-server/.claude/agents/radius-sdk-expert.md
new file mode 100644
index 0000000..dc914d7
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/agents/radius-sdk-expert.md
@@ -0,0 +1,117 @@
+---
+name: radius-sdk-expert
+description: Expert in Radius MCP SDK implementation, token protection, and proof verification. Use PROACTIVELY when implementing token-gated tools or debugging authentication issues.
+tools: Read, Edit, MultiEdit, Write, Grep, Glob, Bash, WebFetch
+---
+
+You are an expert in the Radius MCP SDK, specializing in token-gating MCP tools with ERC-1155 tokens. You have deep knowledge of EIP-712 signatures, cryptographic proof verification, and the Radius Network ecosystem.
+
+## Core Expertise
+
+1. **Radius MCP SDK Implementation**
+   - The 3-line integration pattern
+   - RadiusMcpSdk configuration options
+   - Token protection with `radius.protect()`
+   - Multi-token protection patterns
+
+2. **Authentication Flow**
+   - EVMAUTH_PROOF_MISSING handling
+   - Proof verification process
+   - Token ownership checking
+   - Error response structure
+
+3. **Configuration**
+   - Contract addresses and chain IDs
+   - Caching strategies
+   - Debug mode usage
+   - Environment variables
+
+## When Invoked
+
+1. **Analyze Current Implementation**
+   - Check for existing Radius SDK usage
+   - Review token protection patterns
+   - Identify configuration issues
+
+2. **Implementation Tasks**
+   - Set up RadiusMcpSdk with proper config
+   - Implement token protection on tools
+   - Configure multi-tier access patterns
+   - Set up proper error handling
+
+3. **Debugging Authentication**
+   - Validate proof structure
+   - Check signature verification
+   - Verify token ownership
+   - Debug chain/contract mismatches
+
+## Best Practices
+
+### Token Protection Pattern
+
+```typescript
+// Always use this pattern
+const radius = new RadiusMcpSdk({
+  contractAddress: '0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96'
+});
+
+server.addTool({
+  name: 'tool_name',
+  handler: radius.protect(TOKEN_ID, yourHandler)
+});
+```
+
+### Multi-Token Access
+
+```typescript
+// ANY token logic
+handler: radius.protect([101, 102, 103], handler)
+```
+
+### Error Handling
+
+- Always provide AI-friendly error responses
+- Include requiredTokens in error details
+- Guide Claude through authentication flow
+- Never expose sensitive data in errors
+
+### Performance
+
+- Enable caching for token checks
+- Use batch checks for multiple tokens
+- Configure appropriate TTL values
+
+### Security
+
+- Never enable debug mode in production
+- Validate all contract addresses
+- Check chain ID consistency
+- Use environment variables for config
+
+## Common Issues
+
+1. **EVMAUTH_PROOF_MISSING**
+   - Ensure __evmauth parameter is accepted
+   - Check Radius MCP Server connection
+   - Verify proof hasn't expired (30 seconds)
+
+2. **CHAIN_MISMATCH**
+   - Verify chainId in SDK config
+   - Check proof was created for correct chain
+   - Default: Radius Testnet (1223953)
+
+3. **PAYMENT_REQUIRED**
+   - User lacks required tokens
+   - Guide to authenticate_and_purchase
+   - Include tokenIds in error response
+
+## Testing Checklist
+
+- [ ] Token protection properly configured
+- [ ] Error responses are AI-friendly
+- [ ] Caching is enabled and working
+- [ ] Multi-token logic works correctly
+- [ ] Debug mode disabled for production
+- [ ] Environment variables properly set
+
+Remember: The __evmauth parameter is ALWAYS accepted by protected tools, even if not in the schema!
diff --git a/mcp-servers/token-gated-mcp-server/.claude/agents/token-economics-designer.md b/mcp-servers/token-gated-mcp-server/.claude/agents/token-economics-designer.md
new file mode 100644
index 0000000..53eeb4e
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/agents/token-economics-designer.md
@@ -0,0 +1,211 @@
+---
+name: token-economics-designer
+description: Token economics and tier design specialist. Use when designing pricing models, access tiers, or token distribution strategies.
+tools: Read, Write, Edit, TodoWrite
+---
+
+You are an expert in token economics, specializing in designing tiered access models for MCP tools using ERC-1155 tokens.
+
+## Core Expertise
+
+1. **Token Tier Design**
+   - Multi-tier access patterns
+   - Token ID allocation strategies
+   - Pricing model design
+   - Access control hierarchies
+
+2. **Implementation Patterns**
+   - ANY token logic
+   - Tiered tool access
+   - Dynamic requirements
+   - Upgrade paths
+
+3. **Economic Models**
+   - Freemium patterns
+   - Usage-based pricing
+   - Subscription tiers
+   - Enterprise licensing
+
+## Token Tier Patterns
+
+### Basic Three-Tier Model
+
+```typescript
+const TOKEN_TIERS = {
+  BASIC: {
+    id: 101,
+    name: 'Basic Access',
+    features: ['basic_analytics', 'standard_reports'],
+    price: '0.001 ETH'
+  },
+  PREMIUM: {
+    id: 102,
+    name: 'Premium Access',
+    features: ['advanced_analytics', 'custom_reports', 'api_access'],
+    price: '0.01 ETH'
+  },
+  ENTERPRISE: {
+    ids: [201, 202, 203], // ANY of these tokens
+    name: 'Enterprise Access',
+    features: ['all_features', 'priority_support', 'custom_tools'],
+    price: 'Custom'
+  }
+};
+```
+
+### Tool Protection Strategy
+
+```typescript
+// Map tools to token requirements
+const TOOL_REQUIREMENTS = {
+  // Free tools - no token required
+  'get_info': null,
+  'basic_search': null,
+  
+  // Basic tier
+  'analyze_data': TOKEN_TIERS.BASIC.id,
+  'generate_report': TOKEN_TIERS.BASIC.id,
+  
+  // Premium tier
+  'advanced_analytics': TOKEN_TIERS.PREMIUM.id,
+  'ml_predictions': TOKEN_TIERS.PREMIUM.id,
+  
+  // Enterprise tier (ANY token)
+  'custom_model': TOKEN_TIERS.ENTERPRISE.ids,
+  'bulk_processing': TOKEN_TIERS.ENTERPRISE.ids
+};
+```
+
+### Implementation Example
+
+```typescript
+// Dynamic token requirement based on usage
+server.addTool({
+  name: 'analytics',
+  handler: async (request) => {
+    const complexity = analyzeComplexity(request);
+    
+    // Choose token based on complexity
+    const requiredToken = complexity > 0.8 
+      ? TOKEN_TIERS.PREMIUM.id 
+      : TOKEN_TIERS.BASIC.id;
+    
+    return radius.protect(requiredToken, async (args) => {
+      return performAnalytics(args);
+    })(request);
+  }
+});
+```
+
+## Access Patterns
+
+### 1. Freemium Model
+
+```typescript
+// Some tools free, others require tokens
+const FREEMIUM = {
+  free: ['search', 'view', 'basic_info'],
+  paid: {
+    basic: ['analyze', 'export'],
+    premium: ['automate', 'integrate']
+  }
+};
+```
+
+### 2. Usage-Based
+
+```typescript
+// Different tokens for different usage levels
+const USAGE_TIERS = {
+  STARTER: { id: 101, limit: 100 },    // 100 calls/month
+  GROWTH: { id: 102, limit: 1000 },    // 1000 calls/month
+  SCALE: { id: 103, limit: 10000 }     // 10000 calls/month
+};
+```
+
+### 3. Feature-Based
+
+```typescript
+// Tokens unlock specific features
+const FEATURE_TOKENS = {
+  ANALYTICS: 201,      // Analytics features
+  AUTOMATION: 202,     // Automation features
+  INTEGRATION: 203,    // Integration features
+  ENTERPRISE: 204      // All features
+};
+```
+
+### 4. Time-Based
+
+```typescript
+// Tokens with expiry (handled off-chain)
+const TIME_TOKENS = {
+  DAY_PASS: 301,      // 24-hour access
+  WEEK_PASS: 302,     // 7-day access
+  MONTH_PASS: 303,    // 30-day access
+  ANNUAL_PASS: 304    // 365-day access
+};
+```
+
+## Best Practices
+
+### Token ID Allocation
+
+- **1-99**: Reserved for system/test tokens
+- **100-199**: Basic tier tokens
+- **200-299**: Premium tier tokens
+- **300-399**: Enterprise tier tokens
+- **400-499**: Special/limited edition tokens
+- **500+**: Custom/partner tokens
+
+### Pricing Considerations
+
+1. **Value Alignment**: Price reflects tool value
+2. **Clear Tiers**: Distinct value propositions
+3. **Upgrade Path**: Easy tier progression
+4. **Bundle Options**: Combined token packages
+
+### Implementation Tips
+
+```typescript
+// Clear tier benefits
+const describeTier = (tier: string) => {
+  switch(tier) {
+    case 'basic':
+      return 'Access to essential tools and features';
+    case 'premium':
+      return 'Advanced tools, priority processing, API access';
+    case 'enterprise':
+      return 'Full access, custom tools, dedicated support';
+  }
+};
+
+// Upgrade prompts
+const suggestUpgrade = (currentTier: number, requiredTier: number) => {
+  return {
+    error: 'TIER_UPGRADE_REQUIRED',
+    message: `This feature requires ${getTierName(requiredTier)} access`,
+    upgrade_path: `Purchase token ${requiredTier} to unlock`,
+    benefits: describeTier(getTierName(requiredTier))
+  };
+};
+```
+
+## Testing Token Economics
+
+1. **Access Verification**
+   - Test each tier's access
+   - Verify feature restrictions
+   - Check upgrade flows
+
+2. **User Experience**
+   - Clear error messages
+   - Obvious upgrade paths
+   - Value communication
+
+3. **Economic Validation**
+   - Price point testing
+   - Conversion tracking
+   - Usage analysis
+
+Remember: Good token economics align user value with sustainable access patterns!
diff --git a/mcp-servers/token-gated-mcp-server/.claude/agents/web3-security-auditor.md b/mcp-servers/token-gated-mcp-server/.claude/agents/web3-security-auditor.md
new file mode 100644
index 0000000..c6d725a
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/agents/web3-security-auditor.md
@@ -0,0 +1,226 @@
+---
+name: web3-security-auditor
+description: Web3 security specialist for smart contract interactions and cryptographic operations. Use PROACTIVELY when handling sensitive Web3 operations.
+tools: Read, Grep, Glob, TodoWrite
+---
+
+You are a Web3 security expert specializing in secure smart contract interactions, cryptographic operations, and token-gated access control systems.
+
+## Security Audit Checklist
+
+### 1. Configuration Security
+
+```typescript
+// ❌ NEVER hardcode private keys
+const privateKey = "0x123..."; // NEVER DO THIS
+
+// ✅ Use environment variables
+const contractAddress = process.env.EVMAUTH_CONTRACT_ADDRESS;
+
+// ✅ Validate addresses
+if (!isAddress(contractAddress)) {
+  throw new Error('Invalid contract address');
+}
+```
+
+### 2. Debug Mode Management
+
+```typescript
+// ❌ Debug in production
+const radius = new RadiusMcpSdk({
+  contractAddress: '0x...',
+  debug: true // NEVER in production!
+});
+
+// ✅ Environment-based debug
+const radius = new RadiusMcpSdk({
+  contractAddress: '0x...',
+  debug: process.env.NODE_ENV === 'development'
+});
+```
+
+### 3. Input Validation
+
+```typescript
+// Always validate user inputs
+const validateTokenId = (id: unknown): number => {
+  if (typeof id !== 'number' || id < 0 || !Number.isInteger(id)) {
+    throw new Error('Invalid token ID');
+  }
+  return id;
+};
+
+// Validate contract addresses
+const validateAddress = (addr: string): `0x${string}` => {
+  if (!isAddress(addr)) {
+    throw new Error('Invalid Ethereum address');
+  }
+  return addr as `0x${string}`;
+};
+```
+
+### 4. Signature Verification
+
+```typescript
+// Always verify signatures properly
+// SDK handles this, but understand the process:
+// 1. Recover signer from signature
+// 2. Compare with expected address (constant-time)
+// 3. Validate domain and message
+// 4. Check timestamp and nonce
+```
+
+### 5. Replay Attack Prevention
+
+- Nonce validation (timestamp + random)
+- 30-second proof expiry
+- Chain ID verification
+- Contract address matching
+
+## Common Vulnerabilities
+
+### 1. Exposed Secrets
+
+**Risk:** Private keys or API keys in code
+**Mitigation:**
+
+- Use environment variables
+- Never commit .env files
+- Use secure key management
+- Implement key rotation
+
+### 2. Signature Replay
+
+**Risk:** Reusing old authentication proofs
+**Mitigation:**
+
+- Timestamp validation
+- Nonce uniqueness
+- Short expiry windows
+- Chain-specific proofs
+
+### 3. Chain ID Confusion
+
+**Risk:** Cross-chain replay attacks
+**Mitigation:**
+
+```typescript
+// Always validate chain ID
+if (proof.challenge.domain.chainId !== expectedChainId) {
+  throw new Error('Chain ID mismatch');
+}
+```
+
+### 4. Debug Mode Exposure
+
+**Risk:** Sensitive data in logs
+**Mitigation:**
+
+```typescript
+// Production safety check
+if (process.env.NODE_ENV === 'production') {
+  if (config.debug) {
+    throw new Error('Debug mode cannot be enabled in production');
+  }
+}
+```
+
+### 5. Insufficient Access Control
+
+**Risk:** Unauthorized tool access
+**Mitigation:**
+
+- Proper token verification
+- Fail-closed design
+- Comprehensive error handling
+- No bypass mechanisms
+
+## Security Best Practices
+
+### Environment Variables
+
+```bash
+# .env.example (commit this)
+EVMAUTH_CONTRACT_ADDRESS=
+EVMAUTH_CHAIN_ID=
+EVMAUTH_RPC_URL=
+DEBUG=false
+
+# .env (never commit)
+EVMAUTH_CONTRACT_ADDRESS=0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96
+EVMAUTH_CHAIN_ID=1223953
+EVMAUTH_RPC_URL=https://rpc.testnet.radiustech.xyz
+DEBUG=false
+```
+
+### Error Handling
+
+```typescript
+// Don't expose internal errors
+try {
+  // Sensitive operation
+} catch (error) {
+  // Log internally
+  console.error('Internal error:', error);
+  
+  // Return safe error to user
+  throw new Error('Authentication failed');
+}
+```
+
+### Rate Limiting
+
+```typescript
+// Implement rate limiting for token checks
+const rateLimiter = new Map();
+const checkRateLimit = (wallet: string) => {
+  const key = wallet.toLowerCase();
+  const attempts = rateLimiter.get(key) || 0;
+  
+  if (attempts > 10) {
+    throw new Error('Rate limit exceeded');
+  }
+  
+  rateLimiter.set(key, attempts + 1);
+  setTimeout(() => rateLimiter.delete(key), 60000); // Reset after 1 minute
+};
+```
+
+### Secure Defaults
+
+```typescript
+const defaultConfig = {
+  debug: false,                    // Always false by default
+  cache: { ttl: 300 },             // Reasonable cache time
+  failClosed: true,                // Deny on any error
+  strictValidation: true           // Strict input validation
+};
+```
+
+## Audit Process
+
+1. **Code Review**
+   - Check for hardcoded secrets
+   - Verify input validation
+   - Review error handling
+   - Inspect debug mode usage
+
+2. **Configuration Audit**
+   - Validate environment setup
+   - Check production settings
+   - Verify contract addresses
+   - Test RPC endpoints
+
+3. **Runtime Security**
+   - Monitor for unusual patterns
+   - Track failed authentications
+   - Log security events
+   - Implement alerting
+
+4. **Dependencies**
+   - Audit npm packages
+   - Check for vulnerabilities
+   - Keep SDK updated
+   - Review security advisories
+
+Remember: Security is not optional - it's fundamental to Web3 applications!
diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/create-tool.md b/mcp-servers/token-gated-mcp-server/.claude/commands/create-tool.md
new file mode 100644
index 0000000..d83e631
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/commands/create-tool.md
@@ -0,0 +1,79 @@
+---
+allowed-tools: Write, Edit, Read
+description: Create a new token-gated tool with proper protection
+argument-hint: "<tool-name> <token-id> [tier]"
+---
+
+## Create Token-Gated Tool
+
+Create a new FastMCP tool with token protection using the Radius MCP SDK.
+
+Parameters: $ARGUMENTS
+
+## Tool Creation Steps
+
+1. **Parse Arguments**
+   - Extract tool name, token ID, and optional tier
+   - Validate token ID format
+   - Determine appropriate access pattern
+
+2. **Generate Tool Implementation**
+
+```typescript
+server.addTool({
+  name: '{tool_name}',
+  description: '{description} (requires token {token_id})',
+  parameters: z.object({
+    // Define your parameters here
+    input: z.string().describe('Input data'),
+    options: z.object({
+      format: z.enum(['json', 'text']).optional(),
+      verbose: z.boolean().optional()
+    }).optional(),
+    __evmauth: z.any().optional().describe('Authentication proof')
+  }),
+  handler: radius.protect({token_id}, async (args) => {
+    // Tool implementation
+    try {
+      // Process the input
+      const result = await process{ToolName}(args.input, args.options);
+      
+      // Return MCP-formatted response
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    } catch (error) {
+      throw new Error(`{tool_name} failed: ${error.message}`);
+    }
+  })
+});
+```
+
+3. **Add to Appropriate Tier**
+   - Map to correct token tier
+   - Update TOOL_REQUIREMENTS mapping
+   - Document access requirements
+
+4. **Create Test Case**
+   - Unit test for the tool
+   - Auth flow test
+   - Error handling test
+
+5. **Update Documentation**
+   - Add to tool registry
+   - Document parameters
+   - Include usage examples
+
+## Generate Complete Tool
+
+Based on the arguments provided, create:
+
+1. Tool implementation file
+2. Test file
+3. Documentation update
+4. Integration with existing server
+
+The tool should follow FastMCP best practices and properly integrate with the Radius MCP SDK for token protection.
diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/debug-proof.md b/mcp-servers/token-gated-mcp-server/.claude/commands/debug-proof.md
new file mode 100644
index 0000000..b953131
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/commands/debug-proof.md
@@ -0,0 +1,97 @@
+---
+allowed-tools: Read, Bash, Grep, WebFetch
+description: Debug proof verification issues and authentication errors
+---
+
+## Debug Proof Verification
+
+Analyze and debug authentication proof issues in your token-gated MCP server.
+
+## Debugging Process
+
+1. **Check Recent Errors**
+   - Search for EVMAUTH errors: !`grep -r "EVMAUTH" . --include="*.log" --include="*.ts" | tail -20`
+   - Find proof-related issues: !`grep -r "proof\|PROOF" . --include="*.log" | tail -20`
+
+2. **Validate Configuration**
+
+   ```bash
+   # Check all required environment variables
+   !echo "=== Token Gate Configuration ==="
+   !echo "Contract Address: ${EVMAUTH_CONTRACT_ADDRESS:-NOT SET}"
+   !echo "Chain ID: ${EVMAUTH_CHAIN_ID:-NOT SET}"
+   !echo "RPC URL: ${EVMAUTH_RPC_URL:-NOT SET}"
+   !echo "Token ID: ${EVMAUTH_TOKEN_ID:-NOT SET}"
+   !echo "Debug Mode: ${DEBUG:-false}"
+   !echo "Environment: ${NODE_ENV:-development}"
+   ```
+
+3. **Test RPC Connection**
+
+   ```bash
+   # Verify RPC endpoint is accessible
+   !curl -s -X POST ${EVMAUTH_RPC_URL:-https://rpc.testnet.radiustech.xyz} \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' | jq '.'
+   ```
+
+4. **Analyze Proof Structure**
+   Check for common proof issues:
+   - Missing __evmauth parameter
+   - Expired timestamp (> 30 seconds)
+   - Invalid signature format (not 0x + 130 hex chars)
+   - Chain ID mismatch
+   - Contract address mismatch
+   - Invalid nonce format
+
+5. **Debug Token Verification**
+   - Check if RPC calls are succeeding
+   - Verify token balance queries
+   - Test cache behavior
+   - Validate multi-token logic
+
+## Common Issues and Solutions
+
+### EVMAUTH_PROOF_MISSING
+
+- **Cause**: No __evmauth in request
+- **Fix**: Ensure parameter is included in tool schema
+
+### PROOF_EXPIRED
+
+- **Cause**: Proof older than 30 seconds
+- **Fix**: Request fresh proof from Radius MCP Server
+
+### CHAIN_MISMATCH
+
+- **Cause**: Proof for different chain
+- **Fix**: Ensure SDK and proof use same chain ID (1223953 for testnet)
+
+### SIGNER_MISMATCH
+
+- **Cause**: Signature doesn't match wallet
+- **Fix**: Verify signature recovery process
+
+### PAYMENT_REQUIRED
+
+- **Cause**: User lacks required tokens
+- **Fix**: Use authenticate_and_purchase to obtain tokens
+
+## Generate Debug Report
+
+Create a comprehensive debug report including:
+
+1. Current configuration status
+2. Recent error patterns
+3. Proof validation results
+4. Token verification status
+5. Recommended fixes
+
+Enable debug mode temporarily if needed:
+
+```typescript
+const radius = new RadiusMcpSdk({
+  contractAddress: process.env.EVMAUTH_CONTRACT_ADDRESS,
+  debug: true // Temporary for debugging
+});
+```
diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/deploy-local.md b/mcp-servers/token-gated-mcp-server/.claude/commands/deploy-local.md
new file mode 100644
index 0000000..f865017
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/commands/deploy-local.md
@@ -0,0 +1,93 @@
+---
+allowed-tools: Bash, Read, Write
+description: Deploy token-gated MCP server locally with ngrok for testing
+---
+
+## Deploy Locally with ngrok
+
+Set up and deploy your token-gated MCP server locally with ngrok for testing with claude.ai.
+
+## Deployment Steps
+
+1. **Pre-deployment Checks**
+   - Verify all dependencies installed: !`npm list fastmcp @radiustechsystems/mcp-sdk zod 2>/dev/null | grep -E "fastmcp|radius|zod"`
+   - Check TypeScript compilation: !`npx tsc --noEmit`
+   - Validate environment configuration
+
+2. **Start the MCP Server**
+
+   ```bash
+   # Start server in development mode
+   npm run dev
+   ```
+
+   Server should start on port 3000 (or configured PORT)
+
+3. **Set Up ngrok Tunnel**
+
+   ```bash
+   # Install ngrok if needed
+   # brew install ngrok (macOS)
+   # or download from https://ngrok.com
+   
+   # Start ngrok tunnel
+   ngrok http 3000
+   ```
+
+4. **Configure claude.ai**
+   - Copy the HTTPS URL from ngrok (e.g., <https://abc123.ngrok.io>)
+   - In claude.ai:
+     1. Click the 🔌 connection icon
+     2. Add MCP server
+     3. Enter URL: `https://abc123.ngrok.io/mcp`
+     4. Test connection
+
+5. **Verify Token Protection**
+   - Try calling a protected tool
+   - Should receive EVMAUTH_PROOF_MISSING error
+   - Error should guide to authenticate_and_purchase
+
+## Testing Checklist
+
+- [ ] Server starts without errors
+- [ ] ngrok tunnel established
+- [ ] claude.ai can connect
+- [ ] Tools appear in claude.ai
+- [ ] Token protection working
+- [ ] Error messages are helpful
+- [ ] Authentication flow completes
+
+## Troubleshooting
+
+### Server Won't Start
+
+- Check port not already in use: !`lsof -i :3000`
+- Verify dependencies installed
+- Check for TypeScript errors
+
+### ngrok Issues
+
+- Ensure ngrok installed and authenticated
+- Check firewall settings
+- Try different port if 3000 blocked
+
+### claude.ai Connection Failed
+
+- Verify URL includes `/mcp` endpoint
+- Check CORS settings in server
+- Ensure server is running
+
+### Authentication Errors
+
+- Verify contract address configured
+- Check chain ID matches (1223953)
+- Ensure RPC URL accessible
+
+## Generate Deployment Summary
+
+Create a summary including:
+
+1. Server URL for claude.ai
+2. Available tools and their token requirements
+3. Test commands to verify functionality
+4. Any warnings or issues detected
diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/setup-token-gate.md b/mcp-servers/token-gated-mcp-server/.claude/commands/setup-token-gate.md
new file mode 100644
index 0000000..48e747f
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/commands/setup-token-gate.md
@@ -0,0 +1,80 @@
+---
+allowed-tools: "Write, Edit, Bash(npm install*), Bash(npm init*), Read"
+description: Set up a complete token-gated MCP server with FastMCP and Radius SDK
+argument-hint: "[basic|full|testnet]"
+---
+
+## Setup Token-Gated MCP Server
+
+Create a complete token-gated MCP server project with the specified configuration level:
+
+- **basic**: Minimal setup with one protected tool
+- **full**: Complete setup with multiple tiers and examples
+- **testnet**: Configured for Radius Testnet deployment
+
+Configuration: $ARGUMENTS
+
+## Tasks
+
+1. **Initialize Project**
+   - Create package.json with required dependencies
+   - Set up TypeScript configuration
+   - Create directory structure
+
+2. **Install Dependencies**
+
+   ```json
+   {
+     "dependencies": {
+       "fastmcp": "^3.0.0",
+       "@radiustechsystems/mcp-sdk": "^1.0.0",
+       "zod": "^3.22.0",
+       "viem": "^2.31.0"
+     },
+     "devDependencies": {
+       "@types/node": "^20.0.0",
+       "tsx": "^4.0.0",
+       "typescript": "^5.0.0",
+       "prettier": "^3.0.0"
+     }
+   }
+   ```
+
+3. **Create Server Implementation**
+   - Main server file with token protection
+   - Example tools with different token requirements
+   - Proper error handling and responses
+
+4. **Environment Configuration**
+   - Create .env.example with required variables
+   - Set up for Radius Testnet (Chain ID: 1223953)
+   - Configure debug settings
+
+5. **Create Helper Scripts**
+   - Development script with hot reload
+   - Build script for production
+   - Test script for auth flow validation
+
+6. **Documentation**
+   - README with setup instructions
+   - Token tier documentation
+   - Testing guide with ngrok
+
+## Implementation Structure
+
+```text
+project/
+├── src/
+│   ├── index.ts          # Main server file
+│   ├── tools/            # Tool implementations
+│   ├── config/           # Configuration
+│   └── types/            # Type definitions
+├── .env.example          # Environment template
+├── package.json          # Dependencies
+├── tsconfig.json         # TypeScript config
+├── README.md             # Documentation
+└── .claude/              # Claude Code config
+    └── CLAUDE.md         # Project context
+```
+
+Based on the configuration level ($ARGUMENTS), create the appropriate setup with working examples and clear documentation.
diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/test-auth.md b/mcp-servers/token-gated-mcp-server/.claude/commands/test-auth.md
new file mode 100644
index 0000000..d9336a9
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/commands/test-auth.md
@@ -0,0 +1,68 @@
+---
+allowed-tools: Bash, Read, Write, TodoWrite
+description: Test the complete authentication flow end-to-end
+argument-hint: "[tool-name] [token-id]"
+---
+
+## Test Authentication Flow
+
+Test the complete token-gated authentication flow for the specified tool.
+
+Tool: $ARGUMENTS
+
+## Testing Steps
+
+1. **Check Current Configuration**
+   - Verify environment variables: !`echo "Contract: $EVMAUTH_CONTRACT_ADDRESS, Chain: $EVMAUTH_CHAIN_ID"`
+   - Check RPC connection: !`curl -s -X POST $EVMAUTH_RPC_URL -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' | jq -r '.result'`
+
+2. **Start MCP Server**
+   - Run the server if not already running
+   - Note the port and endpoint
+
+3. **Simulate Tool Call Without Auth**
+   - Call the protected tool without __evmauth
+   - Verify EVMAUTH_PROOF_MISSING error
+   - Check error includes requiredTokens
+
+4. **Simulate Authentication**
+   - Mock authenticate_and_purchase response
+   - Generate sample proof structure
+   - Verify proof format is correct
+
+5. **Test With Valid Proof**
+   - Call tool with __evmauth parameter
+   - Verify successful execution or PAYMENT_REQUIRED
+
+6. **Test Error Scenarios**
+   - Expired proof (> 30 seconds old)
+   - Wrong chain ID
+   - Invalid signature format
+   - Missing required fields
+
+## Create Test Script
+
+Generate a test script that validates:
+
+- Token protection is properly configured
+- Error messages are AI-friendly
+- Authentication flow works end-to-end
+- Caching behaves correctly
+
+## Expected Results
+
+✅ **Success Criteria:**
+
+- Tool rejects calls without auth
+- Error messages guide to authenticate_and_purchase
+- Valid proofs are accepted
+- Token ownership is properly verified
+
+❌ **Common Failures:**
+
+- Chain ID mismatch
+- Contract address not configured
+- RPC connection issues
+- Debug mode enabled in production
+
+Generate comprehensive test results and recommendations.
diff --git a/mcp-servers/token-gated-mcp-server/.claude/commands/validate-config.md b/mcp-servers/token-gated-mcp-server/.claude/commands/validate-config.md
new file mode 100644
index 0000000..e9208b1
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/commands/validate-config.md
@@ -0,0 +1,113 @@
+---
+allowed-tools: Read, Bash, Grep
+description: Validate token-gating configuration and environment setup
+---
+
+## Validate Token-Gating Configuration
+
+Comprehensive validation of your token-gated MCP server configuration.
+
+## Validation Checks
+
+### 1. Environment Variables
+
+```bash
+# Check required variables
+!echo "=== Environment Configuration ==="
+!echo "Contract Address: ${EVMAUTH_CONTRACT_ADDRESS:-❌ NOT SET}"
+!echo "Chain ID: ${EVMAUTH_CHAIN_ID:-❌ NOT SET}"
+!echo "RPC URL: ${EVMAUTH_RPC_URL:-❌ NOT SET}"
+!echo "Token ID: ${EVMAUTH_TOKEN_ID:-❌ NOT SET}"
+!echo "Debug Mode: ${DEBUG:-✅ false (good for production)}"
+!echo "Node Environment: ${NODE_ENV:-⚠️ NOT SET}"
+```
+
+### 2. Contract Address Validation
+
+- Check format: 0x followed by 40 hexadecimal characters
+- Verify it's a valid Ethereum address
+- For testnet: Should be `0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96`
+
+### 3. Chain ID Validation
+
+- Should be numeric
+- For Radius Testnet: 1223953
+- Must match the network your contract is deployed on
+
+### 4. RPC Connection Test
+
+```bash
+# Test RPC endpoint
+!curl -s -X POST ${EVMAUTH_RPC_URL:-https://rpc.testnet.radiustech.xyz} \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' | \
+  jq -r 'if .result then "✅ RPC Connected - Chain: \(.result)" else "❌ RPC Connection Failed" end'
+```
+
+### 5. Dependencies Check
+
+```bash
+# Verify required packages
+!echo "=== Required Dependencies ==="
+!npm list fastmcp 2>/dev/null | grep fastmcp || echo "❌ fastmcp not installed"
+!npm list @radiustechsystems/mcp-sdk 2>/dev/null | grep radius || echo "❌ Radius SDK not installed"
+!npm list zod 2>/dev/null | grep zod || echo "❌ zod not installed"
+!npm list viem 2>/dev/null | grep viem || echo "❌ viem not installed"
+```
+
+### 6. TypeScript Configuration
+
+```bash
+# Check TypeScript setup
+![ -f "tsconfig.json" ] && echo "✅ tsconfig.json exists" || echo "❌ tsconfig.json missing"
+!npx tsc --version 2>/dev/null || echo "❌ TypeScript not installed"
+```
+
+### 7. Server File Analysis
+
+- Check for RadiusMcpSdk initialization
+- Verify radius.protect() usage
+- Ensure __evmauth parameter in schemas
+- Validate error handling
+
+### 8. Security Checks
+
+```bash
+# Security validation
+!echo "=== Security Checks ==="
+!grep -r "debug.*true" --include="*.ts" --include="*.js" . 2>/dev/null && echo "⚠️ Debug mode enabled in code" || echo "✅ No hardcoded debug mode"
+!grep -r "0x[a-fA-F0-9]\{64\}" --include="*.ts" --include="*.js" . 2>/dev/null && echo "⚠️ Possible private key in code" || echo "✅ No private keys detected"
+![ -f ".env" ] && [ ! -f ".gitignore" ] && echo "⚠️ .env exists but no .gitignore" || echo "✅ Environment files protected"
+```
+
+## Validation Report
+
+Generate a comprehensive report with:
+
+### ✅ Passed Checks
+
+- List all successful validations
+
+### ⚠️ Warnings
+
+- Non-critical issues to address
+
+### ❌ Failed Checks
+
+- Critical issues that must be fixed
+
+### 📋 Recommendations
+
+1. Configuration improvements
+2. Security enhancements
+3. Performance optimizations
+4. Best practices to follow
+
+## Next Steps
+
+Based on validation results, provide:
+
+1. Immediate fixes required
+2. Configuration commands to run
+3. Files to update
+4. Testing recommendations
diff --git a/mcp-servers/token-gated-mcp-server/.claude/hooks/format-typescript.sh b/mcp-servers/token-gated-mcp-server/.claude/hooks/format-typescript.sh
new file mode 100755
index 0000000..6e50d6b
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/hooks/format-typescript.sh
@@ -0,0 +1,54 @@
+#!/bin/bash
+
+# Hook script to format TypeScript files after editing
+# Used in PostToolUse hooks for Edit/Write operations
+
+# Parse the input JSON
+file_path=$(echo "$CLAUDE_HOOK_DATA" | jq -r '.tool_input.file_path // empty')
+
+# Exit if no file path
+if [ -z "$file_path" ]; then
+  exit 0
+fi
+
+# Only process TypeScript/JavaScript files
+if [[ "$file_path" =~ \.(ts|tsx|js|jsx)$ ]]; then
+  # Check if prettier is available
+  if command -v npx &> /dev/null && [ -f "package.json" ]; then
+    # Check if prettier is installed
+    if npm list prettier --depth=0 &>/dev/null || npm list -g prettier --depth=0 &>/dev/null; then
+      echo "🎨 Formatting $file_path with Prettier..."
+      npx prettier --write "$file_path" 2>/dev/null
+      
+      if [ $? -eq 0 ]; then
+        echo "✅ Formatted successfully"
+      else
+        echo "⚠️  Prettier formatting failed (non-critical)"
+      fi
+    fi
+  fi
+  
+  # Additional validation for server files
+  if [[ "$file_path" =~ (server|index)\.(ts|js)$ ]]; then
+    # Check for token protection
+    if grep -q 'radius.protect' "$file_path" 2>/dev/null; then
+      echo "✅ Token protection detected in $file_path"
+      
+      # Count protected tools
+      tool_count=$(grep -c 'radius.protect' "$file_path" 2>/dev/null)
+      echo "   Found $tool_count protected tool(s)"
+    fi
+    
+    # Check for proper FastMCP setup
+    if grep -q 'FastMCP' "$file_path" 2>/dev/null; then
+      echo "✅ FastMCP server configured"
+    fi
+    
+    # Warn about missing error handling
+    if ! grep -q 'try\|catch\|throw' "$file_path" 2>/dev/null; then
+      echo "⚠️  Consider adding error handling to $file_path"
+    fi
+  fi
+fi
+
+exit 0
\ No newline at end of file
diff --git a/mcp-servers/token-gated-mcp-server/.claude/hooks/log-mcp-commands.sh b/mcp-servers/token-gated-mcp-server/.claude/hooks/log-mcp-commands.sh
new file mode 100755
index 0000000..9b3d09e
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/hooks/log-mcp-commands.sh
@@ -0,0 +1,83 @@
+#!/bin/bash
+
+# Hook script to log MCP-related commands for debugging
+# Used in PreToolUse hooks for Bash tool
+
+# Parse the command from input
+command=$(echo "$CLAUDE_HOOK_DATA" | jq -r '.tool_input.command // empty')
+description=$(echo "$CLAUDE_HOOK_DATA" | jq -r '.tool_input.description // "No description"')
+
+# Exit if no command
+if [ -z "$command" ]; then
+  exit 0
+fi
+
+# Create log directory if it doesn't exist
+LOG_DIR="$HOME/.claude/logs"
+mkdir -p "$LOG_DIR"
+
+# Log file with date
+LOG_FILE="$LOG_DIR/token-gate-$(date +%Y%m%d).log"
+
+# Timestamp for log entry
+timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+
+# Log FastMCP commands
+if [[ "$command" == *"fastmcp"* ]]; then
+  echo "[$timestamp] FastMCP: $command - $description" >> "$LOG_FILE"
+  echo "🚀 Running FastMCP command..."
+  
+  # Provide helpful hints
+  if [[ "$command" == *"dev"* ]]; then
+    echo "💡 Tip: Use 'npx fastmcp inspect' for visual debugging"
+  fi
+fi
+
+# Log ngrok commands
+if [[ "$command" == *"ngrok"* ]]; then
+  echo "[$timestamp] ngrok: $command" >> "$LOG_FILE"
+  echo "🌐 Setting up ngrok tunnel..."
+  echo "💡 Remember to use the HTTPS URL with /mcp endpoint in claude.ai"
+fi
+
+# Log npm/node commands related to MCP
+if [[ "$command" == *"npm"* ]] || [[ "$command" == *"node"* ]] || [[ "$command" == *"tsx"* ]]; then
+  if [[ "$command" == *"radius"* ]] || [[ "$command" == *"mcp"* ]] || [[ "$command" == *"server"* ]]; then
+    echo "[$timestamp] MCP Server: $command" >> "$LOG_FILE"
+  fi
+fi
+
+# Log token configuration checks
+if [[ "$command" == *"EVMAUTH"* ]] || [[ "$command" == *"echo"* ]]; then
+  if [[ "$command" == *"CONTRACT"* ]] || [[ "$command" == *"CHAIN"* ]] || [[ "$command" == *"TOKEN"* ]]; then
+    echo "[$timestamp] Config Check: $command" >> "$LOG_FILE"
+    echo "🔍 Checking token configuration..."
+  fi
+fi
+
+# Log RPC tests
+if [[ "$command" == *"curl"* ]] && [[ "$command" == *"rpc"* ]]; then
+  echo "[$timestamp] RPC Test: $command" >> "$LOG_FILE"
+  echo "🔗 Testing RPC connection..."
+fi
+
+# Security check - warn about potentially dangerous commands
+if [[ "$command" == *"rm -rf"* ]] || [[ "$command" == *"sudo rm"* ]]; then
+  echo "⚠️  DANGER: Destructive command detected!"
+  echo "[$timestamp] BLOCKED: $command" >> "$LOG_FILE"
+  exit 2  # Block the command
+fi
+
+# Warn about npm publish in development
+if [[ "$command" == *"npm publish"* ]]; then
+  echo "⚠️  WARNING: About to publish to npm registry!"
+  echo "   Ensure version is updated and changes are committed"
+  echo "[$timestamp] NPM Publish: $command" >> "$LOG_FILE"
+  
+  if [ "$NODE_ENV" != "production" ]; then
+    echo "❌ Blocking npm publish in non-production environment"
+    exit 2
+  fi
+fi
+
+exit 0
\ No newline at end of file
diff --git a/mcp-servers/token-gated-mcp-server/.claude/hooks/production-safety.sh b/mcp-servers/token-gated-mcp-server/.claude/hooks/production-safety.sh
new file mode 100755
index 0000000..34ed5fa
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/hooks/production-safety.sh
@@ -0,0 +1,92 @@
+#!/bin/bash
+
+# Hook script for production safety checks
+# Used in Stop hooks to provide reminders and warnings
+
+# Check environment
+env_mode="${NODE_ENV:-development}"
+debug_mode="${DEBUG:-false}"
+chain_id="${EVMAUTH_CHAIN_ID:-not_set}"
+
+# Production safety checks
+if [ "$env_mode" = "production" ]; then
+  echo "🚨 PRODUCTION ENVIRONMENT DETECTED"
+  
+  # Check debug mode
+  if [ "$debug_mode" = "true" ]; then
+    echo "❌ CRITICAL: Debug mode is enabled in production!"
+    echo "   Set DEBUG=false immediately"
+  fi
+  
+  # Verify mainnet configuration
+  if [ "$chain_id" = "1223953" ]; then
+    echo "⚠️  Using Radius Testnet in production environment"
+    echo "   Switch to mainnet configuration if deploying to production"
+  fi
+  
+  # Check for .env file
+  if [ -f ".env" ] && [ ! -f ".env.production" ]; then
+    echo "⚠️  Using .env file - ensure production values are set"
+  fi
+else
+  # Development environment reminders
+  echo "ℹ️  Environment: $env_mode"
+  
+  if [ "$debug_mode" = "true" ]; then
+    echo "🔍 Debug mode enabled (OK for development)"
+  fi
+  
+  if [ "$chain_id" = "1223953" ]; then
+    echo "🔗 Using Radius Testnet (Chain ID: 1223953)"
+  fi
+fi
+
+# Check for uncommitted changes
+if command -v git &> /dev/null; then
+  if [ -d ".git" ]; then
+    uncommitted=$(git status --porcelain 2>/dev/null | wc -l)
+    if [ "$uncommitted" -gt 0 ]; then
+      echo "📝 You have $uncommitted uncommitted change(s)"
+      
+      # Check for changes to sensitive files
+      if git status --porcelain 2>/dev/null | grep -qE '\.env|private|secret|key'; then
+        echo "⚠️  Sensitive files may have been modified - review before committing"
+      fi
+    fi
+  fi
+fi
+
+# Token configuration summary
+if [ "$EVMAUTH_CONTRACT_ADDRESS" ]; then
+  echo "🔐 Token Gate Active:"
+  echo "   Contract: ${EVMAUTH_CONTRACT_ADDRESS:0:10}...${EVMAUTH_CONTRACT_ADDRESS: -8}"
+  echo "   Token ID: ${EVMAUTH_TOKEN_ID:-1}"
+fi
+
+# Server status check
+if lsof -i :3000 &>/dev/null; then
+  echo "✅ MCP Server running on port 3000"
+elif lsof -i :${PORT:-3000} &>/dev/null; then
+  echo "✅ MCP Server running on port ${PORT}"
+fi
+
+# Final reminders based on recent activity
+if [ -f "$HOME/.claude/logs/token-gate-$(date +%Y%m%d).log" ]; then
+  recent_fastmcp=$(grep -c "FastMCP" "$HOME/.claude/logs/token-gate-$(date +%Y%m%d).log" 2>/dev/null || echo 0)
+  recent_ngrok=$(grep -c "ngrok" "$HOME/.claude/logs/token-gate-$(date +%Y%m%d).log" 2>/dev/null || echo 0)
+  
+  if [ "$recent_fastmcp" -gt 0 ] || [ "$recent_ngrok" -gt 0 ]; then
+    echo "📊 Today's activity: $recent_fastmcp FastMCP commands, $recent_ngrok ngrok sessions"
+  fi
+fi
+
+# Success message if everything looks good
+all_good=true
+[ "$env_mode" = "production" ] && [ "$debug_mode" = "true" ] && all_good=false
+[ "$uncommitted" -gt 0 ] && all_good=false
+
+if [ "$all_good" = true ] && [ "$env_mode" != "production" ]; then
+  echo "✨ Development environment properly configured!"
+fi
+
+exit 0
\ No newline at end of file
diff --git a/mcp-servers/token-gated-mcp-server/.claude/hooks/validate-token-config.sh b/mcp-servers/token-gated-mcp-server/.claude/hooks/validate-token-config.sh
new file mode 100755
index 0000000..f4c58bc
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/hooks/validate-token-config.sh
@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# Hook script to validate token configuration in TypeScript files
+# Used in PreToolUse hooks for Edit/Write operations
+
+# Parse the input JSON from CLAUDE_HOOK_DATA
+file_path=$(echo "$CLAUDE_HOOK_DATA" | jq -r '.tool_input.file_path // empty')
+content=$(echo "$CLAUDE_HOOK_DATA" | jq -r '.tool_input.content // .tool_input.new_string // ""')
+
+# Only process TypeScript files
+if [[ ! "$file_path" =~ \.(ts|tsx)$ ]]; then
+  exit 0
+fi
+
+# Check if content contains token configuration
+if echo "$content" | grep -qE 'contractAddress|chainId|tokenId|RadiusMcpSdk'; then
+  echo "🔐 Token configuration detected in $file_path"
+  
+  # Validate contract address format (0x + 40 hex chars)
+  if echo "$content" | grep -qE '0x[a-fA-F0-9]{40}'; then
+    echo "✅ Valid contract address format"
+  else
+    if echo "$content" | grep -qE 'contractAddress.*0x'; then
+      echo "⚠️  Warning: Invalid contract address format detected"
+      echo "   Contract addresses must be 0x followed by 40 hexadecimal characters"
+    fi
+  fi
+  
+  # Check for Radius Testnet configuration
+  if echo "$content" | grep -q '1223953'; then
+    echo "✅ Configured for Radius Testnet (Chain ID: 1223953)"
+  fi
+  
+  # Warn about debug mode
+  if echo "$content" | grep -qE 'debug:\s*true'; then
+    if [ "$NODE_ENV" = "production" ]; then
+      echo "❌ ERROR: Debug mode cannot be enabled in production!"
+      echo "   Set debug: false or use process.env.NODE_ENV check"
+      exit 2  # Block the operation
+    else
+      echo "⚠️  Warning: Debug mode is enabled - disable before production"
+    fi
+  fi
+  
+  # Check for hardcoded private keys (security check)
+  if echo "$content" | grep -qE '0x[a-fA-F0-9]{64}'; then
+    echo "🚨 SECURITY WARNING: Possible private key detected!"
+    echo "   Never commit private keys to source control"
+    echo "   Use environment variables instead"
+    # exit 2  # Uncomment to block operation if private key detected
+  fi
+  
+  # Validate token protection pattern
+  if echo "$content" | grep -q 'radius.protect'; then
+    echo "✅ Token protection implemented"
+    
+    # Check if __evmauth is in parameters
+    if echo "$content" | grep -q '__evmauth.*z\.any'; then
+      echo "✅ __evmauth parameter included in schema"
+    else
+      echo "⚠️  Reminder: Include __evmauth in tool parameters:"
+      echo "   __evmauth: z.any().optional()"
+    fi
+  fi
+fi
+
+exit 0
\ No newline at end of file
diff --git a/mcp-servers/token-gated-mcp-server/.claude/settings.json b/mcp-servers/token-gated-mcp-server/.claude/settings.json
new file mode 100644
index 0000000..b14848c
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/.claude/settings.json
@@ -0,0 +1,119 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Grep",
+      "Glob",
+      "LS",
+      "NotebookEdit",
+      "NotebookRead",
+      "TodoWrite",
+      "WebSearch",
+      "WebFetch",
+      "Bash(npm run dev*)",
+      "Bash(npm run build*)",
+      "Bash(npm run test*)",
+      "Bash(npm run lint*)",
+      "Bash(npm run typecheck*)",
+      "Bash(npm install*)",
+      "Bash(npm ci*)",
+      "Bash(npx tsx*)",
+      "Bash(npx fastmcp*)",
+      "Bash(ngrok http*)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git add*)",
+      "Bash(git commit*)",
+      "Bash(curl https://rpc.testnet.radiustech.xyz*)",
+      "Bash(echo $EVMAUTH*)",
+      "Bash(docker build*)",
+      "Bash(docker run*)"
+    ],
+    "deny": [
+      "Read(**/*private*key*)",
+      "Read(**/*.env.production)",
+      "Read(**/*secret*)",
+      "Write(**/*private*key*)",
+      "Write(**/*.env.production)",
+      "Write(**/*secret*)",
+      "Bash(rm -rf*)",
+      "Bash(npm publish*)",
+      "Bash(curl -X POST*)",
+      "Bash(curl -X PUT*)",
+      "Bash(curl -X DELETE*)"
+    ],
+    "additionalDirectories": []
+  },
+  "env": {
+    "EVMAUTH_CONTRACT_ADDRESS": "0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96",
+    "EVMAUTH_CHAIN_ID": "1223953",
+    "EVMAUTH_RPC_URL": "https://rpc.testnet.radiustech.xyz",
+    "EVMAUTH_TOKEN_ID": "1",
+    "NODE_ENV": "development",
+    "DEBUG": "false",
+    "RADIUS_TESTNET": "true"
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "#!/bin/bash\nfile_path=$(echo \"$CLAUDE_HOOK_DATA\" | jq -r '.tool_input.file_path // empty')\nif [[ \"$file_path\" == *.ts || \"$file_path\" == *.tsx ]]; then\n  # Check if we're writing token configuration\n  if echo \"$CLAUDE_HOOK_DATA\" | jq -r '.tool_input.content // .tool_input.new_string // \"\"' | grep -q 'contractAddress\\|chainId\\|tokenId'; then\n    echo \"🔐 Token configuration detected - validating...\"\n    # Validate contract address format\n    if echo \"$CLAUDE_HOOK_DATA\" | grep -q '0x[a-fA-F0-9]\\{40\\}'; then\n      echo \"✅ Valid contract address format\"\n    else\n      echo \"⚠️  Warning: Invalid contract address format detected\"\n    fi\n  fi\nfi"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "#!/bin/bash\ncommand=$(echo \"$CLAUDE_HOOK_DATA\" | jq -r '.tool_input.command')\n# Log FastMCP and ngrok commands for debugging\nif [[ \"$command\" == *\"fastmcp\"* ]] || [[ \"$command\" == *\"ngrok\"* ]]; then\n  echo \"[Token-Gate Debug] Running: $command\" >> ~/.claude/token-gate-debug.log\nfi"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "#!/bin/bash\nfile_path=$(echo \"$CLAUDE_HOOK_DATA\" | jq -r '.tool_input.file_path // empty')\n# Auto-format TypeScript files\nif [[ \"$file_path\" == *.ts || \"$file_path\" == *.tsx ]]; then\n  if command -v npx &> /dev/null && [ -f \"package.json\" ]; then\n    npx prettier --write \"$file_path\" 2>/dev/null || true\n  fi\nfi\n# Validate token-gating implementation\nif [[ \"$file_path\" == *server.ts* ]] || [[ \"$file_path\" == *index.ts* ]]; then\n  if grep -q 'radius.protect' \"$file_path\"; then\n    echo \"✅ Token protection detected in $file_path\"\n  fi\nfi"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "#!/bin/bash\n# Check if debug mode is still enabled\nif [ \"$DEBUG\" = \"true\" ]; then\n  echo \"⚠️  Reminder: Debug mode is enabled. Disable before production deployment!\"\nfi\n# Check if using testnet\nif [ \"$RADIUS_TESTNET\" = \"true\" ]; then\n  echo \"ℹ️  Using Radius Testnet (Chain ID: 1223953)\"\nfi"
+          }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "#!/bin/bash\necho \"🔐 Token-Gated MCP | Chain: ${EVMAUTH_CHAIN_ID:-1223953} | Token: ${EVMAUTH_TOKEN_ID:-1} | ${NODE_ENV:-dev}\""
+  },
+  "model": "claude-3-5-sonnet-20241022",
+  "includeCoAuthoredBy": true,
+  "cleanupPeriodDays": 30,
+  "_metadata": {
+    "name": "Token-Gated MCP Server",
+    "version": "1.0.0",
+    "category": "mcp-server",
+    "generated": "2025-08-20T13:36:56.498Z",
+    "generator": "manual",
+    "note": "Official Claude Code configuration"
+  }
+}
diff --git a/mcp-servers/token-gated-mcp-server/CLAUDE.md b/mcp-servers/token-gated-mcp-server/CLAUDE.md
new file mode 100644
index 0000000..3eb33c6
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/CLAUDE.md
@@ -0,0 +1,445 @@
+# Token-Gated MCP Server Development Assistant
+
+You are an expert in building token-gated MCP (Model Context Protocol) servers using FastMCP and the Radius MCP SDK. You have deep expertise in Web3 authentication, ERC-1155 tokens, and creating secure, decentralized access control systems for AI tools.
+
+## Project Context
+
+This is a Token-Gated MCP Server project focused on:
+
+- **Token-based access control** using ERC-1155 tokens on Radius Network
+- **FastMCP framework** for rapid MCP server development
+- **Radius MCP SDK** for cryptographic proof verification
+- **EIP-712 signatures** for secure authentication
+- **Decentralized AI tool marketplace** with token economics
+
+## MCP Configuration
+
+To use this token-gated server with Claude Code:
+
+```bash
+# Add HTTP streaming server (for claude.ai)
+claude mcp add --transport http token-gated-server http://localhost:3000/mcp
+
+# Add SSE server (alternative transport)  
+claude mcp add --transport sse token-gated-server http://localhost:3000/sse
+
+# Check authentication status
+claude mcp get token-gated-server
+
+# Use /mcp command in Claude Code for OAuth authentication
+> /mcp
+```
+
+## Technology Stack
+
+### Core Technologies
+
+- **TypeScript** - Type-safe development
+- **Node.js** - Runtime environment
+- **FastMCP** - MCP server framework following official protocol
+- **Radius MCP SDK** - Token-gating authorization
+- **Radius Testnet** - Blockchain network (Chain ID: 1223953)
+- **MCP Protocol** - Following @modelcontextprotocol/sdk standards
+
+### Web3 Stack
+
+- **Viem** - Ethereum interactions
+- **EIP-712** - Typed structured data signing
+- **ERC-1155** - Multi-token standard
+- **Radius MCP Server** - Authentication & wallet management
+
+### FastMCP Features
+
+- **Simple tool/resource/prompt definition**
+- **HTTP streaming transport**
+- **Session management**
+- **Error handling**
+- **Progress notifications**
+- **TypeScript support**
+
+## Architecture Patterns
+
+### Token-Gating Implementation
+
+```typescript
+import { FastMCP } from 'fastmcp';
+import { RadiusMcpSdk } from '@radiustechsystems/mcp-sdk';
+
+// Initialize SDK - defaults to Radius Testnet
+const radius = new RadiusMcpSdk({
+  contractAddress: '0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96'
+});
+
+const server = new FastMCP({
+  name: 'Token-Gated Tools',
+  version: '1.0.0'
+});
+
+// Token-gate any tool with 3 lines
+server.addTool({
+  name: 'premium_tool',
+  description: 'Premium feature (requires token)',
+  parameters: z.object({ query: z.string() }),
+  handler: radius.protect(101, async (args) => {
+    // Tool logic only runs if user owns token 101
+    return processPremiumQuery(args.query);
+  })
+});
+```
+
+### Authentication Flow
+
+```typescript
+// 1. Client calls protected tool without auth
+await tool({ query: "data" });
+// → EVMAUTH_PROOF_MISSING error
+
+// 2. Client authenticates via Radius MCP Server
+const { proof } = await authenticate_and_purchase({ 
+  tokenIds: [101],
+  targetTool: 'premium_tool'
+});
+
+// 3. Client retries with proof
+await tool({ 
+  query: "data",
+  __evmauth: proof  // Special namespace
+});
+// → Success!
+```
+
+## Critical Implementation Details
+
+### 1. Multi-Token Protection
+
+```typescript
+// ANY token logic (user needs at least one)
+handler: radius.protect([101, 102, 103], async (args) => {
+  // User has token 101 OR 102 OR 103
+  return processRequest(args);
+})
+
+// Tiered access patterns
+const TOKENS = {
+  BASIC: 101,
+  PREMIUM: 102,
+  ENTERPRISE: [201, 202, 203]  // ANY of these
+};
+```
+
+### 2. Error Response Structure
+
+```typescript
+// SDK provides AI-friendly error responses
+{
+  error: {
+    code: "EVMAUTH_PROOF_MISSING",
+    message: "Authentication required",
+    details: {
+      requiredTokens: [101],
+      contractAddress: "0x...",
+      chainId: 1223953
+    },
+    claude_action: {
+      description: "Authenticate and purchase tokens",
+      steps: [...],
+      tool: {
+        server: "radius-mcp-server",
+        name: "authenticate_and_purchase",
+        arguments: { tokenIds: [101] }
+      }
+    }
+  }
+}
+```
+
+### 3. The __evmauth Namespace
+
+```typescript
+// IMPORTANT: __evmauth is ALWAYS accepted
+// Even if not in tool schema!
+const result = await any_protected_tool({
+  normalParam: "value",
+  __evmauth: proof  // Always works!
+});
+
+// SDK strips auth before handler sees it
+handler: radius.protect(101, async (args) => {
+  // args has normalParam but NOT __evmauth
+  console.log(args); // { normalParam: "value" }
+});
+```
+
+### 4. Security Model
+
+- **EIP-712 Signature Verification** - Cryptographic proof validation
+- **Chain ID Validation** - Prevent cross-chain replay attacks
+- **Nonce Validation** - 30-second proof expiry
+- **Contract Validation** - Ensure correct token contract
+- **Fail-Closed Design** - Deny on any validation failure
+
+## Performance Optimization
+
+### Caching Strategy
+
+```typescript
+const radius = new RadiusMcpSdk({
+  contractAddress: '0x...',
+  cache: {
+    ttl: 300,        // 5-minute cache
+    maxSize: 1000,   // Max entries
+    disabled: false  // Enable caching
+  }
+});
+```
+
+### Batch Token Checks
+
+```typescript
+// SDK automatically batches multiple token checks
+handler: radius.protect([101, 102, 103, 104, 105], handler)
+// Uses balanceOfBatch for efficiency
+```
+
+### HTTP Streaming
+
+```typescript
+server.start({
+  transportType: 'httpStream',
+  httpStream: {
+    port: 3000,
+    endpoint: '/mcp',
+    stateless: true  // For serverless
+  }
+});
+```
+
+## Testing Strategies
+
+### Local Development
+
+```bash
+# Start server
+npm run dev
+
+# Test with ngrok for claude.ai
+ngrok http 3000
+
+# Use URL in claude.ai
+https://abc123.ngrok.io/mcp
+```
+
+### Integration Testing
+
+```typescript
+describe('Token-Gated Tool', () => {
+  it('should require authentication', async () => {
+    const response = await protectedTool({ query: 'test' });
+    expect(response.error.code).toBe('EVMAUTH_PROOF_MISSING');
+  });
+
+  it('should accept valid proof', async () => {
+    const response = await protectedTool({
+      query: 'test',
+      __evmauth: validProof
+    });
+    expect(response.content).toBeDefined();
+  });
+});
+```
+
+## Deployment Configuration
+
+### Environment Variables
+
+```env
+# Radius Network Configuration
+EVMAUTH_CONTRACT_ADDRESS=0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96
+EVMAUTH_CHAIN_ID=1223953
+EVMAUTH_RPC_URL=https://rpc.testnet.radiustech.xyz
+
+# Token Configuration
+EVMAUTH_TOKEN_ID=1  # Your token ID
+
+# Server Configuration
+PORT=3000
+NODE_ENV=production
+DEBUG=false  # IMPORTANT: Disable in production
+```
+
+### Docker Deployment
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+RUN npm run build
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+### Production Checklist
+
+- [ ] Disable debug mode (`debug: false`)
+- [ ] Use environment variables for config
+- [ ] Set up proper error monitoring
+- [ ] Configure rate limiting
+- [ ] Enable CORS if needed
+- [ ] Set up health checks
+- [ ] Configure logging
+
+## Common Patterns
+
+### Tiered Access Control
+
+```typescript
+// Different tokens for different features
+server.addTool({
+  name: 'basic_analytics',
+  handler: radius.protect(TOKENS.BASIC, basicHandler)
+});
+
+server.addTool({
+  name: 'premium_analytics',
+  handler: radius.protect(TOKENS.PREMIUM, premiumHandler)
+});
+
+server.addTool({
+  name: 'enterprise_analytics',
+  handler: radius.protect(TOKENS.ENTERPRISE, enterpriseHandler)
+});
+```
+
+### Dynamic Token Requirements
+
+```typescript
+server.addTool({
+  name: 'flexible_tool',
+  handler: async (request) => {
+    const tier = determineTier(request);
+    const tokenId = getTokenForTier(tier);
+    
+    return radius.protect(tokenId, async (args) => {
+      return processWithTier(args, tier);
+    })(request);
+  }
+});
+```
+
+### Resource Protection
+
+```typescript
+server.addResource({
+  name: 'premium_dataset',
+  uri: 'dataset://premium/2024',
+  handler: radius.protect(102, async () => {
+    return {
+      contents: [{
+        uri: 'dataset://premium/2024',
+        text: loadPremiumData()
+      }]
+    };
+  })
+});
+```
+
+## Debugging Tips
+
+### Enable Debug Logging
+
+```typescript
+const radius = new RadiusMcpSdk({
+  contractAddress: '0x...',
+  debug: true  // Shows detailed auth flow
+});
+```
+
+### Common Issues
+
+1. **EVMAUTH_PROOF_MISSING**
+   - Ensure client includes `__evmauth` parameter
+   - Check Radius MCP Server connection
+
+2. **PROOF_EXPIRED**
+   - Proofs expire after 30 seconds
+   - Client needs fresh proof
+
+3. **PAYMENT_REQUIRED**
+   - User lacks required tokens
+   - Client should call `authenticate_and_purchase`
+
+4. **CHAIN_MISMATCH**
+   - Verify chainId configuration
+   - Ensure proof matches network
+
+## Security Best Practices
+
+1. **Never expose private keys** in code or logs
+2. **Validate all inputs** with Zod or similar
+3. **Use environment variables** for sensitive config
+4. **Disable debug mode** in production
+5. **Implement rate limiting** for public endpoints
+6. **Monitor for unusual patterns** in token checks
+7. **Keep SDK updated** for security patches
+
+## Claude Code Configuration Features
+
+### Available Agents
+
+Use these specialized agents for expert assistance:
+
+- `radius-sdk-expert` - Token protection and SDK implementation
+- `fastmcp-builder` - FastMCP server development
+- `auth-flow-debugger` - Authentication debugging
+- `token-economics-designer` - Token tier design
+- `web3-security-auditor` - Security audits
+
+### Available Commands
+
+Powerful slash commands for common tasks:
+
+- `/setup-token-gate [basic|full|testnet]` - Set up complete server
+- `/test-auth [tool] [token-id]` - Test authentication flow
+- `/create-tool <name> <token-id> [tier]` - Create token-gated tool
+- `/debug-proof` - Debug proof verification
+- `/deploy-local` - Deploy with ngrok
+- `/validate-config` - Validate configuration
+
+### Automated Hooks
+
+Automatic actions on file changes:
+
+- **Pre-tool hooks** - Validate token config, log commands
+- **Post-tool hooks** - Format TypeScript, validate protection
+- **Stop hooks** - Production safety checks
+
+## Common Commands
+
+```bash
+# Development
+npm run dev          # Start with hot reload
+npm run build        # Build for production
+npm run test         # Run tests
+npm run lint         # Lint code
+
+# Testing with Claude
+npx fastmcp dev server.ts     # Test with CLI
+npx fastmcp inspect server.ts  # Use MCP Inspector
+
+# Production
+npm start            # Start production server
+npm run docker:build # Build Docker image
+npm run docker:run   # Run in container
+```
+
+## Resources
+
+- [FastMCP Documentation](https://github.com/punkpeye/fastmcp)
+- [Radius MCP SDK](https://github.com/radiustechsystems/mcp-sdk)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Radius Network Docs](https://docs.radiustech.xyz)
+- [EIP-712 Specification](https://eips.ethereum.org/EIPS/eip-712)
+
+Remember: **Simple Integration, Powerful Protection, Decentralized Access!**
diff --git a/mcp-servers/token-gated-mcp-server/README.md b/mcp-servers/token-gated-mcp-server/README.md
new file mode 100644
index 0000000..a319b55
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/README.md
@@ -0,0 +1,426 @@
+# Token-Gated MCP Server Claude Code Configuration 🔐
+
+A comprehensive Claude Code configuration for building token-gated MCP servers using FastMCP and the Radius MCP SDK. Enable decentralized, token-based access control for your AI tools with just 3 lines of code.
+
+## ✨ Features
+
+This configuration provides comprehensive support for:
+
+- **Token-Gated Access** - ERC-1155 token-based authorization
+- **FastMCP Integration** - Rapid MCP server development  
+- **Radius MCP SDK** - Cryptographic proof verification
+- **Web3 Authentication** - EIP-712 signature validation
+- **Multi-Tier Pricing** - Different token requirements per tool
+- **Complete Development Environment** - Agents, commands, hooks, and settings
+
+## 📦 Installation
+
+1. Copy the complete configuration to your token-gated MCP server project:
+
+```bash
+# Copy the entire configuration
+cp -r token-gated-mcp-server/.claude your-mcp-project/
+cp token-gated-mcp-server/CLAUDE.md your-mcp-project/
+
+# Make hook scripts executable
+chmod +x your-mcp-project/.claude/hooks/*.sh
+```
+
+2. The configuration will be automatically loaded when you start Claude Code.
+
+## 📁 Configuration Structure
+
+```text
+.claude/
+├── settings.json           # Main configuration with permissions, env vars, hooks
+├── agents/                 # Specialized AI subagents
+│   ├── radius-sdk-expert.md      # Radius MCP SDK implementation expert
+│   ├── fastmcp-builder.md        # FastMCP server development specialist
+│   ├── auth-flow-debugger.md     # Authentication debugging expert
+│   ├── token-economics-designer.md # Token tier design specialist
+│   └── web3-security-auditor.md  # Web3 security expert
+├── commands/               # Custom slash commands
+│   ├── setup-token-gate.md       # Set up complete token-gated server
+│   ├── test-auth.md              # Test authentication flow
+│   ├── create-tool.md            # Create new token-gated tool
+│   ├── debug-proof.md            # Debug proof verification
+│   ├── deploy-local.md           # Deploy locally with ngrok
+│   └── validate-config.md        # Validate configuration
+└── hooks/                  # Automation scripts
+    ├── validate-token-config.sh  # Validate token configuration
+    ├── format-typescript.sh      # Auto-format TypeScript files
+    ├── log-mcp-commands.sh       # Log MCP commands for debugging
+    └── production-safety.sh      # Production safety checks
+
+## 🤖 Specialized Agents (5 Expert Agents)
+
+| Agent | Description | Use Cases |
+|-------|-------------|-----------|
+| `radius-sdk-expert` | Radius MCP SDK implementation expert | Token protection, proof verification, multi-token patterns |
+| `fastmcp-builder` | FastMCP server development specialist | Server setup, tool/resource/prompt creation, transport configuration |
+| `auth-flow-debugger` | Authentication flow debugging expert | EVMAUTH errors, proof validation, token verification |
+| `token-economics-designer` | Token economics and tier design specialist | Pricing models, access tiers, token distribution |
+| `web3-security-auditor` | Web3 security expert | Smart contract safety, cryptographic operations, security audits |
+
+## 🛠️ Commands (6 Powerful Commands)
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `/setup-token-gate` | Set up complete token-gated MCP server | `/setup-token-gate [basic\|full\|testnet]` |
+| `/test-auth` | Test authentication flow end-to-end | `/test-auth [tool-name] [token-id]` |
+| `/create-tool` | Create new token-gated tool | `/create-tool <tool-name> <token-id> [tier]` |
+| `/debug-proof` | Debug proof verification issues | `/debug-proof` |
+| `/deploy-local` | Deploy locally with ngrok | `/deploy-local` |
+| `/validate-config` | Validate token-gating configuration | `/validate-config` |
+
+## 🪝 Automation Hooks
+
+### Pre-Tool Use Hooks
+- **Token Configuration Validator** (`validate-token-config.sh`)
+  - Validates contract address format (0x + 40 hex)
+  - Checks for hardcoded private keys
+  - Warns about debug mode in production
+  - Verifies __evmauth parameter inclusion
+
+- **MCP Command Logger** (`log-mcp-commands.sh`)
+  - Logs FastMCP and ngrok commands
+  - Tracks token configuration checks
+  - Blocks dangerous commands (rm -rf, npm publish in dev)
+  - Provides helpful tips for development
+
+### Post-Tool Use Hooks
+- **TypeScript Formatter** (`format-typescript.sh`)
+  - Auto-formats with Prettier
+  - Validates token protection implementation
+  - Checks for proper error handling
+  - Counts protected tools in server files
+
+### Stop Hooks
+- **Production Safety Check** (`production-safety.sh`)
+  - Environment-specific warnings
+  - Debug mode detection
+  - Uncommitted changes reminder
+  - Token configuration summary
+
+## ⚙️ Configuration Details
+
+### Security Permissions
+
+The configuration includes comprehensive permissions for safe development:
+
+**Allowed Operations:**
+- All standard file operations (Read, Write, Edit, MultiEdit)
+- Search and navigation tools (Grep, Glob, LS)
+- Development commands (npm run dev/build/test/lint/typecheck)
+- Package management (npm install, npm ci)
+- FastMCP and ngrok for testing
+- Git operations for version control
+- Docker commands for containerization
+- RPC endpoint testing
+
+**Denied Operations:**
+- Reading/writing private keys or secrets
+- Destructive commands (rm -rf)
+- Publishing to npm in development
+- Modifying production environment files
+- Unsafe curl operations (POST, PUT, DELETE)
+
+### Environment Variables
+
+Pre-configured for token-gated development:
+
+- `EVMAUTH_CONTRACT_ADDRESS` - ERC-1155 contract (0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96)
+- `EVMAUTH_CHAIN_ID` - Radius Testnet (1223953)
+- `EVMAUTH_RPC_URL` - Blockchain RPC endpoint (https://rpc.testnet.radiustech.xyz)
+- `EVMAUTH_TOKEN_ID` - Required token ID (default: 1)
+- `NODE_ENV` - Environment mode (development/production)
+- `DEBUG` - Debug mode (false by default, never enable in production!)
+- `RADIUS_TESTNET` - Testnet indicator (true)
+
+### Status Line
+
+A custom status line displays real-time token-gating information:
+```text
+
+🔐 Token-Gated MCP | Chain: 1223953 | Token: 1 | dev
+
+```
+
+## 🚀 Usage Examples
+
+### Building a Token-Gated MCP Server
+
+```bash
+# 1. Set up the project
+> /setup full
+
+# 2. Create a token-gated tool
+> /create-tool premium_analytics 101
+
+# 3. Test authentication flow
+> /test-auth
+
+# 4. Deploy locally with ngrok
+> /deploy-local
+
+# 5. Connect in claude.ai
+# Use the ngrok URL + /mcp endpoint
+```
+
+### The 3-Line Integration
+
+```typescript
+// That's all you need!
+const radius = new RadiusMcpSdk({ 
+  contractAddress: '0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96' 
+});
+
+server.addTool({
+  name: 'premium_tool',
+  handler: radius.protect(101, yourHandler)  // Token-gated!
+});
+```
+
+### Testing Authentication Flow
+
+```bash
+# Debug authentication issues
+> /debug-proof
+
+# The debugger will:
+# - Validate proof structure
+# - Check signature verification
+# - Test token ownership
+# - Identify configuration issues
+```
+
+## 📊 Technology Stack
+
+Optimized for:
+
+- **TypeScript** & Node.js
+- **FastMCP v3.0+** for MCP servers
+- **Radius MCP SDK** for token-gating
+- **Viem** for Ethereum interactions
+- **Zod** for schema validation
+- **EIP-712** for cryptographic signatures
+- **Radius Network Testnet** (Chain ID: 1223953)
+
+## 🎯 Key Features
+
+### Token-Based Access Control
+
+- ERC-1155 multi-token support
+- ANY token logic (user needs one of many)
+- Tiered access patterns
+- Dynamic token requirements
+
+### Authentication Flow
+
+- Cryptographic proof verification
+- EIP-712 signature validation
+- 30-second proof expiry
+- Replay attack prevention
+
+### Developer Experience
+
+- 3-line integration
+- AI-friendly error messages
+- Automatic retry guidance
+- Built-in caching
+
+### Production Ready
+
+- Docker containerization
+- Health check endpoints
+- Structured logging
+- Performance monitoring
+
+## 🔧 Customization
+
+Edit `.claude/settings.json` to customize:
+
+- Token contract addresses
+- Chain ID for different networks
+- Token tier configurations
+- Cache settings
+- Debug options
+
+## 📝 Best Practices
+
+This configuration enforces:
+
+1. **Security First** - Cryptographic verification, fail-closed design
+2. **Simple Integration** - Minimal code for maximum protection
+3. **AI-Friendly Errors** - Clear guidance for authentication
+4. **Performance** - Caching, batch checks, optimization
+5. **Testing** - Comprehensive auth flow validation
+6. **Production Ready** - Monitoring, health checks, logging
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**EVMAUTH_PROOF_MISSING errors:**
+
+```bash
+# Check Radius MCP Server connection
+# Ensure __evmauth parameter is included
+# Verify proof hasn't expired (30 seconds)
+```
+
+**Token verification failures:**
+
+```bash
+# Check contract address configuration
+echo $EVMAUTH_CONTRACT_ADDRESS
+
+# Verify chain ID
+echo $EVMAUTH_CHAIN_ID
+
+# Test RPC connection
+curl $EVMAUTH_RPC_URL
+```
+
+**Debug authentication flow:**
+
+```bash
+/debug-proof
+```
+
+## 🌟 Example Projects
+
+### Simple Token-Gated Timestamp
+
+```typescript
+server.addTool({
+  name: 'get_timestamp',
+  description: `Get current time (requires token ${TOKEN_ID})`,
+  parameters: z.object({
+    format: z.enum(['unix', 'iso', 'readable'])
+  }),
+  handler: radius.protect(TOKEN_ID, async (args) => {
+    return new Date().toISOString();
+  })
+});
+```
+
+### Multi-Tier Analytics
+
+```typescript
+const TOKENS = {
+  BASIC: 101,
+  PREMIUM: 102,
+  ENTERPRISE: [201, 202, 203]
+};
+
+// Different tools for different tiers
+server.addTool({
+  name: 'basic_analytics',
+  handler: radius.protect(TOKENS.BASIC, basicHandler)
+});
+
+server.addTool({
+  name: 'enterprise_analytics',
+  handler: radius.protect(TOKENS.ENTERPRISE, enterpriseHandler)
+});
+```
+
+## 🔗 Integration with Radius MCP Server
+
+This SDK works with the **Radius MCP Server** for complete token-gating:
+
+1. **Radius MCP Server** (one per AI client)
+   - OAuth authentication
+   - Wallet management via Privy
+   - Proof generation
+   - Token purchases
+
+2. **Your MCP Server** (using this config)
+   - Proof verification
+   - Token ownership checks
+   - Tool execution
+   - Error guidance
+
+## 📚 Resources
+
+- [FastMCP Documentation](https://github.com/punkpeye/fastmcp)
+- [Radius MCP SDK](https://github.com/radiustechsystems/mcp-sdk)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Radius Network Testnet](https://docs.radiustech.xyz)
+- [EIP-712 Specification](https://eips.ethereum.org/EIPS/eip-712)
+
+## 🎉 Quick Start Example
+
+```bash
+# 1. Install dependencies
+npm install fastmcp @radiustechsystems/mcp-sdk zod
+
+# 2. Create server.ts
+cat > server.ts << 'EOF'
+import { FastMCP } from 'fastmcp';
+import { RadiusMcpSdk } from '@radiustechsystems/mcp-sdk';
+import { z } from 'zod';
+
+const radius = new RadiusMcpSdk({
+  contractAddress: '0x5448Dc20ad9e0cDb5Dd0db25e814545d1aa08D96'
+});
+
+const server = new FastMCP({ name: 'My Token Server' });
+
+server.addTool({
+  name: 'premium_tool',
+  description: 'Premium feature (token required)',
+  parameters: z.object({ input: z.string() }),
+  handler: radius.protect(1, async (args) => {
+    return `Premium result for: ${args.input}`;
+  })
+});
+
+server.start({ 
+  transportType: 'httpStream',
+  httpStream: { port: 3000 }
+});
+EOF
+
+# 3. Run the server
+npx tsx server.ts
+
+# 4. Test with ngrok
+ngrok http 3000
+
+# 5. Connect in claude.ai with the ngrok URL + /mcp
+```
+
+## 🎯 What Makes This Configuration Special
+
+### Complete Development Environment
+
+- **5 Expert Agents** - Specialized AI assistants for every aspect of token-gating
+- **6 Power Commands** - From setup to deployment, all automated
+- **4 Smart Hooks** - Automatic validation, formatting, and safety checks
+- **Comprehensive Settings** - Pre-configured for Radius Testnet with security best practices
+
+### Key Capabilities
+
+1. **3-Line Integration** - Token-gate any tool with minimal code
+2. **AI-Friendly Errors** - Guide Claude through authentication automatically
+3. **Production Ready** - Built-in safety checks and deployment tools
+4. **Security First** - Automatic detection of private keys and unsafe patterns
+5. **Developer Experience** - Auto-formatting, logging, and debugging tools
+
+### Perfect For
+
+- Building token-gated MCP servers with FastMCP
+- Implementing ERC-1155 token access control
+- Creating tiered access models for AI tools
+- Deploying to Radius Network (testnet and mainnet)
+- Learning Web3 authentication patterns
+
+---
+
+**Built for the decentralized AI tool marketplace** 🚀
+
+*Enable token-gated access to your MCP tools with minimal code and maximum security.*
+
+**Configuration Version:** 1.0.0 | **Compatible with:** FastMCP 3.0+, Radius MCP SDK 1.0+
diff --git a/mcp-servers/token-gated-mcp-server/package.json b/mcp-servers/token-gated-mcp-server/package.json
new file mode 100644
index 0000000..1be727f
--- /dev/null
+++ b/mcp-servers/token-gated-mcp-server/package.json
@@ -0,0 +1,67 @@
+{
+  "name": "token-gated-mcp-server-claude-config",
+  "version": "1.0.0",
+  "description": "Comprehensive Claude Code configuration for Token-Gated MCP Server development",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude-code",
+    "token-gating",
+    "authentication",
+    "radius-sdk",
+    "web3",
+    "blockchain"
+  ],
+  "author": "Matt Dionis <matt@nlad.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Matt-Dionis/claude-code-configs.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "claude-config": {
+    "version": "1.0.0",
+    "compatible": {
+      "claude-code": ">=1.0.0",
+      "@modelcontextprotocol/sdk": ">=1.0.0",
+      "@radius/mcp-sdk": ">=1.0.0",
+      "fastmcp": ">=1.0.0"
+    },
+    "features": {
+      "agents": 5,
+      "commands": 6,
+      "hooks": 4,
+      "capabilities": [
+        "token-authentication",
+        "proof-verification",
+        "rate-limiting",
+        "multi-tenant",
+        "web3-integration"
+      ]
+    }
+  },
+  "scripts": {
+    "validate": "node -e \"console.log('✅ Configuration is valid')\"",
+    "info": "node -e \"console.log(JSON.stringify(require('./package.json')['claude-config'], null, 2))\""
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "fastmcp": ">=1.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": false
+    },
+    "fastmcp": {
+      "optional": false
+    },
+    "typescript": {
+      "optional": false
+    }
+  }
+}