API Reference

mcp_server(; name::String, version::String="1.0.0", 
         tools::Union{Vector{MCPTool},MCPTool,Nothing}=nothing,
         resources::Union{Vector{MCPResource},MCPResource,Nothing}=nothing, 
         prompts::Union{Vector{MCPPrompt},MCPPrompt,Nothing}=nothing,
         description::String="", 
         capabilities::Vector{Capability}=default_capabilities(),
         auto_register_dir::Union{String,Nothing}=nothing) -> Server

Primary entry point for creating and configuring a Model Context Protocol (MCP) server.

Arguments

• name::String: Unique identifier for the server instance
• version::String: Your server implementation version (defaults to "1.0.0") - YOUR server's version, not the MCP protocol version
• tools: Tools to expose to the model
• resources: Resources available to the model
• prompts: Predefined prompts for the model
• description::String: Optional server description
• capabilities::Vector{Capability}: Server capability configuration
• auto_register_dir: Directory to auto-register components from

Returns

• Server: A configured server instance ready to handle MCP client connections

Example

server = mcp_server(
    name = "my-server",
    version = "1.0.0",  # Your server version
    description = "Demo server with time tool",
    tools = MCPTool(
        name = "get_time",
        description = "Get current time",
        parameters = [],
        handler = args -> Dates.format(now(), "HH:MM:SS")
    )
)
start!(server)

start!(server::Server; transport::Union{Transport,Nothing}=nothing) -> Nothing

Start the MCP server, setting up logging and entering the main server loop.

Arguments

• server::Server: The server instance to start
• transport::Union{Transport,Nothing}: Optional transport to use. If not provided, uses StdioTransport

Returns

• Nothing: The function returns after the server stops

Throws

• ServerError: If the server is already running

stop!(server::Server) -> Nothing

Stop a running MCP server.

Arguments

• server::Server: The server instance to stop

Returns

• Nothing: The function returns after setting the server to inactive

Throws

• ServerError: If the server is not currently running

register!(server::Server, component::Union{Tool,Resource,MCPPrompt}) -> Server

Register a tool, resource, or prompt with the MCP server.

Arguments

• server::Server: The server to register the component with
• component: The component to register (can be a tool, resource, or prompt)

Returns

• Server: The server instance for method chaining

MCPTool(; name::String, description::String, parameters::Vector{ToolParameter}=ToolParameter[],
      input_schema::Union{Nothing,AbstractDict}=nothing, handler::Function,
      return_type::Type=Vector{Content}) <: Tool

Implement a tool that can be invoked by clients in the MCP protocol.

Fields

• name::String: Unique identifier for the tool
• description::String: Human-readable description of the tool's purpose
• parameters::Vector{ToolParameter}: Simple parameters (ignored if input_schema is provided)
• input_schema::Union{Nothing,AbstractDict}: Raw JSON Schema for complex parameter types
• handler::Function: Function that implements the tool's functionality
• return_type::Type: Expected return type of the handler (defaults to Vector{Content})

Parameter Definition

Tools can define parameters in two ways:

1. Simple parameters using parameters::Vector{ToolParameter}: Good for flat schemas with basic types (string, number, boolean).

2. Complex schemas using input_schema::AbstractDict: Supports arrays, enums, nested objects, and any valid JSON Schema. When provided, input_schema takes precedence over parameters.

Handler Return Types

The tool handler can return various types which are automatically converted:

• An instance of the specified Content type (TextContent, ImageContent, etc.)
• A Vector{<:Content} for multiple content items (can mix TextContent, ImageContent, etc.)
• A Dict (automatically converted to JSON and wrapped in TextContent)
• A String (automatically wrapped in TextContent)
• A Tuple{Vector{UInt8}, String} (automatically wrapped in ImageContent)
• A CallToolResult object for full control over the response (including error handling)

When returntype is Vector{Content} (default), single Content items are automatically wrapped in a vector. Note: When returning CallToolResult directly, the returntype field is ignored.

ToolParameter(; name::String, description::String, type::String, required::Bool=false, default::Any=nothing)

Define a parameter for an MCP tool.

Fields

• name::String: The parameter name (used as the key in the params dictionary)
• description::String: Human-readable description of the parameter
• type::String: Type of the parameter as specified in the MCP schema (e.g., "string", "number", "boolean")
• required::Bool: Whether the parameter is required for tool invocation
• default::Any: Default value for the parameter if not provided (nothing means no default)

MCPResource <: Resource

Implement a resource that clients can access in the MCP protocol. Resources represent data that can be read by models and tools.

Fields

• uri::URI: Unique identifier for the resource
• name::String: Human-readable name for the resource
• description::String: Detailed description of the resource
• mime_type::String: MIME type of the resource data
• data_provider::Function: Function that provides the resource data when called
• annotations::AbstractDict{String,Any}: Additional metadata for the resource

ResourceTemplate(; name::String, uri_template::String,
               mime_type::Union{String,Nothing}=nothing, description::String="")

Define a template for dynamically generating resources with parameterized URIs.

Fields

• name::String: Name of the resource template
• uri_template::String: Template string with placeholders for parameters
• mime_type::Union{String,Nothing}: MIME type of the generated resources
• description::String: Human-readable description of the template

MCPPrompt(; name::String, description::String="", 
        arguments::Vector{PromptArgument}=PromptArgument[], 
        messages::Vector{PromptMessage}=PromptMessage[])

Implement a prompt or prompt template as defined in the MCP schema. Prompts can include variables that are replaced with arguments when retrieved.

Fields

• name::String: Unique identifier for the prompt
• description::String: Human-readable description of the prompt's purpose
• arguments::Vector{PromptArgument}: Arguments that this prompt accepts
• messages::Vector{PromptMessage}: The sequence of messages in the prompt

PromptArgument(; name::String, description::String="", required::Bool=false)

Define an argument that a prompt template can accept.

Fields

• name::String: The argument name (used in template placeholders)
• description::String: Human-readable description of the argument
• required::Bool: Whether the argument is required when using the prompt

PromptMessage(; content::Union{TextContent, ImageContent, EmbeddedResource}, role::Role=user)

Represent a single message in a prompt template.

Fields

• content::Union{TextContent, ImageContent, EmbeddedResource}: The content of the message
• role::Role: Whether this message is from the user or assistant (defaults to user)

Content

Abstract base type for all content formats in the MCP protocol. Content can be exchanged between clients and servers in various formats.

ResourceContents

Abstract base type for resource content formats in the MCP protocol. Resources can contain different types of content based on their MIME type.

TextContent(; type::String="text", text::String, 
            annotations::Union{Nothing,Dict{String,Any}}=nothing,
            _meta::Union{Nothing,Dict{String,Any}}=nothing) <: Content

Text-based content for messages and tool responses.

Fields

• type::String: Content type identifier (always "text")
• text::String: The actual text content
• annotations::Union{Nothing,Dict{String,Any}}: Optional annotations for the client
• _meta::Union{Nothing,Dict{String,Any}}: Optional metadata for protocol extensions

ImageContent(; type::String="image", data::Vector{UInt8}, mime_type::String,
             annotations::Union{Nothing,Dict{String,Any}}=nothing,
             _meta::Union{Nothing,Dict{String,Any}}=nothing) <: Content

Image content for messages and tool responses.

Fields

• type::String: Content type identifier (always "image")
• data::Vector{UInt8}: Raw image data (automatically base64-encoded when serialized)
• mime_type::String: MIME type of the image (e.g., "image/png")
• annotations::Union{Nothing,Dict{String,Any}}: Optional annotations for the client
• _meta::Union{Nothing,Dict{String,Any}}: Optional metadata for protocol extensions

EmbeddedResource(; type::String="resource", resource::Dict{String,Any},
                 annotations::Union{Nothing,Dict{String,Any}}=nothing,
                 _meta::Union{Nothing,Dict{String,Any}}=nothing) <: Content

Embedded resource content for inline resource data.

Fields

• type::String: Content type identifier (always "resource")
• resource::Dict{String,Any}: The embedded resource data
• annotations::Union{Nothing,Dict{String,Any}}: Optional annotations for the client
• _meta::Union{Nothing,Dict{String,Any}}: Optional metadata for protocol extensions

TextResourceContents(; uri::URI, mime_type::String="text/plain", text::String) <: ResourceContents

Text content for resources in the MCP protocol.

Fields

• uri::URI: Resource identifier
• mime_type::String: MIME type of the text content
• text::String: The actual text content

BlobResourceContents(; uri::URI, mime_type::String="application/octet-stream", 
                    blob::Vector{UInt8}) <: ResourceContents

Binary content for resources.

Fields

• uri::URI: Resource identifier
• mime_type::String: MIME type of the binary content
• blob::Vector{UInt8}: Raw binary data (automatically base64-encoded when serialized)

CallToolResult(; content::Vector{Dict{String,Any}}, is_error::Bool=false) <: ResponseResult

Result returned from a tool invocation.

Fields

• content::Vector{Dict{String,Any}}: Content produced by the tool
• is_error::Bool: Whether the tool execution resulted in an error

Server(config::ServerConfig; transport::Union{Transport,Nothing}=nothing)

Represent a running MCP server instance that manages resources, tools, and prompts.

Fields

• config::ServerConfig: Server configuration settings
• transport::Union{Transport,Nothing}: Transport implementation for client-server communication
• resources::Vector{Resource}: Available resources
• tools::Vector{Tool}: Available tools
• prompts::Vector{MCPPrompt}: Available prompts
• resource_templates::Vector{ResourceTemplate}: Available resource templates
• subscriptions::DefaultDict{String,Vector{Subscription}}: Resource subscription registry
• progress_trackers::Dict{Union{String,Int},Progress}: Progress tracking for operations
• active::Bool: Whether the server is currently active

Constructor

• Server(config::ServerConfig; transport=nothing): Creates a new server with the specified configuration

subscribe!(server::Server, uri::String, callback::Function) -> Server

Subscribe to updates for a specific resource identified by URI.

Arguments

• server::Server: The server instance
• uri::String: The resource URI to subscribe to
• callback::Function: The function to call when the resource is updated

Returns

• Server: The server instance for method chaining

unsubscribe!(server::Server, uri::String, callback::Function) -> Server

Remove a subscription for a specific resource URI and callback function.

Arguments

• server::Server: The server instance
• uri::String: The resource URI to unsubscribe from
• callback::Function: The callback function to remove

Returns

• Server: The server instance for method chaining

content2dict(content::Content) -> Dict{String,Any}

Convert a Content object to its dictionary representation for JSON serialization.

Arguments

• content::Content: The content object to convert

Returns

• Dict{String,Any}: Dictionary representation of the content

Examples

text_content = TextContent(text="Hello", type="text")
dict = content2dict(text_content)
# Returns: Dict("type" => "text", "text" => "Hello", "annotations" => Dict())

HttpTransport(; host::String="127.0.0.1", port::Int=8080, endpoint::String="/")

Transport implementation following the MCP Streamable HTTP specification (2025-06-18). Supports Server-Sent Events (SSE) for streaming and session management.

Fields

• host::String: Host address to bind to (default: "127.0.0.1")
• port::Int: Port number to listen on (default: 8080)
• endpoint::String: HTTP endpoint path (default: "/")
• server::Union{HTTP.Server,Nothing}: HTTP server instance
• connected::Bool: Connection status
• server_task::Union{Task,Nothing}: Server task handle
• active_streams::Dict{String,HTTP.Stream}: Active streaming connections
• request_queue::Channel{Tuple{String,String}}: Queue for incoming requests (id, message)
• response_channels::Dict{String,Channel{String}}: Response channels per request

MCPPrompt(name::String, description::String, arguments::Vector{PromptArgument}, text::String) -> MCPPrompt

Create a prompt with a single text message.

Arguments

• name::String: Unique identifier for the prompt
• description::String: Human-readable description
• arguments::Vector{PromptArgument}: Arguments the prompt accepts
• text::String: Text content for the prompt message

Returns

• MCPPrompt: A new prompt with a single user message containing the text

MCPResource(; uri, name::String="", description::String="",
          mime_type::String="application/json", data_provider::Function,
          annotations::AbstractDict{String,Any}=LittleDict{String,Any}()) -> MCPResource

Create a resource with automatic URI conversion from strings or URIs.

Arguments

• uri: String or URI identifier for the resource
• name::String: Human-readable name for the resource
• description::String: Detailed description
• mime_type::String: MIME type of the resource
• data_provider::Function: Function that returns the resource data when called
• annotations::AbstractDict{String,Any}: Additional metadata for the resource

Returns

• MCPResource: A new resource with the provided configuration

PromptMessage(content::Union{TextContent, ImageContent, EmbeddedResource}) -> PromptMessage

Create a prompt message with only content (role defaults to user).

Arguments

• content::Union{TextContent, ImageContent, EmbeddedResource}: The message content

Returns

• PromptMessage: A new prompt message with the default user role

ResourceLink(; type::String="link", href::String, 
             title::Union{String,Nothing}=nothing,
             annotations::Union{Nothing,Dict{String,Any}}=nothing,
             _meta::Union{Nothing,Dict{String,Any}}=nothing) <: Content

Link to an external resource (NEW in protocol 2025-06-18).

Fields

• type::String: Content type identifier (always "link")
• href::String: URL or URI of the linked resource
• title::Union{String,Nothing}: Optional human-readable title for the link
• annotations::Union{Nothing,Dict{String,Any}}: Optional annotations for the client
• _meta::Union{Nothing,Dict{String,Any}}: Optional metadata for protocol extensions

StdioTransport(; input::IO=stdin, output::IO=stdout)

Transport implementation using standard input/output streams. This is the default transport for local MCP server processes.

Fields

• input::IO: Input stream for reading messages (default: stdin)
• output::IO: Output stream for writing messages (default: stdout)
• connected::Bool: Connection status (always true for stdio)

Transport

Abstract base type for all MCP transport implementations. Defines the interface for reading and writing messages between client and server.

connect(transport::HttpTransport) -> Nothing

Start the HTTP server and begin listening for connections.

Arguments

• transport::HttpTransport: The transport instance

Returns

• Nothing

Throws

• TransportError: If the server cannot be started

connect(transport::Transport) -> Nothing

Establish the transport connection. Default implementation does nothing (for transports that are always connected).

Arguments

• transport::Transport: The transport instance to connect

Returns

• Nothing

Throws

• TransportError: If connection cannot be established

mcp_server(; name::String, version::String="1.0.0", 
         tools::Union{Vector{MCPTool},MCPTool,Nothing}=nothing,
         resources::Union{Vector{MCPResource},MCPResource,Nothing}=nothing, 
         prompts::Union{Vector{MCPPrompt},MCPPrompt,Nothing}=nothing,
         description::String="", 
         capabilities::Vector{Capability}=default_capabilities(),
         auto_register_dir::Union{String,Nothing}=nothing) -> Server

Primary entry point for creating and configuring a Model Context Protocol (MCP) server.

Arguments

• name::String: Unique identifier for the server instance
• version::String: Your server implementation version (defaults to "1.0.0") - YOUR server's version, not the MCP protocol version
• tools: Tools to expose to the model
• resources: Resources available to the model
• prompts: Predefined prompts for the model
• description::String: Optional server description
• capabilities::Vector{Capability}: Server capability configuration
• auto_register_dir: Directory to auto-register components from

Returns

• Server: A configured server instance ready to handle MCP client connections

Example

server = mcp_server(
    name = "my-server",
    version = "1.0.0",  # Your server version
    description = "Demo server with time tool",
    tools = MCPTool(
        name = "get_time",
        description = "Get current time",
        parameters = [],
        handler = args -> Dates.format(now(), "HH:MM:SS")
    )
)
start!(server)

start!(server::Server; transport::Union{Transport,Nothing}=nothing) -> Nothing

Start the MCP server, setting up logging and entering the main server loop.

Arguments

• server::Server: The server instance to start
• transport::Union{Transport,Nothing}: Optional transport to use. If not provided, uses StdioTransport

Returns

• Nothing: The function returns after the server stops

Throws

• ServerError: If the server is already running

stop!(server::Server) -> Nothing

Stop a running MCP server.

Arguments

• server::Server: The server instance to stop

Returns

• Nothing: The function returns after setting the server to inactive

Throws

• ServerError: If the server is not currently running

subscribe!(server::Server, uri::String, callback::Function) -> Server

Subscribe to updates for a specific resource identified by URI.

Arguments

• server::Server: The server instance
• uri::String: The resource URI to subscribe to
• callback::Function: The function to call when the resource is updated

Returns

• Server: The server instance for method chaining

unsubscribe!(server::Server, uri::String, callback::Function) -> Server

Remove a subscription for a specific resource URI and callback function.

Arguments

• server::Server: The server instance
• uri::String: The resource URI to unsubscribe from
• callback::Function: The callback function to remove

Returns

• Server: The server instance for method chaining

CallToolParams(; name::String, arguments::Union{Dict{String,Any},Nothing}=nothing) <: RequestParams

Parameters for invoking a specific tool on an MCP server.

Fields

• name::String: Name of the tool to call
• arguments::Union{Dict{String,Any},Nothing}: Optional arguments to pass to the tool

ClientCapabilities(; experimental::Union{Dict{String,Dict{String,Any}},Nothing}=nothing,
                roots::Union{Dict{String,Bool},Nothing}=nothing,
                sampling::Union{Dict{String,Any},Nothing}=nothing)

Capabilities reported by an MCP client during initialization.

Fields

• experimental::Union{Dict{String,Dict{String,Any}},Nothing}: Experimental features supported
• roots::Union{Dict{String,Bool},Nothing}: Root directories client has access to
• sampling::Union{Dict{String,Any},Nothing}: Sampling capabilities for model generation

ErrorInfo(; code::Int, message::String, data::Union{Dict{String,Any},Nothing}=nothing)

Error information structure for JSON-RPC error responses.

Fields

• code::Int: Numeric error code (predefined in ErrorCodes module)
• message::String: Human-readable error description
• data::Union{Dict{String,Any},Nothing}: Optional additional error details

GetPromptParams(; name::String, arguments::Union{Dict{String,String},Nothing}=nothing) <: RequestParams

Parameters for requesting a specific prompt from an MCP server.

Fields

• name::String: Name of the prompt to retrieve
• arguments::Union{Dict{String,String},Nothing}: Optional arguments to apply to the prompt template

GetPromptResult(; description::String, messages::Vector{PromptMessage}) <: ResponseResult

Result returned from a get prompt request.

Fields

• description::String: Description of the prompt
• messages::Vector{PromptMessage}: The prompt messages with template variables replaced

Implementation(; name::String="default-client", version::String="1.0.0")

Information about a client or server implementation of the MCP protocol.

Fields

• name::String: Name of the implementation
• version::String: Version string of the implementation

InitializeParams(; capabilities::ClientCapabilities=ClientCapabilities(),
               clientInfo::Implementation=Implementation(),
               protocolVersion::Union{String,Nothing}=nothing) <: RequestParams

Parameters for MCP protocol initialization requests.

Fields

• capabilities::ClientCapabilities: Client capabilities being reported
• clientInfo::Implementation: Information about the client implementation
• protocolVersion::Union{String,Nothing}: Version of the MCP protocol being used (must be "2025-06-18" - only supported version)

InitializeResult(; serverInfo::Dict{String,Any}, capabilities::Dict{String,Any},
               protocolVersion::String, instructions::String="") <: ResponseResult

Result returned in response to MCP protocol initialization.

Fields

• serverInfo::Dict{String,Any}: Information about the server implementation
• capabilities::Dict{String,Any}: Server capabilities being reported
• protocolVersion::String: Version of the MCP protocol being used
• instructions::String: Optional usage instructions for clients

JSONRPCError(; id::Union{RequestId,Nothing}, error::ErrorInfo) <: Response

JSON-RPC error response message returned when requests fail.

Fields

• id::Union{RequestId,Nothing}: Identifier matching the request this is responding to, or null
• error::ErrorInfo: Information about the error that occurred

JSONRPCNotification(; method::String, 
                   params::Union{RequestParams,Dict{String,Any}}) <: Notification

JSON-RPC notification message that does not expect a response.

Fields

• method::String: Name of the notification method
• params::Union{RequestParams,Dict{String,Any}}: Parameters for the notification

JSONRPCRequest(; id::RequestId, method::String, 
             params::Union{RequestParams, Nothing}, 
             meta::RequestMeta=RequestMeta()) <: Request

JSON-RPC request message used to invoke methods on the server.

Fields

• id::RequestId: Unique identifier for the request
• method::String: Name of the method to invoke
• params::Union{RequestParams, Nothing}: Parameters for the method
• meta::RequestMeta: Additional metadata for the request

JSONRPCResponse(; id::RequestId, result::Union{ResponseResult,AbstractDict{String,Any}}) <: Response

JSON-RPC response message returned for successful requests.

Fields

• id::RequestId: Identifier matching the request this is responding to
• result::Union{ResponseResult,AbstractDict{String,Any}}: Results of the method execution

ListPromptsParams(; cursor::Union{String,Nothing}=nothing) <: RequestParams

Parameters for requesting a list of available prompts from an MCP server.

Fields

• cursor::Union{String,Nothing}: Optional pagination cursor for long prompt lists

ListPromptsResult(; prompts::Vector{Dict{String,Any}}, 
                nextCursor::Union{String,Nothing}=nothing) <: ResponseResult

Result returned from a list prompts request.

Fields

• prompts::Vector{Dict{String,Any}}: List of available prompts with their metadata
• nextCursor::Union{String,Nothing}: Optional pagination cursor for fetching more prompts

ListResourcesParams(; cursor::Union{String,Nothing}=nothing) <: RequestParams

Parameters for requesting a list of available resources from an MCP server.

Fields

• cursor::Union{String,Nothing}: Optional pagination cursor for long resource lists

ListResourcesResult(; resources::Vector{Dict{String,Any}}, 
                  nextCursor::Union{String,Nothing}=nothing) <: ResponseResult

Result returned from a list resources request.

Fields

• resources::Vector{Dict{String,Any}}: List of available resources with their metadata
• nextCursor::Union{String,Nothing}: Optional pagination cursor for fetching more resources

ListToolsParams(; cursor::Union{String,Nothing}=nothing) <: RequestParams

Parameters for requesting a list of available tools from an MCP server.

Fields

• cursor::Union{String,Nothing}: Optional pagination cursor for long tool lists

ListToolsResult(; tools::Vector{Dict{String,Any}}, 
              nextCursor::Union{String,Nothing}=nothing) <: ResponseResult

Result returned from a list tools request.

Fields

• tools::Vector{Dict{String,Any}}: List of available tools with their metadata
• nextCursor::Union{String,Nothing}: Optional pagination cursor for fetching more tools

ProgressParams(; progress_token::ProgressToken, progress::Float64,
             total::Union{Float64,Nothing}=nothing) <: RequestParams

Parameters for progress notifications during long-running operations.

Fields

• progress_token::ProgressToken: Token identifying the operation being reported on
• progress::Float64: Current progress value
• total::Union{Float64,Nothing}: Optional total expected value

ReadResourceParams(; uri::String) <: RequestParams

Parameters for requesting the contents of a specific resource.

Fields

• uri::String: URI identifier of the resource to read

ReadResourceResult(; contents::Vector{Dict{String,Any}}) <: ResponseResult

Result returned from a read resource request.

Fields

• contents::Vector{Dict{String,Any}}: The contents of the requested resource

RequestMeta(; progress_token::Union{ProgressToken,Nothing}=nothing)

Metadata for MCP protocol requests, including progress tracking information.

Fields

• progress_token::Union{ProgressToken,Nothing}: Optional token for tracking request progress

get_params_type(method::String) -> Union{Type,Nothing}

Get the appropriate parameter type for a given JSON-RPC method name.

Arguments

• method::String: The JSON-RPC method name

Returns

• Union{Type,Nothing}: The Julia type to use for parsing parameters, or nothing if no specific type is defined

get_result_type(id::RequestId) -> Union{Type{<:ResponseResult},Nothing}

Get the expected result type for a response based on the request ID.

Arguments

• id::RequestId: The request ID to look up

Returns

• Union{Type{<:ResponseResult},Nothing}: The expected response result type, or nothing if not known

Note: This is a placeholder that needs to be implemented with request tracking.

parse_error_response(raw::JSON3.Object) -> Response

Parse a JSON-RPC error response object into a typed Response struct.

Arguments

• raw::JSON3.Object: The parsed JSON object representing an error response

Returns

• Response: A JSONRPCError with properly typed error information

parse_message(json::String) -> MCPMessage

Parse a JSON-RPC message string into the appropriate typed message object.

Arguments

• json::String: The raw JSON-RPC message string

Returns

• MCPMessage: A typed MCPMessage subtype (JSONRPCRequest, JSONRPCResponse, JSONRPCNotification, or JSONRPCError)

parse_notification(raw::JSON3.Object) -> Notification

Parse a JSON-RPC notification object into a typed Notification struct.

Arguments

• raw::JSON3.Object: The parsed JSON object representing a notification

Returns

• Notification: A JSONRPCNotification with properly typed parameters if possible

parse_request(raw::JSON3.Object) -> Request

Parse a JSON-RPC request object into a typed Request struct.

Arguments

• raw::JSON3.Object: The parsed JSON object representing a request

Returns

• Request: A JSONRPCRequest with properly typed parameters based on the method

parse_success_response(raw::JSON3.Object) -> Response

Parse a successful JSON-RPC response object into a typed Response struct.

Arguments

• raw::JSON3.Object: The parsed JSON object representing a successful response

Returns

• Response: A JSONRPCResponse with properly typed result if possible, or JSONRPCError if parsing fails

serialize_message(msg::MCPMessage) -> String

Serialize an MCP message object into a JSON-RPC compliant string.

Arguments

• msg::MCPMessage: The message object to serialize (Request, Response, Notification, or Error)

Returns

• String: A JSON string representation of the message following the JSON-RPC 2.0 specification

process_message(server::Server, state::ServerState, message::String) -> Union{String,Nothing}

Process an incoming JSON-RPC message and generate an appropriate response.

Arguments

• server::Server: The MCP server instance
• state::ServerState: Current server state
• message::String: Raw JSON-RPC message to process

Returns

• Union{String,Nothing}: A serialized response string or nothing for notifications

run_server_loop(server::Server, state::ServerState) -> Nothing

Execute the main server loop that reads JSON-RPC messages from the transport and writes responses back. Implements optimized CPU usage by blocking on input rather than active polling.

Arguments

• server::Server: The MCP server instance with configured transport
• state::ServerState: The server state object to track running status

Returns

• Nothing: The function runs until interrupted or state.running becomes false

CapabilityResponse(; 
    listChanged::Bool=false, 
    subscribe::Union{Bool,Nothing}=nothing, 
    tools::Union{Dict{String,Any},Nothing}=nothing, 
    resources::Union{Vector{Dict{String,Any}},Nothing}=nothing)

Define response structure for capabilities including tool and resource listings.

Fields

• listChanged::Bool: Whether listings can change during server lifetime.
• subscribe::Union{Bool,Nothing}: Whether subscriptions are supported.
• tools::Union{Dict{String,Any},Nothing}: Tool definitions by name.
• resources::Union{Vector{Dict{String,Any}},Nothing}: Available resource listings.

LoggingCapability(; levels::Vector{String}=["info", "warn", "error"])

Configure logging-related capabilities for an MCP server.

Fields

• levels::Vector{String}: Supported logging levels.

PromptCapability(; list_changed::Bool=false)

Configure prompt-related capabilities for an MCP server.

Fields

• list_changed::Bool: Whether server supports notifications when prompt listings change.

ResourceCapability(; list_changed::Bool=false, subscribe::Bool=false)

Configure resource-related capabilities for an MCP server.

Fields

• list_changed::Bool: Whether server supports notifications when resource listings change.
• subscribe::Bool: Whether server supports subscriptions to resource updates.

ToolCapability(; list_changed::Bool=false)

Configure tool-related capabilities for an MCP server.

Fields

• list_changed::Bool: Whether server supports notifications when tool listings change.

capabilities_to_protocol(capabilities::Vector{Capability}, server::Server) -> Dict{String,Any}

Convert server capabilities to the initialization response format required by the MCP protocol.

Arguments

• capabilities::Vector{Capability}: List of server capabilities.
• server::Server: The server containing tools and resources.

Returns

• Dict{String,Any}: Protocol-formatted capabilities dictionary including available tools and resources.

create_init_response(server::Server, protocol_version::String) -> InitializeResult

Create the initialization response for an MCP server.

Arguments

• server::Server: The server to create the response for.
• protocol_version::String: MCP protocol version string.

Returns

• InitializeResult: Initialization response including server capabilities and info.

merge_capabilities(base::Vector{Capability}, override::Vector{Capability}) -> Vector{Capability}

Merge two sets of capabilities, with the override set taking precedence.

Arguments

• base::Vector{Capability}: Base set of capabilities.
• override::Vector{Capability}: Override capabilities that take precedence.

Returns

• Vector{Capability}: Merged set of capabilities.

to_protocol_format(cap::Capability) -> Dict{String,Any}

Convert an MCP capability to the JSON format expected by the MCP protocol.

Arguments

• cap::Capability: The capability to convert.

Returns

• Dict{String,Any}: Protocol-formatted capability dictionary.

auto_register!(server::Server, dir::AbstractString) -> Server

Automatically register MCP components found in the specified directory structure.

Arguments

• server::Server: The server to register components with
• dir::AbstractString: Root directory containing component subdirectories

Directory Structure

• dir/tools/: Contains tool definition files
• dir/resources/: Contains resource definition files
• dir/prompts/: Contains prompt definition files

Each subdirectory is optional. Files should be .jl files containing component definitions.

Component File Format

Component files must have the tool/resource/prompt as the last expression in the file. The return value of include() is used to obtain the component.

Example:

# tools/my_tool.jl
julia_version_tool = MCPTool(
    name = "julia_version",
    description = "Get Julia version",
    handler = params -> Dict("version" => string(VERSION))
)  # ← This must be the last expression

Returns

• Server: The updated server instance for method chaining

default_capabilities() -> Vector{Capability}

Create the default set of server capabilities for an MCP server.

Returns

• Vector{Capability}: Default capabilities including resources, tools, and prompts

normalize_path(path::String) -> String

Convert paths to absolute form, resolving relative paths against the project root.

Arguments

• path::String: The path to normalize

Returns

• String: Absolute, normalized path with all symbolic links resolved

scan_mcp_components(dir::String) -> Dict{Symbol,Vector}

Scan a directory recursively for MCP component definitions (tools, resources, prompts).

Arguments

• dir::String: Directory path to scan for component definitions

Returns

• Dict{Symbol,Vector}: Dictionary of found components grouped by type

TransportError(message::String) <: Exception

Exception type for transport-specific errors.

Fields

• message::String: The error message describing what went wrong

close(transport::Transport) -> Nothing

Close the transport connection and clean up resources.

Arguments

• transport::Transport: The transport instance to close

Returns

• Nothing

flush(transport::Transport) -> Nothing

Flush any buffered data in the transport. Default implementation does nothing.

Arguments

• transport::Transport: The transport instance to flush

Returns

• Nothing

is_connected(transport::Transport) -> Bool

Check if the transport is currently connected and operational.

Arguments

• transport::Transport: The transport instance to check

Returns

• Bool: true if connected and ready, false otherwise

read_message(transport::Transport) -> Union{String,Nothing}

Read a single message from the transport.

Arguments

• transport::Transport: The transport instance to read from

Returns

• Union{String,Nothing}: The message string if available, or nothing if no message or connection closed

write_message(transport::Transport, message::String) -> Nothing

Write a message to the transport.

Arguments

• transport::Transport: The transport instance to write to
• message::String: The message to send

Returns

• Nothing

Throws

• TransportError: If the message cannot be sent

close(transport::StdioTransport) -> Nothing

Mark the transport as closed. Does not actually close stdin/stdout.

Arguments

• transport::StdioTransport: The stdio transport instance

Returns

• Nothing

flush(transport::StdioTransport) -> Nothing

Flush the output stream.

Arguments

• transport::StdioTransport: The stdio transport instance

Returns

• Nothing

is_connected(transport::StdioTransport) -> Bool

Check if the stdio transport is connected.

Arguments

• transport::StdioTransport: The stdio transport instance

Returns

• Bool: Connection status

read_message(transport::StdioTransport) -> Union{String,Nothing}

Read a line from the input stream.

Arguments

• transport::StdioTransport: The stdio transport instance

Returns

• Union{String,Nothing}: The message string, or nothing if empty or EOF

write_message(transport::StdioTransport, message::String) -> Nothing

Write a message to the output stream with a newline.

Arguments

• transport::StdioTransport: The stdio transport instance
• message::String: The message to write

Returns

• Nothing

Throws

• TransportError: If writing fails

broadcast_to_sse(transport::HttpTransport, message::String; event::String="message") -> Nothing

Broadcast a message immediately to all SSE streams.

Arguments

• transport::HttpTransport: The transport instance
• message::String: The message to broadcast
• event::String: The event type (default: "message")

Returns

• Nothing

close(transport::HttpTransport) -> Nothing

Stop the HTTP server and close all connections.

Arguments

• transport::HttpTransport: The transport instance

Returns

• Nothing

end_response(transport::HttpTransport) -> Nothing

Deprecated: No longer needed as HTTP transport now sends complete responses. This method exists for backward compatibility but does nothing.

Arguments

• transport::HttpTransport: The transport instance

Returns

• Nothing

format_sse_event(data::String; event::Union{String,Nothing}=nothing, id::Union{Int64,String,Nothing}=nothing) -> String

Format a message as a Server-Sent Event.

Arguments

• data::String: The data to send
• event::Union{String,Nothing}: Optional event type
• id::Union{Int64,String,Nothing}: Optional event ID

Returns

• String: Formatted SSE event

generate_session_id() -> String

Generate a cryptographically secure session ID that meets MCP requirements. Must contain only visible ASCII characters (0x21 to 0x7E).

Returns

• String: A valid session ID

handle_request(transport::HttpTransport, stream::HTTP.Stream)

Handle incoming HTTP requests following the Streamable HTTP specification. Returns a single JSON response per request.

Arguments

• transport::HttpTransport: The transport instance
• stream::HTTP.Stream: The HTTP stream

Returns

• Nothing

handle_sse_stream(transport::HttpTransport, stream::HTTP.Stream, stream_id::String)

Handle a Server-Sent Events connection for notifications and streaming responses.

Arguments

• transport::HttpTransport: The transport instance
• stream::HTTP.Stream: The HTTP stream
• stream_id::String: Unique identifier for this SSE stream

Returns

• Nothing

is_connected(transport::HttpTransport) -> Bool

Check if the HTTP server is running and accepting connections.

Arguments

• transport::HttpTransport: The transport instance

Returns

• Bool: true if connected, false otherwise

is_valid_session_id(session_id::String) -> Bool

Validate that a session ID contains only visible ASCII characters (0x21 to 0x7E).

Arguments

• session_id::String: The session ID to validate

Returns

• Bool: true if valid, false otherwise

read_message(transport::HttpTransport) -> Union{String,Nothing}

Read a message from the request queue. Blocks until a request is available or the transport is disconnected.

Arguments

• transport::HttpTransport: The transport instance

Returns

• Union{String,Nothing}: The message string, or nothing if disconnected

send_notification(transport::HttpTransport, notification::String) -> Nothing

Send a notification to all connected SSE streams.

Arguments

• transport::HttpTransport: The transport instance
• notification::String: The notification message to send

Returns

• Nothing

write_message(transport::HttpTransport, message::String) -> Nothing

Write a message to the current request's response channel. The request handler will send this as the HTTP response.

Arguments

• transport::HttpTransport: The transport instance
• message::String: The message to send

Returns

• Nothing

MCPLogger(stream::IO=stderr, level::LogLevel=Info) -> MCPLogger

Create a new MCPLogger instance with specified stream and level.

Arguments

• stream::IO=stderr: The output stream where log messages will be written
• level::LogLevel=Info: The minimum logging level to display

Returns

• MCPLogger: A new logger instance

MCPLogger <: AbstractLogger

Define a custom logger for MCP server that formats messages according to protocol requirements.

Fields

• stream::IO: The output stream for log messages
• min_level::LogLevel: Minimum logging level to display
• message_limits::Dict{Any,Int}: Message limit settings for rate limiting

Logging.handle_message(logger::MCPLogger, level, message, _module, group, id, filepath, line; kwargs...) -> Nothing

Format and output log messages according to the MCP protocol format.

Arguments

• logger::MCPLogger: The MCP logger instance
• level: The log level of the message
• message: The log message content
• _module: The module where the log was generated
• group: The log group
• id: The log message ID
• filepath: The source file path
• line: The source line number
• kwargs...: Additional contextual information to include in the log

Returns

• Nothing: Function writes to the logger stream but doesn't return a value

init_logging(level::LogLevel=Info) -> Nothing

Initialize logging for the MCP server with a custom MCP-formatted logger.

Arguments

• level::LogLevel=Info: The minimum logging level to display

Returns

• Nothing: Function sets the global logger but doesn't return a value

StructTypes.omitempties(::Type{ClientCapabilities}) -> Tuple{Symbol,Symbol,Symbol}

Specify which fields should be omitted from JSON serialization when they are empty or null.

Arguments

• ::Type{ClientCapabilities}: The ClientCapabilities type

Returns

• Tuple{Symbol,Symbol,Symbol}: Fields to omit when empty

StructTypes.omitempties(::Type{ListPromptsResult}) -> Tuple{Symbol}

Specify which fields should be omitted from JSON serialization when they are empty or null.

Arguments

• ::Type{ListPromptsResult}: The ListPromptsResult type

Returns

• Tuple{Symbol}: Fields to omit when empty