Hermes.MCP.ID (hermes_mcp v0.9.1)

Utilities for working with MCP message identifiers.

This module provides functions for generating request IDs and progress tokens used in the MCP protocol.

ID Format

Generated IDs are Base64-encoded strings containing:

Timestamp component (to ensure temporal uniqueness)
Process identifier hash (to ensure process-level uniqueness)
Random component (to ensure collision resistance)

This format ensures uniqueness across nodes, processes, and repeated calls.

Examples

# Generate a standard request ID
request_id = Hermes.MCP.ID.generate()

# Generate a progress token
progress_token = Hermes.MCP.ID.generate_progress_token()

Summary

Functions

generate()

Generates a unique request ID.

generate_error_id()

Generates a unique error ID.

generate_progress_token()

Generates a unique progress token.

generate_request_id()

Generates a unique request ID.

generate_session_id()

Generates a unique session ID.

timestamp_from_id(id)

Extracts timestamp from an ID for debugging purposes.

valid?(id)

Checks if a string appears to be a valid MCP ID.

valid_progress_token?(token)

Checks if a string appears to be a valid progress token.

valid_request_id?(id)

Checks if a string appears to be a valid request ID.

Functions

generate()

@spec generate() :: String.t()

Generates a unique request ID.

Creates a Base64 encoded string containing:

Timestamp component (nanoseconds)
Process identifier hash
Random component

Examples

iex> id = Hermes.MCP.ID.generate()
iex> is_binary(id)
true

generate_error_id()

@spec generate_error_id() :: String.t()

Generates a unique error ID.

Creates a standard ID with a "err_" prefix for clarity. error IDs are used to correlate errors with their responses.

Examples

iex> id = Hermes.MCP.ID.generate_error_id()
iex> String.starts_with?(id, "err_")
true

generate_progress_token()

@spec generate_progress_token() :: String.t()

Generates a unique progress token.

Creates a standard request ID with a "progress_" prefix for clarity. Progress tokens are used in the MCP protocol to track long-running operations.

Examples

iex> token = Hermes.MCP.ID.generate_progress_token()
iex> String.starts_with?(token, "progress_")
true

generate_request_id()

@spec generate_request_id() :: String.t()

Generates a unique request ID.

Creates a standard ID with a "req_" prefix for clarity. Request IDs are used to correlate requests with their responses.

Examples

iex> id = Hermes.MCP.ID.generate_request_id()
iex> String.starts_with?(id, "req_")
true

generate_session_id()

@spec generate_session_id() :: String.t()

Generates a unique session ID.

Creates a standard ID with a "session_" prefix for clarity. Session IDs are used to track HTTP sessions in transports.

Examples

iex> id = Hermes.MCP.ID.generate_session_id()
iex> String.starts_with?(id, "session_")
true

timestamp_from_id(id)

@spec timestamp_from_id(String.t()) :: integer() | nil

Extracts timestamp from an ID for debugging purposes.

This is primarily useful for troubleshooting timing issues or analyzing the sequence of requests.

Parameters

id - An ID generated by this module

Returns

The timestamp (in nanoseconds) or nil if the ID cannot be parsed

Examples

iex> id = Hermes.MCP.ID.generate()
iex> timestamp = Hermes.MCP.ID.timestamp_from_id(id)
iex> is_integer(timestamp)
true

iex> Hermes.MCP.ID.timestamp_from_id("invalid-id")
nil

valid?(id)

@spec valid?(term()) :: boolean()

Checks if a string appears to be a valid MCP ID.

This performs a basic validation to check if the string conforms to the expected ID format.

Examples

iex> id = Hermes.MCP.ID.generate()
iex> Hermes.MCP.ID.valid?(id)
true

iex> Hermes.MCP.ID.valid?("invalid-id")
false

valid_progress_token?(token)

@spec valid_progress_token?(term()) :: boolean()

Checks if a string appears to be a valid progress token.

Validates that the string starts with "progress_" and the remainder is a valid MCP ID.

Examples

iex> token = Hermes.MCP.ID.generate_progress_token()
iex> Hermes.MCP.ID.valid_progress_token?(token)
true

iex> Hermes.MCP.ID.valid_progress_token?("not-a-token")
false

valid_request_id?(id)

@spec valid_request_id?(term()) :: boolean()

Checks if a string appears to be a valid request ID.

Validates that the string starts with "req_" and the remainder is a valid MCP ID.

Examples

iex> id = Hermes.MCP.ID.generate_request_id()
iex> Hermes.MCP.ID.valid_request_id?(id)
true

iex> Hermes.MCP.ID.valid_request_id?("not-an-id")
false