pforge-codegen

Code generation engine for pforge - converts YAML configuration into optimized Rust code.

Features

• YAML → Rust: Transform declarative configuration into type-safe Rust code
• Handler Registry: Generate optimized handler registration code
• Schema Generation: Automatic JSON Schema generation for tool parameters
• Type Safety: Compile-time validation of generated code
• Zero Runtime Cost: All code generation happens at build time
• Optimized Output: Clean, idiomatic Rust code with minimal overhead

Installation

cargo add pforge-codegen

Usage

Generate from Configuration

use pforge_codegen::generate_server;
use pforge_config::ForgeConfig;

let config: ForgeConfig = serde_yaml::from_str(yaml_config)?;

// Generate Rust code
let generated_code = generate_server(&config)?;

// Write to file
std::fs::write("src/generated.rs", generated_code)?;

What Gets Generated

For this YAML configuration:

forge:
  name: calculator
  version: 0.1.0

tools:
  - type: native
    name: add
    description: "Add two numbers"
    handler:
      path: handlers::add_handler
    params:
      a: { type: number, required: true }
      b: { type: number, required: true }

The codegen generates:

// Handler registration
pub fn register_handlers(registry: &mut HandlerRegistry) -> Result<()> {
    registry.register("add", Arc::new(handlers::add_handler()))?;
    Ok(())
}

// JSON Schema for parameters
pub fn add_schema() -> schemars::schema::RootSchema {
    schemars::schema_for!(AddParams)
}

#[derive(Serialize, Deserialize, JsonSchema)]
pub struct AddParams {
    pub a: f64,
    pub b: f64,
}

// Server initialization
pub async fn start_server() -> Result<()> {
    let mut registry = HandlerRegistry::new();
    register_handlers(&mut registry)?;

    // Start MCP server with stdio transport
    pmcp::start_stdio_server(registry).await
}

Code Generation Pipeline

1. Parse Configuration: Load and validate YAML using pforge-config
2. AST Generation: Build Rust Abstract Syntax Tree
3. Optimization: Apply compiler optimizations
4. Code Emission: Generate clean, formatted Rust code

Generated Components

Handler Registration

Generates optimized registry initialization:

let mut registry = HandlerRegistry::new();
registry.register("tool1", Arc::new(Tool1Handler::default()))?;
registry.register("tool2", Arc::new(Tool2Handler::default()))?;

Type Definitions

Creates type-safe parameter structs:

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct ToolParams {
    pub input: String,
    #[serde(default)]
    pub optional: Option<i64>,
}

Schema Generation

Automatic JSON Schema for MCP protocol:

pub fn tool_schema() -> schemars::schema::RootSchema {
    schemars::schema_for!(ToolParams)
}

Transport Setup

Generates transport-specific initialization:

// For stdio transport
pmcp::start_stdio_server(registry).await?;

// For SSE transport
pmcp::start_sse_server("0.0.0.0:3000", registry).await?;

// For WebSocket transport
pmcp::start_ws_server("0.0.0.0:3001", registry).await?;

CLI Integration

The code generator is used by pforge-cli during the build process:

# Automatically runs codegen
pforge build

# Or explicitly
pforge codegen

Advanced Usage

Custom Templates

Provide custom code generation templates:

use pforge_codegen::{CodegenConfig, generate_with_config};

let config = CodegenConfig {
    template_dir: Some("templates/".into()),
    output_format: OutputFormat::Formatted,
    optimize: true,
};

let code = generate_with_config(&forge_config, &config)?;

Inline Handlers

Generate handlers with inline logic:

tools:
  - type: native
    name: echo
    description: "Echo input"
    handler:
      inline: |
        Ok(json!({ "output": params["input"] }))
    params:
      input: { type: string, required: true }

Generates:

#[async_trait::async_trait]
impl Handler for EchoHandler {
    async fn handle(&self, params: Value) -> Result<Value> {
        Ok(json!({ "output": params["input"] }))
    }
}

Generated Code Quality

All generated code follows Rust best practices:

• ✅ Formatted: Uses rustfmt for consistent style
• ✅ Clippy Clean: Passes clippy with no warnings
• ✅ Type Safe: Full type inference and checking
• ✅ Documented: Includes doc comments from YAML descriptions
• ✅ Optimized: Dead code elimination and inlining hints

Performance

The code generator is designed for fast build times:

• < 10ms for typical configurations (< 10 tools)
• < 100ms for large configurations (100+ tools)
• Incremental: Only regenerates when configuration changes

Documentation

• API Documentation
• Code Generation Guide
• Examples

License

MIT