内容
<p align="center">
<img src="https://img.shields.io/badge/MCP-Server-5A45FF?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMiAyTDIgN2wxMCA1IDEwLTV6Ii8+PHBhdGggZD0iTTIgMTdsMTAgNSAxMC01Ii8+PHBhdGggZD0iTTIgMTJsMTAgNSAxMC01Ii8+PC9zdmc+" alt="MCP 服务器" />
<img src="https://img.shields.io/badge/Priority-ERP-FF6B35?style=for-the-badge" alt="Priority ERP" />
<img src="https://img.shields.io/badge/TypeScript-Strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
</p>
<h1 align="center">Priority MCP 服务器</h1>
<p align="center">
<strong>连接 AI 助手到 Priority ERP</strong><br/>
72 个工具 · 3 个资源 · 5 个工作流提示 · 12 个业务领域
</p>
<p align="center">
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License" /></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node 22+" /></a>
<a href="#tools-72"><img src="https://img.shields.io/badge/tools-72-blue.svg" alt="72 个工具" /></a>
<a href="#mcp-prompts-5"><img src="https://img.shields.io/badge/prompts-5-purple.svg" alt="5 个提示" /></a>
</p>
<p align="center">
<a href="#-quick-start">快速开始</a> •
<a href="#-setup-recipes">设置配方</a> •
<a href="#%EF%B8%8F-configuration">配置</a> •
<a href="#-tools-72">工具</a> •
<a href="#-deployment">部署</a> •
<a href="#-priority-setup">Priority 设置</a>
</p>
---
## 什么是 Priority MCP 服务器？
一个开源的 **[MCP（模型上下文协议）](https://modelcontextprotocol.io)** 服务器，它封装了 **Priority ERP 的 OData REST API**，并将其暴露为任何与 MCP 兼容的 AI 助手可以使用的工具。
向您的 AI 助手提问：
> *"显示所有逾期发票超过 10,000 美元的客户"*
>
> *"为客户 C1001 创建销售订单，包含 50 单位的产品 X"*
>
> *"给我一个晨间简报：新订单、现金状况和低库存警报"*
>
> *"为客户 ACME 运行债务催收工作流"*
与 **Claude Desktop**、**Claude Code**、**Cursor**、**Windsurf** 和任何与 MCP 兼容的客户端兼容。
---
## 快速开始
```bash
# 设置您的 Priority 凭证
export PRIORITY_API_URL="https://your-server.com/odata/Priority"
export PRIORITY_ENVIRONMENT="wlnd"
export PRIORITY_COMPANY="demodata"
export PRIORITY_USERNAME="apiuser"
export PRIORITY_PASSWORD="your-password"
# 运行它
npx priority-mcp-server
```
服务器在 stdio 上启动，准备好供您的 MCP 客户端使用。就是这样。
---
## 设置配方
### Claude Desktop
添加到您的配置文件：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"priority": {
"command": "npx",
"args": ["-y", "priority-mcp-server"],
"env": {
"PRIORITY_API_URL": "https://your-server.com/odata/Priority",
"PRIORITY_ENVIRONMENT": "wlnd",
"PRIORITY_COMPANY": "demodata",
"PRIORITY_USERNAME": "apiuser",
"PRIORITY_PASSWORD": "your-password"
}
}
}
}
```
### Claude Code
```bash
claude mcp add priority \
-e PRIORITY_API_URL="https://your-server.com/odata/Priority" \
-e PRIORITY_ENVIRONMENT="wlnd" \
-e PRIORITY_COMPANY="demodata" \
-e PRIORITY_USERNAME="apiuser" \
-e PRIORITY_PASSWORD="your-password" \
-- npx -y priority-mcp-server
```
### Cursor
打开 **设置 > MCP 服务器 > 添加**，并粘贴与 Claude Desktop 相同的 JSON 配置。
### Windsurf
使用与 Claude Desktop 相同的 JSON 结构，将其添加到您的 Windsurf MCP 配置中。
### Docker（远程/HTTP 模式）
```bash
docker run -p 3000:3000 \
-e MCP_TRANSPORT=http \
-e PRIORITY_API_URL="https://your-server.com/odata/Priority" \
-e PRIORITY_ENVIRONMENT="wlnd" \
-e PRIORITY_COMPANY="demodata" \
-e PRIORITY_USERNAME="apiuser" \
-e PRIORITY_PASSWORD="your-password" \
ghcr.io/assafch/priority-mcp:latest
```
---
## 配置
所有配置均通过环境变量进行验证。启动时验证 - 服务器如果缺少任何内容，则会快速失败并显示清晰的错误信息。
| 变量 | 必需 | 默认值 | 描述 |
|:---------|:--------:|:-------:|:------------|
| `PRIORITY_API_URL` | **是** | — | Priority OData 端点 URL |
| `PRIORITY_ENVIRONMENT` | **是** | — | 环境名称（例如 `wlnd`、`demo`） |
| `PRIORITY_COMPANY` | **是** | — | 公司数据库（例如 `demodata`、`usdemo`） |
| `PRIORITY_USERNAME` | **是** | — | API 用户名 |
| `PRIORITY_PASSWORD` | **是** | — | API 密码 |
| `PRIORITY_LANGUAGE` | 否 | `EN` | `EN` 或 `HE` - 控制字段名称的本地化 |
| `PRIORITY_CUSTOM_PREFIX` | 否 | — | 自定义实体的前缀（例如 `ORGT_`） |
| `PRIORITY_CUSTOM_ENTITIES` | 否 | — | 以逗号分隔的自定义实体名称 |
| `PRIORITY_READ_ONLY` | 否 | `false` | 阻止所有写操作 |
| `PRIORITY_ALLOWED_TOOLS` | 否 | — | 以逗号分隔的工具允许列表 |
| `PRIORITY_BLOCKED_TOOLS` | 否 | — | 以逗号分隔的工具阻止列表 |
| `CACHE_TTL_SECONDS` | 否 | `60` | 内存缓存 TTL |
| `RATE_LIMIT_PER_MINUTE` | 否 | `120` | 每分钟最大 API 请求数 |
| `LOG_LEVEL` | 否 | `info` | `trace` / `debug` / `info` / `warn` / `error` |
| `MCP_TRANSPORT` | 否 | `stdio` | `stdio`（本地）或 `http`（远程） |
| `MCP_HTTP_PORT` | 否 | `3000` | HTTP 端口（当传输为 `http` 时） |
---
## 工具（72 个）
### 客户（10 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_customers` | 读取 | 列出客户并过滤（状态、余额、销售代表） |
| `priority_get_customer` | 读取 | 通过 CUSTNAME 获取完整的客户记录 |
| `priority_search_customers` | 读取 | 按名称、税务 ID、电话、电子邮件进行模糊搜索 |
| `priority_get_customer_balance` | 读取 | 开放余额 + 信用额度 + 可用信用 |
| `priority_get_customer_contacts` | 读取 | 联系人列表，包含电话/电子邮件/角色 |
| `priority_get_customer_price_list` | 读取 | 分配的价格列表和折扣 |
| `priority_get_customer_documents` | 读取 | 客户的所有发票、订单、报价 |
| `priority_get_customer_aging` | 读取 | 老化桶（0-30、31-60、61-90、90+ 天） |
| `priority_create_customer` | 写入 | 创建新的客户记录 |
| `priority_update_customer` | 写入 | 更新客户字段 |
### 债务和收款（7 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_get_open_debts` | 读取 | 所有开放的 AR， 可按老化/金额/代表过滤 |
| `priority_get_aging_report` | 读取 | 公司范围的老化报告，包含客户明细 |
| `priority_get_overdue_invoices` | 读取 | 按逾期天数排序的逾期发票 |
| `priority_get_payment_history` | 读取 | 客户的历史付款行为 |
| `priority_get_top_debtors` | 读取 | 按开放债务排名的前 N 名客户 |
| `priority_record_payment_promise` | 写入 | 记录付款承诺日期 |
| `priority_mark_invoice_disputed` | 写入 | 将发票标记为有争议并附上原因 |
### 发票（6 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_invoices` | 读取 | 按日期范围、客户、状态过滤 |
| `priority_get_invoice` | 读取 | 完整的发票，包含行项目 |
| `priority_get_unpaid_invoices_for_customer` | 读取 | 客户的未付发票，用于收款工作流 |
| `priority_create_invoice` | 写入 | 创建发票，包含行项目 |
| `priority_void_invoice` | 写入 | 作废/取消发票 |
| `priority_create_credit_memo` | 写入 | 对发票发出信用备忘录 |
### 订单（9 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_orders` | 读取 | 销售订单并过滤 |
| `priority_get_order` | 读取 | 完整的订单，包含行和状态 |
| `priority_get_pending_orders` | 读取 | 待处理的订单 |
| `priority_get_order_shipment_status` | 读取 | 跟踪信息和承运商详情 |
| `priority_get_backorder_report` | 读取 | 有库存问题的订单 |
| `priority_create_order` | 写入 | 创建新的销售订单 |
| `priority_update_order` | 写入 | 修改订单头/行 |
| `priority_cancel_order` | 写入 | 取消并附上原因 |
| `priority_confirm_order` | 写入 | 移至确认状态 |
### 产品和库存（11 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_products` | 读取 | 产品并过滤类别/库存/活动 |
| `priority_get_product` | 读取 | 完整的产品详情 |
| `priority_search_products` | 读取 | 按名称、SKU、条码搜索 |
| `priority_get_stock_levels` | 读取 | 每个仓库的库存并保留/可用 |
| `priority_get_low_stock_alerts` | 读取 | 低于补货点的产品 |
| `priority_get_out_of_stock` | 读取 | 零库存产品 |
| `priority_get_product_price` | 读取 | 价格，可选按客户 |
| `priority_get_product_sales_history` | 读取 | 销售速度数据 |
| `priority_update_product_price` | 写入 | 更改列表价格 |
| `priority_adjust_stock` | 写入 | 库存调整并附上原因代码 |
| `priority_transfer_stock` | 写入 | 在仓库之间转移库存 |
### 仓库（1 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_warehouses` | 读取 | 所有仓库并包含位置信息 |
### 供应商（3 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_suppliers` | 读取 | 列表并搜索 |
| `priority_get_supplier` | 读取 | 完整的供应商记录 |
| `priority_get_supplier_balance` | 读取 | 开放的 AP 余额 |
### 采购订单（4 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_purchase_orders` | 读取 | 采购订单并过滤状态/日期 |
| `priority_get_purchase_order` | 读取 | 采购订单并包含行项目 |
| `priority_get_incoming_shipments` | 读取 | 采购订单在途并包含预期日期 |
| `priority_create_purchase_order` | 写入 | 创建新的采购订单 |
### 财务和分析（8 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_get_bank_balances` | 读取 | 所有银行账户余额 |
| `priority_get_cash_position` | 读取 | 账户现金总额 |
| `priority_get_revenue_by_period` | 读取 | 按日期范围划分的收入明细 |
| `priority_get_top_customers` | 读取 | 按收入划分的前 N 名客户 |
| `priority_get_top_products` | 读取 | 按收入划分的前 N 名产品 |
| `priority_get_ar_aging_summary` | 读取 | AR 老化总结 |
| `priority_get_ap_aging_summary` | 读取 | AP 老化总结 |
| `priority_get_cashflow_projection` | 读取 | AR vs AP 投影 |
### 活动/CRM（5 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_activities` | 读取 | 调用、会议、任务 |
| `priority_get_customer_activities` | 读取 | 客户活动历史 |
| `priority_get_open_tasks` | 读取 | 按到期日期排序的待处理任务 |
| `priority_create_activity` | 写入 | 记录电话/电子邮件/会议 |
| `priority_schedule_followup` | 写入 | 创建未来日期的任务 |
### 文档（3 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_attachments` | 读取 | 任何实体的附件 |
| `priority_get_attachment_url` | 读取 | 文件的下载 URL |
| `priority_upload_attachment` | 写入 | 将文件附加到实体 |
### 元数据/管理员（5 个）
| 工具 | 类型 | 描述 |
|:-----|:----:|:------------|
| `priority_list_entities` | 读取 | 发现所有可用实体 |
| `priority_get_entity_schema` | 读取 | 任何实体的字段列表和类型 |
| `priority_list_companies` | 读取 | 环境中的公司 |
| `priority_get_current_user` | 读取 | 当前身份验证上下文 |
| `priority_execute_odata_query` | 读取 | 原始 OData 出口 |
---
## MCP 资源（3 个）
| URI | 描述 |
|:----|:------------|
| `priority://schema/{entity}` | 任何实体的 JSON 模式 |
| `priority://company/info` | 当前公司元数据 |
| `priority://user/profile` | 当前用户和连接信息 |
---
## MCP 提示（5 个）
| 提示 | 描述 |
|:-------|:------------|
| `debt_collection_workflow` | 客户的分步收款工作流 |
| `daily_briefing` | 晨间简报：订单、逾期、现金、库存、任务 |
| `cash_position_summary` | 现金快照与 AR/AP 投影 |
| `order_fulfillment_check` | 可以发货吗？库存检查 + ETA |
| `inventory_reorder_check` | 需要补货的产品，建议数量 |
---
## 工具安全
所有 18 个写入工具都包含内置安全功能：
* **默认干预** - 写入工具默认 `dryRun: true`，预览有效载体而不进行更改
* **只读模式** - 设置 `PRIORITY_READ_ONLY=true` 在全局禁用所有写入
* **工具允许列表/阻止列表** - 细粒度控制哪些工具被暴露 |
---
## 部署
### 本地（stdio）
```bash
npx priority-mcp-server`
### Docker
```bash
docker build -t priority-mcp-server .
docker run -p 3000:3000 --env-file .env -e MCP_TRANSPORT=http priority-mcp-server
### Google Cloud Run
```bash
gcloud builds submit --tag gcr.io/YOUR_PROJECT/priority-mcp-server
gcloud run deploy priority-mcp-server \
--image gcr.io/YOUR_PROJECT/priority-mcp-server \
--port 3000 \
--set-env-vars="MCP_TRANSPORT=http" \
--update-secrets="PRIORITY_PASSWORD=latest" \
--no-allow-unauthenticated
```
### Railway
在 [railway.app](https://railway.app) 上连接您的仓库，设置环境变量并部署。Railway 自动检测 Dockerfile。
详见 [docs/deployment.md](docs/deployment.md) 了解详细指南。
---
## Priority 设置
1. **在 Priority 中创建 API 用户** 在 **系统管理 > 用户**
2. **分配权限** - 用户需要访问您要公开的实体
3. **启用 OData** - 确保 Priority OData REST API 可通过 HTTPS 访问
4. **测试连接：**
```bash
curl -u user:pass "https://your-server/odata/Priority/wlnd/odata/Priority/tabula.ini/demodata/CUSTOMERS?\$top=1"
```
5. 对于只读访问，在 Priority **和** 设置 `PRIORITY_READ_ONLY=true` 处删除写权限
详见 [docs/priority-notes.md](docs/priority-notes.md) 了解 OData 怪癖、希伯来语字段名称、日期格式和其他注意事项。
---
## 安全
| 功能 | 描述 |
|:--------|:------------|
| 只读模式 | `PRIORITY_READ_ONLY=true` 阻止所有写入 |
| 工具访问控制 | 允许或阻止特定工具 |
| 速率限制 | 内置，可配置的每分钟限制 |
| 凭证安全 | 永远不会被记录，永远不会在工具响应中 |
| PII 删减 | 电话、电子邮件、税务 ID 从日志中删除 |
| 无依赖 Docker | 生产环境中的最小攻击面 |
详见 [docs/security.md](docs/security.md) 了解完整的安全指南。
---
## 开发
```bash
git clone https://github.com/assafch/Priority-Mcp.git
cd Priority-Mcp
npm install
npm run dev # 使用 Node 的 TypeScript 剥离运行
npm test # Vitest
npm run lint # Biome
npm run inspect # MCP 检测
```
详见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。
---
## 架构
```
src/
├── index.ts # 入口点 - stdio 或 HTTP 传输
├── server.ts # McpServer 设置
├── config.ts # Zod 环境验证
├── logger.ts # Pino 结构化日志记录
├── client/ # Priority OData HTTP 客户端
│ ├── priority-client.ts
│ ├── odata-builder.ts # 类型安全的 $filter/$expand/$select 构建器
│ ├── cache.ts # 内存 LRU，带 TTL
│ ├── rate-limit.ts # 滑动窗口速率限制器
│ └── errors.ts # Priority→MCP 错误映射
├── tools/ # 72 个 MCP 工具，跨 12 个文件
├── resources/ # 3 个 MCP 资源
├── prompts/ # 5 个 MCP 提示
└── lib/ # 共享实用程序
```
---
## 许可证
[MIT](LICENSE) - 随意使用。
---
<p align="center">
为 Priority ERP 社区构建<br/>
<sub>欢迎贡献 · <a href="https://github.com/assafch/Priority-Mcp/issues">报告问题</a></sub>
</p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器