@tklein1801/express-mcp-template

A ready-to-use template for building an MCP (Model Context Protocol) service on top of Express.js, written in TypeScript.

Features

| Feature | Tool | |---|---| | HTTP server | Express.js | | MCP protocol | @modelcontextprotocol/sdk via Streamable HTTP transport | | Language | TypeScript (ESM, NodeNext) | | Linting & formatting | Biome | | Git hooks | Husky + lint-staged | | Unit tests | Vitest | | CI | GitHub Actions | | npx executable | bin entry + shebang |

Quick start (npx)

Run the MCP server without cloning:

# Install globally (optional)
npm install -g @tklein1801/express-mcp-template

npx express-mcp-template

The server starts on http://localhost:3000 by default.

CLI flags (take precedence over environment variables):

npx express-mcp-template --port 8080
npx express-mcp-template --port 8080 --host 0.0.0.0
npx express-mcp-template --help

Environment variables (used when no CLI flag is given):

| Variable | Default | Description | |---|---|---| | PORT | 3000 | TCP port | | HOST | localhost | Bind address |

MCP endpoint

| Endpoint | Description | |---|---| | POST /mcp | Initialize a new session or send a message (primary endpoint) | | GET /mcp | Open SSE stream for server-initiated notifications | | DELETE /mcp | Close a session | | GET /health | Health check |

Connecting with an MCP client

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Built-in capabilities

Tools

| Tool | Description | |---|---| | echo | Returns the input message unchanged | | add | Adds two numbers | | get_current_time | Current date/time, optionally in a given IANA timezone | | random_number | Random integer in [min, max] | | base64_encode | Encodes a UTF-8 string to Base64 | | base64_decode | Decodes a Base64 string to UTF-8 | | server_info | Returns runtime info (name, version, Node.js, platform, uptime) |

Prompts

| Prompt | Description | |---|---| | summarize | Summarize text at a given length (short / medium / long) | | code_review | Review a code snippet for bugs, quality, and security | | explain_error | Explain an error message or stack trace and suggest fixes | | write_commit_message | Generate a Conventional Commits message from a diff |

Resources

| URI | Description | |---|---| | mcp://server/info | Runtime info (name, version, Node.js, platform, arch, uptime) | | mcp://server/env | Safe env vars (NODE_ENV, PORT, HOST, TZ) | | mcp://server/tools | Human-readable catalogue of all registered tools |

Add your own tools in src/mcp/tools.ts, prompts in src/mcp/prompts.ts, and resources in src/mcp/resources.ts.

Development

Prerequisites

• Node.js ≥ 18
• npm ≥ 9

Setup

git clone [email protected]:tklein1801/express-mcp-template.git
cd express-mcp-template
npm install

Scripts

npm run dev          # Start with hot-reload (tsx watch)
npm run build        # Compile TypeScript → dist/
npm run start        # Run compiled output
npm test             # Run unit tests (Vitest)
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report
npm run lint         # Biome check
npm run lint:fix     # Biome check + auto-fix
npm run format       # Biome format (write)

Pre-commit hook

Husky runs lint-staged before every commit. Staged *.ts, *.js, and *.json files are automatically checked and fixed by Biome.

Project structure

.
├── src/
│   ├── index.ts          # Bin entry point (shebang, starts the server)
│   ├── server.ts         # Express app factory (Streamable HTTP transport)
│   └── mcp/
│       ├── server.ts     # MCP server factory (one per session)
│       ├── tools.ts      # Tool registrations
│       ├── prompts.ts    # Prompt registrations
│       └── resources.ts  # Resource registrations
├── tests/
│   ├── server.test.ts    # Express route tests
│   └── tools.test.ts     # MCP tool unit tests
├── .github/workflows/
│   └── ci.yml            # Build · Lint · Test on Node 18 / 20 / 22
├── .husky/
│   └── pre-commit        # lint-staged
├── biome.json
├── tsconfig.json
└── package.json

GitHub Actions CI

The workflow (.github/workflows/ci.yml) runs on every push / pull request:

1. Lint — biome check .
2. Build — tsc
3. Test — vitest run
4. Pack dry-run — npm pack --dry-run (verifies publish readiness)

Matrix: Node.js 18, 20, 22.

Documentation

| File | Contents | |---|---| | docs/transports.md | Streamable HTTP transport internals, all endpoint details, comparison with legacy SSE & stdio |

License

MIT