MCP Server Template (TypeScript)

A reference MCP server demonstrating best-practice patterns for building quality MCP servers in TypeScript. Includes 6 example tools with proper schemas, descriptions, error handling, and fuzz resilience.

Use this as a starter template for your own MCP server, or as a reference for what a high-scoring server looks like on MCP Scoreboard.

Looking for Python? See mcp-server-template for the Python version.

Quick Start

# Install
npm install mcp-server-template-ts

# Run via stdio (default)
npx mcp-server-template

# Run via HTTP
npx mcp-server-template --http --port 8080

From source

git clone https://github.com/Brightwing-Systems-LLC/mcp-server-template-ts.git
cd mcp-server-template-ts
npm install
npm run dev            # stdio
npm run dev:http       # HTTP on port 8080

Tools

| Tool | Description | |------|-------------| | echo | Echo a message back — useful for testing connectivity | | calculate | Perform arithmetic operations (add, subtract, multiply, divide) | | list_files | List files in a directory with optional glob pattern filtering | | get_weather | Get simulated weather data for a city | | search_notes | Search stored notes by keyword | | create_note | Create a new note with title, content, and optional tags |

Usage

With Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "template": {
      "command": "npx",
      "args": ["mcp-server-template-ts"]
    }
  }
}

With Cursor / Claude Code

# stdio mode
npx mcp-server-template-ts

# HTTP mode (for remote connections)
npx mcp-server-template-ts --http --port 8080

Score This Server

# Score via HTTP
uvx mcp-score http://localhost:8080/mcp

# Score via stdio
uvx mcp-score stdio -- npx mcp-server-template-ts

Best Practices Demonstrated

• Clear tool descriptions explaining what each tool does and when to use it
• Typed input schemas via Zod with property descriptions and format hints
• Proper error handling — returns isError: true with clear messages, never crashes
• Fuzz resilience — handles empty strings, huge numbers, null values, and wrong types gracefully
• Both transports — stdio for local use, HTTP (Streamable HTTP) for remote connections

Development

# Install dependencies
npm install

# Run in dev mode (with tsx)
npm run dev

# Run tests
npm test

# Type check
npm run typecheck

# Build
npm run build

Project Structure

src/
├── index.ts          # Entry point (stdio/HTTP transport)
├── server.ts         # McpServer creation and tool registration
├── storage.ts        # NoteStore (in-memory stateful example)
└── tools/
    ├── echo.ts       # Simple connectivity test
    ├── calculate.ts  # Numeric validation example
    ├── files.ts      # Directory listing with filtering
    ├── weather.ts    # Simulated data
    └── notes.ts      # Two related tools + shared state

License

MIT