使用说明

Roony治理

开源AI代理支付治理引擎。

让您的AI代理能够通过内置的支出控制、审批工作流和审计跟踪进行购买。

为什么是Roony？

人工智能代理越来越自主——预订旅行、购买软件、管理订阅。但是，你如何在不失去控制的情况下给人工智能信用卡呢？

Roony提供：

🔒 支出限额 -每笔交易、每日和每月上限
🏪 商户控制 -允许/阻止特定商家或类别
👤 人类认可 -需要对大额或异常购买进行审查
🏢 组织护栏 -所有代理商的全公司政策
💳 虚拟卡 -购买后过期的一次性卡
🤖 MCP支持 -与Claude、Cursor和其他MCP客户端配合使用

快速开始

选项1：使用托管Roony（最简单）

只需使用 roony.pay -我们处理一切：

用于管理代理和策略的仪表板
虚拟卡的条纹集成
没有要管理的基础设施

选项2：自助主机

npm install @roony-pay/governance

import {
  createRoonyMCPServer,
  InMemoryStorageProvider,
  MockPaymentProvider,
} from "@roony-pay/governance";

// Create providers (use your own implementations for production)
const storage = new InMemoryStorageProvider();
const payments = new MockPaymentProvider();

// Add an organization
storage.addOrganization({
  id: "org_123",
  name: "Acme Corp",
  monthlyBudget: 10000,
  guardrails: {
    maxTransactionAmount: 500,
    requireApprovalAbove: 200,
  },
});

// Add an agent with spending controls
storage.addAgent({
  id: "agent_123",
  organizationId: "org_123",
  name: "Shopping Assistant",
  status: "active",
  monthlyLimit: 1000,
  perTransactionLimit: 100,
  approvalThreshold: 50,
  flagNewVendors: true,
});

// Create MCP server
const server = createRoonyMCPServer({
  storage,
  paymentProvider: payments,
});

// Handle requests (e.g., in Next.js API route)
export async function POST(req: Request) {
  const body = await req.json();
  const response = await server.handleRequest(body, "agent_123", "org_123");
  return Response.json(response);
}

运作原理

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  AI Agent   │────▶│  Roony Gateway   │────▶│  Your Payment   │
│  (Claude)   │     │                  │     │  Provider       │
└─────────────┘     │  ✓ Check limits  │     │  (Stripe, etc)  │
                    │  ✓ Evaluate rules│     └─────────────────┘
                    │  ✓ Log & audit   │              │
                    │  ✓ Issue card    │              ▼
                    └──────────────────┘     ┌─────────────────┐
                             │               │    Merchant     │
                             ▼               └─────────────────┘
                    ┌──────────────────┐
                    │  Approval Queue  │
                    │  (if needed)     │
                    └──────────────────┘

MCP工具

当通过MCP连接时，代理可以访问这些工具：

工具	说明
`request_purchase`	申请购买，获得批准后获得虚拟卡
`check_budget`	检查剩余预算和限额
`list_transactions`	查看交易历史记录
`get_policy_info`	查看适用于此代理的规则

示例：代理请求购买

// Agent calls request_purchase
{
  "amount": 49.99,
  "currency": "usd",
  "description": "Monthly Figma subscription",
  "merchant_name": "Figma"
}

// If approved, agent receives:
{
  "status": "approved",
  "card": {
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2025,
    "cvc": "123"
  },
  "hard_limit_amount": 49.99,
  "expires_at": "2025-12-05T15:00:00Z"
}

// If rejected:
{
  "status": "rejected",
  "reason_code": "OVER_TRANSACTION_LIMIT",
  "message": "Amount $49.99 exceeds per-transaction limit of $25.00",
  "suggestion": "Try a smaller purchase amount..."
}

// If needs approval:
{
  "status": "pending_approval",
  "message": "Amount exceeds approval threshold",
  "purchase_intent_id": "pi_abc123"
}

支出控制

代理级别控制

控制	描述
`monthlyLimit`	每月最大支出
`dailyLimit`	每日最大消费
`perTransactionLimit`	单次购买的最大金额
`approvalThreshold`	以上需要人工批准
`flagNewVendors`	首次在新商家购买时需要获得批准
`blockedMerchants`	被屏蔽商户名称列表
`allowedMerchants`	如果设置，则只允许这些商家

组织护栏

护栏	说明
`monthlyBudget`	所有代理的总预算
`maxTransactionAmount`	任何单一交易的硬上限
`requireApprovalAbove`	以上所有购买都需要审核
`flagAllNewVendors`	所有新供应商都需要批准
`blockCategories`	阻止整个商户类别

实施提供商

存储提供程序

实施 StorageProvider 使用您自己的数据库：

import type { StorageProvider } from "@roony-pay/governance";

class PostgresStorageProvider implements StorageProvider {
  async getAgent(agentId: string) {
    return await db.query("SELECT * FROM agents WHERE id = $1", [agentId]);
  }
  
  async getAgentSpend(agentId: string, period: "daily" | "monthly") {
    // Sum approved purchases for the period
  }
  
  // ... implement other methods
}

支付提供商

实施 PaymentProvider 使用您的支付处理器：

import type { PaymentProvider } from "@roony-pay/governance";
import Stripe from "stripe";

class StripePaymentProvider implements PaymentProvider {
  private stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
  
  async createVirtualCard(request) {
    const card = await this.stripe.issuing.cards.create({
      cardholder: process.env.CARDHOLDER_ID,
      type: "virtual",
      currency: request.currency,
      spending_controls: {
        spending_limits: [{
          amount: request.amount * 100,
          interval: "all_time",
        }],
      },
    });
    
    // Return card details
  }
}

Docker部署

# docker-compose.yml
version: '3.8'
services:
  roony:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://...
      - STRIPE_SECRET_KEY=sk_...
      - STRIPE_CARDHOLDER_ID=ich_...

api参考

`createRoonyMCPServer(config)`

创建用于AI代理治理的MCP服务器。

const server = createRoonyMCPServer({
  storage: StorageProvider,      // Your database implementation
  paymentProvider: PaymentProvider, // Your payment processor
});

// Handle requests
const response = await server.handleRequest(
  mcpRequest,   // The MCP JSON-RPC request
  agentId,      // ID of the agent making the request  
  organizationId // ID of the organization
);

`createSpendingChecker(config)`

创建一个独立的支出检查器（不带MCP）：

const checker = createSpendingChecker({
  storage: myStorageProvider,
});

const result = await checker.checkSpending({
  agentId: "agent_123",
  amount: 50.00,
  currency: "usd",
  merchantName: "Amazon",
  description: "Office supplies",
});

if (result.allowed && !result.requiresApproval) {
  // Proceed with purchase
} else if (result.requiresApproval) {
  // Queue for human review
} else {
  // Rejected - show result.rejectionMessage
}

拒收代码

代码	描述
`AGENT_NOT_FOUND`	找不到代理ID
`OVER_TRANSACTION_LIMIT`	超过每笔交易限额
`DAILY_LIMIT_EXCEEDED`	已达到每日消费限额
`MONTHLY_LIMIT_EXCEEDED`	已达到每月支出限额
`ORG_BUDGET_EXCEEDED`	组织预算已用尽
`OVER_ORG_MAX_TRANSACTION`	超过组织最大交易额
`MERCHANT_BLOCKED`	商户被封锁
`MERCHANT_NOT_ALLOWED`	商人不在敌对状态
`CATEGORY_BLOCKED`	商户类别被阻止

托管与自托管

功能	自托管	托管（roony.pay）
支出控制	✅	✅
审批工作流	✅	✅
MCP支持	✅	✅
虚拟卡	您实现	✅ 内置
仪表板	您构建	✅ 包括
条纹集成	您实现	✅ 包括
支持	社区	优先级

贡献

我们欢迎捐款！看贡献.md 作为指导方针。

# Clone the repo
git clone https://github.com/roony-pay/roony-mcp.git
cd roony-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

许可证

MIT© Roony

问题？ 打开问题或联系hello@roony.pay