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