claude-brain 0.30.2 → 0.30.3

package/src/server/mcp-server.ts

@@ -1,284 +1,285 @@
-/**
- * Claude Brain MCP Server
- * Main MCP server implementation using the Model Context Protocol SDK
- * Phase 6.5: Enhanced with system prompts and resources
- */
-
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema
-} from '@modelcontextprotocol/sdk/types.js'
-import type { Logger } from 'pino'
-import type { Config } from '@/config'
-import type { ConnectionState, ServerStatus, ServerOptions, ServerEvents } from './types'
-import { PromptProvider } from './providers/prompts'
-import { ResourceProvider } from './providers/resources'
-
-export class ClaudeBrainMCPServer {
-  private server: Server
-  private logger: Logger
-  private config: Config
-  private isRunning: boolean = false
-  private connectionState: ConnectionState = 'disconnected'
-  private startedAt?: Date
-  private requestCount: number = 0
-  private events: ServerEvents
-
-  // Phase 6.5: Prompt and Resource providers
-  private promptProvider: PromptProvider
-  private resourceProvider: ResourceProvider
-
-  constructor(config: Config, logger: Logger, options: ServerOptions = {}) {
-    this.config = config
-    this.logger = logger.child({ component: 'mcp-server' })
-    this.events = options.events || {}
-
-    // Phase 6.5: Initialize providers
-    this.promptProvider = new PromptProvider(logger)
-    this.resourceProvider = new ResourceProvider(logger)
-
-    // Initialize MCP Server with metadata and enhanced capabilities
-    this.server = new Server(
-      {
-        name: config.serverName,
-        version: config.serverVersion
-      },
-      {
-        capabilities: {
-          tools: {},
-          prompts: {},    // Phase 6.5: Enable prompts
-          resources: {}   // Phase 6.5: Enable resources
-        }
-      }
-    )
-
-    // Setup request handlers
-    this.setupHandlers()
-
-    // Setup error handling
-    this.setupErrorHandling()
-
-    this.logger.debug('MCP server instance created with Phase 6.5 enhancements')
-  }
-
-  /**
-   * Setup MCP request handlers for tools, prompts, and resources
-   */
-  private setupHandlers(): void {
-    // Handle tools/list request
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      this.logger.debug('Handling tools/list request')
-
-      // Import dynamically to avoid circular dependencies
-      const { handleListTools } = await import('./handlers/list-tools')
-      return await handleListTools()
-    })
-
-    // Handle tools/call request
-    // @ts-expect-error - SDK handler type expects extra param we don't use
-    this.server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
-      const toolName = request.params.name
-      const args = request.params.arguments || {}
-
-      this.requestCount++
-      const requestId = `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`
-
-      this.logger.debug({
-        tool: toolName,
-        args,
-        requestId
-      }, 'Handling tools/call request')
-
-      // Emit request event
-      this.events.onRequest?.(toolName, requestId)
-
-      const startTime = Date.now()
-
-      try {
-        // Import dynamically to avoid circular dependencies
-        const { handleCallTool } = await import('./handlers/call-tool')
-        const result = await handleCallTool(toolName, args, this.logger)
-
-        const duration = Date.now() - startTime
-        this.logger.debug({
-          tool: toolName,
-          requestId,
-          durationMs: duration
-        }, 'Tool call completed')
-
-        // Emit response event
-        this.events.onResponse?.(toolName, requestId, duration)
-
-        return result
-      } catch (error) {
-        const duration = Date.now() - startTime
-        this.logger.error({
-          tool: toolName,
-          requestId,
-          durationMs: duration,
-          error: error instanceof Error ? error.message : String(error)
-        }, 'Tool call failed')
-
-        throw error
-      }
-    })
-
-    // Phase 6.5: Handle prompts/list request
-    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
-      this.logger.debug('Handling prompts/list request')
-      return await this.promptProvider.listPrompts()
-    })
-
-    // Phase 6.5: Handle prompts/get request
-    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      this.logger.debug({ name: request.params.name }, 'Handling prompts/get request')
-      return await this.promptProvider.getPrompt(request.params.name)
-    })
-
-    // Phase 6.5: Handle resources/list request
-    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
-      this.logger.debug('Handling resources/list request')
-      return await this.resourceProvider.listResources()
-    })
-
-    // Phase 6.5: Handle resources/read request
-    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      this.logger.debug({ uri: request.params.uri }, 'Handling resources/read request')
-      return await this.resourceProvider.readResource(request.params.uri)
-    })
-
-    this.logger.debug('Request handlers configured (tools, prompts, resources)')
-  }
-
-  /**
-   * Setup error handling for the server
-   */
-  private setupErrorHandling(): void {
-    this.server.onerror = (error) => {
-      this.logger.error({
-        error: error instanceof Error ? {
-          message: error.message,
-          stack: error.stack,
-          name: error.name
-        } : error
-      }, 'MCP server error')
-
-      this.events.onError?.(error instanceof Error ? error : new Error(String(error)))
-    }
-  }
-
-  /**
-   * Update connection state and emit events
-   */
-  private setConnectionState(state: ConnectionState): void {
-    const previousState = this.connectionState
-    this.connectionState = state
-
-    if (previousState !== state) {
-      this.logger.info({
-        previousState,
-        newState: state
-      }, 'Connection state changed')
-
-      this.events.onConnectionStateChange?.(state)
-    }
-  }
-
-  /**
-   * Start the MCP server and connect via stdio transport
-   */
-  async start(): Promise<void> {
-    if (this.isRunning) {
-      this.logger.warn('Server already running')
-      return
-    }
-
-    try {
-      this.logger.info('Starting MCP server...')
-      this.setConnectionState('connecting')
-
-      const transport = new StdioServerTransport()
-      await this.server.connect(transport)
-
-      this.isRunning = true
-      this.startedAt = new Date()
-      this.setConnectionState('connected')
-
-      this.logger.info({
-        name: this.config.serverName,
-        version: this.config.serverVersion,
-        startedAt: this.startedAt.toISOString()
-      }, 'MCP server started successfully')
-
-    } catch (error) {
-      this.setConnectionState('disconnected')
-      this.logger.error({
-        error: error instanceof Error ? {
-          message: error.message,
-          stack: error.stack
-        } : error
-      }, 'Failed to start MCP server')
-      throw error
-    }
-  }
-
-  /**
-   * Stop the MCP server gracefully
-   */
-  async stop(): Promise<void> {
-    if (!this.isRunning) {
-      this.logger.debug('Server not running, skip stop')
-      return
-    }
-
-    try {
-      this.logger.info('Stopping MCP server...')
-      await this.server.close()
-
-      this.isRunning = false
-      this.setConnectionState('disconnected')
-
-      this.logger.info({
-        totalRequests: this.requestCount,
-        uptimeMs: this.startedAt ? Date.now() - this.startedAt.getTime() : 0
-      }, 'MCP server stopped')
-
-    } catch (error) {
-      this.logger.error({
-        error: error instanceof Error ? {
-          message: error.message,
-          stack: error.stack
-        } : error
-      }, 'Error stopping MCP server')
-      throw error
-    }
-  }
-
-  /**
-   * Get current server status
-   */
-  getStatus(): ServerStatus {
-    return {
-      running: this.isRunning,
-      name: this.config.serverName,
-      version: this.config.serverVersion,
-      connectionState: this.connectionState,
-      startedAt: this.startedAt,
-      requestCount: this.requestCount,
-      capabilities: ['tools', 'prompts', 'resources']
-    }
-  }
-
-  /**
-   * Health check method
-   */
-  isHealthy(): boolean {
-    return this.isRunning && this.connectionState === 'connected'
-  }
-}
+/**
+ * Claude Brain MCP Server
+ * Main MCP server implementation using the Model Context Protocol SDK
+ * Phase 6.5: Enhanced with system prompts and resources
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js'
+import type { Logger } from 'pino'
+import type { Config } from '@/config'
+import type { ConnectionState, ServerStatus, ServerOptions, ServerEvents } from './types'
+import { PromptProvider } from './providers/prompts'
+import { ResourceProvider } from './providers/resources'
+
+export class ClaudeBrainMCPServer {
+  private server: Server
+  private logger: Logger
+  private config: Config
+  private isRunning: boolean = false
+  private connectionState: ConnectionState = 'disconnected'
+  private startedAt?: Date
+  private requestCount: number = 0
+  private events: ServerEvents
+
+  // Phase 6.5: Prompt and Resource providers
+  private promptProvider: PromptProvider
+  private resourceProvider: ResourceProvider
+
+  constructor(config: Config, logger: Logger, options: ServerOptions = {}) {
+    this.config = config
+    this.logger = logger.child({ component: 'mcp-server' })
+    this.events = options.events || {}
+
+    // Phase 6.5: Initialize providers
+    this.promptProvider = new PromptProvider(logger)
+    this.resourceProvider = new ResourceProvider(logger)
+
+    // Initialize MCP Server with metadata and enhanced capabilities
+    this.server = new Server(
+      {
+        name: config.serverName,
+        version: config.serverVersion
+      },
+      {
+        capabilities: {
+          tools: {},
+          prompts: {},    // Phase 6.5: Enable prompts
+          resources: {}   // Phase 6.5: Enable resources
+        }
+      }
+    )
+
+    // Setup request handlers
+    this.setupHandlers()
+
+    // Setup error handling
+    this.setupErrorHandling()
+
+    this.logger.debug('MCP server instance created with Phase 6.5 enhancements')
+  }
+
+  /**
+   * Setup MCP request handlers for tools, prompts, and resources
+   */
+  private setupHandlers(): void {
+    // Handle tools/list request
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      this.logger.debug('Handling tools/list request')
+
+      // Import dynamically to avoid circular dependencies
+      const { handleListTools } = await import('./handlers/list-tools')
+      return await handleListTools()
+    })
+
+    // Handle tools/call request
+    // @ts-expect-error - SDK handler type expects extra param we don't use
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- MCP SDK request handler type
+    this.server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
+      const toolName = request.params.name
+      const args = request.params.arguments || {}
+
+      this.requestCount++
+      const requestId = `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`
+
+      this.logger.debug({
+        tool: toolName,
+        args,
+        requestId
+      }, 'Handling tools/call request')
+
+      // Emit request event
+      this.events.onRequest?.(toolName, requestId)
+
+      const startTime = Date.now()
+
+      try {
+        // Import dynamically to avoid circular dependencies
+        const { handleCallTool } = await import('./handlers/call-tool')
+        const result = await handleCallTool(toolName, args, this.logger)
+
+        const duration = Date.now() - startTime
+        this.logger.debug({
+          tool: toolName,
+          requestId,
+          durationMs: duration
+        }, 'Tool call completed')
+
+        // Emit response event
+        this.events.onResponse?.(toolName, requestId, duration)
+
+        return result
+      } catch (error) {
+        const duration = Date.now() - startTime
+        this.logger.error({
+          tool: toolName,
+          requestId,
+          durationMs: duration,
+          error: error instanceof Error ? error.message : String(error)
+        }, 'Tool call failed')
+
+        throw error
+      }
+    })
+
+    // Phase 6.5: Handle prompts/list request
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      this.logger.debug('Handling prompts/list request')
+      return await this.promptProvider.listPrompts()
+    })
+
+    // Phase 6.5: Handle prompts/get request
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      this.logger.debug({ name: request.params.name }, 'Handling prompts/get request')
+      return await this.promptProvider.getPrompt(request.params.name)
+    })
+
+    // Phase 6.5: Handle resources/list request
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      this.logger.debug('Handling resources/list request')
+      return await this.resourceProvider.listResources()
+    })
+
+    // Phase 6.5: Handle resources/read request
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      this.logger.debug({ uri: request.params.uri }, 'Handling resources/read request')
+      return await this.resourceProvider.readResource(request.params.uri)
+    })
+
+    this.logger.debug('Request handlers configured (tools, prompts, resources)')
+  }
+
+  /**
+   * Setup error handling for the server
+   */
+  private setupErrorHandling(): void {
+    this.server.onerror = (error) => {
+      this.logger.error({
+        error: error instanceof Error ? {
+          message: error.message,
+          stack: error.stack,
+          name: error.name
+        } : error
+      }, 'MCP server error')
+
+      this.events.onError?.(error instanceof Error ? error : new Error(String(error)))
+    }
+  }
+
+  /**
+   * Update connection state and emit events
+   */
+  private setConnectionState(state: ConnectionState): void {
+    const previousState = this.connectionState
+    this.connectionState = state
+
+    if (previousState !== state) {
+      this.logger.info({
+        previousState,
+        newState: state
+      }, 'Connection state changed')
+
+      this.events.onConnectionStateChange?.(state)
+    }
+  }
+
+  /**
+   * Start the MCP server and connect via stdio transport
+   */
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      this.logger.warn('Server already running')
+      return
+    }
+
+    try {
+      this.logger.info('Starting MCP server...')
+      this.setConnectionState('connecting')
+
+      const transport = new StdioServerTransport()
+      await this.server.connect(transport)
+
+      this.isRunning = true
+      this.startedAt = new Date()
+      this.setConnectionState('connected')
+
+      this.logger.info({
+        name: this.config.serverName,
+        version: this.config.serverVersion,
+        startedAt: this.startedAt.toISOString()
+      }, 'MCP server started successfully')
+
+    } catch (error) {
+      this.setConnectionState('disconnected')
+      this.logger.error({
+        error: error instanceof Error ? {
+          message: error.message,
+          stack: error.stack
+        } : error
+      }, 'Failed to start MCP server')
+      throw error
+    }
+  }
+
+  /**
+   * Stop the MCP server gracefully
+   */
+  async stop(): Promise<void> {
+    if (!this.isRunning) {
+      this.logger.debug('Server not running, skip stop')
+      return
+    }
+
+    try {
+      this.logger.info('Stopping MCP server...')
+      await this.server.close()
+
+      this.isRunning = false
+      this.setConnectionState('disconnected')
+
+      this.logger.info({
+        totalRequests: this.requestCount,
+        uptimeMs: this.startedAt ? Date.now() - this.startedAt.getTime() : 0
+      }, 'MCP server stopped')
+
+    } catch (error) {
+      this.logger.error({
+        error: error instanceof Error ? {
+          message: error.message,
+          stack: error.stack
+        } : error
+      }, 'Error stopping MCP server')
+      throw error
+    }
+  }
+
+  /**
+   * Get current server status
+   */
+  getStatus(): ServerStatus {
+    return {
+      running: this.isRunning,
+      name: this.config.serverName,
+      version: this.config.serverVersion,
+      connectionState: this.connectionState,
+      startedAt: this.startedAt,
+      requestCount: this.requestCount,
+      capabilities: ['tools', 'prompts', 'resources']
+    }
+  }
+
+  /**
+   * Health check method
+   */
+  isHealthy(): boolean {
+    return this.isRunning && this.connectionState === 'connected'
+  }
+}

package/src/server/middleware/auth.ts

@@ -0,0 +1,39 @@
+/**
+ * API Key Authentication Middleware
+ * Phase 1: Security Hardening
+ */
+
+import type { Context, Next } from 'hono'
+import { timingSafeEqual } from 'crypto'
+
+/**
+ * Verify API key from X-API-Key header or Authorization: Bearer <key>
+ * Returns 401 if no key, 403 if invalid key.
+ */
+export function apiKeyAuth(apiKey: string | undefined) {
+  return async (c: Context, next: Next) => {
+    // If no API key configured, skip auth (local-only mode)
+    if (!apiKey) {
+      await next()
+      return
+    }
+
+    // Extract key from header
+    const headerKey = c.req.header('X-API-Key')
+      || c.req.header('Authorization')?.replace('Bearer ', '')
+
+    if (!headerKey) {
+      return c.json({ error: 'Authentication required. Provide X-API-Key header.' }, 401)
+    }
+
+    // Timing-safe comparison to prevent timing attacks
+    const expected = Buffer.from(apiKey)
+    const received = Buffer.from(headerKey)
+
+    if (expected.length !== received.length || !timingSafeEqual(expected, received)) {
+      return c.json({ error: 'Invalid API key' }, 403)
+    }
+
+    await next()
+  }
+}

package/src/server/middleware/error-handler.ts

@@ -0,0 +1,37 @@
+/**
+ * Error Handler Middleware
+ * Phase 1: Security Hardening
+ *
+ * Catches unhandled errors and returns sanitized responses.
+ * Full error details are logged internally, only safe messages are returned to clients.
+ */
+
+import type { Context, Next } from 'hono'
+import type { Logger } from 'pino'
+
+export function errorHandler(logger: Logger) {
+  return async (c: Context, next: Next) => {
+    try {
+      await next()
+    } catch (error) {
+      const requestId = crypto.randomUUID().slice(0, 8)
+
+      // Log full error internally
+      logger.error({
+        error,
+        requestId,
+        method: c.req.method,
+        path: c.req.path,
+      }, 'Unhandled API error')
+
+      // Return sanitized error to client
+      const status = (error && typeof error === 'object' && 'status' in error && typeof (error as Record<string, unknown>).status === 'number')
+        ? (error as Record<string, unknown>).status as number
+        : 500
+      return c.json({
+        error: status >= 500 ? 'Internal server error' : (error as Error).message,
+        requestId,
+      }, status)
+    }
+  }
+}