MCP Server Template (TypeScript)

A Model Context Protocol (MCP) server template implementation using TypeScript and Express.js.

Overview

This server provides a foundation for implementing MCP tools and integrations. It currently includes a simple echo tool as a placeholder, which can be expanded with additional functionality.

Features

• MCP Protocol Compliance: Full implementation of the Model Context Protocol specification
• Streamable HTTP Transport: Modern HTTP-based transport with session management
• Express.js Integration: Built on Express.js for familiar web server patterns
• TypeScript: Full TypeScript support with type safety
• Placeholder Echo Tool: Simple tool for testing and demonstration

Installation

# Install dependencies
pnpm install

# Build the project
pnpm build

Usage

Starting the Server

# Start the server
node dist/server.js

The server will start on port 3000 (or the port specified in the PORT environment variable).

Server Endpoints

• POST /mcp: Main MCP protocol endpoint for client requests
• GET /mcp: Server-to-client notifications via Server-Sent Events (SSE)
• DELETE /mcp: Session termination endpoint

Testing the Server

You can test the server using curl commands:

1. Initialize a session:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}' \
  -v

The session ID will be returned in the mcp-session-id response header. Look for a line like:

< mcp-session-id: fa178930-3286-443c-ac8e-395b63cf649f

2. List available tools:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Or use this one-liner to initialize and immediately list tools:

SESSION_ID=$(curl -s -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}' \
  -D - | grep -i "mcp-session-id:" | cut -d' ' -f2 | tr -d '\r') && \
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

3. Call the echo tool:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "echo", "arguments": {"message": "Hello!"}}}'

Or use this one-liner to initialize and immediately call the echo tool:

SESSION_ID=$(curl -s -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}' \
  -D - | grep -i "mcp-session-id:" | cut -d' ' -f2 | tr -d '\r') && \
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "echo", "arguments": {"message": "Hello!"}}}'

Development

Available Scripts

• pnpm build: Compile TypeScript to JavaScript
• pnpm lint: Run ESLint on source files
• pnpm format: Format all files with Prettier
• pnpm test: Run Jest tests
• pnpm test:watch: Run Jest in watch mode

Project Structure

src/
├── server.ts          # Main server implementation
└── __tests__/         # Test files
    └── example.test.ts
dist/                  # Compiled JavaScript output

Adding New Tools

To add new tools to the server, modify the createMcpServer() function in src/server.ts:

// Add a new tool
server.tool(
  'tool-name',
  'Tool description',
  {
    /* schema definition if needed */
  },
  async (args: any) => ({
    content: [
      {
        type: 'text',
        text: `Result: ${args.someParameter}`,
      },
    ],
  }),
);

MCP Protocol Features

This server supports the following MCP capabilities:

• Tools: Execute functions and return results
• Session Management: Stateful connections with session IDs
• Streamable HTTP: Modern HTTP transport with SSE for notifications

Next Steps

This server provides a foundation for building more complex MCP integrations. Consider adding:

• More sophisticated tools with proper input validation
• Resource endpoints for exposing data
• Prompt templates for LLM interactions
• Integration with external APIs or services

Using with Cline (VSCode Extension)

To use this MCP server with the Cline VSCode extension, add the following configuration to your VSCode settings JSON:

{
  "mcpServers": {
    "localhost": {
      "url": "http://localhost:3000/mcp",
      "disabled": false,
      "type": "streamableHttp",
      "autoApprove": []
    }
  }
}

Make sure your MCP server is running on port 3000 before connecting Cline to it.

Resources

• Model Context Protocol Documentation
• MCP TypeScript SDK
• MCP Specification