Crate elicitation

Expand description

Conversational elicitation of strongly-typed Rust values via MCP.

The elicitation library provides a trait-based system for eliciting strongly-typed values from users through conversational interaction via the Model Context Protocol (MCP). It transforms LLM conversations into type-safe Rust values with compile-time guarantees.

§MCP Setup Required

This library runs as an MCP server and requires an MCP client (like Claude Desktop or Claude CLI) to provide the elicitation tools. Your application won’t work standalone - it must be invoked by an MCP client.

See the README for setup instructions.

§Core Concepts

§Traits

Prompt - Provides prompt metadata for a type
Elicit - Main trait for eliciting values

§Interaction Paradigms

Select - Choose from finite options (enum pattern)
Affirm - Yes/no confirmation (bool pattern)
Survey - Multi-field elicitation (struct pattern)
Authorize - Permission policies (planned for v0.2.0)

§Example

use elicitation::{Elicitation, ElicitResult};
use rmcp::service::{Peer, RoleClient};

async fn example(client: &Peer<RoleClient>) -> ElicitResult<()> {
    // Elicit a simple integer
    let age: i32 = i32::elicit(communicator).await?;

    // Elicit an optional value
    let nickname: Option<String> = Option::<String>::elicit(communicator).await?;

    // Elicit a collection
    let scores: Vec<i32> = Vec::<i32>::elicit(communicator).await?;
    Ok(())
}

§Derive Macros

The library provides derive macros for automatic implementation:

use elicitation::Elicit;

// Enums automatically use the Select paradigm
#[derive(Elicit)]
enum Color {
    Red,
    Green,
    Blue,
}

// Structs automatically use the Survey paradigm
#[derive(Elicit)]
struct Person {
    #[prompt("What is your name?")]
    name: String,
    #[prompt("What is your age?")]
    age: u8,
}

§MCP Integration

The library uses the rmcp crate - the official Rust MCP SDK - for MCP client integration. All elicitation happens through asynchronous MCP tool calls.

Re-exports§

pub use contracts::And;
pub use contracts::Established;
pub use contracts::Implies;
pub use contracts::InVariant;
pub use contracts::Is;
pub use contracts::Prop;
pub use contracts::Refines;
pub use contracts::both;
pub use contracts::downcast;
pub use contracts::fst;
pub use contracts::snd;
pub use tool::Tool;
pub use tool::True;
pub use tool::both_tools;
pub use tool::then;
pub use rmcp;

Modules§

contracts: Proof-carrying composition primitives.
mcp: MCP (Model Context Protocol) integration.
style: Elicitation style system - separates UX from behavior.
tool: Contract-based tool system for MCP.
verification: Formal verification framework for tool chains.

Macros§

default_style: Generate a default-only style enum for a type.
elicit_router: Creates an aggregator struct that registers elicit_checked tools from multiple types.

Structs§

DurationGenerator: Generator for creating Duration values with a specified strategy.
ElicitBuilder: Builder for one-off style overrides.
ElicitClient: Client wrapper that carries style context.
ElicitError: Elicitation error with location tracking.
ElicitServer: Server wrapper that carries style context.
ElicitToolDescriptor: Describes an elicit tool that can be registered with MCP.
FieldInfo: Metadata for a single survey field.
Formatter: Formatting helper - unit struct with formatting methods.
IoErrorGenerator: Generator for creating std::io::Error instances for testing.
JsonError: JSON parsing error wrapper.
Parser: Parser helper - unit struct with parsing methods.
RmcpError: RMCP error wrapper.
ServiceError: RMCP ServiceError wrapper for error conversion.
StyleContext: Storage for type-specific styles.
SystemTimeGenerator: Generator for creating SystemTime values with a specified strategy.
Validator: Validation helper - unit struct with validation methods.

Enums§

DurationGenerationMode: Generation mode for Duration.
ElicitErrorKind: Specific error conditions during elicitation.
IoErrorGenerationMode: Generation mode for std::io::Error.
SystemTimeGenerationMode: Generation mode for SystemTime.

Traits§

Affirm: Binary confirmation (yes/no, true/false pattern).
Authorize: Permission-granting interaction with policy choices.
ElicitCommunicator: Abstraction for elicitation communication.
Elicitation: Main elicitation trait - entry point for value elicitation.
ElicitationStyle: Trait for elicitation style types.
Generator: Trait for generating values of a type.
Prompt: Shared metadata for prompts across all elicitation patterns.
Select: Select one value from a finite set (dropdown/radio button pattern).
Survey: Multi-field structured elicitation (form/wizard pattern).

Functions§

collect_all_elicit_tools: Collect all elicit tools registered via #[derive(Elicit)].

Type Aliases§

ElicitResult: Convenience alias for elicitation results.

Derive Macros§

Elicit: Derive the Elicit trait for enums (→ Select) or structs (→ Survey).