MCP Server Template

A minimal Model Context Protocol (MCP) server template written in TypeScript.

Use this as a starting point for building your own MCP server. It ships with a single hello_world demonstration tool and a fully working integration-test harness.

Features

• Ready-to-go structure – one command to build and test
• Demonstration tool – hello_world shows the full request/response cycle
• Type-safe – TypeScript throughout with Zod input validation
• Integration tests – Vitest + Execa test suite that talks to the real server process

Available Tools

hello_world

Returns a friendly greeting. Replace or extend this with your own tools.

Input (all optional):

Field	Type	Description
name	string	Name to include in the greeting

Example call:

{
  "tool": "hello_world",
  "arguments": {
    "name": "Alice"
  }
}

Using PowerShell

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hello_world","arguments":{"name":"Alice"}}}' | node build/server.js 

Using Git Bash (call node.exe explicitly to avoid node shims)

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"hello_world","arguments":{"name":"Alice"}}}' \
  | node.exe build/server.js
  
# or single command (note \n in string)
printf '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"hello_world","arguments":{"name":"Alice"}}}\n' | node.exe build/server.js

Response:

Hello, Alice! Welcome to the MCP Server Template.

Getting Started

1. Install dependencies

npm install

2. Build

npm run build

This compiles TypeScript to build/server.js.

3. Run tests

npm test

4. Start the server manually

node build/server.js

The server communicates over stdio using the MCP JSON-RPC protocol.

Adding Your Own Tools

1. Define a Zod schema for the tool's input in src/server.ts.
2. Register the tool in the ListToolsRequestSchema handler.
3. Add a case in the CallToolRequestSchema switch statement.
4. Add an integration test in tests/integration/integration.test.ts.

Connecting to an MCP Client

GitHub Copilot Chat (VS Code)

Add to your VS Code settings (.vscode/mcp.json):

{
  "servers": {
    "hello_world": {
      "command": "node",
      "args": [
        "absolute/path/to/build/server.js"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Cline Extension

Add to cline_mcp_settings.json as a STDIO transport local server:

{
  "mcpServers": {
    "hello_world": {
      "command": "node",
      "args": ["/absolute/path/to/build/server.js"]
    }
  }
}

Claude Code

# Project Scope (run in project folder, recommended)
claude mcp add --transport stdio hello_world "node.exe /absolute/path/to/build/server.js"
# or
# User Scope (always available, always consumes context)
claude mcp add --transport stdio --scope user hello_world "node.exe /absolute/path/to/build/server.js"

Manual in .claude.json

  "mcpServers": {
    "hello_world": {
      "type": "stdio",
      "command": "node.exe",
      "args": [
        "absolute\\path\\to\\build\\server.js"
      ],
      "env": {}
    }
  }

Restart the client after making configuration changes.

Scripts

Command	Description
npm run build	Compile TypeScript
npm run dev	Build and run server
npm run watch	Watch mode (rebuild on save)
npm test	Build + run all tests
npm run test:integration	Build + run integration tests only
npm run test:watch	Run tests in watch mode
npm run test:coverage	Generate coverage report

Project Structure

src/
  server.ts              # MCP server – tools live here
tests/
  integration/
    integration.test.ts  # Integration tests
  helpers/
    mcp_client.ts        # JSON-RPC client for tests
    test_db.ts           # Temp-file utilities for tests
build/                   # Compiled output (git-ignored)

Resources

• MCP TypeScript SDK
• MCP Specification
• Zod Documentation

License

MIT