mcp-server-template-typescript by goughjo02 - MCP Server

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:

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

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"}'

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.

goughjo02/mcp-server-template-typescript