mapping-mcp-server/README.md

Model Context Protocol server for interactive map visualization with real-time VATSIM aircraft tracking

# Mapping MCP Server

A Model Context Protocol (MCP) server for interactive map visualization with real-time VATSIM aircraft tracking, featuring WebSocket updates and custom aircraft icons.

## Features

- **Interactive Web Map**: Leaflet-based map with pan, zoom, and object interaction
- **Real-time VATSIM Integration**: Fetch and display live aircraft data from VATSIM
- **WebSocket Updates**: Live map updates without page refresh
- **Custom Aircraft Icons**: Rotatable aircraft icons showing heading direction
- **Multi-Object Support**: Display aircraft, controllers, airports, and waypoints
- **Flexible Data Input**: Accept callsigns or full position data
- **Auto Port Selection**: Automatically finds available port if 3001 is in use
- **React 19 & TypeScript**: Modern tech stack with full type safety

## Installation

```bash
npm install -g mapping-mcp-server
```

Or with Bun:
```bash
bun install -g mapping-mcp-server
```

## Usage

### Command Line
```bash
# Using npm/node
mapping-mcp-server

# Using bun directly
bun mapping-mcp-server
```

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mapping": {
      "command": "mapping-mcp-server"
    }
  }
}
```

Or with Bun:
```json
{
  "mcpServers": {
    "mapping": {
      "command": "bun",
      "args": ["mapping-mcp-server"]
    }
  }
}
```

## Available Tools

### `show_map`
Display geo-located objects on an interactive map.

**Parameters:**
- `topic` (string): Title for the map display
- `objects` (array): Array of geo-located objects with:
  - `latitude` (number): Required
  - `longitude` (number): Required
  - `type` (string): "aircraft", "controller", "airport", or "waypoint"
  - `callsign` (string): Object identifier
  - `altitude` (number): Altitude in feet
  - `heading` (number): Direction in degrees (0-360)
  - `groundspeed` (number): Speed in knots
  - Additional fields as needed

**Example:**
```javascript
{
  "topic": "European Traffic",
  "objects": [
    {
      "callsign": "DLH123",
      "latitude": 50.0264,
      "longitude": 8.5431,
      "altitude": 35000,
      "heading": 270,
      "groundspeed": 420,
      "type": "aircraft",
      "aircraft": "A320",
      "departure": "EDDF",
      "arrival": "EGLL"
    }
  ]
}
```

### `show_aircraft_by_callsigns`
Display aircraft by fetching real-time VATSIM data using callsigns.

**Parameters:**
- `callsigns` (array): Array of aircraft callsigns
- `topic` (string): Optional map title
- `center` (object): Optional center point with latitude, longitude, radius

**Example:**
```javascript
{
  "callsigns": ["DLH123", "SAS456", "KLM789"],
  "topic": "Selected VATSIM Flights"
}
```

### `open_map`
Open the mapping interface in a browser window.

### `clear_map`
Clear all objects from the current map display.

## Integration with VATSIM MCP

The mapping server works seamlessly with the VATSIM MCP server:

1. **VATSIM queries**: Use vatsim-mcp to search for flights
2. **Send to map**: VATSIM MCP sends callsigns to mapping server
3. **Data fetch**: Mapping server fetches complete data from VATSIM API
4. **Display**: Aircraft appear on map with real-time positions

## Web Interface Features

The web interface at `http://localhost:3001` provides:

- **Interactive Map**: Pan, zoom, and click on objects
- **Aircraft Icons**: Rotatable emoji icons showing heading
- **Popup Details**: Click any object for full information
- **Real-time Updates**: WebSocket connection for live updates
- **Auto-centering**: Map centers on displayed objects
- **Legend**: Shows object counts by type

## API Endpoints

- `GET /` - Main map interface
- `GET /api/data` - Current map data as JSON
- `POST /api/show-aircraft-by-callsigns` - Display aircraft by callsigns
- `WS /ws` - WebSocket for real-time updates

## Development

```bash
# Clone repository
git clone <repository>
cd mapping-mcp-server

# Install dependencies
bun install

# Development with hot reload
bun run dev

# Build for distribution
npm run build

# Run tests
npm test
```

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Claude     │────▶│  VATSIM MCP  │────▶│ Mapping MCP  │
│   Desktop    │     │    Server    │     │    Server    │
└──────────────┘     └──────────────┘     └──────────────┘
                            │                      │
                            ▼                      ▼
                     ┌──────────────┐      ┌──────────────┐
                     │  VATSIM API  │      │  Web Browser │
                     └──────────────┘      │   (Leaflet)  │
                                           └──────────────┘
```

## Performance

- **Caching**: 30-second cache for VATSIM data
- **Bundling**: Frontend bundled on-the-fly with Bun
- **WebSocket**: Efficient real-time updates
- **Port Management**: Automatic port selection if default is busy

## Troubleshooting

### Blank Map Page
- Check browser console for errors
- Verify frontend.tsx is being bundled correctly
- Ensure Leaflet CSS is loading

### Connection Issues
- Default port is 3001, automatically increments if busy
- Check firewall settings for localhost connections
- Verify WebSocket connection in browser DevTools

### VATSIM Data Not Loading
- Check internet connection
- Verify VATSIM API is accessible
- Check for rate limiting (30-second cache)

## Requirements

- Node.js 18+ or Bun 1.0+
- Modern web browser with JavaScript enabled
- Internet connection for VATSIM data

## License

MIT

## Data Sources

- **VATSIM API**: https://data.vatsim.net/v3/vatsim-data.json
- **Map Tiles**: OpenStreetMap via Leaflet
- **Icons**: Native emoji for aircraft and markers

## Contributing

Contributions welcome! Please submit PRs or issues on GitHub.

## Changelog

### v1.0.0
- Initial release with full VATSIM integration
- WebSocket real-time updates
- Custom aircraft icons with heading
- Support for npm and Bun runtimes