Crate fastmcp_core 

Core types and traits for FastMCP.

This crate provides the fundamental building blocks:

• McpContext wrapping asupersync’s Cx
• Error types for MCP operations
• Core traits for tool, resource, and prompt handlers

Design Principles

• Zero-copy where possible
• No runtime reflection (compile-time via macros)
• All types support Send + Sync
• Cancel-correct via asupersync integration

Role in the System

fastmcp-core is the foundation layer shared by every other crate. It defines:

• McpContext, the capability-carrying handle that wraps asupersync’s Cx
• The FastMCP error model (McpError, McpErrorCode, McpResult)
• Budget/cancellation semantics that handlers and transports must obey
• Outcome bridging utilities so server/client code can stay 4-valued

If you are implementing a new transport, handler, or runtime adapter, this is the crate that gives you the shared primitives used everywhere else.

Asupersync Integration

This crate uses asupersync as its async runtime foundation, providing:

• Structured concurrency: Tool handlers run in regions
• Cancel-correctness: Graceful cancellation via checkpoints
• Budgeted timeouts: Request timeouts via budget exhaustion
• Deterministic testing: Lab runtime for reproducible tests

Re-exports

pub use runtime::block_on;

Modules

combinator

Parallel combinator helpers for MCP handlers.

logging

Structured logging for FastMCP.

runtime

Minimal runtime helpers for FastMCP.

Macros

log_handler

Logs a handler execution event at DEBUG level.

log_router

Logs a request routing event at DEBUG level.

log_server

Logs a server lifecycle event at INFO level.

log_transport

Logs a transport event at DEBUG level.

Structs

AccessToken

Parsed access token (scheme + token value).

AuthContext

Authentication context stored for a request/session.

Budget

A budget constraining resource usage for a task or region.

CancelledError

Error returned when a request has been cancelled.

ClientCapabilityInfo

Client capability information accessible from handlers.

Cx

The capability context for a task.

ElicitationRequest

Parameters for an elicitation request.

ElicitationResponse

Response from an elicitation request.

LabConfig

Configuration for the lab runtime.

LabRuntime

The deterministic lab runtime.

McpContext

MCP context that wraps asupersync’s capability context.

McpError

An MCP error response.

NoOpElicitationSender

A no-op elicitation sender that always returns an error.

NoOpNotificationSender

A no-op notification sender used when progress reporting is disabled.

NoOpSamplingSender

A no-op sampling sender that always returns an error.

ParseDurationError

Error type for duration parsing.

ProgressReporter

Progress reporter that wraps a notification sender with a progress token.

RegionId

A unique identifier for a region in the runtime.

ResourceContentItem

A single item of resource content.

ResourceReadResult

Result of reading a resource.

SamplingRequest

Parameters for a sampling request.

SamplingRequestMessage

A message in a sampling request.

SamplingResponse

Response from a sampling request.

Scope

A scope for spawning work within a region.

ServerCapabilityInfo

Server capability information accessible from handlers.

SessionState

Thread-safe session state container for per-session key-value storage.

TaskId

A unique identifier for a task in the runtime.

ToolCallResult

Result of calling a tool.

Enums

ElicitationAction

Action taken by the user in response to elicitation.

ElicitationMode

Mode of elicitation.

McpErrorCode

Standard MCP/JSON-RPC error codes.

Outcome

The four-valued outcome of a concurrent operation.

SamplingRole

Role in a sampling message.

SamplingStopReason

Stop reason for sampling.

ToolContentItem

A single item of content returned from a tool call.

Constants

AUTH_STATE_KEY

Session state key used to store authentication context.

DISABLED_PROMPTS_KEY

Session state key for disabled prompts.

DISABLED_RESOURCES_KEY

Session state key for disabled resources.

DISABLED_TOOLS_KEY

Session state key for disabled tools.

MAX_RESOURCE_READ_DEPTH

Maximum depth for nested resource reads to prevent infinite recursion.

MAX_TOOL_CALL_DEPTH

Maximum depth for nested tool calls to prevent infinite recursion.

Traits

ElicitationSender

Trait for sending elicitation requests to the client.

IntoOutcome

Extension trait for converting MCP results to asupersync Outcome.

NotificationSender

Trait for sending notifications back to the client.

OutcomeExt

Extension trait for converting Outcomes to MCP-friendly forms.

ResourceReader

Trait for reading resources from within handlers.

ResultExt

Extension trait for converting Results to Outcomes.

SamplingSender

Trait for sending sampling requests to the client.

ToolCaller

Trait for calling tools from within handlers.

Functions

cancelled

Creates an MCP error Outcome from a cancellation.

err

Creates an MCP error Outcome with the given error.

ok

Creates an MCP success Outcome.

parse_duration

Parses a human-readable duration string into a Duration.

Type Aliases

McpOutcome

Outcome type alias for MCP operations with 4-valued returns.

McpResult

Result type alias for MCP operations.