pulseengine_mcp_macros/
lib.rs

1//! # PulseEngine MCP Macros
2//!
3//! Procedural macros for the PulseEngine MCP Framework that dramatically simplify
4//! server and tool development while maintaining enterprise-grade capabilities.
5//!
6//! ## Quick Start
7//!
8//! Create a simple MCP server with tools:
9//!
10//! ```rust,ignore
11//! use pulseengine_mcp_macros::{mcp_server, mcp_tool};
12//!
13//! #[mcp_server(name = "Hello World")]
14//! struct HelloWorld;
15//!
16//! #[mcp_tool]
17//! impl HelloWorld {
18//!     /// Say hello to someone
19//!     async fn say_hello(&self, name: String) -> String {
20//!         format!("Hello, {}!", name)
21//!     }
22//! }
23//! ```
24//!
25//! ## Features
26//!
27//! - **Zero Boilerplate**: Focus on business logic, not protocol details
28//! - **Type Safety**: Compile-time validation of tool definitions  
29//! - **Auto Schema Generation**: JSON schemas derived from Rust types
30//! - **Doc Comments**: Function documentation becomes tool descriptions
31//! - **Progressive Complexity**: Start simple, add enterprise features as needed
32
33use proc_macro::TokenStream;
34
35mod mcp_backend;
36mod mcp_server;
37mod mcp_tool;
38mod utils;
39
40/// Automatically generates MCP tool definitions from Rust functions.
41///
42/// This macro transforms regular Rust functions into MCP tools with automatic
43/// JSON schema generation, parameter validation, and error handling.
44///
45/// # Basic Usage
46///
47/// ```rust,ignore
48/// use pulseengine_mcp_macros::mcp_tool;
49///
50/// #[mcp_tool]
51/// async fn say_hello(name: String) -> String {
52///     format!("Hello, {}!", name)
53/// }
54/// ```
55///
56/// # With Custom Description
57///
58/// ```rust,ignore
59/// #[mcp_tool(description = "Say hello to someone or something")]
60/// async fn say_hello(name: String, greeting: Option<String>) -> String {
61///     format!("{}, {}!", greeting.unwrap_or("Hello"), name)
62/// }
63/// ```
64///
65/// # Parameters
66///
67/// - `description`: Optional custom description (defaults to doc comments)
68/// - `name`: Optional custom tool name (defaults to function name)
69///
70/// # Features
71///
72/// - **Automatic Schema**: JSON schemas generated from Rust parameter types
73/// - **Doc Comments**: Function documentation becomes tool description
74/// - **Type Safety**: Compile-time validation of parameters
75/// - **Error Handling**: Automatic conversion of Result types
76/// - **Async Support**: Both sync and async functions supported
77#[proc_macro_attribute]
78pub fn mcp_tool(attr: TokenStream, item: TokenStream) -> TokenStream {
79    mcp_tool::mcp_tool_impl(attr.into(), item.into())
80        .unwrap_or_else(|err| err.to_compile_error())
81        .into()
82}
83
84/// Auto-implements the McpBackend trait with smart defaults.
85///
86/// This macro generates a complete McpBackend implementation with minimal
87/// configuration required. It inspects the struct and automatically generates
88/// appropriate server info, capabilities, and default implementations.
89///
90/// # Basic Usage
91///
92/// ```rust,ignore
93/// use pulseengine_mcp_macros::mcp_backend;
94///
95/// #[mcp_backend(name = "My Server")]
96/// struct MyBackend {
97///     data: String,
98/// }
99/// ```
100///
101/// # Parameters
102///
103/// - `name`: Server name (required)
104/// - `version`: Server version (defaults to Cargo package version)
105/// - `description`: Server description (defaults to doc comments)
106/// - `capabilities`: Custom capabilities (auto-detected by default)
107///
108/// # Features
109///
110/// - **Smart Capabilities**: Auto-detects capabilities from available tools
111/// - **Default Implementations**: Provides sensible defaults for all methods
112/// - **Error Handling**: Automatic error type conversion
113/// - **Version Integration**: Uses Cargo.toml version by default
114#[proc_macro_attribute]
115pub fn mcp_backend(attr: TokenStream, item: TokenStream) -> TokenStream {
116    mcp_backend::mcp_backend_impl(attr.into(), item.into())
117        .unwrap_or_else(|err| err.to_compile_error())
118        .into()
119}
120
121/// Complete server generation from a simple struct.
122///
123/// This macro combines `#[mcp_backend]` with additional server lifecycle
124/// management, providing a complete MCP server implementation.
125///
126/// # Basic Usage
127///
128/// ```rust,ignore
129/// use pulseengine_mcp_macros::mcp_server;
130///
131/// #[mcp_server(name = "Hello World")]
132/// struct HelloWorld;
133/// ```
134///
135/// # With Configuration
136///
137/// ```rust,ignore
138/// #[mcp_server(
139///     name = "Advanced Server",
140///     version = "1.0.0",
141///     description = "A more advanced MCP server"
142/// )]
143/// struct AdvancedServer {
144///     config: MyConfig,
145/// }
146/// ```
147///
148/// # Parameters
149///
150/// - `name`: Server name (required)
151/// - `version`: Server version (defaults to Cargo package version)
152/// - `description`: Server description (defaults to doc comments)
153/// - `transport`: Default transport type (defaults to auto-detect)
154///
155/// # Features
156///
157/// - **Complete Implementation**: Backend + server management
158/// - **Fluent Builder**: Provides `.serve_*()` methods
159/// - **Transport Auto-Detection**: Smart defaults based on environment
160/// - **Configuration Integration**: Works with PulseEngine config system
161#[proc_macro_attribute]
162pub fn mcp_server(attr: TokenStream, item: TokenStream) -> TokenStream {
163    mcp_server::mcp_server_impl(attr.into(), item.into())
164        .unwrap_or_else(|err| err.to_compile_error())
165        .into()
166}
167
168/// Derives MCP tool implementations for all methods in an impl block.
169///
170/// This is a convenience macro that applies `#[mcp_tool]` to all public
171/// methods in an impl block.
172///
173/// # Usage
174///
175/// ```rust,ignore
176/// use pulseengine_mcp_macros::mcp_tools;
177///
178/// #[mcp_tools]
179/// impl MyServer {
180///     /// This becomes an MCP tool
181///     async fn tool_one(&self, param: String) -> String {
182///         param.to_uppercase()
183///     }
184///
185///     /// This also becomes an MCP tool
186///     fn tool_two(&self, x: i32, y: i32) -> i32 {
187///         x + y
188///     }
189///
190///     // Private methods are ignored
191///     fn helper_method(&self) -> bool {
192///         true
193///     }
194/// }
195/// ```
196#[proc_macro_attribute]
197pub fn mcp_tools(attr: TokenStream, item: TokenStream) -> TokenStream {
198    mcp_tool::mcp_tools_impl(attr.into(), item.into())
199        .unwrap_or_else(|err| err.to_compile_error())
200        .into()
201}
pulseengine_mcp_macros/lib.rs

pulseengine_mcp_macros/
lib.rs
