create-mcp-craft/README.md

Create MCP TypeScript servers with Bun and Hono - the fastest way to scaffold Model Context Protocol servers

# create-mcp-craft

> Create MCP TypeScript servers with Bun and Hono - the fastest way to scaffold Model Context Protocol servers

## ⚡ Quick Start

The easiest way to create a new MCP server is using the create command:

```bash
# Using bunx (recommended)
bunx create-mcp-craft@latest my-mcp-server

# Using npm
npm create mcp-craft@latest my-mcp-server

# Using yarn
yarn create mcp-craft my-mcp-server

# Using pnpm
pnpm create mcp-craft my-mcp-server

# Using bun create
bun create mcp-craft my-mcp-server
```

Then navigate to your new project and start developing:

```bash
cd my-mcp-server
bun install
bun run dev:stdio
```

Your project comes with git already initialized and an initial commit made! Ready to push to your repository.

## 🚀 What You Get

This template creates a production-ready MCP TypeScript server with:

### 🔧 **Modern Tooling**
- **Bun** - Lightning-fast package manager and runtime (20-30x faster than npm)
- **Hono** - Ultra-lightweight web framework (14kB, zero dependencies)
- **TypeScript** - Full type safety with native Bun support
- **ESLint + Prettier** - Code linting and formatting configured
- **Git** - Repository initialized with initial commit

### 📡 **Complete MCP Implementation**
- **Dual Transport Support**: Both stdio (process communication) and HTTP+SSE (web-based)
- **All MCP Request Types**: Complete implementation of the MCP specification
- **Example Tools**: Calculator and weather API demonstrations
- **Example Resources**: Static config and dynamic greeting resources
- **Example Prompts**: Code review prompt with configurable focus areas
- **Transport-aware Logging**: Proper stderr logging for stdio, console for HTTP

### 🛠️ **Built-in Examples**
- **Tools**: `add`, `subtract`, `multiply`, `divide`, `fetch-weather`, `get-forecast`
- **Resources**: `config://app`, `greeting://{name}`
- **Prompts**: `review-code` with focus options (security, performance, readability)
- **Zod Validation**: Runtime type checking for all parameters

## 🎯 Development Workflow

After creating your project, you'll have these commands available:

```bash
# Development
bun run dev:stdio     # Run with stdio transport (for Claude Desktop)
bun run dev:http      # Run with HTTP+SSE transport (for web clients)
bun run dev           # Run with file watching

# Quality Assurance
bun run typecheck     # TypeScript type checking
bun run lint          # ESLint code linting
bun run lint:fix      # Auto-fix linting issues
bun run format        # Prettier code formatting

# Production
bun run build         # Build the project
bun run start         # Start production server
```

## 🔗 Integration Examples

### Claude Desktop Configuration

Add your server to Claude Desktop by updating your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-mcp-server": {
      "command": "bun",
      "args": ["/path/to/my-mcp-server/src/index.ts"]
    }
  }
}
```

### Web Client (HTTP+SSE)

```typescript
// Connect to your MCP server via HTTP
const response = await fetch('http://localhost:3000/mcp/sse')
const eventSource = new EventSource('http://localhost:3000/mcp/sse')

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('MCP message:', data)
}
```

## 📊 Performance Benefits

| Metric | npm/Express | Bun/Hono | Improvement |
|--------|-------------|-----------|-------------|
| Install Speed | ~15s | ~2s | **7.5x faster** |
| Framework Size | ~200kB | ~14kB | **93% smaller** |
| Runtime Overhead | High | Minimal | **Native TypeScript** |
| Cold Start | ~500ms | ~50ms | **10x faster** |

## 🏗️ Template Structure

Your generated project will have this structure:

```
my-mcp-server/
├── src/
│   ├── index.ts              # Main server (stdio transport)
│   ├── http.ts               # HTTP server with SSE
│   ├── config/
│   │   └── server.ts         # Server configuration
│   ├── handlers/             # MCP request handlers
│   ├── services/             # Business logic
│   ├── types/                # TypeScript definitions
│   └── utils/                # Utility functions
├── docs/                     # Documentation
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
├── .eslintrc.json           # ESLint configuration
├── .prettierrc              # Prettier configuration
└── README.md                # Project documentation
```

## 🧪 Advanced Features

The template includes advanced MCP features out of the box:

- **Resource Subscriptions**: Real-time updates for dynamic resources
- **Prompt Templates**: Parameterized prompts for various use cases
- **Sampling Integration**: Ready for LLM model integration
- **Session Management**: Stateful client sessions
- **Logging Levels**: Configurable logging with proper transport handling
- **Error Handling**: Comprehensive error responses with proper codes

## 📝 Customization

The template automatically replaces placeholders with your project details:

- Project name and description
- Author information (from git config)
- Repository URL
- Current year for copyright

## 🤝 Contributing

Found a bug or have a feature request? Please visit:
- 🐛 [Issues](https://github.com/kiliczsh/create-mcp-craft/issues)
- 🔄 [Pull Requests](https://github.com/kiliczsh/create-mcp-craft/pulls)

## 📄 License

MIT License © 2025 Muhammed Kılıç

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) - The open standard this template implements
- [Bun](https://bun.sh/) - The incredibly fast JavaScript runtime and toolkit
- [Hono](https://hono.dev/) - The ultrafast web framework for the Edges
- [Claude](https://claude.ai/) - AI assistant that helps developers build amazing MCP servers