Crate server_less 

Server-less - Composable derive macros for Rust

Server-less takes an impl-first approach: write your Rust methods, and derive macros project them into various protocols (HTTP, CLI, MCP, WebSocket).

Quick Start

use server_less::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct User { name: String, email: String }

#[derive(Debug, ServerlessError)]
enum UserError { NotFound }

struct UserService;

#[mcp]
impl UserService {
    /// Create a new user
    async fn create_user(&self, name: String, email: String) -> Result<User, UserError> {
        Ok(User { name, email })
    }

    /// List all users
    async fn list_users(&self, limit: Option<u32>) -> Vec<User> {
        let _ = limit;
        vec![]
    }
}

This generates:

• MCP: Tools create_user, list_users (Model Context Protocol)

Available Macros

Macro	Protocol	Generated Methods
#[http]	HTTP/REST	http_router(), openapi_spec()
#[cli]	Command Line	cli_command(), cli_run()
#[mcp]	MCP	mcp_tools(), mcp_call(), mcp_call_async()
#[ws]	WebSocket	ws_router(), ws_handle_message(), ws_handle_message_async()

Naming Conventions

Method names infer HTTP methods and CLI subcommand structure:

Prefix	HTTP	CLI
create_*, add_*	POST	<cmd> create-*
get_*, fetch_*	GET (single)	<cmd> get-*
list_*, find_*	GET (collection)	<cmd> list-*
update_*, set_*	PUT	<cmd> update-*
delete_*, remove_*	DELETE	<cmd> delete-*

Return Types

Type	HTTP	CLI	MCP/WS
T	200 + JSON	stdout JSON	JSON result
Option<T>	200 or 404	stdout or exit 1	result or null
Result<T, E>	200 or error	stdout or stderr	result or error
()	204	silent	{"success": true}
impl Stream<Item=T>	SSE	N/A	N/A

Async Methods

All macros support async methods:

use server_less::prelude::*;

struct MyService;

#[mcp]
impl MyService {
    /// Sync method - works with mcp_call() and mcp_call_async()
    pub fn sync_method(&self) -> String {
        String::from("hello")
    }

    /// Async method - use mcp_call_async() for proper await
    pub async fn async_method(&self) -> String {
        String::from("hello async")
    }
}

#[tokio::main]
async fn main() {
    let service = MyService;
    // Sync call (errors on async methods)
    service.mcp_call("sync_method", serde_json::json!({}));
    // Async call (awaits async methods properly)
    service.mcp_call_async("async_method", serde_json::json!({})).await;
}

SSE Streaming (HTTP)

Return impl Stream<Item=T> for Server-Sent Events:

use server_less::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Clone, Serialize, Deserialize)]
struct Event { message: String }

#[derive(Clone)]
struct StreamService;

#[http]
impl StreamService {
    // Note: Rust 2024 requires `+ use<>` to avoid lifetime capture
    pub fn stream_events(&self) -> impl futures::Stream<Item = Event> + use<> {
        futures::stream::iter(vec![Event { message: String::from("hello") }])
    }
}

Feature Flags

Enable only what you need:

[dependencies]
server-less = { version = "0.2", default-features = false, features = ["http", "cli"] }

Available features:

• mcp - MCP macro (no extra deps)
• http - HTTP macro (requires axum)
• cli - CLI macro (requires clap)
• ws - WebSocket macro (requires axum, futures)
• full - All features (default)

Re-exports

pub use futures;

pub use async_graphql;

pub use async_graphql_axum;

pub use serde;

pub use serde_json;

Modules

config

Config management types for #[derive(Config)].

error

Error handling and protocol-specific error mapping.

extract

Context and parameter extraction types.

prelude

Prelude for convenient imports

Structs

ConfigFieldMeta

Metadata about a single field in a Config-implementing struct.

Context

Protocol-agnostic request context.

ErrorResponse

A generic error response that can be serialized

HttpStatusHelper

Helper wrapper used by generated HTTP handler code to map error values to HTTP status codes.

MethodInfo

Runtime method metadata with string-based types.

OpenApiBuilder

Builder for composing OpenAPI specs from multiple sources.

OpenApiOperation

An OpenAPI operation (endpoint).

OpenApiParameter

An OpenAPI parameter.

OpenApiPath

An OpenAPI path with its operations.

OpenApiSchema

An OpenAPI schema definition.

ParamInfo

Runtime parameter metadata with string-based types.

SchemaValidationError

Error type for schema validation failures.

SchemaValueParser

A clap [TypedValueParser] that uses schemars::JsonSchema to surface enum variants as possible values, and std::str::FromStr for actual parsing.

WsSender

WebSocket sender for server-push messaging.

Enums

ConfigError

Error returned by Config::load.

ConfigSource

Specifies where configuration values should be loaded from.

ErrorCode

Protocol-agnostic error code that maps to HTTP status, gRPC code, CLI exit code, etc.

HttpMethod

HTTP method inferred from function name

OpenApiError

Errors that can occur during OpenAPI composition.

Traits

CliSubcommand

Trait for types that can be mounted as CLI subcommand groups.

ConfigTrait

Trait implemented by #[derive(Config)] structs.

HttpMount

Trait for types that can be mounted as HTTP route groups.

HttpStatusFallback

Fallback trait used by HttpStatusHelper when the concrete error type does not implement IntoErrorCode.

IntoErrorCode

Trait for converting errors to protocol-agnostic error codes.

JsonRpcMount

Trait for types that can be mounted as JSON-RPC method namespaces.

McpNamespace

Trait for types that can be mounted as MCP tool namespaces.

WsMount

Trait for types that can be mounted as WebSocket method namespaces.

Functions

cli_format_output

Format a serde_json::Value according to the active JSON output flag.

cli_schema_for

Generate a JSON Schema for a type at runtime using schemars.

infer_path

Infer URL path from method name

Attribute Macros

app

Attach protocol-neutral application metadata to an impl block.

asyncapi

Generate AsyncAPI specification for event-driven services.

capnp

Generate Cap’n Proto schema from an impl block.

cli

Generate a CLI application from an impl block.

connect

Generate Connect protocol schema from an impl block.

graphql

Generate GraphQL schema from an impl block using async-graphql.

graphql_enum

Define a GraphQL enum type.

graphql_input

Define a GraphQL input type.

grpc

Generate Protocol Buffers schema from an impl block.

http

Generate HTTP handlers from an impl block.

jsonrpc

Generate JSON-RPC 2.0 handlers over HTTP.

jsonschema

Generate JSON Schema from an impl block.

markdown

Generate Markdown API documentation from an impl block.

mcp

Generate MCP (Model Context Protocol) tools from an impl block.

openapi

Generate OpenAPI specification without HTTP routing.

openrpc

Generate OpenRPC specification for JSON-RPC services.

program

Blessed preset: CLI application with Markdown docs.

response

Helper attribute for method-level HTTP response customization.

route

Helper attribute for method-level HTTP route customization.

rpc

Blessed preset: JSON-RPC server with OpenRPC spec and serve.

serve

Coordinate multiple protocol handlers into a single server.

server

Blessed preset: HTTP server with OpenAPI and serve.

smithy

Generate Smithy IDL schema from an impl block.

thrift

Generate Apache Thrift schema from an impl block.

tool

Blessed preset: MCP tools with JSON Schema.

ws

Generate WebSocket JSON-RPC handlers from an impl block.

Derive Macros

Config

Derive config loading from multiple sources for a struct.

ServerlessError

Derive macro for error types that implement IntoErrorCode.