Procurementexpress MCP

ProcurementExpress MCP服务器

A. 模型上下文协议（MCP） 为LLM提供访问权限的服务器 采购快递 API通过自然语言管理采购订单、发票、预算、供应商和采购工作流程。

特性

• 100+工具 覆盖整个ProcurementExpress API表面
• 双API版本支持 --V1（基于令牌）和V3（OAuth2）身份验证
• 版本无关的工具层 -所有工具在API版本中的工作方式相同
• 类型安全 -适用于所有API实体的全面TypeScript接口
• 文件上传 --支持PO、注释和数字发票的多部分文件上传
• 政府采购 --SAM.gov检查、政策、供应商批准
• 零外部运行时依赖关系 --只有 @modelcontextprotocol/sdk 和 zod

快速开始

先决条件

• Node.js 18+
• 具有API访问权限的ProcurementExpress帐户

安装

无需安装--直接使用运行 npx:

npx -y @procurementexpress.com/mcp

使用Claude Desktop

将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "procurementexpress": {
      "command": "npx",
      "args": ["-y", "@procurementexpress.com/mcp"],
      "env": {
        "PROCUREMENTEXPRESS_API_VERSION": "v1",
        "PROCUREMENTEXPRESS_AUTH_TOKEN": "your_token",
        "PROCUREMENTEXPRESS_COMPANY_ID": "your_company_id"
      }
    }
  }
}

使用Claude代码

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "procurementexpress": {
      "command": "npx",
      "args": ["-y", "@procurementexpress.com/mcp"],
      "env": {
        "PROCUREMENTEXPRESS_API_VERSION": "v1",
        "PROCUREMENTEXPRESS_AUTH_TOKEN": "your_token",
        "PROCUREMENTEXPRESS_COMPANY_ID": "your_company_id"
      }
    }
  }
}

配置

服务器完全通过环境变量配置（在 env 块上面）。

V1身份验证（推荐）

静态令牌身份验证。令牌永远不会过期。

V3身份验证（OAuth2）

OAuth2密码授予。代币有时间限制，需要 client_id/client_secret.

认证

服务器支持两种身份验证模式，由 PROCUREMENTEXPRESS_API_VERSION 环境变量。

V1——基于令牌（默认）

集 PROCUREMENTEXPRESS_API_VERSION=v1。通过环境变量提供您的静态令牌和公司ID，或将它们传递给 authenticate 工具在运行时。

• 发送 authentication_token 和 app_company_id 每个请求上的标头
• 令牌永不过期——无需刷新逻辑
• 环境变量： PROCUREMENTEXPRESS_AUTH_TOKEN, PROCUREMENTEXPRESS_COMPANY_ID

V3--OAuth2

集 PROCUREMENTEXPRESS_API_VERSION=v3。需要 PROCUREMENTEXPRESS_CLIENT_ID 和 PROCUREMENTEXPRESS_CLIENT_SECRET 环境变量。打电话给 authenticate 使用电子邮件/密码获取Bearer令牌的工具。

• 发送 Authorization: Bearer 每个请求的标题
• 令牌有刷新支持的时间限制
• 验证后，使用 set_active_company 选择一家公司

可用工具

身份验证（3个工具）

用户（4个工具）

公司（12种工具）

预算（4种工具）

部门（4个工具）

供应商（7种工具）

产品（6工具）

采购订单（19个工具）

发票（13个工具）

自定义字段（6个工具）

合规性（10个工具）

上传（3个工具）

政策（6个工具）

聊天信息（3个工具，仅限V3）

数字发票（1个工具）

审批流程（13个工具）

付款（3种工具）

税率（4个工具）

Webhooks（5个工具）

评论（2个工具）

补充（8个工具）

AI代理技能

服务器附带10个特定模块 Claude代码技能 在 .claude/skills/ 它将AI代理路由到正确的MCP工具调用，而无需读取整个源文件。技能使用 pex: 命名空间：

复杂模式的技能包括 references/ 用于逐步披露的子目录（例如，行项目模式、审批条件、工作流）。

在项目中安装技能

要在您自己的项目中与MCP服务器一起使用这些技能，请复制 .claude/skills/pex-* 项目中的目录：

# From your project root
mkdir -p .claude/skills

# Copy all PEX skills from the package
cp -r node_modules/@procurementexpress.com/mcp/.claude/skills/pex-* .claude/skills/

或者只挑选你需要的技能：

# Example: only purchase orders and invoices
cp -r node_modules/@procurementexpress.com/mcp/.claude/skills/pex-purchase-orders .claude/skills/
cp -r node_modules/@procurementexpress.com/mcp/.claude/skills/pex-invoices .claude/skills/

一旦安装，Claude Code将自动发现技能并使用它们来路由到正确的MCP工具调用（例如。， /pex:purchase-orders, /pex:invoices).

项目结构

src/
  index.ts              # Entry point — MCP server setup, auth tools, tool registration
  api-client.ts         # HTTP client with versioned path building, auth headers, multipart support
  auth.ts               # Dual auth manager (V1 token / V3 OAuth2)
  tool-helpers.ts       # Shared response helpers and error handling wrapper
  types.ts              # TypeScript interfaces for all API entities
  schemas.ts            # Shared Zod schemas (custom field values, line items, nested attributes)
  tools/
    approval-flows.ts   # Approval flow CRUD, publish/unpublish, runs, versions, rerun
    budgets.ts          # Budget CRUD
    chat-messages.ts    # Chat messages (V3 only) — list, create, delete
    comments.ts         # PO and invoice comments
    companies.ts        # Company details, employees, approvers, invitations, pending invites
    compliance.ts       # Compliance checks, bulk checks, justifications, memos, evidence packs
    custom-fields.ts    # Custom field CRUD + position reordering
    departments.ts      # Department CRUD
    digital-invoices.ts # Digital invoice creation from scanned documents
    invoices.ts         # Invoice CRUD, approve/reject/cancel/archive, rerun approval, PO linking
    payments.ts         # Payment creation (standalone, PO-linked, NPayment) and get
    policies.ts         # Policy CRUD + policy templates
    products.ts         # Product CRUD + bulk create + SKU listing
    purchase-orders.ts  # PO CRUD, approve/reject/cancel/archive/delete, delivery, PDF, bulk save
    supplementary.ts    # Chart of accounts, QBO integration, email forwarding
    suppliers.ts        # Supplier CRUD + top suppliers + SAM.gov check + supplier approvals
    tax-rates.ts        # Tax rate CRUD
    uploads.ts          # File uploads (PO attachments, comment files, upload status)
    users.ts            # Current user profile and currency listing
    webhooks.ts         # Webhook CRUD + delete
tests/
  e2e/
    setup.ts            # MockApiServer with version-agnostic route registration
    *.test.ts           # E2E tests for each tool group (211 tests)

发展

对于希望在服务器上工作的贡献者：

git clone https://github.com/przbadu/procurementexpress-mcp.git
cd procurementexpress-mcp
npm install

构建

npm run build      # Compile TypeScript to dist/
npm run dev        # Watch mode for development

测试

npm test                                    # Run all tests
npm run test:e2e                            # Run E2E tests only
npx vitest run tests/e2e/auth.test.ts       # Run a single test file
npm run test:watch                          # Watch mode

测试使用a MockApiServer -模拟ProcurementExpress API的轻量级HTTP服务器。模拟路由使用与版本无关的正则表达式模式(/api/v[13]/)因此测试适用于V1和V3配置。

添加新工具

1. 添加TypeScript接口 src/types.ts 如有需要
2. 在中创建或编辑文件 src/tools/ 遵循现有模式：

import { z } from "zod";
import type { ApiClient } from "../api-client.js";
import type { Server } from "../tool-helpers.js";
import { jsonResponse, withErrorHandling } from "../tool-helpers.js";

export function registerMyTools(server: Server, apiClient: ApiClient): void {
  server.registerTool(
    "my_tool_name",
    {
      description: "What this tool does",
      inputSchema: {
        id: z.number().int().positive().describe("Resource ID"),
      },
    },
    withErrorHandling(async (args) => {
      const result = await apiClient.get(apiClient.buildPath(`/my_resource/${args.id}`));
      return jsonResponse(result);
    }),
  );
}

1. 在中注册工具组 src/index.ts:

import { registerMyTools } from "./tools/my-tools.js";
registerMyTools(server, apiClient);

1. 在中添加模拟路线和测试 tests/e2e/

主要惯例：

• 总是使用 apiClient.buildPath("/resource") --从不硬编码 /api/v1/ 或 /api/v3/
• 用 withErrorHandling()
• 使用 jsonResponse() 数据和 textResponse() 用于消息
• 所有进口必须使用 .js 扩展（ES模块）

发布新版本

要将新版本发布到npm：

1. 确保你的工作树干净，所有测试都通过：

   npm test

1. 修改版本，创建一个git标签，然后发布：

   # Choose one: patch (bug fixes), minor (new features), major (breaking changes)
   npm version patch -m "v%s"   # or minor / major

   # Push the commit and tag
   git push && git push --tags

   # Publish to npm (auto-builds via prepublishOnly)
   npm publish

1. 验证发布的版本：

   npm view @procurementexpress.com/mcp version

该包发布为 @procurementexpress.com/mcp 在npm上。

环境变量引用

许可证

ISC