@prmichaelsen/acp-mcp 0.1.0

package/agent/patterns/mcp-server-starter.bootstrap.md

@@ -0,0 +1,597 @@
+# Bootstrap Pattern
+
+**Pattern**: Project Initialization and Directory Structure
+**Category**: Setup
+**Complexity**: Beginner
+**Last Updated**: 2026-02-22
+
+---
+
+## Overview
+
+The Bootstrap Pattern provides a standardized approach to initializing TypeScript MCP server projects with the correct directory structure, configuration files, and dependencies. This pattern ensures consistency across projects and sets up a solid foundation for development.
+
+**When to use this pattern**:
+- Starting a new MCP server project
+- Converting an existing project to MCP
+- Setting up a development environment for MCP servers
+- Creating a template for team projects
+
+---
+
+## Core Principles
+
+### 1. ES Modules (ESM) First
+Modern JavaScript/TypeScript projects should use ESM syntax (`import`/`export`) rather than CommonJS (`require`/`module.exports`). MCP SDK is built for ESM.
+
+### 2. TypeScript for Type Safety
+TypeScript provides compile-time type checking, better IDE support, and improved maintainability for MCP servers.
+
+### 3. Dual Build Support
+Projects should support both standalone execution (stdio transport) and library usage (factory pattern for mcp-auth).
+
+### 4. Development Workflow
+Fast iteration with watch mode, hot reload, and immediate feedback during development.
+
+---
+
+## Directory Structure
+
+```
+my-mcp-server/
+├── src/                    # Source code
+│   ├── server.ts          # Standalone server entry point
+│   ├── server-factory.ts  # Factory for mcp-auth (optional)
+│   ├── config.ts          # Configuration management
+│   ├── tools/             # MCP tool implementations
+│   │   └── example-tool.ts
+│   ├── utils/             # Utility functions
+│   │   ├── logger.ts
+│   │   └── error-handler.ts
+│   └── types/             # TypeScript type definitions
+│       └── index.ts
+├── dist/                   # Compiled JavaScript (generated)
+│   ├── server.js
+│   └── server-factory.js
+├── tests/                  # Test files (optional)
+│   └── server.spec.ts
+├── node_modules/           # Dependencies (generated)
+├── package.json            # Project manifest
+├── tsconfig.json           # TypeScript configuration
+├── esbuild.build.js        # Build script
+├── esbuild.watch.js        # Watch mode script (optional)
+├── jest.config.js          # Test configuration (optional)
+├── .env.example            # Environment variable template
+├── .gitignore              # Git ignore rules
+├── README.md               # Project documentation
+└── LICENSE                 # License file
+```
+
+### Directory Purposes
+
+**`src/`** - All TypeScript source code
+- Organized by feature/function
+- Tools in `tools/` subdirectory
+- Utilities in `utils/` subdirectory
+- Types in `types/` subdirectory
+
+**`dist/`** - Compiled JavaScript output
+- Generated by build process
+- Not committed to git
+- Contains bundled, executable code
+
+**`tests/`** - Test files
+- Can be colocated (`*.spec.ts`) or separate
+- Mirrors `src/` structure if separate
+
+**`node_modules/`** - npm dependencies
+- Generated by `npm install`
+- Not committed to git
+
+---
+
+## Configuration Files
+
+### package.json
+
+Complete example with all necessary fields:
+
+```json
+{
+  "name": "@username/my-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for [purpose]",
+  "type": "module",
+  "main": "dist/server.js",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./factory": {
+      "types": "./dist/server-factory.d.ts",
+      "import": "./dist/server-factory.js"
+    }
+  },
+  "bin": {
+    "my-mcp-server": "./dist/server.js"
+  },
+  "scripts": {
+    "build": "node esbuild.build.js",
+    "build:watch": "node esbuild.watch.js",
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "typescript"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19",
+    "esbuild": "^0.20.0",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.3"
+  }
+}
+```
+
+**Key Fields**:
+- `"type": "module"` - Enables ESM
+- `"main"` - Entry point for standalone usage
+- `"exports"` - Dual export (server + factory)
+- `"bin"` - CLI executable
+- `"scripts"` - Development workflow commands
+
+### tsconfig.json
+
+TypeScript configuration for ESM + modern features:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+**Key Settings**:
+- `ES2022` target for modern JavaScript
+- `strict: true` for maximum type safety
+- `declaration: true` for `.d.ts` files
+- Path aliases (`@/*`) for clean imports
+
+### .env.example
+
+Environment variable template:
+
+```bash
+# Service Configuration
+SERVICE_URL=http://localhost:8080
+SERVICE_API_KEY=
+
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+LOG_LEVEL=info
+
+# MCP Configuration
+MCP_TRANSPORT=stdio
+```
+
+**Purpose**: Documents required environment variables without exposing secrets.
+
+### .gitignore
+
+Git ignore rules for MCP projects:
+
+```gitignore
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.js
+*.d.ts
+*.js.map
+!esbuild.*.js
+!jest.config.js
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# Temporary
+*.tmp
+.cache/
+```
+
+---
+
+## Dependencies
+
+### Core Dependencies
+
+**@modelcontextprotocol/sdk** (^1.0.4)
+- Purpose: MCP protocol implementation
+- Required: Yes
+- Why: Provides Server, transport, and types
+
+**dotenv** (^16.4.5)
+- Purpose: Load environment variables from `.env`
+- Required: Recommended
+- Why: Simplifies configuration management
+
+### Development Dependencies
+
+**typescript** (^5.3.3)
+- Purpose: TypeScript compiler
+- Required: Yes
+- Why: Compiles TypeScript to JavaScript
+
+**esbuild** (^0.20.0)
+- Purpose: Fast JavaScript bundler
+- Required: Yes
+- Why: Bundles code for distribution
+
+**tsx** (^4.7.1)
+- Purpose: TypeScript execution with watch mode
+- Required: Recommended
+- Why: Enables `npm run dev` with hot reload
+
+**@types/node** (^20.11.19)
+- Purpose: Node.js type definitions
+- Required: Yes
+- Why: Provides types for Node.js APIs
+
+### Optional Dependencies
+
+**jest** + **ts-jest** + **@types/jest**
+- Purpose: Testing framework
+- When: If writing tests
+
+**@prmichaelsen/mcp-auth**
+- Purpose: Multi-tenant authentication
+- When: If building production multi-tenant server
+
+---
+
+## Implementation
+
+### Step-by-Step Setup
+
+#### 1. Initialize Project
+
+```bash
+mkdir my-mcp-server
+cd my-mcp-server
+npm init -y
+```
+
+#### 2. Configure package.json
+
+Add `"type": "module"` and update scripts:
+
+```bash
+npm pkg set type="module"
+npm pkg set scripts.build="node esbuild.build.js"
+npm pkg set scripts.dev="tsx watch src/server.ts"
+npm pkg set scripts.start="node dist/server.js"
+```
+
+#### 3. Install Dependencies
+
+```bash
+# Core dependencies
+npm install @modelcontextprotocol/sdk dotenv
+
+# Dev dependencies
+npm install -D typescript esbuild tsx @types/node
+```
+
+#### 4. Create Directory Structure
+
+```bash
+mkdir -p src/tools src/utils src/types
+mkdir -p dist tests
+```
+
+#### 5. Create Configuration Files
+
+Create `tsconfig.json`, `.env.example`, `.gitignore` (see examples above).
+
+#### 6. Create Build Script
+
+Create `esbuild.build.js`:
+
+```javascript
+import * as esbuild from 'esbuild';
+
+await esbuild.build({
+  entryPoints: ['src/server.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: 'dist/server.js',
+  sourcemap: true,
+  external: ['@modelcontextprotocol/sdk'],
+  banner: {
+    js: "import { createRequire } from 'module'; const require = createRequire(import.meta.url);"
+  }
+});
+
+console.log('✓ Build complete');
+```
+
+#### 7. Initialize Git
+
+```bash
+git init
+git add .
+git commit -m "chore: initial project setup"
+```
+
+#### 8. Create README.md
+
+Document your project's purpose, installation, and usage.
+
+---
+
+## Examples
+
+### Minimal Server Setup
+
+After bootstrapping, create a minimal server:
+
+**src/server.ts**:
+```typescript
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new Server(
+  { name: 'my-mcp-server', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+console.error('Server running on stdio');
+```
+
+Build and run:
+```bash
+npm run build
+npm start
+```
+
+---
+
+## Benefits
+
+### 1. Consistency
+- Standard structure across all MCP projects
+- Familiar layout for team members
+- Easy onboarding for new developers
+
+### 2. Best Practices
+- ESM for modern JavaScript
+- TypeScript for type safety
+- Proper separation of concerns
+
+### 3. Development Speed
+- Fast builds with esbuild
+- Hot reload with tsx watch
+- Immediate feedback loop
+
+### 4. Production Ready
+- Dual build (standalone + factory)
+- Proper error handling setup
+- Configuration management
+
+### 5. Maintainability
+- Clear directory structure
+- Documented configuration
+- Type-safe codebase
+
+---
+
+## Anti-Patterns
+
+### ❌ Don't: Use CommonJS
+
+```javascript
+// ❌ Wrong
+const { Server } = require('@modelcontextprotocol/sdk/server');
+module.exports = server;
+```
+
+```javascript
+// ✅ Correct
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export { server };
+```
+
+**Why**: MCP SDK is built for ESM. CommonJS causes compatibility issues.
+
+### ❌ Don't: Skip TypeScript
+
+```javascript
+// ❌ Wrong - Plain JavaScript
+const server = new Server({ name: 'server' });
+```
+
+```typescript
+// ✅ Correct - TypeScript
+const server = new Server(
+  { name: 'server', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+);
+```
+
+**Why**: TypeScript catches errors at compile time and improves IDE support.
+
+### ❌ Don't: Commit dist/ or node_modules/
+
+```gitignore
+# ❌ Wrong - Missing from .gitignore
+# (no entries)
+```
+
+```gitignore
+# ✅ Correct
+node_modules/
+dist/
+```
+
+**Why**: Generated files should not be in version control.
+
+### ❌ Don't: Hardcode Configuration
+
+```typescript
+// ❌ Wrong
+const apiKey = 'sk-1234567890';
+const dbUrl = 'mongodb://localhost:27017';
+```
+
+```typescript
+// ✅ Correct
+import dotenv from 'dotenv';
+dotenv.config();
+
+const apiKey = process.env.API_KEY;
+const dbUrl = process.env.DATABASE_URL;
+```
+
+**Why**: Configuration should be environment-specific and not committed to git.
+
+### ❌ Don't: Mix Concerns in Root Directory
+
+```
+# ❌ Wrong
+my-mcp-server/
+├── tool1.ts
+├── tool2.ts
+├── utils.ts
+├── server.ts
+```
+
+```
+# ✅ Correct
+my-mcp-server/
+├── src/
+│   ├── server.ts
+│   ├── tools/
+│   │   ├── tool1.ts
+│   │   └── tool2.ts
+│   └── utils/
+│       └── utils.ts
+```
+
+**Why**: Organized structure improves maintainability and scalability.
+
+---
+
+## Related Patterns
+
+- [Server Standalone Pattern](mcp-server-starter.server-standalone.md) - Uses this bootstrap structure
+- [Server Factory Pattern](mcp-server-starter.server-factory.md) - Builds on this foundation
+- [Build Config Pattern](mcp-server-starter.build-config.md) - Detailed build configuration
+- [Config Management Pattern](mcp-server-starter.config-management.md) - Environment variable handling
+
+---
+
+## Troubleshooting
+
+**Problem**: `Cannot find module` errors
+
+**Solution**: Ensure `"type": "module"` in package.json and use `.js` extensions in imports:
+```typescript
+import { tool } from './tools/tool.js'; // ✅ Include .js
+```
+
+**Problem**: TypeScript compilation errors
+
+**Solution**: Check `tsconfig.json` has correct `target` and `module` settings (ES2022).
+
+**Problem**: esbuild fails to bundle
+
+**Solution**: Verify `esbuild.build.js` exists and has correct entry points.
+
+---
+
+## Checklist
+
+- [ ] Created project directory
+- [ ] Initialized npm (`npm init -y`)
+- [ ] Set `"type": "module"` in package.json
+- [ ] Installed core dependencies (@modelcontextprotocol/sdk, dotenv)
+- [ ] Installed dev dependencies (typescript, esbuild, tsx, @types/node)
+- [ ] Created directory structure (src/, dist/, tests/)
+- [ ] Created tsconfig.json
+- [ ] Created esbuild.build.js
+- [ ] Created .env.example
+- [ ] Created .gitignore
+- [ ] Initialized git repository
+- [ ] Created README.md
+- [ ] Verified build works (`npm run build`)
+- [ ] Verified dev mode works (`npm run dev`)
+
+---
+
+**Pattern**: Bootstrap
+**Status**: Production Ready
+**Last Updated**: 2026-02-22