sumitvairagar/mcp-server-starter

Simple MCP Server

A simple Model Context Protocol (MCP) server implementation using TypeScript and the official MCP SDK.

Features

This MCP server provides:

Tools

• echo: Echoes back the input text
• add_numbers: Adds two numbers together
• get_current_time: Returns the current date and time
• get_flight_status: Get real-time flight status using flight number (supports both mock and real API data)

Resources

• info://server: Server information and capabilities
• greeting://hello: A simple greeting message

Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

Usage

Development Mode

Run the server in development mode with hot reloading:

npm run dev

Production Mode

Build and run the compiled server:

npm run build
npm start

Watch Mode

Build and watch for changes:

npm run watch

MCP Client Integration

To use this server with an MCP client, you'll need to configure the client to connect to this server. The server uses stdio transport, so it can be launched as a subprocess.

Example configuration for MCP clients:

{
  "mcpServers": {
    "simple-server": {
      "command": "node",
      "args": ["path/to/dist/index.js"]
    }
  }
}

Project Structure

├── examples/                   # Example implementations
│   ├── resources/
│   │   └── example-resource.ts # Example resource implementations
│   └── tools/
│       └── example-tool.ts     # Example tool implementations
├── src/                        # Source code
│   ├── handlers/
│   │   └── index.ts            # MCP request handlers
│   ├── resources/
│   │   ├── index.ts            # Resource implementations
│   │   └── registry.ts         # Resource registry
│   ├── tools/
│   │   ├── index.ts            # Tool implementations
│   │   └── registry.ts         # Tool registry
│   ├── types/
│   │   └── index.ts            # TypeScript type definitions
│   ├── utils/
│   │   └── config.ts           # Configuration and utilities
│   ├── index.ts                # Main entry point
│   └── server.ts               # Core server implementation
├── dist/                       # Compiled JavaScript (generated)
├── package.json                # Node.js dependencies and scripts
├── tsconfig.json               # TypeScript configuration
├── test.js                     # Basic test script
├── test-comprehensive.js       # Comprehensive test script
└── README.md                   # This file

Modular Architecture

The server is built with a modular architecture that makes it easy to extend:

• Tools: Each tool is a separate class implementing the ToolHandler interface
• Resources: Each resource is a separate class implementing the ResourceHandler interface
• Registries: Central registries manage all tools and resources
• Handlers: Request handlers manage MCP protocol communication
• Types: Shared TypeScript interfaces for type safety

Development

Adding New Tools

1. Create a new tool class implementing ToolHandler in src/tools/
2. Add the tool to the ToolRegistry in src/tools/registry.ts
3. See examples/tools/example-tool.ts for a complete example

Adding New Resources

1. Create a new resource class implementing ResourceHandler in src/resources/
2. Add the resource to the ResourceRegistry in src/resources/registry.ts
3. See examples/resources/example-resource.ts for complete examples

Flight Status Tool

The flight status tool provides real-time flight information:

Features:

• Real-time flight status (scheduled, active, landed, cancelled, delayed)
• Departure and arrival airport information
• Airline details
• Scheduled times
• International flight support

Usage:

# Test the flight status tool
node test-flight-status.js

API Integration: By default, the tool uses mock data. To get real flight data:

1. Sign up for a free API key at AviationStack
2. Set the environment variable: AVIATIONSTACK_API_KEY=your_api_key
3. Rebuild and restart the server

Testing

Run the test scripts to verify functionality:

# Basic test
node test.js

# Comprehensive test with all features
node test-comprehensive.js

# Test flight status tool specifically
node test-flight-status.js

Git Configuration

The project includes a comprehensive .gitignore file that excludes:

• Environment files (.env*) containing API keys
• Compiled output (dist/)
• Dependencies (node_modules/)
• IDE/editor files
• OS-specific files
• Logs and temporary files

Important Security Note: API keys and secrets are automatically excluded from git tracking.

See GITIGNORE_INFO.md for detailed information about ignored files.

MCP Protocol

This server implements the Model Context Protocol (MCP) which allows AI assistants to securely access external tools and data sources. The server communicates via JSON-RPC over stdio.

For more information about MCP, visit: https://modelcontextprotocol.io/