Pforge

pforge

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 serverpforge 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.iocargo install pforge-cli
# From sourcegit clone https://github.com/paiml/pforgecd pforgecargo install --path crates/pforge-cli

Quick Start

# Create new projectpforge new my-servercd my-server
# Run the serverpforge 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 testscargo test --all
# Run quality gatesmake quality-gate
# Watch modemake watch
# Build releasemake 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.