Agent documentation

1. Start with explicit machine entrypoints

Base URL: https://map.blacksail.top. The homepage is HTML for discovery; machine interfaces retain JSON contracts. Public data and /agent/mcp are anonymous and read-only.

• AI map service manifest — Black Sail Map's own discovery format.
• OpenAPI 3.1 contract — REST routes and input schemas.
• Feature collections and static STAC 1.0 catalog — approved layer navigation.
• Plain-text integration notes — supplemental documentation, not an automatic discovery guarantee.

curl -H 'User-Agent: YourAgent/1.0' \
  https://map.blacksail.top/.well-known/ai-map.json

curl -H 'User-Agent: YourAgent/1.0' \
  'https://map.blacksail.top/v1/maps?downloadable=true&limit=7'

2. Run a real REST map workflow

Discover candidates with explicit constraints

curl https://map.blacksail.top/v1/match \
  -H 'User-Agent: YourAgent/1.0' \
  -H 'Content-Type: application/json' \
  -d '{"task":"Find a reference country polygon for Chengdu",
       "theme":"boundaries","requires_processing":true,
       "license":"public_domain","bbox":[103,30,105,32]}'

Read the returned candidate metadata and required checks. Matching is deterministic discovery; it does not certify unspecified accuracy, time, depth or task requirements. Prefer an explicit theme; unrecognized free-text tasks return no candidates and request constraints.

Process a reference point

curl https://map.blacksail.top/v1/process/point \
  -H 'User-Agent: YourAgent/1.0' \
  -H 'Content-Type: application/json' \
  -d '{"id":"ne-110m-countries",
       "longitude":104.0665,"latitude":30.5723}'

The Chengdu reference query returns China / CHN in the approved Natural Earth country layer. This is a coarse geographical classification, not a legal boundary judgment.

Read the schema, fetch actual geometry, verify the source

curl -H 'User-Agent: YourAgent/1.0' \
  https://map.blacksail.top/v1/maps/ne-110m-countries/schema

curl https://map.blacksail.top/v1/fetch \
  -H 'User-Agent: YourAgent/1.0' \
  -H 'Content-Type: application/json' \
  -d '{"id":"ne-110m-countries","where":{"ADM0_A3":"CHN"},
       "limit":1,"include_geometry":true}'

curl -H 'User-Agent: YourAgent/1.0' \
  https://map.blacksail.top/v1/maps/ne-110m-countries/verify

Use actual field names from map_schema before filtering. map_fetch returns a GeoJSON FeatureCollection with genuine geometry; source provenance appears at black_sail.provenance.

3. Connect through MCP

Use a compatible Streamable HTTP client. The server supports the 2026-07-28 and legacy 2025 protocol families. Send a truthful User-Agent and let the SDK negotiate the protocol and manage headers.

// Official @modelcontextprotocol/client 2.3.1
import { Client, StreamableHTTPClientTransport }
  from '@modelcontextprotocol/client';

const client = new Client(
  { name: 'your-agent', version: '1.0.0' },
  { versionNegotiation: { mode: 'auto' } }
);
await client.connect(new StreamableHTTPClientTransport(
  new URL('https://map.blacksail.top/agent/mcp'),
  { requestInit: { headers: { 'User-Agent': 'YourAgent/1.0' } } }
));
const { tools } = await client.listTools();
const result = await client.callTool({
  name: 'map_point_lookup',
  arguments: {
    id: 'ne-110m-countries', longitude: 104.0665, latitude: 30.5723
  }
});
console.log(result.structuredContent);
await client.close();

For direct protocol integration, use Content-Type: application/json and Accept: application/json, text/event-stream, perform initialize, and send the negotiated MCP-Protocol-Version afterward. A standalone browser GET returns HTTP 405 by design.

4. Public tool directory

Obtain authoritative input schemas through MCP tools/list or OpenAPI. The normal workflow is map_match → map_get → map_schema → map_point_lookup → map_fetch → map_verify.

5. Data and processing contract

Coordinates

OGC CRS84: longitude before latitude. Points use longitude, latitude; bbox is [west,south,east,north]. Split antimeridian-crossing boxes into two requests.

Filters and pagination

where is exact property-value equality; strings are case-insensitive. bbox uses actual geometry intersection and returns whole features, without clipping. offset and limit support pagination.

Provenance

Data results carry the publisher, source URL, release, SHA-256, license, acquisition time, CRS, scale and validation scope. Feature results use black_sail.provenance; schema, point and verification results use provenance.

Cache and freshness

Approved publisher snapshots are cached. Normal reads refresh after 24 hours. On upstream failure an already verified stale snapshot may be returned with cache: verified_stale_snapshot and failure details. A hash mismatch fails closed. Check acquisition time before claiming freshness.

Bounded requests

Request bodies: 32 KiB. Approved upstream acquisition: 4 MiB / 15 seconds. Data responses: at most 200 features / 3 MiB. Rate control is a per-IP, per-isolate weighted budget; it is not a global quota.

6. Errors and access control

REST errors use {"error":{"code":"…","message":"…"}}, with details where available. An MCP tool failure uses isError: true; an HTTP 200 transport response alone is not proof of tool success.

Maintenance writes require a protected bearer token. Upstream acquisition is restricted to approved fixed sources; caller-supplied URLs are rejected. Robots rules are crawler guidance and are not authorization.

7. Sources, license and appropriate use

Automatic processing currently covers seven Natural Earth v5.1.2 GeoJSON layers: country boundaries, land, coastline, ocean, lakes, rivers and populated places. Source bytes are pinned to known SHA-256 digests.

Natural Earth data are public domain under the publisher's terms. Additional provider records are discovery-only: their licenses and access instructions must be inspected separately.

• The 110m edition is 1:110,000,000 map scale, not 110-meter positional accuracy.
• Do not use this data for navigation, cadastral decisions, precision engineering or legal boundaries.
• Live weather, hour-specific ocean-current values, street-level routing and clipping are not implemented.
• Release dates are not uniform observation dates; SHA-256 checks integrity, not scientific accuracy.
• Collection routes are OGC-inspired and the catalog is static STAC; no formal OGC/STAC certification is claimed.

Always include source, license, scale, cache state and relevant limitations in an agent's derived result.