pforge

pforge

使用 YAML 配置构建模型上下文协议（MCP）服务的声明式框架。

MCP 服务

注册表名称： io.github.paiml/pforge

pforge 已在模型上下文协议（MCP）注册表中发布。可通过以下方式安装：

# Via Cargo (recommended)
cargo install pforge-cli

# Then run as MCP server
pforge serve

维护者须知： 发布说明请参阅 MCP 注册表发布指南。

什么是 pforge？

pforge 让你可以使用 YAML 定义 MCP 服务，而不必编写样板代码。它基于 pmcp（rust-mcp-sdk）构建，并根据配置生成经过优化的 Rust 代码。

快速示例：

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 }

安装

# From crates.io
cargo install pforge-cli

# From source
git clone https://github.com/paiml/pforge
cd pforge
cargo install --path crates/pforge-cli

快速开始

# Create new project
pforge new my-server
cd my-server

# Run the server
pforge serve

生成的项目包含一个可运行的示例处理程序。编辑 pforge.yaml 以添加更多工具，然后在 src/handlers/ 中实现处理程序。

处理程序类型

pforge 支持四种处理程序类型：

1. Native - 具备完整类型安全性的 Rust 函数
2. CLI - 执行 Shell 命令
3. HTTP - 代理 HTTP 端点
4. Pipeline - 将多个工具串联起来

有关每种类型的详细示例，请参阅手册。

语言桥接

pforge 提供语言桥接，方便你使用偏好的语言构建 MCP 服务：

Deno/TypeScript 桥接

使用 TypeScript 和 Deno 构建具备原生性能的类型安全 MCP 服务：

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);

功能：

• 使用 TypeScript 泛型定义类型安全的处理程序
• 无外部依赖的运行时模式验证
• O(1) 处理程序查找性能
• 支持同步和异步处理程序
• 74+ 项测试通过，质量门禁全部达标

文档： bridges/deno/README.md

即将推出

• Python 桥接（基于 FFI，支持 asyncio）
• Go 桥接（基于 CGo，支持 goroutine）
• Node.js 桥接（基于 N-API 的原生扩展）

文档

• 手册 - 完整指南，包含示例和对比
• 架构 - 技术设计详情
• 用户指南 - 使用指南
• 实现状态 - 当前项目状态
• CLAUDE.md - 贡献者开发工作流

示例

• hello-world - 最简原生处理程序示例
• calculator - 数学运算及测试
• rest-api-proxy - HTTP 处理程序示例

项目状态

版本： 0.1.2

已发布的 crate：

• pforge-config - 配置解析
• pforge-macro - 过程宏
• pforge-runtime - 核心运行时（依赖 pmcp）
• pforge-codegen - 代码生成
• pforge-cli - 命令行工具

测试结果： 120+ 项测试通过（90+ 项单元/集成测试、12 项基于属性的测试、8 项质量门禁、5+ 项文档测试）

详细进展请参阅 IMPLEMENTATION_STATUS.md。

开发

# Run tests
cargo test --all

# Run quality gates
make quality-gate

# Watch mode
make watch

# Build release
make build-release

完整的开发工作流请参阅 CLAUDE.md。

架构

pforge 基于 pmcp（rust-mcp-sdk）构建为一个框架：

┌─────────────────────────────────┐
│   pforge (Framework Layer)      │
│   - YAML → Rust codegen         │
│   - Handler registry            │
│   - State management            │
└─────────────────────────────────┘
              ↓
┌─────────────────────────────────┐
│   pmcp (Protocol SDK)           │
│   - MCP protocol implementation │
│   - Transport handling          │
└─────────────────────────────────┘

适合直接使用 pmcp 的情况：你需要精细控制 MCP 协议细节，或希望避免代码生成。

适合使用 pforge 的情况：你希望通过更少的代码，以声明式配置快速开发 MCP 服务。

贡献

欢迎贡献。请：

1. 阅读 CLAUDE.md，了解开发规范
2. 查看 ROADMAP.md，了解当前优先事项
3. 确保测试通过：cargo test --all
4. 确保质量门禁通过：make quality-gate

所有提交都会经过提交前钩子的验证，检查代码格式、Lint、测试、复杂度、覆盖率和 Markdown 链接有效性（使用 pmat validate-docs），以防止文档链接失效。

许可证

MIT - 详见 LICENSE

致谢

基于 Pragmatic AI Labs 的 pmcp 构建。