Crate thulp_core 

thulp-core

Core types, traits, and error definitions for the thulp execution context platform.

This crate provides the foundational abstractions for defining, validating, and executing tools in AI agent environments. It includes type-safe parameter definitions, tool metadata, and extensible traits for implementing custom tool providers and transports.

Core Types

• ToolDefinition: Describes an available tool with its parameters and metadata
• ToolCall: Represents a request to execute a specific tool with arguments
• ToolResult: The result of a tool execution (success or failure)
• Parameter: Defines a tool parameter with type information and validation rules
• ParameterType: Strongly-typed parameter types (String, Integer, Number, Boolean, Array, Object)

MCP Types

• Resource: MCP resource definition with URI, name, and metadata
• ResourceContents: Content of a read resource (text or blob)
• Prompt: MCP prompt definition with arguments
• PromptMessage: Message in a rendered prompt

Traits

• Tool: Trait for implementing executable tools
• Transport: Trait for implementing tool transport layers (e.g., MCP, HTTP, gRPC)

Features

• Type Safety: Compile-time and runtime validation of tool parameters
• Builder Pattern: Ergonomic API for constructing tool definitions
• JSON Serialization: Full serde support for all types
• MCP Integration: Parse MCP JSON Schema to Thulp parameter definitions
• Async Support: Built on tokio for efficient async execution

Quick Start

Defining a Tool

use thulp_core::{ToolDefinition, Parameter, ParameterType};

let tool = ToolDefinition::builder("read_file")
    .description("Read contents of a file")
    .parameter(
        Parameter::builder("path")
            .param_type(ParameterType::String)
            .required(true)
            .description("Path to the file to read")
            .build()
    )
    .parameter(
        Parameter::builder("encoding")
            .param_type(ParameterType::String)
            .default(serde_json::Value::String("utf-8".to_string()))
            .description("File encoding")
            .build()
    )
    .build();

assert_eq!(tool.name, "read_file");
assert_eq!(tool.parameters.len(), 2);

Validating Tool Arguments

use thulp_core::{ToolDefinition, Parameter, ParameterType};
use serde_json::json;

let tool = ToolDefinition::builder("add")
    .description("Add two numbers")
    .parameter(
        Parameter::builder("a")
            .param_type(ParameterType::Number)
            .required(true)
            .build()
    )
    .parameter(
        Parameter::builder("b")
            .param_type(ParameterType::Number)
            .required(true)
            .build()
    )
    .build();

// Valid arguments
let args = json!({"a": 5.0, "b": 3.0});
assert!(tool.validate_args(&args).is_ok());

// Invalid - missing required parameter
let args = json!({"a": 5.0});
assert!(tool.validate_args(&args).is_err());

// Invalid - wrong type
let args = json!({"a": "not a number", "b": 3.0});
assert!(tool.validate_args(&args).is_err());

Creating Tool Calls

use thulp_core::ToolCall;
use serde_json::json;

let call = ToolCall::builder("search")
    .arg("query", json!("rust programming"))
    .arg("max_results", json!(10))
    .build();

assert_eq!(call.tool, "search");

Parsing MCP JSON Schema

use thulp_core::ToolDefinition;
use serde_json::json;

let schema = json!({
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "User name"
        },
        "age": {
            "type": "integer",
            "description": "User age"
        }
    },
    "required": ["name"]
});

let params = ToolDefinition::parse_mcp_input_schema(&schema).unwrap();
assert_eq!(params.len(), 2);
assert!(params.iter().find(|p| p.name == "name").unwrap().required);
assert!(!params.iter().find(|p| p.name == "age").unwrap().required);

Working with MCP Resources

use thulp_core::{Resource, ResourceContents};

let resource = Resource::builder("file:///docs/readme.md", "readme.md")
    .title("Project README")
    .mime_type("text/markdown")
    .description("Main project documentation")
    .build();

let contents = ResourceContents::text("file:///docs/readme.md", "# Project\n...");

Working with MCP Prompts

use thulp_core::{Prompt, PromptArgument, PromptMessage, GetPromptResult};

let prompt = Prompt::builder("code_review")
    .title("Code Review")
    .description("Review code for best practices")
    .argument(PromptArgument::required("code", "Code to review"))
    .build();

let result = GetPromptResult::new(vec![
    PromptMessage::user_text("Please review this code"),
]);

Error Handling

All fallible operations return Result<T, Error>, where Error provides detailed error information:

use thulp_core::{ToolDefinition, Error};
use serde_json::json;

let tool = ToolDefinition::builder("test")
    .parameter(
        thulp_core::Parameter::builder("required_param")
            .param_type(thulp_core::ParameterType::String)
            .required(true)
            .build()
    )
    .build();

match tool.validate_args(&json!({})) {
    Ok(_) => println!("Valid!"),
    Err(Error::MissingParameter(name)) => {
        eprintln!("Missing required parameter: {}", name);
    }
    Err(e) => eprintln!("Other error: {}", e),
}

Structs

EmbeddedResource

Embedded resource in prompt content.

GetPromptResult

Result of getting a prompt.

Parameter

A parameter definition for a tool.

ParameterBuilder

Builder for Parameter.

Prompt

MCP Prompt definition.

PromptArgument

Prompt argument definition.

PromptBuilder

Builder for Prompt.

PromptListResult

Result of listing prompts.

PromptMessage

Message returned when getting a prompt.

Resource

MCP Resource definition.

ResourceAnnotations

Resource annotations for additional metadata.

ResourceBuilder

Builder for Resource.

ResourceContents

Resource contents after reading.

ResourceListResult

Result of listing resources.

ResourceTemplate

Resource template with URI template pattern.

ResourceTemplateListResult

Result of listing resource templates.

ToolCall

A request to execute a tool.

ToolCallBuilder

Builder for ToolCall.

ToolDefinition

Definition of an available tool.

ToolDefinitionBuilder

Builder for ToolDefinition.

ToolResult

The result of a tool execution.

Enums

Error

Errors that can occur in thulp-core.

ParameterType

The type of a parameter.

PromptContent

Prompt content variants.

Traits

Tool

Trait for executable tools.

Transport

Trait for communication transports (MCP, HTTP, etc.).

Type Aliases

Result

Result type alias using [Error].