claude-brain 0.3.0

package/src/server/utils/request-context.ts

@@ -0,0 +1,122 @@
+/**
+ * Request Context
+ * Utilities for tracking request context and timing
+ */
+
+import { randomUUID } from 'crypto'
+
+/**
+ * RequestContext tracks information about a single request
+ */
+export class RequestContext {
+  /** Unique identifier for this request */
+  readonly id: string
+
+  /** Timestamp when request started */
+  readonly startTime: number
+
+  /** Name of the tool being called (if applicable) */
+  readonly toolName?: string
+
+  /** Additional metadata for this request */
+  readonly metadata: Record<string, unknown>
+
+  /**
+   * Create a new RequestContext
+   * @param toolName - Optional tool name for this request
+   * @param metadata - Optional additional metadata
+   */
+  constructor(toolName?: string, metadata: Record<string, unknown> = {}) {
+    this.id = randomUUID()
+    this.startTime = Date.now()
+    this.toolName = toolName
+    this.metadata = metadata
+  }
+
+  /**
+   * Get the duration since request started
+   * @returns Duration in milliseconds
+   */
+  getDuration(): number {
+    return Date.now() - this.startTime
+  }
+
+  /**
+   * Get context information suitable for logging
+   * @returns Object with request context for logs
+   */
+  toLogContext(): Record<string, unknown> {
+    return {
+      requestId: this.id,
+      toolName: this.toolName,
+      durationMs: this.getDuration(),
+      ...this.metadata
+    }
+  }
+
+  /**
+   * Create a child context with additional metadata
+   * @param additionalMetadata - Additional metadata to include
+   * @returns New context object for logging
+   */
+  withMetadata(additionalMetadata: Record<string, unknown>): Record<string, unknown> {
+    return {
+      ...this.toLogContext(),
+      ...additionalMetadata
+    }
+  }
+}
+
+/**
+ * Timer for measuring operation duration
+ */
+export class Timer {
+  private readonly startTime: number
+  private endTime?: number
+
+  constructor() {
+    this.startTime = performance.now()
+  }
+
+  /**
+   * Stop the timer
+   * @returns Duration in milliseconds
+   */
+  stop(): number {
+    this.endTime = performance.now()
+    return this.getDuration()
+  }
+
+  /**
+   * Get current duration (without stopping)
+   * @returns Duration in milliseconds
+   */
+  getDuration(): number {
+    const end = this.endTime ?? performance.now()
+    return Math.round(end - this.startTime)
+  }
+
+  /**
+   * Check if timer has been stopped
+   * @returns true if stopped
+   */
+  isStopped(): boolean {
+    return this.endTime !== undefined
+  }
+}
+
+/**
+ * Create a new timer
+ * @returns Timer instance
+ */
+export function createTimer(): Timer {
+  return new Timer()
+}
+
+/**
+ * Generate a short request ID
+ * @returns Short unique ID string
+ */
+export function generateShortId(): string {
+  return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`
+}

package/src/server/utils/response-formatter.ts

@@ -0,0 +1,124 @@
+/**
+ * Response Formatter
+ * Utilities for formatting MCP tool responses
+ */
+
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js'
+import type { ToolResponse } from '@/tools/types'
+
+/**
+ * ResponseFormatter provides methods for creating properly formatted MCP responses
+ */
+export class ResponseFormatter {
+  /**
+   * Format text content for MCP response
+   * @param content - Text content to include in response
+   * @returns Properly formatted ToolResponse
+   */
+  static text(content: string): ToolResponse {
+    return {
+      content: [{
+        type: 'text',
+        text: content
+      }]
+    }
+  }
+
+  /**
+   * Format multiple text blocks for MCP response
+   * @param contents - Array of text content
+   * @returns Properly formatted ToolResponse with multiple content blocks
+   */
+  static multiText(contents: string[]): ToolResponse {
+    return {
+      content: contents.map(text => ({
+        type: 'text' as const,
+        text
+      }))
+    }
+  }
+
+  /**
+   * Format error as MCP error (throws)
+   * @param message - Error message
+   * @param code - MCP error code
+   * @throws McpError
+   */
+  static error(message: string, code: ErrorCode = ErrorCode.InternalError): never {
+    throw new McpError(code, message)
+  }
+
+  /**
+   * Format error response (returns response with isError flag)
+   * @param message - Error message
+   * @returns ToolResponse with error flag
+   */
+  static errorResponse(message: string): ToolResponse {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: ${message}`
+      }],
+      isError: true
+    }
+  }
+
+  /**
+   * Format structured data as formatted text
+   * @param data - Object to format
+   * @returns Properly formatted ToolResponse
+   */
+  static structured(data: Record<string, unknown>): ToolResponse {
+    const formatted = Object.entries(data)
+      .map(([key, value]) => {
+        const formattedValue = typeof value === 'object'
+          ? JSON.stringify(value, null, 2)
+          : String(value)
+        return `${key}: ${formattedValue}`
+      })
+      .join('\n\n')
+
+    return this.text(formatted)
+  }
+
+  /**
+   * Format JSON data as pretty-printed text
+   * @param data - Data to serialize as JSON
+   * @param label - Optional label to prefix the JSON
+   * @returns Properly formatted ToolResponse
+   */
+  static json(data: unknown, label?: string): ToolResponse {
+    const jsonStr = JSON.stringify(data, null, 2)
+    const content = label ? `${label}:\n${jsonStr}` : jsonStr
+    return this.text(content)
+  }
+
+  /**
+   * Format a list of items
+   * @param items - Array of items to format
+   * @param title - Optional title for the list
+   * @returns Properly formatted ToolResponse
+   */
+  static list(items: string[], title?: string): ToolResponse {
+    const listContent = items.map((item, i) => `${i + 1}. ${item}`).join('\n')
+    const content = title ? `${title}:\n${listContent}` : listContent
+    return this.text(content)
+  }
+
+  /**
+   * Format a success message
+   * @param message - Success message
+   * @param details - Optional additional details
+   * @returns Properly formatted ToolResponse
+   */
+  static success(message: string, details?: Record<string, unknown>): ToolResponse {
+    let content = `✓ ${message}`
+    if (details) {
+      const detailsStr = Object.entries(details)
+        .map(([k, v]) => `  ${k}: ${v}`)
+        .join('\n')
+      content += `\n\nDetails:\n${detailsStr}`
+    }
+    return this.text(content)
+  }
+}

package/src/server/utils/validators.ts

@@ -0,0 +1,210 @@
+/**
+ * Tool Validators
+ * Utilities for validating tool arguments
+ */
+
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+
+/**
+ * ToolValidator provides methods for validating tool inputs
+ */
+export class ToolValidator {
+  /**
+   * Validate tool arguments against a Zod schema
+   * @param args - Arguments to validate
+   * @param schema - Zod schema to validate against
+   * @returns Parsed and validated arguments
+   * @throws McpError if validation fails
+   */
+  static validate<T>(args: unknown, schema: z.ZodSchema<T>): T {
+    try {
+      return schema.parse(args)
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        const issues = error.issues
+          .map(issue => `${issue.path.join('.')}: ${issue.message}`)
+          .join(', ')
+        throw new McpError(
+          ErrorCode.InvalidParams,
+          `Invalid parameters: ${issues}`
+        )
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Validate and return a required string parameter
+   * @param value - Value to validate
+   * @param name - Parameter name for error messages
+   * @returns Validated string
+   * @throws McpError if validation fails
+   */
+  static requireString(value: unknown, name: string): string {
+    if (typeof value !== 'string') {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `${name} is required and must be a string`
+      )
+    }
+    if (value.trim() === '') {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `${name} cannot be empty`
+      )
+    }
+    return value
+  }
+
+  /**
+   * Get an optional string parameter with default
+   * @param value - Value to check
+   * @param defaultValue - Default value if not provided
+   * @returns String value or default
+   * @throws McpError if value is present but not a string
+   */
+  static optionalString(value: unknown, defaultValue: string = ''): string {
+    if (value === undefined || value === null) {
+      return defaultValue
+    }
+    if (typeof value !== 'string') {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        'Parameter must be a string'
+      )
+    }
+    return value
+  }
+
+  /**
+   * Validate and return a required number parameter
+   * @param value - Value to validate
+   * @param name - Parameter name for error messages
+   * @returns Validated number
+   * @throws McpError if validation fails
+   */
+  static requireNumber(value: unknown, name: string): number {
+    if (typeof value !== 'number' || isNaN(value)) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `${name} is required and must be a number`
+      )
+    }
+    return value
+  }
+
+  /**
+   * Get an optional number parameter with default
+   * @param value - Value to check
+   * @param defaultValue - Default value if not provided
+   * @returns Number value or default
+   * @throws McpError if value is present but not a number
+   */
+  static optionalNumber(value: unknown, defaultValue: number): number {
+    if (value === undefined || value === null) {
+      return defaultValue
+    }
+    if (typeof value !== 'number' || isNaN(value)) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        'Parameter must be a number'
+      )
+    }
+    return value
+  }
+
+  /**
+   * Validate and return a required boolean parameter
+   * @param value - Value to validate
+   * @param name - Parameter name for error messages
+   * @returns Validated boolean
+   * @throws McpError if validation fails
+   */
+  static requireBoolean(value: unknown, name: string): boolean {
+    if (typeof value !== 'boolean') {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `${name} is required and must be a boolean`
+      )
+    }
+    return value
+  }
+
+  /**
+   * Get an optional boolean parameter with default
+   * @param value - Value to check
+   * @param defaultValue - Default value if not provided
+   * @returns Boolean value or default
+   */
+  static optionalBoolean(value: unknown, defaultValue: boolean): boolean {
+    if (value === undefined || value === null) {
+      return defaultValue
+    }
+    if (typeof value !== 'boolean') {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        'Parameter must be a boolean'
+      )
+    }
+    return value
+  }
+
+  /**
+   * Validate and return a required array parameter
+   * @param value - Value to validate
+   * @param name - Parameter name for error messages
+   * @returns Validated array
+   * @throws McpError if validation fails
+   */
+  static requireArray<T>(value: unknown, name: string): T[] {
+    if (!Array.isArray(value)) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `${name} is required and must be an array`
+      )
+    }
+    return value as T[]
+  }
+
+  /**
+   * Get an optional array parameter with default
+   * @param value - Value to check
+   * @param defaultValue - Default value if not provided
+   * @returns Array value or default
+   */
+  static optionalArray<T>(value: unknown, defaultValue: T[] = []): T[] {
+    if (value === undefined || value === null) {
+      return defaultValue
+    }
+    if (!Array.isArray(value)) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        'Parameter must be an array'
+      )
+    }
+    return value as T[]
+  }
+
+  /**
+   * Validate value is one of allowed enum values
+   * @param value - Value to validate
+   * @param allowed - Array of allowed values
+   * @param name - Parameter name for error messages
+   * @returns Validated value
+   * @throws McpError if validation fails
+   */
+  static requireEnum<T extends string>(
+    value: unknown,
+    allowed: readonly T[],
+    name: string
+  ): T {
+    if (typeof value !== 'string' || !allowed.includes(value as T)) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `${name} must be one of: ${allowed.join(', ')}`
+      )
+    }
+    return value as T
+  }
+}

package/src/setup/index.ts

@@ -0,0 +1,22 @@
+import { createLogger } from '@/utils/logger'
+import { resolveHomePath } from '@/config/home'
+import { ensureHomeDirectory } from '@/cli/auto-setup'
+import { SetupWizard } from './wizard'
+
+export * from './wizard'
+
+export async function runSetup() {
+  ensureHomeDirectory()
+
+  const logger = createLogger('info', resolveHomePath('./logs/setup.log'))
+
+  try {
+    const wizard = new SetupWizard(logger)
+    const answers = await wizard.run()
+    await wizard.applyConfiguration(answers)
+
+  } catch (error) {
+    console.error('\nSetup failed:', error)
+    process.exit(1)
+  }
+}