Tools for agents: Closest point on a 3D polyline

Project a point onto a 3D path and return exact nearest positions, segment parameters and squared distance.

Connect with MCP

{
  "mcpServers": {
    "super-agent-tools": {
      "url": "https://app.getsupers.com/sites/agent-polyline-nearest/mcp"
    }
  }
}
Streamable HTTP · No API key · Stateless

Use this URL in any client supporting remote Streamable HTTP MCP. Calls return structured JSON; inputs are processed without persistence.

Call nearest_polyline_point

Segments connect consecutive vertices in the supplied order; the path is open. To close a path, repeat its first vertex at the end. Indices are zero-based. A segment point is start + parameter*(end-start), with parameter in [0,1]; this is not normalized path length. Return all exactly tied nearest segments in index order, including shared vertices and overlaps. A zero-length segment is treated as a point with parameter 0 and is also listed in degenerate_segments. Squared Euclidean distance stays exact; ordinary distance is its square root and may be irrational. Inputs are integers or quoted decimal/fraction strings; JSON floats and booleans are rejected. Coordinates use one common Cartesian unit; no geographic, geodesic or curved-path interpretation is applied. Uses rational arithmetic and scans every segment; intended for small exact geometry tasks.

Input and output schemas
{
  "name": "nearest_polyline_point",
  "title": "Closest point on a 3D polyline",
  "description": "Project a 3D query onto each consecutive segment of an open polyline. Return every exactly tied nearest segment with rational coordinates and squared Euclidean distance.",
  "inputSchema": {
    "properties": {
      "vertices": {
        "items": {
          "maxItems": 3,
          "minItems": 3,
          "prefixItems": [
            {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            }
          ],
          "type": "array"
        },
        "title": "Vertices",
        "type": "array"
      },
      "query": {
        "maxItems": 3,
        "minItems": 3,
        "prefixItems": [
          {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ]
          },
          {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ]
          },
          {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ]
          }
        ],
        "title": "Query",
        "type": "array"
      }
    },
    "required": [
      "vertices",
      "query"
    ],
    "title": "nearest_polyline_pointArguments",
    "type": "object"
  },
  "outputSchema": {
    "additionalProperties": true,
    "title": "nearest_polyline_pointDictOutput",
    "type": "object"
  },
  "icons": null,
  "annotations": {
    "title": null,
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "meta": null,
  "execution": null
}

Run the example to see the actual result.

HTTP alternative

POST https://app.getsupers.com/sites/agent-polyline-nearest/call
Content-Type: application/json

{
  "vertices": [
    [
      0,
      0,
      0
    ],
    [
      4,
      0,
      0
    ],
    [
      4,
      4,
      0
    ]
  ],
  "query": [
    2,
    1,
    3
  ]
}

The HTTP and MCP interfaces execute the same implementation. Validation errors are returned explicitly. See the tool notes above for its supported inputs and behavior.

Exact projections choose the nearest open-path segment

Read the explanation

The supplied open path has two segments. Query two, one, three projects onto the first at two, zero, zero, with parameter one half. Its squared distance is one squared plus three squared, or ten. The second projects at four, one, zero, parameter one quarter, with squared distance two squared plus three squared, or thirteen. Ten is smaller, so segment zero is nearest. Ordinary distance is square root ten; rational squared distance stays exact. Each parameter belongs to that segment, using start plus parameter times direction. One half and one quarter are not normalized positions over the whole path. The projection formula uses the dot product divided by squared direction length, clamped inclusively to zero and one. If query is minus one, zero, zero on the first segment, unconstrained parameter minus one quarter clamps to zero, so the endpoint is nearest and squared distance is one. Endpoints are valid results. Repeating a vertex produces a zero-length segment. It is treated as a point with parameter zero and listed as degenerate, rather than dividing by zero. All exactly tied nearest segments are returned in index order, including shared vertices and overlaps. The path stays open unless the first vertex is repeated at the end. Inputs require integer or quoted rational coordinates, not floats or booleans. These calculations illustrate the published contract; no backend or remote MCP execution was requested or verified.

Exact Closest Point on a 3D Polyline

How does the nearest_polyline_point tool calculate the exact closest point on a piecewise-linear 3D polyline without floating-point inaccuracy?

The nearest_polyline_point tool calculates the orthogonal projection of a 3D query point onto each individual line segment formed by consecutive polyline vertices. For each segment from point a to b with direction vector d = b - a, an unconstrained linear parameter is computed using rational vector arithmetic as (q - a) · d / (d · d). Clamping this parameter to the unit interval [0, 1] determines the unique closest point on that bounded segment. The tool evaluates squared Euclidean distances across all segments, flags degenerate zero-length segments, and returns exact rational coordinates along with every segment that ties for the minimum distance.

The parameter t is localized to each segment in [0, 1] rather than normalized across cumulative polyline arc length. The implementation conducts an exhaustive linear scan of all segments without spatial bounding trees, making it suitable for moderate polyline sizes. Inputs must be integers or quoted rational/decimal strings; native JSON floats are rejected to prevent precision loss. Calculations assume Cartesian flat Euclidean space and do not account for curved paths or geodesics.

Try a worked example

In the default JSON arguments, the polyline consists of vertices [0,0,0], [4,0,0], and [4,4,0], with query point [2,1,3]. Clicking 'Run tool' executes the rational projection: for segment 0 from [0,0,0] to [4,0,0], the parameter is (2*4)/(16) = 1/2, locating point [2,0,0] at squared distance (2-2)² + (1-0)² + (3-0)² = 10. For segment 1 from [4,0,0] to [4,4,0], the clamped parameter is 1/4, locating point [4,1,0] at squared distance 13. The structured output displays segment 0 as the sole nearest segment with squared_distance '10', parameter '1/2', and location 'interior'.

Segment Parameterization and Clamping

Each polyline segment between consecutive vertices a and b is parameterized by p(t) = a + t * (b - a). Minimizing Euclidean distance to query point q leads to the projection parameter t = ((q - a) · (b - a)) / |b - a|². Bounding the projection to the physical segment requires clamping t to the range [0, 1]. A value of t = 0 corresponds to the start vertex, t = 1 represents the end vertex, and values strictly between 0 and 1 correspond to an interior orthogonal projection.

Exact Rational Arithmetic and Tie Handling

By parsing inputs as exact fractions, the calculation avoids floating-point roundoff errors. The comparison of candidate segments evaluates squared Euclidean distance directly, preserving rational exactness without computing irrational square roots. When multiple segments yield identical minimum squared distances—such as at shared vertices, overlapping lines, or equidistant symmetry—the tool preserves all tied candidates in their original index order.