Order Management MCP

订单管理MCP服务器

用于管理多家公司订单的MCP（模型上下文协议）服务器，设计为使用OpenAI Apps SDK的ChatGPT自定义应用程序。

特性

• 多公司支持：用户可以拥有/访问多家公司
• 无状态设计：每个工具调用都包含company_id，从而为不同的公司提供并行对话
• OAuth身份验证：所有工具都需要通过Bearer令牌进行身份验证
• 订单管理工具:

- list_companies -查看您有权访问的所有公司 - list_orders -列出特定公司的订单 - get_order -获取特定订单的详细信息 - update_order_status -通过验证更改订单状态

无状态架构

此服务器使用 无状态设计 哪里 company_id 在每个与订单相关的操作中都需要。这种方法：

• ✅ 支持不同公司的并行ChatGPT对话
• ✅ 可横向扩展（无共享会话状态）
• ✅ 与ChatGPT的上下文管理完美配合
• ✅ 更容易调试和推理

项目结构

order-management-mcp/
├── src/
│   ├── index.ts        # Main MCP server and HTTP handling
│   ├── types.ts        # TypeScript type definitions
│   ├── mock-data.ts    # Sample data for testing
│   └── auth.ts         # OAuth token validation
├── package.json
├── tsconfig.json
├── Dockerfile
├── fly.toml            # Fly.io deployment config
└── README.md

快速开始

先决条件

• Node.js 20+
• npm或纱线

本地开发

1. 安装依赖项:

   npm install

1. 构建项目:

   npm run build

1. 启动服务器:

   npm start

或者用于自动重新加载的开发：

   npm run dev

1. 测试服务器:

   # Health check
   curl http://localhost:3000/health

   # Test MCP endpoint with mock token
   curl -X POST http://localhost:3000/mcp \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer mock_token_user_001" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

模拟用户进行测试

服务器包括用于测试的模拟数据：

部署到Fly.io

首次设置

1. 安装Fly CLI:

   # macOS
   brew install flyctl

   # Windows
   powershell -Command "iwr https://fly.io/install.ps1 -useb | iex"

   # Linux
   curl -L https://fly.io/install.sh | sh

1. 登录Fly.io:

   fly auth login

1. 创建应用程序:

   fly apps create order-management-mcp

1. 设置秘密 （用于生产JWT验证）：

   fly secrets set JWT_SECRET=your-secure-secret-key

1. 部署:

   fly deploy

后续部署

fly deploy

api参考

工具

list_companies

列出经过身份验证的用户有权访问的所有公司。

输入：无

输出:

{
  "companies": [
    {
      "id": "company_001",
      "name": "Tech Gadgets Inc",
      "slug": "tech-gadgets",
      "industry": "Electronics",
      "createdAt": "2023-01-15T10:00:00Z"
    }
  ],
  "count": 1
}

list_orders

列出特定公司的订单。

输入:

{
  "company_id": "company_001",
  "status": "pending",
  "limit": 50
}

输出:

{
  "orders": [
    {
      "id": "order_001",
      "orderNumber": "TG-2024-0001",
      "customerName": "Alice Johnson",
      "status": "processing",
      "totalAmount": 231.34,
      "currency": "USD",
      "createdAt": "2024-01-10T08:30:00Z"
    }
  ],
  "count": 1,
  "companyId": "company_001",
  "companyName": "Tech Gadgets Inc"
}

get_order

获取特定订单的详细信息。

输入:

{
  "company_id": "company_001",
  "order_id": "order_001"
}

输出：包含客户详细信息、商品、送货地址等的完整订单对象。

update_order_status

通过验证更新订单的状态。

输入:

{
  "company_id": "company_001",
  "order_id": "order_001",
  "new_status": "shipped",
  "notes": "Shipped via FedEx"
}

有效状态转换:

• pending → confirmed, cancelled
• confirmed → processing, cancelled
• processing → shipped, cancelled
• shipped → delivered
• delivered → refunded
• cancelled → （终端）
• refunded → （终端）

ChatGPT对话示例

User: Show me my companies

ChatGPT: [calls list_companies]
You have access to 2 companies:
- Tech Gadgets Inc (ID: company_001)
- Fashion Forward (ID: company_002)

User: List pending orders for Tech Gadgets

ChatGPT: [calls list_orders with company_id="company_001", status="pending"]
Found 1 pending order for Tech Gadgets Inc:
- TG-2024-0003: Sarah Williams - PENDING - USD 151.76

User: Show me the details of that order

ChatGPT: [calls get_order with company_id="company_001", order_id="order_003"]
[Shows full order details...]

User: Confirm that order

ChatGPT: [calls update_order_status with company_id="company_001", order_id="order_003", new_status="confirmed"]
Order TG-2024-0003 status updated from "pending" to "confirmed".

连接到ChatGPT

1.设置OAuth提供程序

在连接到ChatGPT之前，您需要一个OAuth 2.1提供程序。选项包括：

• 身份验证0
• 八月
• 职员
• 自定义实现

您的OAuth提供商必须支持：

• 动态客户端注册（DCR）
• PKCE
• 标准OIDC发现端点

2.配置发现端点

将这些端点添加到您的服务器（或OAuth提供商）：

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
/.well-known/openid-configuration

3.创建ChatGPT连接器

1. 转到ChatGPT开发人员设置
2. 创建新连接器
3. 输入您的MCP服务器URL： https://your-app.fly.dev/mcp
4. 配置OAuth设置

安全考虑

1. 令牌验证：始终在每次请求时验证OAuth令牌
2. 公司接入：在执行任何操作之前，请验证用户是否有权访问公司
3. 输入验证：对所有工具输入使用Zod模式
4. 状态转换：强制执行有效的状态机转换
5. 审计日志：记录所有状态更改操作（在生产中实施）

扩展服务器

添加真实数据库

替换中的模拟数据 mock-data.ts 使用实际的数据库查询：

// Example with Prisma
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export async function getOrdersByCompany(companyId: string) {
  return prisma.order.findMany({
    where: { companyId },
    include: { customer: true, items: true }
  });
}

添加更多工具

在中注册新工具 index.ts:

server.tool(
  'cancel_order',
  'Cancels an order and initiates refund process.',
  {
    company_id: z.string().describe('The company ID'),
    order_id: z.string().describe('The order ID'),
    reason: z.string().describe('Cancellation reason')
  },
  async ({ company_id, order_id, reason }) => {
    // Implementation
  }
);

许可证

麻省理工学院