@qwickapps/qwickbrain-proxy 1.0.0

package/src/lib/proxy-server.ts

@@ -0,0 +1,320 @@
+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 { ConnectionManager } from './connection-manager.js';
+import { CacheManager } from './cache-manager.js';
+import { QwickBrainClient } from './qwickbrain-client.js';
+import type { Config } from '../types/config.js';
+import type { DB } from '../db/client.js';
+import type { MCPResponse, MCPResponseMetadata } from '../types/mcp.js';
+import { VERSION } from '../version.js';
+
+export class ProxyServer {
+  private server: Server;
+  private connectionManager: ConnectionManager;
+  private cacheManager: CacheManager;
+  private qwickbrainClient: QwickBrainClient;
+  private config: Config;
+
+  constructor(db: DB, config: Config) {
+    this.config = config;
+    this.server = new Server(
+      {
+        name: 'qwickbrain-proxy',
+        version: VERSION,
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.qwickbrainClient = new QwickBrainClient(config.qwickbrain);
+
+    this.connectionManager = new ConnectionManager(
+      this.qwickbrainClient,
+      config.connection
+    );
+
+    this.cacheManager = new CacheManager(db, config.cache);
+
+    this.setupHandlers();
+    this.setupConnectionListeners();
+  }
+
+  private setupConnectionListeners(): void {
+    this.connectionManager.on('stateChange', ({ from, to }) => {
+      console.error(`Connection state: ${from} → ${to}`);
+    });
+
+    this.connectionManager.on('reconnecting', ({ attempt, delay }) => {
+      console.error(`Reconnecting (attempt ${attempt}, delay ${delay}ms)...`);
+    });
+
+    this.connectionManager.on('connected', ({ latencyMs }) => {
+      console.error(`Connected to QwickBrain (latency: ${latencyMs}ms)`);
+    });
+
+    this.connectionManager.on('disconnected', ({ error }) => {
+      console.error(`Disconnected from QwickBrain: ${error}`);
+    });
+  }
+
+  private setupHandlers(): void {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: 'get_workflow',
+          description: 'Get a workflow definition by name',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Workflow name' },
+            },
+            required: ['name'],
+          },
+        },
+        {
+          name: 'get_document',
+          description: 'Get a document by name and type',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Document name' },
+              doc_type: { type: 'string', description: 'Document type (rule, frd, design, etc.)' },
+              project: { type: 'string', description: 'Project name (optional)' },
+            },
+            required: ['name', 'doc_type'],
+          },
+        },
+        {
+          name: 'get_memory',
+          description: 'Get a memory/context document by name',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Memory name' },
+              project: { type: 'string', description: 'Project name (optional)' },
+            },
+            required: ['name'],
+          },
+        },
+      ],
+    }));
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      try {
+        let result: MCPResponse;
+
+        switch (name) {
+          case 'get_workflow':
+            result = await this.handleGetWorkflow(args?.name as string);
+            break;
+          case 'get_document':
+            result = await this.handleGetDocument(
+              args?.doc_type as string,
+              args?.name as string,
+              args?.project as string | undefined
+            );
+            break;
+          case 'get_memory':
+            result = await this.handleGetMemory(
+              args?.name as string,
+              args?.project as string | undefined
+            );
+            break;
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({
+                error: {
+                  code: 'TOOL_ERROR',
+                  message: errorMessage,
+                },
+                _metadata: {
+                  source: 'cache',
+                  status: this.connectionManager.getState(),
+                },
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  private createMetadata(source: 'live' | 'cache' | 'stale_cache', age?: number): MCPResponseMetadata {
+    return {
+      source,
+      age_seconds: age,
+      status: this.connectionManager.getState(),
+    };
+  }
+
+  private async handleGetWorkflow(name: string): Promise<MCPResponse> {
+    return this.handleGetDocument('workflow', name);
+  }
+
+  private async handleGetDocument(
+    docType: string,
+    name: string,
+    project?: string
+  ): Promise<MCPResponse> {
+    // Try cache first
+    const cached = await this.cacheManager.getDocument(docType, name, project);
+
+    if (cached && !cached.isExpired) {
+      return {
+        data: cached.data,
+        _metadata: this.createMetadata('cache', cached.age),
+      };
+    }
+
+    // Try remote if connected
+    if (this.connectionManager.getState() === 'connected') {
+      try {
+        const result = await this.connectionManager.execute(async () => {
+          return await this.qwickbrainClient.getDocument(docType, name, project);
+        });
+
+        // Cache the result
+        await this.cacheManager.setDocument(
+          docType,
+          name,
+          result.content,
+          project,
+          result.metadata
+        );
+
+        return {
+          data: result,
+          _metadata: this.createMetadata('live'),
+        };
+      } catch (error) {
+        console.error('Failed to fetch from QwickBrain:', error);
+        // Fall through to stale cache
+      }
+    }
+
+    // Try stale cache
+    if (cached) {
+      return {
+        data: cached.data,
+        _metadata: {
+          ...this.createMetadata('stale_cache', cached.age),
+          warning: `QwickBrain unavailable - serving cached data (${cached.age}s old)`,
+        },
+      };
+    }
+
+    // No cache, no connection
+    return {
+      error: {
+        code: 'UNAVAILABLE',
+        message: `QwickBrain unavailable and no cached data for ${docType}:${name}`,
+        suggestions: [
+          'Check internet connection',
+          'Wait for automatic reconnection',
+          docType === 'workflow' ? 'Try /plan command as fallback' : undefined,
+        ].filter(Boolean) as string[],
+      },
+      _metadata: this.createMetadata('cache'),
+    };
+  }
+
+  private async handleGetMemory(name: string, project?: string): Promise<MCPResponse> {
+    // Similar logic to handleGetDocument but for memories
+    const cached = await this.cacheManager.getMemory(name, project);
+
+    if (cached && !cached.isExpired) {
+      return {
+        data: cached.data,
+        _metadata: this.createMetadata('cache', cached.age),
+      };
+    }
+
+    if (this.connectionManager.getState() === 'connected') {
+      try {
+        const result = await this.connectionManager.execute(async () => {
+          return await this.qwickbrainClient.getMemory(name, project);
+        });
+
+        await this.cacheManager.setMemory(name, result.content, project, result.metadata);
+
+        return {
+          data: result,
+          _metadata: this.createMetadata('live'),
+        };
+      } catch (error) {
+        console.error('Failed to fetch memory from QwickBrain:', error);
+      }
+    }
+
+    if (cached) {
+      return {
+        data: cached.data,
+        _metadata: {
+          ...this.createMetadata('stale_cache', cached.age),
+          warning: `QwickBrain unavailable - serving cached memory (${cached.age}s old)`,
+        },
+      };
+    }
+
+    return {
+      error: {
+        code: 'UNAVAILABLE',
+        message: `QwickBrain unavailable and no cached memory: ${name}`,
+        suggestions: ['Check connection', 'Wait for reconnection'],
+      },
+      _metadata: this.createMetadata('cache'),
+    };
+  }
+
+  async start(): Promise<void> {
+    // Clean up expired cache entries on startup
+    const { documentsDeleted, memoriesDeleted } = await this.cacheManager.cleanupExpiredEntries();
+    if (documentsDeleted > 0 || memoriesDeleted > 0) {
+      console.error(`Cache cleanup: removed ${documentsDeleted} documents, ${memoriesDeleted} memories`);
+    }
+
+    // Connect to QwickBrain
+    await this.qwickbrainClient.connect();
+
+    // Start connection manager
+    await this.connectionManager.start();
+
+    // Start MCP server
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    console.error('QwickBrain Proxy started');
+  }
+
+  async stop(): Promise<void> {
+    this.connectionManager.stop();
+    await this.qwickbrainClient.disconnect();
+    await this.server.close();
+  }
+}

package/src/lib/qwickbrain-client.ts

@@ -0,0 +1,260 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Config } from '../types/config.js';
+import { z } from 'zod';
+import { VERSION } from '../version.js';
+
+// Zod schema for MCP tool response validation
+const MCPToolResponseSchema = z.object({
+  content: z.array(
+    z.object({
+      type: z.literal('text'),
+      text: z.string(),
+    })
+  ),
+});
+
+// Zod schema for the document/memory data inside the MCP response
+const QwickBrainDocumentSchema = z.object({
+  document: z
+    .object({
+      content: z.string(),
+      metadata: z.record(z.unknown()).optional(),
+    })
+    .optional(),
+});
+
+// Zod schema for HTTP API responses
+const HTTPResponseSchema = z.object({
+  content: z.string(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+export interface QwickBrainResponse {
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+export class QwickBrainClient {
+  private client: Client | null = null;
+  private transport: Transport | null = null;
+  private mode: 'mcp' | 'http' | 'sse';
+  private config: Config['qwickbrain'];
+
+  constructor(config: Config['qwickbrain']) {
+    this.mode = config.mode;
+    this.config = config;
+  }
+
+  async connect(): Promise<void> {
+    if (this.mode === 'mcp') {
+      await this.connectMCP();
+    } else if (this.mode === 'sse') {
+      await this.connectSSE();
+    }
+    // HTTP mode doesn't need persistent connection
+  }
+
+  private async connectMCP(): Promise<void> {
+    if (!this.config.command) {
+      throw new Error('MCP mode requires command to be configured');
+    }
+
+    this.client = new Client(
+      {
+        name: 'qwickbrain-proxy',
+        version: VERSION,
+      },
+      {
+        capabilities: {},
+      }
+    );
+
+    this.transport = new StdioClientTransport({
+      command: this.config.command,
+      args: this.config.args || [],
+    });
+
+    await this.client.connect(this.transport);
+  }
+
+  private async connectSSE(): Promise<void> {
+    if (!this.config.url) {
+      throw new Error('SSE mode requires url to be configured');
+    }
+
+    this.client = new Client(
+      {
+        name: 'qwickbrain-proxy',
+        version: VERSION,
+      },
+      {
+        capabilities: {},
+      }
+    );
+
+    this.transport = new SSEClientTransport(
+      new URL(this.config.url)
+    );
+
+    await this.client.connect(this.transport);
+  }
+
+  async getDocument(
+    docType: string,
+    name: string,
+    project?: string
+  ): Promise<QwickBrainResponse> {
+    if (this.mode === 'mcp' || this.mode === 'sse') {
+      return this.getDocumentMCP(docType, name, project);
+    } else {
+      return this.getDocumentHTTP(docType, name, project);
+    }
+  }
+
+  private async getDocumentMCP(
+    docType: string,
+    name: string,
+    project?: string
+  ): Promise<QwickBrainResponse> {
+    if (!this.client) {
+      throw new Error('MCP client not connected');
+    }
+
+    const result = await this.client.callTool({
+      name: 'get_document',
+      arguments: {
+        doc_type: docType,
+        name,
+        project,
+      },
+    });
+
+    // Validate MCP response structure
+    const parsed = MCPToolResponseSchema.parse(result);
+    const data = QwickBrainDocumentSchema.parse(JSON.parse(parsed.content[0].text));
+
+    return {
+      content: data.document?.content || '',
+      metadata: data.document?.metadata,
+    };
+  }
+
+  private async getDocumentHTTP(
+    docType: string,
+    name: string,
+    project?: string
+  ): Promise<QwickBrainResponse> {
+    if (!this.config.url) {
+      throw new Error('HTTP mode requires url to be configured');
+    }
+
+    const response = await fetch(`${this.config.url}/mcp/document`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.config.apiKey && { 'Authorization': `Bearer ${this.config.apiKey}` }),
+      },
+      body: JSON.stringify({ doc_type: docType, name, project }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const json = await response.json();
+    return HTTPResponseSchema.parse(json);
+  }
+
+  async getMemory(name: string, project?: string): Promise<QwickBrainResponse> {
+    if (this.mode === 'mcp' || this.mode === 'sse') {
+      return this.getMemoryMCP(name, project);
+    } else {
+      return this.getMemoryHTTP(name, project);
+    }
+  }
+
+  private async getMemoryMCP(
+    name: string,
+    project?: string
+  ): Promise<QwickBrainResponse> {
+    if (!this.client) {
+      throw new Error('MCP client not connected');
+    }
+
+    const result = await this.client.callTool({
+      name: 'get_memory',
+      arguments: {
+        name,
+        project,
+      },
+    });
+
+    // Validate MCP response structure
+    const parsed = MCPToolResponseSchema.parse(result);
+    const data = QwickBrainDocumentSchema.parse(JSON.parse(parsed.content[0].text));
+
+    return {
+      content: data.document?.content || '',
+      metadata: data.document?.metadata,
+    };
+  }
+
+  private async getMemoryHTTP(
+    name: string,
+    project?: string
+  ): Promise<QwickBrainResponse> {
+    if (!this.config.url) {
+      throw new Error('HTTP mode requires url to be configured');
+    }
+
+    const response = await fetch(`${this.config.url}/mcp/memory`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.config.apiKey && { 'Authorization': `Bearer ${this.config.apiKey}` }),
+      },
+      body: JSON.stringify({ name, project }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const json = await response.json();
+    return HTTPResponseSchema.parse(json);
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      if (this.mode === 'mcp' || this.mode === 'sse') {
+        // For MCP/SSE mode, check if client is connected
+        if (!this.client) {
+          await this.connect();
+        }
+        // Try listing tools as health check
+        await this.client!.listTools();
+        return true;
+      } else {
+        // For HTTP mode, ping health endpoint
+        if (!this.config.url) {
+          return false;
+        }
+        const response = await fetch(`${this.config.url}/health`);
+        return response.ok;
+      }
+    } catch (error) {
+      return false;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if ((this.mode === 'mcp' || this.mode === 'sse') && this.client && this.transport) {
+      await this.client.close();
+      this.client = null;
+      this.transport = null;
+    }
+  }
+}

package/src/types/config.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+
+export const ConfigSchema = z.object({
+  qwickbrain: z.object({
+    mode: z.enum(['mcp', 'http', 'sse']).default('sse'),
+    // For MCP mode (local stdio)
+    command: z.string().optional(),
+    args: z.array(z.string()).optional(),
+    // For HTTP mode (cloud/remote) or SSE mode
+    url: z.string().url().optional(),
+    apiKey: z.string().optional(),
+  }).default({}),
+  cache: z.object({
+    dir: z.string().optional(),
+    ttl: z.object({
+      workflows: z.number().default(86400), // 24 hours
+      rules: z.number().default(86400), // 24 hours
+      documents: z.number().default(21600), // 6 hours
+      memories: z.number().default(3600), // 1 hour
+    }).default({}),
+    preload: z.array(z.string()).default(['workflows', 'rules']),
+  }).default({}),
+  connection: z.object({
+    healthCheckInterval: z.number().default(30000), // 30 seconds
+    timeout: z.number().default(5000), // 5 seconds
+    maxReconnectAttempts: z.number().default(10),
+    reconnectBackoff: z.object({
+      initial: z.number().default(1000), // 1 second
+      max: z.number().default(60000), // 60 seconds
+      multiplier: z.number().default(2),
+    }).default({}),
+  }).default({}),
+  sync: z.object({
+    interval: z.number().default(300000), // 5 minutes
+    batchSize: z.number().default(10),
+  }).default({}),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+export const CacheConfigSchema = z.object({
+  ttl: z.number(),
+  offline: z.boolean(),
+  preload: z.boolean(),
+});
+
+export type CacheConfig = z.infer<typeof CacheConfigSchema>;