{
  "openapi": "3.1.0",
  "info": {
    "title": "Geoapify MCP Calculate Route Tool",
    "version": "0.1.0",
    "description": "OpenAPI specification for calling the Geoapify MCP calculate_route tool through the JSON-RPC endpoint."
  },
  "servers": [
    {
      "url": "https://api.geoapify.com/v1"
    }
  ],
  "tags": [
    {
      "name": "MCP Calculate Route",
      "description": "Call the Geoapify MCP calculate_route tool through the JSON-RPC endpoint."
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "tags": [
          "MCP Calculate Route"
        ],
        "operationId": "callMcpCalculateRoute",
        "summary": "Call the calculate_route MCP tool",
        "description": "Call the calculate_route MCP tool with a JSON-RPC tools/call request.",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "description": "Geoapify API key.",
            "schema": {
              "type": "string"
            },
            "example": "YOUR_API_KEY"
          }
        ],
        "requestBody": {
          "description": "JSON-RPC request body for the calculate_route MCP tool.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalculateRouteToolCallRequest"
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                  "name": "calculate_route",
                  "arguments": {
                    "waypoints": [
                      {
                        "lat": 52.52,
                        "lon": 13.405
                      },
                      {
                        "lat": 52.51,
                        "lon": 13.39
                      }
                    ],
                    "mode": "drive",
                    "geometry_scope": "route",
                    "geometry_format": "geojson",
                    "include_instructions": false
                  }
                }
              },
              "examples": {
                "calculateRoute": {
                  "summary": "Calculate route",
                  "description": "Calculate a route between geographic waypoints for a supported travel mode.",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/call",
                    "params": {
                      "name": "calculate_route",
                      "arguments": {
                        "waypoints": [
                          {
                            "lat": 52.52,
                            "lon": 13.405
                          },
                          {
                            "lat": 52.51,
                            "lon": 13.39
                          }
                        ],
                        "mode": "drive",
                        "geometry_scope": "route",
                        "geometry_format": "geojson",
                        "include_instructions": false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response for the MCP tool call.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ToolCallResponse"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload or tool arguments."
          },
          "401": {
            "description": "Missing or invalid Geoapify API key."
          },
          "429": {
            "description": "Rate limit or quota exceeded."
          },
          "500": {
            "description": "Internal gateway error."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CalculateRouteToolCallRequest": {
        "type": "object",
        "description": "JSON-RPC tools/call request for the calculate_route MCP tool.",
        "additionalProperties": false,
        "required": [
          "jsonrpc",
          "id",
          "method",
          "params"
        ],
        "properties": {
          "jsonrpc": {
            "description": "JSON-RPC protocol version.",
            "const": "2.0"
          },
          "id": {
            "description": "Client-supplied JSON-RPC request id echoed in the response.",
            "$ref": "#/components/schemas/JsonRpcId"
          },
          "method": {
            "description": "MCP method used to call a tool.",
            "const": "tools/call"
          },
          "params": {
            "description": "Tool call parameters for calculate_route.",
            "$ref": "#/components/schemas/CalculateRouteToolCallParams"
          }
        },
        "examples": [
          {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
              "name": "calculate_route",
              "arguments": {
                "waypoints": [
                  {
                    "lat": 52.52,
                    "lon": 13.405
                  },
                  {
                    "lat": 52.52,
                    "lon": 13.405
                  }
                ]
              }
            }
          }
        ],
        "x-geoapify-mcp-tool": "calculate_route",
        "x-geoapify-mcp-category": "Routing",
        "x-geoapify-mcp-input-schema": "#/components/schemas/CalculateRouteInput",
        "x-geoapify-mcp-output-schema": "#/components/schemas/CalculateRouteOutput"
      },
      "JsonRpcId": {
        "description": "JSON-RPC request identifier. The server echoes this value in the response.",
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ]
      },
      "CalculateRouteToolCallParams": {
        "type": "object",
        "description": "MCP tools/call params for calculate_route.",
        "additionalProperties": false,
        "required": [
          "name",
          "arguments"
        ],
        "properties": {
          "name": {
            "description": "Registered MCP tool name.",
            "const": "calculate_route"
          },
          "arguments": {
            "description": "Arguments validated by the calculate_route input schema.",
            "$ref": "#/components/schemas/CalculateRouteInput"
          }
        }
      },
      "CalculateRouteInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "waypoints"
        ],
        "properties": {
          "waypoints": {
            "type": "array",
            "minItems": 2,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "lat",
                "lon"
              ],
              "properties": {
                "lat": {
                  "type": "number",
                  "minimum": -90,
                  "maximum": 90,
                  "description": "Waypoint latitude."
                },
                "lon": {
                  "type": "number",
                  "minimum": -180,
                  "maximum": 180,
                  "description": "Waypoint longitude."
                }
              }
            },
            "description": "Ordered route waypoints. Provide at least an origin and destination."
          },
          "mode": {
            "type": "string",
            "enum": [
              "drive",
              "light_truck",
              "medium_truck",
              "truck",
              "heavy_truck",
              "truck_dangerous_goods",
              "long_truck",
              "bus",
              "scooter",
              "motorcycle",
              "bicycle",
              "mountain_bike",
              "road_bike",
              "walk",
              "hike",
              "transit",
              "approximated_transit"
            ],
            "default": "drive",
            "description": "Travel or vehicle mode used to calculate the route."
          },
          "waypoint_mode": {
            "type": "string",
            "enum": [
              "stopover",
              "through_stop",
              "pass_through"
            ],
            "default": "stopover",
            "description": "How intermediate waypoints are treated."
          },
          "type": {
            "type": "string",
            "enum": [
              "balanced",
              "short",
              "less_maneuvers"
            ],
            "default": "balanced",
            "description": "Route optimization preference."
          },
          "avoid": {
            "type": "array",
            "maxItems": 3,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "tolls",
                "ferries",
                "highways"
              ]
            },
            "description": "Route features to avoid. Supported values are \"tolls\", \"ferries\", and \"highways\"."
          },
          "geometry_scope": {
            "type": "string",
            "enum": [
              "none",
              "route",
              "legs",
              "steps"
            ],
            "default": "route",
            "description": "Geometry detail to return: none, route only, route and legs, or route, legs, and instruction steps."
          },
          "geometry_format": {
            "type": "string",
            "enum": [
              "geojson",
              "polyline"
            ],
            "default": "geojson",
            "description": "Return geometry as a GeoJSON geometry object or an encoded precision-5 polyline."
          },
          "include_instructions": {
            "type": "boolean",
            "default": false,
            "description": "Include detailed turn-by-turn instruction steps."
          },
          "optimize_stops": {
            "type": "boolean",
            "default": false,
            "description": "Optimize the order of intermediate stops while preserving the first and last waypoint."
          },
          "units": {
            "type": "string",
            "enum": [
              "metric",
              "imperial"
            ],
            "default": "metric",
            "description": "Distance and speed units."
          },
          "lang": {
            "type": "string",
            "enum": [
              "bg",
              "ca",
              "cs",
              "da",
              "de",
              "el",
              "en-GB",
              "en",
              "es",
              "et",
              "fi",
              "fr",
              "hi",
              "hu",
              "it",
              "ja",
              "nb-NO",
              "nl",
              "pl",
              "pt-BR",
              "pt",
              "ro",
              "ru",
              "sk",
              "sl",
              "sv",
              "tr",
              "uk"
            ],
            "default": "en",
            "description": "Language used for turn-by-turn instructions."
          },
          "traffic": {
            "type": "string",
            "enum": [
              "free_flow",
              "approximated"
            ],
            "default": "free_flow",
            "description": "Traffic model used for motorized routing."
          }
        }
      },
      "CalculateRouteOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "units",
          "distance_units",
          "time_units",
          "waypoints",
          "legs"
        ],
        "properties": {
          "distance": {
            "type": "number"
          },
          "units": {
            "type": "string",
            "enum": [
              "metric",
              "imperial"
            ]
          },
          "distance_units": {
            "type": "string",
            "enum": [
              "meters",
              "miles"
            ]
          },
          "time": {
            "type": "number"
          },
          "time_units": {
            "type": "string",
            "enum": [
              "seconds"
            ]
          },
          "waypoints": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "lat",
                "lon"
              ],
              "properties": {
                "lat": {
                  "type": "number"
                },
                "lon": {
                  "type": "number"
                }
              }
            }
          },
          "legs": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "geometry": {
                  "oneOf": [
                    {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "type",
                        "coordinates"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "LineString",
                            "MultiLineString"
                          ]
                        },
                        "coordinates": {
                          "type": "array"
                        }
                      }
                    },
                    {
                      "type": "string",
                      "description": "Precision-5 encoded polyline."
                    }
                  ]
                },
                "steps": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true,
                    "properties": {
                      "geometry": {
                        "oneOf": [
                          {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "type",
                              "coordinates"
                            ],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "LineString",
                                  "MultiLineString"
                                ]
                              },
                              "coordinates": {
                                "type": "array"
                              }
                            }
                          },
                          {
                            "type": "string",
                            "description": "Precision-5 encoded polyline."
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "geometry": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "type",
                  "coordinates"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "LineString",
                      "MultiLineString"
                    ]
                  },
                  "coordinates": {
                    "type": "array"
                  }
                }
              },
              {
                "type": "string",
                "description": "Precision-5 encoded polyline."
              }
            ]
          }
        }
      },
      "ToolCallResponse": {
        "type": "object",
        "description": "Successful JSON-RPC response for tools/call. Tool failures are returned with isError set to true.",
        "additionalProperties": false,
        "required": [
          "jsonrpc",
          "id",
          "result"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "$ref": "#/components/schemas/JsonRpcId"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "content",
              "isError"
            ],
            "properties": {
              "content": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "type",
                    "text"
                  ],
                  "properties": {
                    "type": {
                      "const": "text"
                    },
                    "text": {
                      "type": "string"
                    }
                  }
                }
              },
              "structuredContent": {
                "description": "Structured output returned by the calculate_route tool.",
                "$ref": "#/components/schemas/CalculateRouteOutput"
              },
              "isError": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "JsonRpcErrorResponse": {
        "type": "object",
        "description": "JSON-RPC error response returned for invalid requests or unknown methods.",
        "additionalProperties": false,
        "required": [
          "jsonrpc",
          "id",
          "error"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "$ref": "#/components/schemas/JsonRpcId"
          },
          "error": {
            "$ref": "#/components/schemas/JsonRpcError"
          }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "description": "JSON-RPC error object.",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          },
          "data": true
        }
      }
    }
  }
}