# Ghana Post GPS MCP Server

A Model Context Protocol (MCP) server that converts Ghana Post GPS addresses into detailed location information including coordinates.

## Features

- **GPS Address Lookup**: Convert Ghana Post GPS codes (e.g., "GA-554-3608") to detailed location information
- **Address Validation**: Validate GPS code format before processing
- **Batch Processing**: Look up multiple GPS addresses at once (up to 10)
- **Nearby Coordinates**: Generate coordinates within a specified radius of a known location
- **Real API Integration**: Uses the actual Ghana Post GPS API

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- npm

### Setup

1. **Clone or download this project**
2. **Install dependencies**:
   ```bash
   npm install
   ```

3. **Build the project**:
   ```bash
   npm run build
   ```

## Usage

### Development Mode
```bash
npm run dev
```

### Production Mode
```bash
npm run start
```

### Testing
```bash
# Test server connection
npm run test

# Test GPS lookup
npm run test-lookup
```

## Available Tools

### 1. lookup_gps_address
Converts a Ghana Post GPS address to detailed location information.

**Input**: 
- `gps_code` (string): GPS address code (e.g., "GA-554-3608")

**Output**: Location details including coordinates, street, area, district, region, and postcode.

### 2. validate_gps_code
Validates if a string matches the Ghana Post GPS address format.

**Input**: 
- `gps_code` (string): GPS code to validate

**Output**: Validation result with format information and examples.

### 3. batch_lookup_gps
Looks up multiple GPS addresses at once (maximum 10).

**Input**: 
- `gps_codes` (array): Array of GPS codes to look up

**Output**: Results for all provided GPS codes with status information.

### 4. find_nearby_coordinates
Generates coordinates within a radius of a known GPS location.

**Input**: 
- `gps_code` (string): Base GPS code
- `radius_km` (number, optional): Search radius in kilometers (default: 1)
- `count` (number, optional): Number of points to generate (default: 5)

**Output**: Base location info and array of nearby coordinates.

## Claude Desktop Integration

To use this MCP server with Claude Desktop:

### Windows
1. Edit `%APPDATA%\\Claude\\claude_desktop_config.json`
2. Add the server configuration:

```json
{
  "mcpServers": {
    "ghana-post-gps": {
      "command": "node",
      "args": ["C:\\Users\\FRANKO\\OneDrive\\Desktop\\ghana-post-mcp\\dist\\index.js"],
      "env": {}
    }
  }
}
```

### macOS
1. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
2. Add the server configuration:

```json
{
  "mcpServers": {
    "ghana-post-gps": {
      "command": "node",
      "args": ["/path/to/ghana-post-mcp/dist/index.js"],
      "env": {}
    }
  }
}
```

### Linux
1. Edit `~/.config/Claude/claude_desktop_config.json`
2. Add the server configuration with the appropriate path.

## GPS Address Format

Ghana Post GPS addresses follow this format:
- **Format**: `XX-YYY-ZZZZ`
- **XX**: 2-letter region code (e.g., GA, AK, CP)
- **YYY**: 3-digit area code
- **ZZZZ**: 3-4 digit location code

### Examples
- `GA-554-3608` (Greater Accra)
- `AK-039-5028` (Ashanti)
- `CP-078-2542` (Central)

## API Information

This server uses the Ghana Post GPS API endpoint:
- **URL**: `https://ghanapostgps.sperixlabs.org/get-location`
- **Method**: POST
- **Content-Type**: `application/x-www-form-urlencoded`

## Development

### Project Structure
```
ghana-post-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (after build)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file
```

### Building
```bash
npm run build
```

### Cleaning
```bash
npm run clean
```

## Error Handling

The server includes comprehensive error handling for:
- Invalid GPS code formats
- API connection failures
- Missing or malformed data
- Rate limiting considerations

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

MIT License

## Support

For issues or questions about Ghana Post GPS addresses, refer to the official Ghana Post documentation or contact Ghana Post directly.