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.

Related MCP server: Jotdown

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.