Pforge Macro

A declarative framework for building Model Context Protocol (MCP) servers using YAML configuration.

CI crates.io crates.io License: MIT

MCP Server

Registry Name: io.github.paiml/pforge

pforge is available in the Model Context Protocol (MCP) Registry. Install it via:

# Via Cargo (recommended)
cargo install pforge-cli

# Then run as MCP server
pforge serve

For Maintainers: See MCP Registry Publishing Guide for publishing instructions.

What is pforge?

pforge lets you define MCP servers in YAML instead of writing boilerplate code. It's built on top of pmcp (rust-mcp-sdk) and generates optimized Rust code from your configuration.

Quick example:

forge:
  name: my-server
  version: 0.1.0
  transport: stdio

tools:
  - type: native
    name: greet
    description: "Greet someone"
    handler:
      path: handlers::greet_handler
    params:
      name: { type: string, required: true }

Installation

# From crates.io
cargo install pforge-cli

# From source
git clone https://github.com/paiml/pforge
cd pforge
cargo install --path crates/pforge-cli

Quick Start

# Create new project
pforge new my-server
cd my-server

# Run the server
pforge serve

The scaffolded project includes a working example handler. Edit pforge.yaml to add more tools, then implement handlers in src/handlers/.

Handler Types

pforge supports four handler types:

1. Native - Rust functions with full type safety
2. CLI - Execute shell commands
3. HTTP - Proxy HTTP endpoints
4. Pipeline - Chain multiple tools together

See the book for detailed examples of each type.

Language Bridges

pforge provides language bridges for building MCP servers in your preferred language:

Deno/TypeScript Bridge

Build type-safe MCP servers using TypeScript and Deno with native performance:

import { PforgeBridge } from "https://raw.githubusercontent.com/paiml/pforge/main/bridges/deno/bridge.ts";

const bridge = new PforgeBridge();

bridge.register({
  name: "greet",
  description: "Greet a user by name",
  handler: (input: { name: string }) => ({
    success: true,
    data: { message: `Hello, ${input.name}!` },
  }),
});

const result = await bridge.execute("greet", { name: "Alice" });
console.log(result.data);

Features:

• Type-safe handler definitions with TypeScript generics
• Runtime schema validation with no external dependencies
• O(1) handler lookup performance
• Both sync and async handler support
• 74+ tests passing with full quality gates

Documentation: bridges/deno/README.md

Coming Soon

• Python bridge (FFI-based with asyncio support)
• Go bridge (CGo-based with goroutine support)
• Node.js bridge (Native addon with N-API)

Documentation

• Book - Complete guide with examples and comparisons
• Architecture - Technical design details
• User Guide - Usage guide
• Implementation Status - Current project status
• CLAUDE.md - Development workflow for contributors

Examples

• hello-world - Minimal native handler example
• calculator - Math operations with tests
• rest-api-proxy - HTTP handler examples

Project Status

Version: 0.1.2

Published crates:

• pforge-config - Configuration parsing
• pforge-macro - Procedural macros
• pforge-runtime - Core runtime (depends on pmcp)
• pforge-codegen - Code generation
• pforge-cli - CLI tool

Test results: 120+ tests passing (90+ unit/integration, 12 property-based, 8 quality gates, 5+ doctests)

See IMPLEMENTATION_STATUS.md for detailed progress.

Development

# Run tests
cargo test --all

# Run quality gates
make quality-gate

# Watch mode
make watch

# Build release
make build-release

See CLAUDE.md for full development workflow.

Architecture

pforge is built as a framework on top of pmcp (rust-mcp-sdk):

┌─────────────────────────────────┐
│   pforge (Framework Layer)      │
│   - YAML → Rust codegen         │
│   - Handler registry            │
│   - State management            │
└─────────────────────────────────┘
              ↓
┌─────────────────────────────────┐
│   pmcp (Protocol SDK)           │
│   - MCP protocol implementation │
│   - Transport handling          │
└─────────────────────────────────┘

When to use pmcp directly: You need fine-grained control over MCP protocol details or want to avoid code generation.

When to use pforge: You want declarative configuration and rapid MCP server development with less code.

Contributing

Contributions are welcome. Please:

1. Read CLAUDE.md for development standards
2. Check ROADMAP.md for current priorities
3. Ensure tests pass: cargo test --all
4. Ensure quality gates pass: make quality-gate

All commits are validated by pre-commit hooks that check code formatting, linting, tests, complexity, coverage, and markdown link validity (using pmat validate-docs) to prevent broken documentation links.

License

MIT - see LICENSE

Acknowledgments

Built on pmcp by Pragmatic AI Labs.