Pforge

🚀 pforge

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

🚀 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/.

✨ Features

• Define MCP servers in YAML instead of writing boilerplate code.
• Built on top of pmcp (rust - mcp - sdk) and generate optimized Rust code from configuration.
• Support four handler types: Native, CLI, HTTP, and Pipeline.
• Provide language bridges for building MCP servers in different languages like Deno/TypeScript, with more coming soon (Python, Go, Node.js).

📦 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

💻 Usage Examples

Basic Usage

Quick example of pforge.yaml:

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 }

Advanced Usage - 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 of Deno/TypeScript Bridge:

• 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

📚 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

🔧 Technical Details

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.

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.

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.

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.

🤝 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.