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(client).await?;

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

    // Elicit a collection
    let scores: Vec<i32> = Vec::<i32>::elicit(client).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 rmcp;

Modules§

mcp: MCP (Model Context Protocol) integration.
style: Elicitation style system - separates UX from behavior.

Macros§

default_style: Generate a default-only style enum for a type.

Structs§

ElicitBuilder: Builder for one-off style overrides.
ElicitClient: Client wrapper that carries style context.
ElicitError: Elicitation error with location tracking.
FieldInfo: Metadata for a single survey field.
JsonError: JSON parsing error wrapper.
RmcpError: RMCP error wrapper.
ServiceError: RMCP ServiceError wrapper for error conversion.

Enums§

ElicitErrorKind: Specific error conditions during elicitation.

Traits§

Affirm: Binary confirmation (yes/no, true/false pattern).
Authorize: Permission-granting interaction with policy choices.
Elicitation: Main elicitation trait - entry point for value elicitation.
ElicitationStyle: Trait for elicitation style types.
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).

Type Aliases§

ElicitResult: Convenience alias for elicitation results.

Derive Macros§

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