# 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:
```bash
npm install
```
2. Build the project:
```bash
npm run build
```
## Usage
### Development Mode
Run the server in development mode with hot reloading:
```bash
npm run dev
```
### Production Mode
Build and run the compiled server:
```bash
npm run build
npm start
```
### Watch Mode
Build and watch for changes:
```bash
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:
```json
{
"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:**
```bash
# 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](https://aviationstack.com)
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:
```bash
# 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/
