Skip to content

CLAUDE.md

Latest commit

 

History

History
117 lines (92 loc) · 5.15 KB

CLAUDE.md

File metadata and controls

117 lines (92 loc) · 5.15 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Building and Running

npm run build                    # Compile TypeScript to dist/
npm start                       # Run with default transport (STDIO)
node dist/index.js              # Direct execution (equivalent to npm start)
node dist/index.js --http       # Run with HTTP transport on port 3000
node dist/index.js --stdio      # Run with STDIO transport (explicit)
PORT=8080 node dist/index.js --http  # HTTP transport on custom port

Testing

npm test                        # Run all tests once
npm run test:watch              # Run tests in watch mode
npm run test:coverage           # Run tests with coverage report
npx vitest run src/tools/       # Run specific test directory
npx vitest run --grep "HTTP"    # Run tests matching pattern

Code Quality

npm run lint                    # Lint code with Biome
npm run format                  # Format code with Biome
npm run check:format            # Check formatting without modifying files
npx @biomejs/biome check --fix --unsafe  # Fix import organization

Docker Development

npm run docker:build           # Build Docker image
npm run docker:run             # Run container locally (HTTP mode)
docker compose up -d            # Start with MinIO for testing
sh run-inspector.sh             # Debug with MCP Inspector (auto-detects transport)
sh run-inspector.sh --docker --stdio   # Debug in Docker with STDIO
sh run-inspector.sh --docker --http    # Debug in Docker with HTTP

Architecture Overview

This is an AWS S3 Model Context Protocol (MCP) server with a modular architecture supporting multiple transport protocols (STDIO, HTTP, StreamableHTTP).

Modular Transport Architecture

Application Layer (src/application.ts)

  • Main Application class with dependency injection and configuration management
  • Handles CLI argument parsing and environment setup
  • Orchestrates transport factory creation and server initialization

Entry Point (src/index.ts)

  • Minimal bootstrap that creates Application instance with parsed CLI arguments
  • Supports --stdio, --http, and transport auto-detection based on environment
  • Handles process exit and error scenarios gracefully

Transport Abstraction (src/transports/)

  • ITransport interface provides consistent contract for all transport types
  • ITransportFactory enables runtime transport selection via factory pattern
  • StdioTransport: Direct process communication (default for Claude Desktop)
  • HttpTransport: REST API + Server-Sent Events with session management
  • Supports both StreamableHTTP and traditional HTTP with proper MCP protocol compliance

MCP Server (src/server.ts)

  • Creates McpServer instance with S3 tools registration
  • Transport-agnostic server configuration
  • Tool registration via factory pattern from src/tools/index.ts

Core Components

S3 Resource Layer (src/resources/s3.ts)

  • Centralized AWS S3 client management and configuration
  • Bucket access validation and filtering based on S3_BUCKETS environment variable
  • Provides core S3 operations with error handling and type safety

Tools Layer (src/tools/)

  • Individual MCP tools implementing IMCPTool interface
  • Each tool (ListBuckets, ListObjects, GetObject) wraps S3Resource operations
  • Consistent error handling and response formatting across all tools

HTTP Mock Utilities (src/utils/httpMock.ts)

  • Bridges Hono HTTP context to Node.js IncomingMessage/ServerResponse
  • Enables StreamableHTTPServerTransport compatibility with Hono framework
  • Handles session management and streaming response creation

Key Design Patterns

  • SOLID Principles: Single responsibility, open/closed, dependency inversion throughout
  • Factory Pattern: Transport and tool creation through factory functions
  • Dependency Injection: Application class receives configuration, transport injection
  • Transport Abstraction: Unified interface supporting STDIO, HTTP, and streaming protocols
  • Session Management: HTTP transport maintains stateful MCP sessions with proper initialization

Critical Environment Variables

  • S3_BUCKETS: Comma-separated list of allowed buckets (security control)
  • AWS_REGION: AWS region for S3 operations
  • S3_MAX_BUCKETS: Limits bucket listing results
  • PORT: HTTP server port (default: 3000)
  • MCP_TRANSPORT: Force specific transport type ("stdio" or "http")

Protocol Compliance

MCP Session Lifecycle: HTTP transport requires proper session initialization before tool calls

  • Clients must send initialize request before tools/list or tools/call
  • Sessions are identified by sessionId query parameter or mcp-session-id header
  • StreamableHTTPServerTransport validates Accept headers: requires both application/json and text/event-stream

Testing Architecture

  • Unit Tests: Mocked AWS SDK clients with Vitest
  • Integration Tests: Real HTTP server startup with session management testing
  • SSE Testing: TransformStream and streaming response validation
  • Docker Integration: MinIO compatibility testing via Docker Compose