EncDotNet.S100.Mcp.Tools
EncDotNet.S100.Mcp.Tools contains the logic of the S-100 Model Context
Protocol (MCP) tools: listing datasets, describing features, spatial queries,
coverage sampling, session changes and the Library. It has no MCP protocol
code, transport, Avalonia or viewer dependency. Reference it to call the tools
in-process, or to build tools for another host.
EncDotNet.S100.Mcp serves these tools over
MCP.
For what each tool does from an agent's point of view, see the MCP server guide.
Install
This package isn't published to NuGet. Add a project reference:
<ProjectReference Include="path/to/src/EncDotNet.S100.Mcp.Tools/EncDotNet.S100.Mcp.Tools.csproj" />
The shared catalog, geometry, time and query types that the tools use, such as
IDatasetCatalog, GeoQuery, ToolResult<T>, IdentifyFeaturesService and
SampleCoverageService, are in EncDotNet.S100.Datasets.Pipelines, in the
Catalog, Geometry, Spec, Time and Query namespaces. The s100 identify
command uses the same services, so its results match the tools'.
Call a tool
Each tool is a class with one InvokeAsync method that takes a request record
and returns Task<ToolResult<T>>. Most take an IDatasetCatalog, the set of
datasets the tools can see. FileDatasetCatalog builds one from dataset files:
using EncDotNet.S100.Core;
using EncDotNet.S100.Datasets.Pipelines;
using EncDotNet.S100.Datasets.Pipelines.Catalog;
using EncDotNet.S100.Datasets.Pipelines.Geometry;
using EncDotNet.S100.Datasets.Pipelines.Query;
using EncDotNet.S100.Mcp.Tools;
string path = args[0];
string spec = DatasetPipelineFactory.DetectProductSpec(path)
?? throw new InvalidOperationException($"Couldn't detect the product of {path}.");
IDatasetCatalog catalog = FileDatasetCatalog.Build(
[new FileDatasetInput(new DatasetId("cell"), spec, path)]);
// List the loaded datasets.
var listed = await new ListDatasetsTool(catalog).InvokeAsync(new ListDatasetsRequest());
if (listed.TryGetValue(out var summary))
{
foreach (var dataset in summary.Datasets)
Console.WriteLine($"{dataset.Id} ({dataset.Spec})");
}
// Identify the features at a point, most specific first.
var picked = await new IdentifyFeaturesTool(catalog).InvokeAsync(
new IdentifyFeaturesRequest(Latitude: 50.77, Longitude: -1.30, RadiusMeters: 50));
if (picked.TryGetValue(out var pick))
{
foreach (var match in pick.Features)
Console.WriteLine($"{match.FeatureType} {match.FeatureId} ({match.Geometry}, {match.Containment})");
}
else if (picked.TryGetError(out var error))
{
Console.WriteLine($"{error.Code}: {error.Message}");
}
// Find S-101 lights in a box that have a name.
var lights = await new QueryFeaturesTool(catalog).InvokeAsync(new QueryFeaturesRequest(
new GeoQuery.Box(new GeoBoundingBox(50.7, -1.4, 50.8, -1.2)),
Spec: new SpecRef("S-101", default),
FeatureType: "LIGHTS",
Attributes: [new AttributePredicate("objectName", AttributeOperator.Exists, null)]));
if (lights.TryGetValue(out var page))
{
foreach (var light in page.Features)
Console.WriteLine($"{light.FeatureType} {light.FeatureId}");
}
SpecRef("S-101", default) matches every edition of S-101. Pass a
SpecVersion to match one edition.
The tests in
tests/EncDotNet.S100.Mcp.Tools.Tests
call every tool.
Tools
Query tools
These read an IDatasetCatalog and never change it.
| Class | MCP name | What it does |
|---|---|---|
ListDatasetsTool |
list_datasets |
Lists the loaded datasets, with an optional product and bounding-box filter. |
ListSpecsTool |
list_specs |
Lists the product specifications and what each tool supports for them. |
ListTimeStepsTool |
list_time_steps |
Lists the time steps of a time-varying dataset. |
FindAtTool |
find_at |
Finds the datasets whose declared bounding box contains a point or intersects a GeoQuery. It doesn't check per-cell coverage or no-data masks. |
IdentifyFeaturesTool |
identify_features |
Picks the features at a point, ranked by drawing priority where the dataset was portrayed (S-98 15.1), then point before curve before area, with exact containment for areas and a radius in metres for points and curves. S-101 features include the text of the files their fileReference attributes name. |
NearestFeaturesTool |
nearest_features |
Ranks features by true distance to a point, including the nearest point on a segment, with the bearing. An area that contains the point has distance 0. |
QueryFeaturesTool |
query_features |
Finds the features that intersect a GeoQuery, with optional product, feature type, time window and attribute filters, and pages the results. Set Precise for full-geometry intersection instead of the bounding-box test. |
CountFeaturesTool |
count_features |
Counts features by type, for each dataset. |
SearchFeaturesTool |
search_features |
Finds features by name, in OBJNAM, NOBJNM, objectName and featureName. Substring and case-insensitive by default; set Exact or CaseSensitive to narrow it. FinestOnly keeps a chart-cell hit only where its cell is in the finest band at the feature (CellScaleRanking.FinestBand). |
DescribeFeatureTool |
describe_feature |
Describes one feature, by dataset and feature ID. |
DescribeFeatureTypeTool |
describe_feature_type |
Lists a product's feature types, or one type's attributes and allowed values, from the bundled feature catalogue. It needs no catalog or loaded dataset. |
SampleTool |
sample |
Samples a quantity at a point or along a polyline (vertices, or every SpacingMeters). Depth is charted depth by the route check's rule (S-102, else the finest S-101 cell), with the water mask and, at a time, the water level and available depth, from the host's RouteCheckSourceCache. WaterLevel, Current and Weather sample S-104, S-111 and GRIB2 or NetCDF at one time or over a time window, or any product whose catalog payload implements ICoverageSampler (its values come back as CoverageFieldsSample fields with quantity and unit). A point along a polyline with no value has an error instead of failing the whole call. |
CheckRouteTool |
check_route |
Checks a polyline or a host route (through IPassageRouteProvider) with RouteChecker: charts, areas, S-124 warnings and, with a draft, under-keel clearance. Returns the whole RouteCheckReport as a CheckRouteResult; CheckRouteResult.From projects a report you ran yourself. |
The vector tools (identify_features, nearest_features, query_features,
count_features and search_features) work on every vector product: S-101,
S-401, S-57 (through its S-101 translation) and the GML products. For S-101,
S-401 and S-57, the feature type is the acronym, such as LIGHTS, and the
feature ID is the record ID.
query_features attribute predicates are ANDed together and compare a
feature's simple attributes, with the attribute code matched without regard to
case. The operators are Exists, NotExists, Eq, Ne, Contains,
StartsWith, Gt, Ge, Lt and Le. The numeric operators compare both
sides as numbers. Over MCP, the attributes parameter takes either a map of
code to value, which tests equality, or an array of
{attribute, op, value} objects.
Session tools
These are in the Mutable/ folder. Each takes a capability that the host
supplies, such as IPresentationController, ITimeController,
IViewportController, IImageRenderer or IMutableDatasetCatalog:
OpenDatasetTool, CloseDatasetTool, CloseAllDatasetsTool,
SetPaletteTool, SetDisplayCategoryTool, SetDisplayModeTool,
SetTimeStepTool, SetViewportTool and RenderToImageTool.
SoundCharts and s100 mcp serve both run them. To build them as MCP tools, use
S100MutableTools in EncDotNet.S100.Mcp.
Library tools
These are in the Library/ folder and read or change a Library through
ILibraryReader and ILibraryEditor:
- Read:
ListLibrarySourcesTool,QueryLibraryItemsTool,DescribeLibraryItemTool,ListKnownSourcesTool,ListSecomServicesTool. - Change:
AddLibrarySourceTool,RefreshLibrarySourceTool,LibraryActionTool,RemoveLibrarySourceTool,SetLibrarySourceOptionsTool,AwaitLibraryIdleTool,SetSecomIdentityTool.
HeadlessLibrary implements both interfaces over the Library core, for a host
without view models.
Tide tools
These are in the Tides/ folder and read a tide station catalogue
(EncDotNet.S100.Tides.Stations)
through ITideCatalogueSource. TideCatalogueFileSource reads a catalogue
file and reloads it when the file changes.
| Type | MCP name | What it does |
|---|---|---|
ListTideStationsTool |
list_tide_stations |
Lists tide stations near a point or in a box, nearest first, with their kind, reference station, offsets and datums, and the catalogue's age. |
PredictTideTool |
predict_tide |
Predicts the astronomical tide at a station or the nearest station to a point, as a series or highs and lows. ResolveAsync finds the station and predictor without predicting. |
ListCurrentStationsTool |
list_current_stations |
Lists tidal current stations (one per depth bin) near a point or in a box, nearest first, with their kind, depth, flood and ebb directions and a subordinate station's offsets. |
PredictCurrentTool |
predict_current |
Predicts the astronomical tidal current at a station or the nearest station to a point, as a series of speeds and directions or the slacks and maxima. ResolveAsync finds the station and predictor without predicting. |
SoundCharts and s100 mcp serve both run them, and the s100 tides commands
call them directly. SampleCoverageTool and SampleCoverageAlongTool, given
a RouteCheckSourceCache with tide predictions, fill S-104 gaps with a
tide prediction and S-111 gaps with a tidal current prediction, and say so in
the result's Source. To build them as MCP tools, use TideMcpTools in
EncDotNet.S100.Mcp.
Viewer-only tools
Some tools need the live viewer UI, such as pick_features,
capture_app_screenshot and the panel, route and render-statistics tools. They
live in SoundCharts, not here. See
Tools only SoundCharts has.
Results and errors
ToolResult<T> holds either a value or a ToolError. Use TryGetValue and
TryGetError to read it. Tools don't throw to report a failure; every failure
is a typed ToolError with a stable Code and a Message.
Errors
| Code | When |
|---|---|
invalid_argument |
A request property failed validation, such as a latitude outside −90 to 90. |
geometry_invalid |
A GeoQuery shape is invalid, such as an unclosed polygon ring or a bounding box that crosses the antimeridian. |
dataset_not_found |
The dataset ID isn't in the catalog. |
dataset_closed_during_query |
The dataset was unloaded while the tool read it. You can retry once it's reopened. |
dataset_load_failed |
A recognized path produced no dataset, such as an empty or unsupported exchange set. |
feature_not_found |
The feature ID isn't in the dataset. |
feature_type_not_found |
The feature type isn't in the product's feature catalogue. |
feature_catalogue_not_available |
There's no bundled feature catalogue for the product. |
spec_not_supported_for_tool |
The tool doesn't support the dataset's product. |
not_supported_yet |
The tool supports the product, but not this dataset's shape, such as an S-104 data coding format other than 2. |
no_dataset_covers_point |
No loaded dataset's bounds contain the point. |
out_of_bounds |
The point is outside every loaded dataset of the requested product. |
no_data_at_point |
The grid cell at the point holds the product's no-data value. |
time_out_of_range |
The requested time is outside the time range of every dataset that covers the point. |
host_not_ready |
A session tool's capability isn't attached yet. You can retry once the host is ready. |
library_source_not_found |
No Library collection or source has the ID. |
library_item_not_found |
No Library item has the ID. |
library_change_rejected |
A Library change can't be done as asked; the message says why. |
tide_catalogue_not_available |
There's no tide station catalogue; hint says how to get one. |
tide_station_not_found |
No tide station has the id or name, or a name matches several (candidates). |
no_tide_station_near |
No tide station that can be predicted on the datum is within the radius. |
tide_datum_not_available |
The station can't be predicted on the datum; available lists the datums it can. |
current_station_not_found |
No current station has the id or name, or a name matches several stations (candidates). |
no_current_station_near |
No predictable current station is within the radius. |
current_station_not_predictable |
The current station's constituents, or its reference station, are missing. |
IDatasetCatalog
public interface IDatasetCatalog
{
IReadOnlyList<LoadedDataset> Datasets { get; }
event EventHandler<DatasetCatalogChangedEventArgs>? Changed;
}
A host implements IDatasetCatalog to expose its loaded datasets.
FileDatasetCatalog is a fixed catalog built from files, which s100 identify
uses; the viewer has its own live implementation.
Datasetsis a snapshot. The catalog publishes a new list on every change. A tool reads the property once and uses that list for the whole call, without locking.LoadedDatasetDatais a closed set of variants. Vector products carry their data model, such asS101DatasetDataorS124DatasetData. Coverage products carry a coverage source, such asS102CoverageData, or a station series, such asS104StationSeriesData. Tools pattern-match on the variant.- Coverage handles belong to the host. A dataset can be unloaded between
the snapshot and the read. Tools catch
ObjectDisposedExceptionand returndataset_closed_during_query. The host must publish the new snapshot before it disposes the handle.
Spatial queries
Tools that take an area take a GeoQuery, which has four variants:
| Variant | Holds | Use it for |
|---|---|---|
GeoQuery.Point |
GeoPoint(Latitude, Longitude) |
At a position. |
GeoQuery.Box |
GeoBoundingBox(SouthLatitude, WestLongitude, NorthLatitude, EastLongitude) |
Within a rectangle. |
GeoQuery.Polygon |
GeoPolygon(Ring), a closed ring of GeoPoint |
Inside an area. |
GeoQuery.Polyline |
GeoPolyline(Vertices, CorridorWidthMeters) |
Along a route or line. |
Over MCP, the query (or polyline) parameter takes the same shapes as a JSON
object. A JSON string that contains the object also works.
{"kind": "point", "latitude": 47.6, "longitude": -122.3}
{"kind": "box", "south": 47, "west": -123, "north": 48, "east": -122}
{"kind": "polygon", "ring": [[47, -123], [48, -123], [48, -122], [47, -123]]}
{"kind": "polyline", "vertices": [[47.6, -122.3], [47.7, -122.4]], "corridorWidthMeters": 1000}
- Coarse matching. Each variant has a bounding box, from
GetBoundingBox().SpatialPredicates.Intersectstests a polyline one segment at a time: a box matches when it touches a segment's box, widened byCorridorWidthMeterson each side with an equirectangular approximation. This matches the precision of the dataset bounding boxes.Preciseonquery_featuresadds the exact geometry test. - Validation.
GeoQueryValidator.Validatereturnsnullfor a valid query,invalid_argumentfor an out-of-range orNaNvalue or a negative corridor width, andgeometry_invalidfor a polygon ring that isn't closed or has fewer than 4 points, a polyline with fewer than 2 vertices, or an inverted or antimeridian-crossing bounding box. - Predicates.
SpatialPredicatesalso hasContains(box, point)andContainsPoint(ring, point), a ray-cast point-in-polygon test. - Point requests. Requests such as
FindAtRequesttakeLatitudeandLongitude, and an optionalQuerythat replaces them when you set it.
Feature describers
describe_feature describes a feature through a describer for its product,
registered in FeatureDescriberRegistry:
| Product | Describer | Feature ID |
|---|---|---|
| S-101, S-401, S-57 | S101FeatureDescriber |
The record ID (RCID), such as 42. The result includes the geometry: primitive, bounding box and coordinates. Information associations are followed, and the linked information type's attributes are included. |
| S-102 | S102FeatureDescriber |
The coverage path BathymetryCoverage.01. BathymetryCoverage also works. |
| S-104 | S104FeatureDescriber |
The coverage path WaterLevel[.NN][.Group_KKK], or a station identifier. |
| S-111 | S111FeatureDescriber |
The coverage path SurfaceCurrent[.NN][.Group_KKK], or a station identifier. |
| S-124 | S124FeatureDescriber |
The warning feature's gml:id. |
| S-129 | S129FeatureDescriber |
The gml:id of the plan metadata, plan area, non-navigable or almost non-navigable area, or control point feature. |
| S-122, S-125, S-127, S-128, S-131, S-201, S-411, S-421 | GmlFeatureDescriber |
The feature's gml:id. |
- For S-102, S-104 and S-111, the result describes the coverage instance:
origin, spacing, grid size, CRS, bounding box, no-data value, value ranges,
and the number of time steps and stations. Coverage instances don't reference
each other, so
Referencesis always empty. GmlFeatureDescriberreturns the feature's attributes, but its references are always an empty list. Each of those products models references with its own types, which aren't resolved yet.- A product without a describer returns
spec_not_supported_for_tool.
Field conventions
Every public property that crosses the MCP wire, on requests, results, payload
variants, ToolError types and the shared types such as BoundingBox,
SpecRef, TimeRange and DatasetId, has a
[System.ComponentModel.Description] attribute. Its one sentence states the
units, coordinate reference system and meaning. AnnotationContractTests in
tests/EncDotNet.S100.Mcp.Tools.Tests fails when a new property doesn't have
one. For the conventions themselves, such as WGS-84 decimal degrees, UTC
ISO-8601 times and depths positive down, see
Field conventions.
A DatasetId is a plain JSON string in both directions, through
DatasetIdJsonConverter, so an ID from one tool's result can go straight into
another tool's request. A wrapped {"value":"…"} ID is still accepted as
input.