rully-saputra15/ts-mcp-starter-kit

TypeScript MCP Starter Kit 🚀

A fully functional starter template for building Model Context Protocol (MCP) servers with TypeScript, supporting both HTTP/SSE and stdio transports for seamless integration with AI applications.

✨ Features

• TypeScript Ready: Full TypeScript support with strict type checking
• SSE Transport: Real-time bidirectional communication using Server-Sent Events
• Zod Validation: Runtime type validation and schema parsing
• RESTful Integration: Example implementation with REST Countries API
• Session Management: Built-in session handling for multiple concurrent connections
• CORS Support: Cross-origin resource sharing configured
• Hot Reload: Development server with tsx for instant feedback

🏗️ Architecture

src/
├── index.ts          # HTTP server & SSE transport setup
├── server.ts         # MCP server configuration & tool registration
├── types.ts          # TypeScript type definitions
├── api/              # External API integrations
│   └── fetchRestCountries.ts
├── parser/           # Zod schema validators
│   └── index.ts
└── resources/        # MCP resources configurations
│   └── index.ts
└── tools/            # MCP tool configurations
    └── index.ts

🚀 Quick Start

1. Clone and install dependencies:

   pnpm install
   

2. Start the development server:

   pnpm start
   

3. Server endpoints:

   • SSE Stream: GET http://localhost:8000/mcp
   • Message Endpoint: POST http://localhost:8000/mcp/messages?sessionId={id}

🔧 Configuration

Environment Variables

Create a .env file:

PORT=8000  # Optional, defaults to 8000

Adding New Tools

1. Define the tool configuration in :

export const myNewToolConfig = (): TRegisterTool => ({
  title: "My New Tool",
  description: "Description of what it does",
  inputSchema: {
    param1: z.string().describe("Parameter description")
  },
  outputSchema: {
    result: z.any()
  }
});

2. Register the tool in :

server.registerTool(
  "my_new_tool",
  myNewToolConfig(),
  async ({ param1 }) => {
    // Tool implementation
    return {
      content: [{ type: "text", text: "Result" }],
      structuredContent: { result: "data" }
    };
  }
);

🛠️ Built-in Example: Country Data Tool

The starter includes a complete example that fetches country information:

• Tool Name: get_country_data
• Input: countryName (string)
• API: REST Countries API
• Validation: Zod schema in

Usage:

// The tool accepts a country name and returns detailed country data
{ "countryName": "Germany" }

🔍 Key Components

Core MCP server setup with tool registration and capability configuration.

Handles Server-Sent Events transport layer for real-time communication between client and server.

Handle the client AI application that can't use SSEServerTransport

Type-safe session management for handling multiple concurrent connections.

Example API integration with error handling and response formatting.

📊 Transport Layer

This implementation uses SSE (Server-Sent Events) instead of stdio transport:

• ✅ Real-time: Instant bidirectional communication
• ✅ Web-compatible: Works seamlessly with web clients
• ✅ Session-based: Multiple concurrent connections support
• ✅ Error handling: Robust connection management

🧪 Development

Type Safety

All schemas are validated using Zod with TypeScript integration:

import z from "zod";

export const mySchema = z.object({
  field: z.string().describe("Field description")
});

Adding External APIs

Follow the pattern in :

const fetchMyAPI = async (param: string) => {
  try {
    const res = await fetch(`https://api.example.com/${param}`);
    return await res.json();
  } catch (err) {
    console.error(`API Error: ${err}`);
    return "Error message";
  }
};

📦 Dependencies

• @modelcontextprotocol/sdk: Core MCP functionality
• zod: Runtime type validation
• tsx: TypeScript execution engine
• dotenv: Environment variable management

🌐 Usage with AI Clients

This MCP server supports two transport methods:

Option 1: HTTP/SSE Transport (for ChatGPT via ngrok)

1. Start the HTTP server:

   pnpm start
   

2. Expose your server with ngrok:

   ngrok http 8000
   

3. Configure ChatGPT:

   • Copy the ngrok HTTPS URL (e.g., https://abc123.ngrok.io)
   • In ChatGPT, add your MCP server using the SSE endpoint:
     • SSE Stream: https://abc123.ngrok.io/mcp
     • Message Endpoint: https://abc123.ngrok.io/mcp/messages

Option 2: Stdio Transport (for Claude Desktop & Local AI Apps)

1. Configure Claude Desktop (or other local AI application):

   Edit your claude_desktop_config.json file:

   {
     "mcpServers": {
       "ts_mcp_starter": {
         "command": "C:\\Users\\YOUR_USERNAME\\Development\\mcp\\YOUR_MCP_FOLDER\\node_modules\\.bin\\tsx.cmd",
         "args": ["C:\\Users\\YOUR_USERNAME\\Development\\mcp\\YOUR_MCP_FOLDER\\src\\stdio.ts"],
         "cwd": "C:\\Users\\YOUR_USERNAME\\Development\\mcp\\YOUR_MCP_FOLDER"
       }
     }
   }
   

   Important: Replace YOUR_USERNAME with your actual username and adjust paths as needed.

   For macOS/Linux:

   {
     "mcpServers": {
       "ts_mcp_starter": {
         "command": "node",
         "args": ["/absolute/path/to/YOUR_MCP_FOLDER/node_modules/.bin/tsx", "src/stdio.ts"],
         "cwd": "/absolute/path/to/YOUR_MCP_FOLDER"
       }
     }
   }
   

2. Restart Claude Desktop to load the MCP server

3. Verify connection:

   • Check Claude Desktop logs for successful connection
   • The server will output to stderr: "MCP Server running on stdio"

Which Transport Should I Use?

🚀 Production Deployment

Build and run in production:

# Build the project
npx tsc

# Run the built server
node build/index.js

For containerized deployment, the server runs on the configured port and accepts HTTP connections for MCP communication.

Ready to build your next MCP server? This starter kit provides everything you need to create robust, type-safe MCP applications with modern TypeScript tooling! 🎉