# Server Endpoints
When running the GIS MCP server in HTTP or SSE transport mode, the following endpoints are available:
## MCP Endpoints
### `/mcp` (HTTP Transport)
- **Method**: POST
- **Content-Type**: application/json
- **Description**: Main MCP JSON-RPC endpoint for HTTP transport
- **Usage**: Used by MCP clients to communicate with the server via HTTP POST requests
### `/sse` (SSE Transport)
- **Method**: GET
- **Content-Type**: text/event-stream
- **Description**: Server-Sent Events endpoint for SSE transport
- **Usage**: Used by MCP clients for real-time streaming communication
## Storage Endpoints
The storage endpoints allow clients to upload, download, and list files on the server's storage directory.
### `POST /storage/upload`
Upload a file to the server's storage directory.
**Request:**
- **Content-Type**: `multipart/form-data`
- **Form Fields**:
- `file` (required): The file to upload
- `path` (optional): Remote path where the file should be saved (defaults to filename)
**Response:**
```json
{
"remote_path": "output.gpkg",
"size": 12345,
"message": "File uploaded successfully to output.gpkg"
}
```
**Example using curl:**
```bash
curl -X POST http://localhost:8080/storage/upload \
-F "file=@local_file.gpkg" \
-F "path=output.gpkg"
```
**Example using Python requests:**
```python
import requests
with open('local_file.gpkg', 'rb') as f:
files = {'file': ('local_file.gpkg', f, 'application/octet-stream')}
data = {'path': 'output.gpkg'}
response = requests.post('http://localhost:8080/storage/upload', files=files, data=data)
print(response.json())
```
### `GET /storage/download`
Download a file from the server's storage directory.
**Request:**
- **Query Parameters**:
- `path` (required): Path to the file to download
**Response:**
- **Content-Type**: `application/octet-stream`
- **Body**: File content
**Example using curl:**
```bash
curl -O http://localhost:8080/storage/download?path=output.gpkg
```
**Example using Python requests:**
```python
import requests
response = requests.get('http://localhost:8080/storage/download', params={'path': 'output.gpkg'})
with open('downloaded_file.gpkg', 'wb') as f:
f.write(response.content)
```
### `GET /storage/list`
List files in the server's storage directory.
**Request:**
- **Query Parameters**:
- `path` (optional): Directory path to list (defaults to storage root)
**Response:**
```json
{
"files": [
{
"name": "output.gpkg",
"path": "output.gpkg",
"size": 12345,
"type": "file",
"modified": 1234567890.0
},
{
"name": "subfolder",
"path": "subfolder",
"size": null,
"type": "directory",
"modified": 1234567890.0
}
],
"path": "/"
}
```
**Example using curl:**
```bash
curl http://localhost:8080/storage/list?path=outputs
```
**Example using Python requests:**
```python
import requests
response = requests.get('http://localhost:8080/storage/list', params={'path': 'outputs'})
files = response.json()
for file in files['files']:
print(f"{file['name']} ({file['type']})")
```
## Endpoint Availability
The endpoints are only available when the server is running in HTTP or SSE transport mode:
- **STDIO mode**: No HTTP endpoints available (server communicates via stdin/stdout)
- **HTTP mode**: `/mcp` and `/storage/*` endpoints available
- **SSE mode**: `/sse` and `/storage/*` endpoints available
## Storage Path
Files are stored in the configured storage directory:
- **Default**: `~/.gis_mcp/data/`
- **Configurable**: Set via `GIS_MCP_STORAGE_PATH` environment variable or `--storage-path` CLI argument
Relative paths in storage operations are resolved relative to this storage directory. Absolute paths are used as-is.
## Example Workflow
1. **Upload a file:**
```bash
curl -X POST http://localhost:8080/storage/upload \
-F "file=@input.shp" \
-F "path=input.shp"
```
2. **Process the file using MCP tools** (via `/mcp` or `/sse` endpoint)
3. **List available files:**
```bash
curl http://localhost:8080/storage/list
```
4. **Download the result:**
```bash
curl -O http://localhost:8080/storage/download?path=output.gpkg
```
## Error Responses
All endpoints return appropriate HTTP status codes:
- **200 OK**: Success
- **400 Bad Request**: Invalid request (missing parameters, invalid data)
- **404 Not Found**: File or path not found
- **500 Internal Server Error**: Server error
Error responses include a JSON body with error details:
```json
{
"error": "File not found: output.gpkg",
"message": "File not found: output.gpkg"
}
```
