Pforge

pforge

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

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](https://paiml.github.io/pforge) - Complete guide with examples and comparisons
• [Architecture](docs/ARCHITECTURE.md) - Technical design details
• [User Guide](docs/USER_GUIDE.md) - Usage guide
• [Implementation Status](docs/IMPLEMENTATION_STATUS.md) - Current project status
• [CLAUDE.md](CLAUDE.md) - Development workflow for contributors

Examples

• [hello-world](examples/hello-world/) - Minimal native handler example
• [calculator](examples/calculator/) - Math operations with tests
• [rest-api-proxy](examples/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.