tsMCP by RishabhKodes - MCP Server

MCP TypeScript Boilerplate

A complete boilerplate for creating Model Context Protocol (MCP) servers and clients in TypeScript.

Prerequisites

Node.js 18+ (recommended: latest LTS)
npm or yarn package manager

Quick Start

Clone or download this boilerplate

git clone https://github.com/RishabhKodes/tsMCP.git
cd tsMCP

Install dependencies
```
npm install
```
Build the project
```
npm run build
```
Run the server
```
npm run start:server
```
Test with the client (in a new terminal)
```
npm run start:client
```

Project Structure

src/
├── server.ts          # MCP server implementation
├── client.ts          # Example MCP client
└── types/             # Custom type definitions (if needed)

build/                 # Compiled JavaScript output
package.json          # Dependencies and scripts
tsconfig.json         # TypeScript configuration
README.md            # This file

Available Scripts

npm run build - Compile TypeScript to JavaScript
npm run start:server - Start the MCP server
npm run start:client - Run the example client
npm run dev:server - Build and run server in one command
npm run dev:client - Build and run client in one command
npm run clean - Remove build directory

Server Features

The example server includes:

Tools

calculate - Perform basic arithmetic operations (add, subtract, multiply, divide)
echo - Echo back the provided text
get_memory - Retrieve values from the in-memory store
set_memory - Store values in the in-memory store

Resources

memory://config - Configuration settings
memory://data - Sample application data

Server Implementation

The server is built using the official MCP SDK and includes:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'tsMCP',
  version: '1.0.0',
}, {
  capabilities: {
    resources: {},
    tools: {},
  },
});

Adding New Tools

To add a new tool, implement these handler functions:

List the tool in ListToolsRequestSchema handler:

{
  name: 'my_new_tool',
  description: 'Description of what the tool does',
  inputSchema: {
    type: 'object',
    properties: {
      input: { type: 'string', description: 'Input parameter' }
    },
    required: ['input']
  }
}

Handle tool execution in CallToolRequestSchema handler:

case 'my_new_tool': {
  const input = args?.input;
  // Your tool logic here
  return {
    content: [{
      type: 'text',
      text: `Result: ${result}`
    }]
  };
}

Adding New Resources

List the resource in ListResourcesRequestSchema handler:

{
  uri: 'custom://my-resource',
  mimeType: 'application/json',
  name: 'My Resource',
  description: 'Description of the resource'
}

Handle resource reading in ReadResourceRequestSchema handler:

if (uri === 'custom://my-resource') {
  return {
    contents: [{
      uri,
      mimeType: 'application/json',
      text: JSON.stringify(myData, null, 2)
    }]
  };
}

Client Implementation

The example client demonstrates how to:

Connect to an MCP server
List available tools and resources
Call tools with parameters
Read resources
Handle errors and cleanup

Integration with AI Applications

Claude Desktop

To integrate your MCP server with Claude Desktop, add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "tsMCP": {
      "command": "node",
      "args": ["/path/to/your/project/build/server.js"]
    }
  }
}

Cursor

To integrate your MCP server with Cursor, add this configuration to your MCP settings:

{
  "mcpServers": {
    "tsMCP": {
      "command": "node",
      "args": ["/path/to/your/project/build/server.js"]
    }
  }
}

Other Applications

The server communicates over stdio, making it compatible with any MCP client that supports the stdio transport.

Error Handling

The boilerplate includes comprehensive error handling:

Input validation using Zod schemas
Proper MCP error codes and messages
Graceful cleanup on shutdown
Type-safe parameter handling

Environment Variables

Create a .env file for environment-specific configuration:

# Server configuration
MCP_SERVER_NAME=my-custom-server
MCP_SERVER_VERSION=1.0.0

# Application-specific settings
LOG_LEVEL=info

Advanced Usage

Custom Transports

You can implement custom transports beyond stdio:

import { WebSocketServerTransport } from '@modelcontextprotocol/sdk/server/websocket.js';

const transport = new WebSocketServerTransport({
  port: 8080
});

Middleware and Plugins

Extend the server with custom middleware:

server.setRequestHandler(MyCustomRequestSchema, async (request) => {
  // Custom handling logic
});