Tools

Seven tools. Five are always on and need no configuration — pure-compute utilities plus an SSRF-free IP lookup. Two probe the server host and stay absent from tools/list until you opt in, fail-closed.

toolkit_hash_value

Generate a digest, or constant-time-verify a value against an expected one.

• operation: generate (lowercase-hex digest) or compare (timing-safe check via timingSafeEqual)
• Algorithms: sha256 (default) and sha512 for security; sha1 and md5 are exposed for checksum and file-integrity compatibility only — never for passwords or signatures
• inputEncoding reads value as utf8 (default), hex, or base64, so binary blobs skip a decode round-trip
• Canonical use: match a download against a vendor-published checksum

toolkit_generate_id

Mint cryptographically-random identifiers from the platform CSPRNG — the correct source for IDs that must be unpredictable, unlike model-invented values.

• type: uuid_v4 (random, default), uuid_v7 (time-ordered, sortable by creation), or ulid (26-char Crockford base32, lexicographically sortable)
• count mints a batch up to 1000 in one call; the returned ids array always holds exactly count values
• uuid_v7 and ulid batches are monotonic — strictly increasing even within the same millisecond — so ids stays in sorted creation order
• Read-only — minting changes nothing — but never idempotent, so a client won't cache or deduplicate a batch

toolkit_generate_qr

Encode text or a URL into a QR code.

• format: svg (inline markup), png_base64 (raster bytes with mimeType and byteLength), or terminal (Unicode block string)
• errorCorrection (L/M/Q/H) trades data capacity for damage tolerance; margin sets the quiet-zone width; scale sets pixels per module for raster output
• The returned version (1–40) reflects how dense the encoded data is
• png_base64 also arrives as an MCP image content block, so a client reading content[] can render the code without decoding structuredContent
• A rendered PNG is bounded at 2048 px per side — (modules + 2 × margin) × scale — so a dense symbol at a high scale is rejected with a typed raster_too_large error naming a scale that fits; svg and terminal are unbounded
• data is capped at 2953 bytes — the absolute ceiling (version 40, level L, byte mode); usable capacity is lower at higher errorCorrection levels, so over-capacity input is rejected with a typed data_too_large error rather than a generic failure

toolkit_encode_value

Encode or decode a value, in either direction.

• encoding: base64, base64url (URL-safe alphabet), hex, or url (percent-encoding)
• operation: encode (raw UTF-8 → encoding) or decode (encoded value → text)
• Malformed decode input returns a typed decode_failed error with a recovery hint, not a silent best-effort

toolkit_geolocate_ip

Resolve a public IP or hostname to geographic and network metadata.

• Returns country, region, city, latitude/longitude, ASN, owning organization, and timezone
• proxy, hosting, and mobile flag when the address is a proxy/VPN/Tor exit, a datacenter network, or a mobile carrier — a true on any of them means the coordinates describe infrastructure, not a person. Absent when the provider doesn't report them
• A hostname is DNS-resolved first; resolvedIp echoes the IP actually located, and source names the answering provider
• SSRF-free — the server calls the provider, never the target; the resolved IP is re-checked against private ranges, and private/reserved addresses are rejected (they have no public geolocation)
• Best-effort and provider-bounded: VPNs, proxies, mobile NAT, and anycast all defeat IP-to-location, accuracy is city-level at best, and absent fields are reported as unknown rather than invented
• Provider-supplied strings are truncated and stripped of control characters before they reach the response, so registry-controlled text (org, isp, as) cannot flood or format a model's context
• Keyless by default (ip-api free tier, which is plaintext HTTP — see TOOLKIT_GEO_BASE_URL); results are cached in memory by resolved IP under a fixed entry cap

toolkit_check_network

Gated — registered only when TOOLKIT_ENABLE_NET_DIAGNOSTICS=true. Read-only network diagnostics from the server host.

• mode: ping (ICMP round-trip), traceroute (hop path to the target), connectivity (raw TCP connect to target on port), or public_ip (the host's own egress IP)
• A host that does not respond is reported as reachable: false — a valid result, not an error
• Diagnoses the server's own network, so it is useful on a local or self-hosted deployment; reaching a private/reserved/internal target additionally requires TOOLKIT_ALLOW_PRIVATE_NETWORK=true, which keeps the cloud-metadata endpoint blocked by default

toolkit_check_system

Gated — registered only when TOOLKIT_ENABLE_SYSTEM_INFO=true. Report a facet of the server host's system state, read-only.

• what: os, cpu, memory, load, or interfaces
• Exactly one facet object is populated per call, matching what
• Describes the host this server runs on, not the calling client — meaningful on a local or self-hosted deployment; gated off by default because os and interfaces disclose host topology and version details

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Typed error contracts — each fallible tool declares its failure reasons with recovery hints the agent can act on
• Pluggable auth: none, jwt, oauth
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Toolkit-specific: