# Express MCP Server

A clean, modular implementation of the Model Context Protocol (MCP) using Express.js and TypeScript.

## Quick Start

```bash
# Install dependencies
npm install

# Development (with file watching)
npm run dev

# Production
npm run build
npm start

# Type checking
npm run type-check
```

Server runs on `http://localhost:3001`

## Endpoints

- **Health**: `GET /mcp/health` - Server health status
- **Info**: `GET /mcp/info` - Server information and capabilities
- **MCP Protocol**: `POST/GET/DELETE /mcp` - Main MCP endpoints with streaming support

## Project Structure

```
src/
├── index.ts              Entry point - starts the server
├── app.ts                Express app factory
├── server/
│   └── mcp.ts            Core MCP server logic
├── routes/
│   └── mcp.ts            HTTP route handlers
└── tools/
    └── index.ts          Tool definitions
```

**Total: 201 lines of focused, readable code**

## Architecture

### Single Responsibility Principle
Each module has one clear purpose:
- `index.ts` (10 lines) - Server startup
- `app.ts` (20 lines) - Express setup
- `server/mcp.ts` (60 lines) - MCP protocol handling
- `routes/mcp.ts` (69 lines) - HTTP routing
- `tools/index.ts` (42 lines) - Tool catalog

### Features

✓ Official MCP SDK integration (`StreamableHTTPServerTransport`)
✓ HTTP streaming (chunked encoding + Server-Sent Events)
✓ Session management with automatic UUID generation
✓ Zod schema validation for tool inputs
✓ Comprehensive error handling
✓ Health check and info endpoints
✓ TypeScript strict mode

## Tools

Three example tools are included:

1. **add(a, b)** - Add two numbers
2. **multiply(x, y)** - Multiply two numbers  
3. **echo(message)** - Echo a message

### Adding a New Tool

Edit `src/tools/index.ts` and add to the array:

```typescript
{
  name: "my-tool",
  description: "What this tool does",
  inputSchema: {
    param1: z.string().describe("Parameter description"),
    param2: z.number().describe("Another parameter"),
  },
  handler: async (args) => {
    const p1 = args.param1 as string;
    const p2 = args.param2 as number;
    // Tool logic here
    return `Result: ${p1} ${p2}`;
  },
}
```

Then rebuild:
```bash
npm run build
npm start
```

## Testing

```bash
# Health check
curl http://localhost:3001/mcp/health

# Server info
curl http://localhost:3001/mcp/info

# MCP protocol request (with proper headers)
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

## Development

```bash
# Watch mode (recompiles on file changes)
npm run dev

# Type checking only
npm run type-check

# Build production bundle
npm run build
```

## Environment Variables

- `PORT` (default: 3001) - Server port

```bash
PORT=4000 npm start
```

## Stack

- **Express.js** - Web framework
- **TypeScript** - Type safety
- **Zod** - Schema validation
- **MCP SDK** - Protocol implementation
- **Node.js 18+** - Runtime

## Standards

- MCP Protocol Version: 2024-11-05
- HTTP Streaming: Chunked encoding + SSE
- Schema Validation: Zod
- Code Format: TypeScript with strict mode
- Code Style: Tabs, consistent formatting

## Documentation

- [ARCHITECTURE.md](./ARCHITECTURE.md) - Detailed architecture overview
- [QUICK_START.md](./QUICK_START.md) - 5-minute setup guide
- [COMMANDS.md](./COMMANDS.md) - Command reference
- [REFACTORING_SUMMARY.md](./REFACTORING_SUMMARY.md) - Development history

## License

MIT