Setup bullet-proof TypeScript + ESLint + Prettier configuration

- Migrated to flat ESLint config with strict type-only imports enforcement
- Added comprehensive async safety rules and type checking
- Configured minimal Prettier with high-signal settings only
- Setup pre-commit hooks with husky and lint-staged
- Added GitHub Actions CI workflow for automated validation
- Pinned Node types explicitly and updated tsconfig for NodeNext modules
- Fixed all ESLint warnings and type safety issues
- Cleaned up unused config files and dependencies

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: yigitkonur

.eslintrc.json

@@ -0,0 +1,16 @@
+name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: 'npm' }
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint:ci
+      - run: npm run format:check
+      - run: npm run build

.github/workflows/ci.yml

@@ -0,0 +1 @@
+npm exec lint-staged

.husky/pre-commit

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+coverage/

.prettierignore

@@ -1,21 +1,6 @@
 {
   "printWidth": 100,
-  "tabWidth": 2,
-  "useTabs": false,
-  "semi": true,
   "singleQuote": true,
-  "quoteProps": "as-needed",
-  "jsxSingleQuote": false,
   "trailingComma": "all",
-  "bracketSpacing": true,
-  "bracketSameLine": false,
-  "arrowParens": "always",
-  "requirePragma": false,
-  "insertPragma": false,
-  "proseWrap": "preserve",
-  "htmlWhitespaceSensitivity": "css",
-  "vueIndentScriptAndStyle": false,
-  "endOfLine": "lf",
-  "embeddedLanguageFormatting": "auto",
-  "singleAttributePerLine": false
-}
+  "semi": true
+}

.prettierrc.json

@@ -7,7 +7,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 This is an **Educational Reference Implementation** of a Stateless HTTP Streamable MCP Server. This is NOT just a simple example - it's a comprehensive teaching resource designed to demonstrate production-ready patterns, security best practices, and modern deployment strategies for Model Context Protocol servers.
 
 ### Educational Mission
+
 This repository serves as a **masterclass** in building stateless MCP servers, covering:
+
 - **Architecture Principles**: True stateless design enabling infinite scaling
 - **Security Engineering**: DNS rebinding protection, rate limiting, error sanitization
 - **SDK Integration**: Trust the SDK for protocol concerns, avoid redundant validation
@@ -17,30 +19,34 @@ This repository serves as a **masterclass** in building stateless MCP servers, c
 ### Core Architecture Patterns
 
 #### 1. Fresh Instance Per Request (The Golden Rule)
+
 ```typescript
 // In handleMCPRequest() - this happens for EVERY request:
-const server = createMCPServer();          // 1. Fresh server instance
+const server = createMCPServer(); // 1. Fresh server instance
 const transport = new StreamableHTTPServerTransport({
-  sessionIdGenerator: undefined,            // 2. Stateless mode (critical!)
-  enableDnsRebindingProtection: true,      // 3. Security by design
+  sessionIdGenerator: undefined, // 2. Stateless mode (critical!)
+  enableDnsRebindingProtection: true, // 3. Security by design
 });
-await server.connect(transport);           // 4. Connect ephemeral instances
-await transport.handleRequest(req, res);   // 5. Process single request
+await server.connect(transport); // 4. Connect ephemeral instances
+await transport.handleRequest(req, res); // 5. Process single request
 // 6. Cleanup happens in res.on('close') listener
 ```
 
 #### 2. SDK Trust Principle
+
 - **DO**: Let `StreamableHTTPServerTransport` handle protocol validation internally
 - **DON'T**: Create custom middleware to duplicate SDK validation logic
 - **WHY**: SDK is the source of truth; duplicating creates maintenance burden
 
 #### 3. Security-First Design
+
 - DNS rebinding protection (mandatory for local servers)
 - Rate limiting (1000 requests per 15-minute window)
 - Production error sanitization (hide stack traces)
 - Request size validation before JSON parsing
 
 #### 4. Clean Code Over Optimization
+
 - Simple object creation instead of object pooling
 - Idiomatic TypeScript patterns
 - Clear, maintainable code structure
@@ -49,13 +55,15 @@ await transport.handleRequest(req, res);   // 5. Process single request
 ## Key Implementation Details
 
 ### Server Configuration
+
 - **Port**: Always 1071 (not 3000)
 - **Architecture**: Stateless HTTP + SSE streaming
 - **Transport**: `StreamableHTTPServerTransport` with `sessionIdGenerator: undefined`
 - **Security**: DNS rebinding protection enabled by default
 - **Logging**: Structured JSON with request correlation via `requestId`
 
 ### File Structure
+
 ```
 src/
 ├── types.ts    # Data contracts (schemas, constants, interfaces)
@@ -70,27 +78,31 @@ src/
 ```
 
 ### Tools Implemented
+
 - `calculate`: Core arithmetic with progress notifications
 - `demo_progress`: Progress notification demonstration
 - `solve_math_problem`: Stub tool (shows graceful degradation)
 - `explain_formula`: Stub tool
 - `calculator_assistant`: Stub tool
 
 ### Resources Available
+
 - `calculator://constants`: Math constants (pi, e)
 - `calculator://stats`: Process uptime metrics
 - `calculator://history/*`: Always returns 404 (stateless limitation)
 - `formulas://library`: Mathematical formula collection
 - `request://current`: Current request metadata
 
 ### Prompts Defined
+
 - `explain-calculation`: Step-by-step calculation explanations
 - `generate-problems`: Practice problem generation
 - `calculator-tutor`: Interactive tutoring sessions
 
 ## Common Development Commands
 
 ### Essential Workflow
+
 ```bash
 # Install dependencies
 npm install
@@ -109,6 +121,7 @@ npm run ci
 ```
 
 ### Testing & Validation
+
 ```bash
 # Health checks
 curl http://localhost:1071/health
@@ -127,6 +140,7 @@ npx @modelcontextprotocol/inspector --cli http://localhost:1071/mcp
 ```
 
 ### Code Quality
+
 ```bash
 npm run lint           # ESLint checks
 npm run lint:fix       # Auto-fix linting issues
@@ -138,12 +152,14 @@ npm run format:check   # Check formatting without changes
 ## Critical Configuration Notes
 
 ### TypeScript Settings
+
 - Uses `"moduleResolution": "bundler"` (not "node")
 - Package.json has `"type": "module"`
 - Outputs ES modules to `dist/` with source maps and declarations
 - Strict TypeScript configuration enabled
 
 ### Environment Variables
+
 ```bash
 PORT=1071                    # Server port
 CORS_ORIGIN="*"             # CORS policy (restrict in production)
@@ -154,6 +170,7 @@ NODE_ENV=production         # Production optimizations
 ```
 
 ### Security Requirements
+
 - DNS rebinding protection always enabled
 - Rate limiting on `/mcp` endpoint
 - Stack traces hidden in production
@@ -163,6 +180,7 @@ NODE_ENV=production         # Production optimizations
 ## Educational Patterns to Follow
 
 ### Adding New Tools
+
 1. Define schema in `types.ts` schemas object (compiled once at startup)
 2. Use Zod for parameter validation with `.describe()` for documentation
 3. Generate unique `requestId` for correlation
@@ -171,28 +189,27 @@ NODE_ENV=production         # Production optimizations
 6. Use `SchemaInput<'toolName'>` type for type-safe parameter handling
 
 ### Error Handling Best Practices
+
 ```typescript
 // Use protocol-compliant McpError for predictable failures
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 
-throw new McpError(
-  ErrorCode.InvalidParams,
-  'Division by zero is not allowed.'
-);
+throw new McpError(ErrorCode.InvalidParams, 'Division by zero is not allowed.');
 
 // Global error handler catches unexpected errors
 requestLogger.error('Unhandled error in MCP request handler', { error });
 res.status(500).json({
   jsonrpc: '2.0',
   error: {
     code: ErrorCode.InternalError,
-    message: 'An internal server error occurred.'
+    message: 'An internal server error occurred.',
   },
-  id: req.body?.id || null
+  id: req.body?.id || null,
 });
 ```
 
 ### Request Lifecycle Pattern
+
 1. Generate unique `requestId` for correlation
 2. Create contextual logger with `requestId`
 3. Create fresh MCP server and transport instances
@@ -203,13 +220,15 @@ res.status(500).json({
 ## Testing Stateless Behavior
 
 ### Verification Points
+
 - Each request creates new server instance
 - No shared state between concurrent requests
 - Request correlation works via `requestId`
 - Cleanup happens properly on connection close
 - Metrics collection doesn't leak memory
 
 ### Common Issues to Watch
+
 - Forgetting to set `sessionIdGenerator: undefined`
 - Missing cleanup in `res.on('close')` listener
 - Sharing state accidentally via closures
@@ -218,19 +237,22 @@ res.status(500).json({
 ## Production Deployment
 
 ### Containerization
+
 - Multi-stage Dockerfile (builder + production stages)
 - Docker Compose with health checks
 - Minimal production image (no dev dependencies)
 
 ### Serverless Ready
+
 - `handleMCPRequest` function can be exported as serverless handler
 - No persistent state to manage
 - Scales infinitely without coordination
 
 ### Monitoring
+
 - Structured JSON logging with correlation
 - Prometheus-style metrics endpoint
 - Health checks for load balancers
 - Request duration and tool execution histograms
 
-This server demonstrates that stateless architecture enables simpler, more secure, and infinitely scalable MCP implementations. The educational approach teaches both what to build and what NOT to build, making it an invaluable learning resource.
+This server demonstrates that stateless architecture enables simpler, more secure, and infinitely scalable MCP implementations. The educational approach teaches both what to build and what NOT to build, making it an invaluable learning resource.