@elliotding/ai-agent-mcp 0.1.0

package/src/transport/sse.ts

@@ -0,0 +1,308 @@
+/**
+ * SSE Transport Implementation
+ * MCP protocol over Server-Sent Events
+ */
+
+import { logger, logToolStep } from '../utils/logger';
+import { sessionManager } from '../session/manager';
+import { toolRegistry } from '../tools/registry';
+import { checkToolCallPermission } from '../auth/middleware';
+
+export interface SSEMessage {
+  jsonrpc: '2.0';
+  id?: string | number;
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+export class SSETransport {
+  constructor() {
+    logger.info('SSE transport initialized');
+  }
+
+  /**
+   * Handle incoming message from client
+   */
+  async handleMessage(sessionId: string, message: SSEMessage): Promise<void> {
+    const messageStartTime = Date.now();
+    
+    logger.info({ 
+      type: 'sse_message_received',
+      sessionId, 
+      method: message.method,
+      messageId: message.id,
+      hasParams: !!message.params,
+      timestamp: new Date().toISOString()
+    }, `SSE message received: ${message.method}`);
+
+    try {
+      // Validate session
+      logToolStep('sse', 'Validating session', { sessionId });
+      
+      const session = sessionManager.getSession(sessionId);
+      if (!session) {
+        logger.error({
+          type: 'sse_error',
+          sessionId,
+          method: message.method,
+          error: 'session_not_found',
+          timestamp: new Date().toISOString()
+        }, 'Session not found or expired');
+        throw new Error('Session not found or expired');
+      }
+
+      logger.debug({
+        type: 'sse_session_validated',
+        sessionId,
+        userId: session.userId,
+        email: session.email,
+        groups: session.groups,
+        timestamp: new Date().toISOString()
+      }, 'Session validated');
+
+      // Update session activity
+      sessionManager.updateActivity(sessionId);
+      logToolStep('sse', 'Session activity updated', { sessionId });
+
+      // Handle MCP message
+      if (message.method === 'tools/list') {
+        logToolStep('sse', 'Handling tools/list request', { sessionId });
+        
+        const tools = toolRegistry.getMCPToolDefinitions();
+        
+        logger.info({
+          type: 'sse_tools_list',
+          sessionId,
+          toolCount: tools.length,
+          toolNames: tools.map(t => t.name),
+          timestamp: new Date().toISOString()
+        }, `Returning ${tools.length} tool definitions`);
+        
+        const response: SSEMessage = {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: { tools },
+        };
+        this.sendMessage(sessionId, response);
+      } else if (message.method === 'tools/call') {
+        const params = message.params as { name: string; arguments?: Record<string, unknown> };
+        const toolName = params.name;
+        const args = params.arguments || {};
+
+        logger.info({ 
+          type: 'sse_tool_call',
+          sessionId, 
+          toolName,
+          userId: session.userId,
+          email: session.email,
+          argsPreview: JSON.stringify(args).substring(0, 200),
+          timestamp: new Date().toISOString()
+        }, `Executing tool: ${toolName}`);
+        
+        logToolStep(toolName, 'Tool call initiated via SSE', { 
+          sessionId, 
+          userId: session.userId,
+          email: session.email
+        });
+
+        try {
+          // Check permissions if user is authenticated
+          if (session.userId && session.groups && session.groups.length > 0) {
+            logToolStep(toolName, 'Checking tool permissions', { 
+              userId: session.userId,
+              email: session.email,
+              groups: session.groups
+            });
+            
+            const permissionStartTime = Date.now();
+            const permissionCheck = checkToolCallPermission(toolName, {
+              userId: session.userId,
+              email: session.email,
+              groups: session.groups,
+            });
+            const permissionDuration = Date.now() - permissionStartTime;
+
+            if (!permissionCheck.allowed) {
+              logger.warn(
+                { 
+                  type: 'sse_permission_denied',
+                  sessionId, 
+                  userId: session.userId, 
+                  email: session.email, 
+                  groups: session.groups, 
+                  toolName, 
+                  reason: permissionCheck.reason,
+                  duration: permissionDuration,
+                  timestamp: new Date().toISOString()
+                },
+                `Tool call permission denied for ${toolName}`
+              );
+              
+              const errorResponse: SSEMessage = {
+                jsonrpc: '2.0',
+                id: message.id,
+                error: {
+                  code: -32600, // Invalid Request
+                  message: permissionCheck.reason || 'Permission denied',
+                },
+              };
+              this.sendMessage(sessionId, errorResponse);
+              return;
+            }
+            
+            logger.debug({
+              type: 'sse_permission_granted',
+              sessionId,
+              userId: session.userId,
+              toolName,
+              duration: permissionDuration,
+              timestamp: new Date().toISOString()
+            }, `Permission granted for ${toolName}`);
+          }
+
+          logToolStep(toolName, 'Executing tool handler', { args });
+          const toolStartTime = Date.now();
+          
+          const result = await toolRegistry.callTool(toolName, args);
+          
+          const toolDuration = Date.now() - toolStartTime;
+          
+          // Log complete result
+          logger.info({ 
+            type: 'sse_tool_success',
+            sessionId, 
+            toolName, 
+            userId: session.userId,
+            resultType: typeof result,
+            resultPreview: JSON.stringify(result).substring(0, 500),
+            duration: toolDuration,
+            timestamp: new Date().toISOString()
+          }, `Tool ${toolName} executed successfully`);
+          
+          logToolStep(toolName, 'Tool execution completed', { 
+            duration: toolDuration,
+            resultSize: JSON.stringify(result).length
+          });
+          
+          const response: SSEMessage = {
+            jsonrpc: '2.0',
+            id: message.id,
+            result,
+          };
+          this.sendMessage(sessionId, response);
+        } catch (error) {
+          const toolDuration = Date.now() - messageStartTime;
+          
+          logger.error({
+            type: 'sse_tool_error',
+            sessionId,
+            toolName,
+            userId: session.userId,
+            error: error instanceof Error ? {
+              message: error.message,
+              stack: error.stack,
+              name: error.name
+            } : String(error),
+            duration: toolDuration,
+            timestamp: new Date().toISOString()
+          }, `Tool ${toolName} execution failed`);
+          
+          const errorResponse: SSEMessage = {
+            jsonrpc: '2.0',
+            id: message.id,
+            error: {
+              code: -32603,
+              message: error instanceof Error ? error.message : 'Tool execution failed',
+              data: error,
+            },
+          };
+          this.sendMessage(sessionId, errorResponse);
+        }
+      } else if (message.method === 'initialize') {
+        logger.info({
+          type: 'sse_initialize',
+          sessionId,
+          timestamp: new Date().toISOString()
+        }, 'Client initialization request');
+        
+        const response: SSEMessage = {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: {
+              tools: {},
+            },
+            serverInfo: {
+              name: 'csp-ai-agent-mcp',
+              version: '0.2.0',
+            },
+          },
+        };
+        this.sendMessage(sessionId, response);
+      } else if (message.method === 'ping') {
+        // Keepalive ping
+        logger.debug({
+          type: 'sse_ping',
+          sessionId,
+          timestamp: new Date().toISOString()
+        }, 'Keepalive ping received');
+        
+        const response: SSEMessage = {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: { type: 'pong' },
+        };
+        this.sendMessage(sessionId, response);
+      } else {
+        // Unknown method
+        logger.warn({
+          type: 'sse_unknown_method',
+          sessionId,
+          method: message.method,
+          timestamp: new Date().toISOString()
+        }, `Unknown method: ${message.method}`);
+        
+        const errorResponse: SSEMessage = {
+          jsonrpc: '2.0',
+          id: message.id,
+          error: {
+            code: -32601,
+            message: `Method not found: ${message.method}`,
+          },
+        };
+        this.sendMessage(sessionId, errorResponse);
+      }
+    } catch (error) {
+      logger.error({ error, sessionId }, 'Error handling message');
+      const errorResponse: SSEMessage = {
+        jsonrpc: '2.0',
+        id: message.id,
+        error: {
+          code: -32603,
+          message: error instanceof Error ? error.message : 'Internal error',
+        },
+      };
+      this.sendMessage(sessionId, errorResponse);
+    }
+  }
+
+  /**
+   * Send message to client via SSE
+   */
+  private sendMessage(sessionId: string, message: SSEMessage): void {
+    const sent = sessionManager.sendMessage(sessionId, message);
+    if (!sent) {
+      logger.warn({ sessionId, messageId: message.id }, 'Failed to send message to client');
+    }
+  }
+}
+
+// Singleton instance
+export const sseTransport = new SSETransport();

package/src/types/errors.ts

@@ -0,0 +1,146 @@
+/**
+ * Custom Error Types
+ * Typed errors for different failure scenarios
+ */
+
+/**
+ * Base Error for MCP Server operations
+ */
+export class MCPServerError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Git Operation Error
+ */
+export class GitError extends MCPServerError {
+  constructor(
+    message: string,
+    public readonly operation: string,
+    public readonly repositoryUrl?: string,
+    details?: unknown
+  ) {
+    super(message, 'GIT_ERROR', details);
+    
+    // Redact credentials from repository URL
+    if (this.repositoryUrl) {
+      this.repositoryUrl = this.redactCredentials(this.repositoryUrl);
+    }
+  }
+
+  private redactCredentials(url: string): string {
+    return url.replace(/:\/\/([^:]+):([^@]+)@/, '://***:***@');
+  }
+}
+
+/**
+ * API Request Error
+ */
+export class APIError extends MCPServerError {
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+    public readonly method?: string,
+    public readonly url?: string,
+    public readonly retryCount?: number,
+    details?: unknown
+  ) {
+    super(message, 'API_ERROR', details);
+  }
+}
+
+/**
+ * Resource Validation Error
+ */
+export class ValidationError extends MCPServerError {
+  constructor(
+    message: string,
+    public readonly filePath?: string,
+    public readonly expectedFormat?: string,
+    public readonly validationReason?: string,
+    details?: unknown
+  ) {
+    super(message, 'VALIDATION_ERROR', details);
+  }
+}
+
+/**
+ * Filesystem Operation Error
+ */
+export class FileSystemError extends MCPServerError {
+  constructor(
+    message: string,
+    public readonly operation: string,
+    public readonly path?: string,
+    public readonly systemErrorCode?: string,
+    public readonly suggestedResolution?: string,
+    details?: unknown
+  ) {
+    super(message, 'FILESYSTEM_ERROR', details);
+  }
+}
+
+/**
+ * Error Factory Functions
+ */
+
+export function createGitError(
+  operation: string,
+  error: Error,
+  repositoryUrl?: string
+): GitError {
+  return new GitError(
+    `Git ${operation} failed: ${error.message}`,
+    operation,
+    repositoryUrl,
+    { originalError: error }
+  );
+}
+
+export function createAPIError(
+  method: string,
+  url: string,
+  error: Error,
+  statusCode?: number,
+  retryCount?: number
+): APIError {
+  const message = `API ${method} ${url} failed: ${error.message}`;
+  return new APIError(message, statusCode, method, url, retryCount, { originalError: error });
+}
+
+export function createValidationError(
+  filePath: string,
+  expectedFormat: string,
+  reason: string
+): ValidationError {
+  return new ValidationError(
+    `Resource validation failed: ${reason}`,
+    filePath,
+    expectedFormat,
+    reason
+  );
+}
+
+export function createFileSystemError(
+  operation: string,
+  path: string,
+  error: Error & { code?: string },
+  suggestedResolution?: string
+): FileSystemError {
+  return new FileSystemError(
+    `Filesystem ${operation} failed: ${error.message}`,
+    operation,
+    path,
+    error.code,
+    suggestedResolution,
+    { originalError: error }
+  );
+}

package/src/types/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Type Exports
+ */
+
+export * from './mcp';
+export * from './tools';
+export * from './errors';

package/src/types/mcp.ts

@@ -0,0 +1,61 @@
+/**
+ * MCP Protocol Types
+ */
+
+// MCP Tool Schema
+export interface MCPToolSchema {
+  type: 'object';
+  properties: Record<string, {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+  }>;
+  required?: string[];
+}
+
+// MCP Tool Definition
+export interface MCPToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: MCPToolSchema;
+}
+
+// MCP Initialize Request
+export interface MCPInitializeRequest {
+  protocolVersion: string;
+  capabilities: {
+    tools?: Record<string, never>;
+  };
+  clientInfo: {
+    name: string;
+    version: string;
+  };
+}
+
+// MCP Initialize Response
+export interface MCPInitializeResponse {
+  protocolVersion: string;
+  capabilities: {
+    tools?: Record<string, never>;
+  };
+  serverInfo: {
+    name: string;
+    version: string;
+  };
+}
+
+// MCP Tool Call Request
+export interface MCPToolCallRequest {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+// MCP Tool Call Response
+export interface MCPToolCallResponse {
+  content: Array<{
+    type: 'text';
+    text: string;
+  }>;
+  isError?: boolean;
+}

package/src/types/resources.ts

@@ -0,0 +1,141 @@
+/**
+ * AI Resources Type Definitions
+ * Defines types for multi-source AI resource management
+ */
+
+/**
+ * Resource type enumeration
+ */
+export type ResourceType = 'commands' | 'skills' | 'mcp' | 'rules';
+
+/**
+ * Resource source configuration
+ */
+export interface ResourceSource {
+  /** Source name (identifier) */
+  name: string;
+  
+  /** Relative path to AI-Resources root */
+  path: string;
+  
+  /** Whether this source is enabled */
+  enabled: boolean;
+  
+  /** Priority (higher number = higher priority) */
+  priority: number;
+  
+  /** Mapping of resource types to subdirectories */
+  resources: Partial<Record<ResourceType, string>>;
+  
+  /** Optional description */
+  description?: string;
+}
+
+/**
+ * AI Resources configuration
+ */
+export interface AIResourcesConfig {
+  /** Configuration version */
+  version: string;
+  
+  /** Optional description */
+  description?: string;
+  
+  /** Default resource source (always loaded) */
+  default_source: ResourceSource;
+  
+  /** Extended resource sources */
+  extended_sources: ResourceSource[];
+  
+  /** Supported resource types */
+  resource_types: ResourceType[];
+  
+  /** Loading order strategy */
+  loading_order: 'priority_desc' | 'priority_asc' | 'name_asc';
+  
+  /** Conflict resolution strategy */
+  conflict_resolution: 'highest_priority_wins' | 'merge' | 'error';
+  
+  /** Cache configuration */
+  cache?: {
+    enabled: boolean;
+    ttl: number; // seconds
+  };
+}
+
+/**
+ * Resource metadata
+ */
+export interface ResourceMetadata {
+  /** Resource ID */
+  id: string;
+  
+  /** Resource name */
+  name: string;
+  
+  /** Resource type */
+  type: ResourceType;
+  
+  /** Source name */
+  source: string;
+  
+  /** Source priority */
+  priority: number;
+  
+  /** Full file path */
+  path: string;
+  
+  /** Version (if available) */
+  version?: string;
+  
+  /** Description (if available) */
+  description?: string;
+  
+  /** Tags (if available) */
+  tags?: string[];
+}
+
+/**
+ * Resource conflict information
+ */
+export interface ResourceConflict {
+  /** Resource name */
+  name: string;
+  
+  /** Resource type */
+  type: ResourceType;
+  
+  /** Conflicting resources */
+  conflicts: Array<{
+    source: string;
+    priority: number;
+    path: string;
+  }>;
+  
+  /** Selected resource (after conflict resolution) */
+  selected: {
+    source: string;
+    priority: number;
+    path: string;
+  };
+}
+
+/**
+ * Resource loader statistics
+ */
+export interface LoaderStats {
+  /** Total sources loaded */
+  sourcesLoaded: number;
+  
+  /** Total resources indexed */
+  resourcesIndexed: number;
+  
+  /** Resources by type */
+  byType: Record<ResourceType, number>;
+  
+  /** Conflicts detected */
+  conflictsDetected: number;
+  
+  /** Load duration (ms) */
+  loadDuration: number;
+}